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

For global CLI access:
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

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.
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.

​
Subaccounts

Subaccounts are deterministic child slots derived from your main VEIL_KEY (Base mainnet only):
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:
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.