Skip to main content
@veil-cash/sdk is a TypeScript SDK and CLI for Veil privacy pools on Base. Generate keypairs, register, deposit, withdraw, transfer, and merge ETH and USDC privately—plus deterministic subaccounts and x402 payments.

​
Install

npm install @veil-cash/sdk
# or: yarn add @veil-cash/sdk / pnpm add @veil-cash/sdk
For global CLI access: 
npm install -g @veil-cash/sdk
The CLI binary is veil. The SDK is the entry point for programmatic integration; the CLI is the quickest path for most users.

​
CLI quick start

# 1. Set your Ethereum wallet key
export WALLET_KEY=0x...

# 2. Derive and save your Veil keypair
veil init

# 3. Register your deposit key (one-time)
veil register

# 4. Check your setup
veil status

# 5. Deposit (amount is what lands in your balance; 0.3% fee added on top)
veil deposit ETH 0.1
veil deposit USDC 100

# 6. Inspect balances
veil balance
veil balance queue --pool usdc
veil balance private

# 7. Private actions
veil withdraw ETH 0.05 0xRecipient
veil transfer ETH 0.02 0xRecipient
veil merge ETH 0.1
The CLI is human-readable by default. Add --json for stable machine-readable output, and --unsigned to emit transaction payload JSON for automation and agents (no private key required—set SIGNER_ADDRESS for address-only flows).

​
Deposits

The amount you specify is the net amount that arrives in your Veil balance. A 0.3% protocol fee is added on top automatically. 
veil deposit ETH 0.1            # 0.1 ETH lands in pool (~0.1003 ETH sent)
veil deposit USDC 100           # 100 USDC lands in pool (~100.30 USDC sent)
veil deposit ETH 0.1 --unsigned --address 0x...
Deposits require compliance screening or an instant Verified Users path—see 0xbow Screening for how non-verified deposits are processed. Shielded minimums are 0.01 ETH and 20 USDC (after the 0.3% fee); deposit slightly above the floor so the net amount still clears. See the FAQ for details. After your wallet confirms the transaction, the deposit enters the Veil queue before it reaches your private balance. For addresses without instant verification, 0xbow screening typically takes about 15 minutes (complex cases up to 5 days, plus a holding period). Once approved, queue processing into your private balance is typically around 8–12 minutes.

​
Private actions

Withdraw to a public address, transfer to another registered Veil user, or merge small notes. These build a ZK proof locally and submit through the Veil relay. 
veil withdraw USDC 50 0xRecipient
veil transfer USDC 25 0xRecipient   # recipient must be a registered Veil user
veil merge USDC 100

​
Subaccounts

Subaccounts are deterministic child slots derived from your main VEIL_KEY (Base mainnet only): 
root key → slot → child key → child deposit key → forwarder

veil subaccount derive  --slot 0
veil subaccount status  --slot 0
veil subaccount deploy  --slot 0
veil subaccount sweep   --slot 0 --asset eth
veil subaccount merge   --slot 0 --pool eth
veil subaccount recover --slot 0 --asset usdc --to 0xRecipient --amount 25
See Sub Accounts for how these work end to end.

​
x402 payments

The SDK exposes payX402Resource() and helpers for paying standard x402 resources from a private USDC balance. See the dedicated Private x402 Payments page.

​
Environment

The CLI uses two config files: .env.veil holds your Veil keypair (created by veil init); .env holds your wallet config.
  • VEIL_KEY — your Veil private key (ZK proofs, withdrawals, transfers)
  • DEPOSIT_KEY — your Veil deposit key (public; register/deposit)
  • WALLET_KEY — Ethereum wallet private key (signs transactions)
  • SIGNER_ADDRESS — Ethereum address for unsigned/query flows when signing is external
  • RPC_URL — Base RPC URL (optional; defaults to public RPC)
  • RELAY_URL — override the relay base URL
  • X402_RELAY_URL — x402 relay base URL (optional; defaults to RELAY_URL + /x402 or hosted relay /x402)
WALLET_KEY and SIGNER_ADDRESS are mutually exclusive. Use WALLET_KEY for commands that sign transactions, and SIGNER_ADDRESS for address-only agent flows like status, balance, and register --unsigned.

​
Error handling

Errors are standardized JSON with machine-readable codes so scripts can detect failures reliably: 
{
  "success": false,
  "errorCode": "VEIL_KEY_MISSING",
  "error": "VEIL_KEY required. Set VEIL_KEY env"
}
Common codes include VEIL_KEY_MISSING, INVALID_AMOUNT, INSUFFICIENT_BALANCE, USER_NOT_REGISTERED, NO_UTXOS, RELAY_ERROR, RPC_ERROR, and CONTRACT_ERROR.
Full programmatic API reference, browser proof generation, and AI-agent/signer integration notes live in the SDK guide (SDK.md) in the @veil-cash/sdk repo.