> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veil.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK & CLI

> Integrate Veil programmatically with @veil-cash/sdk and the veil CLI

[`@veil-cash/sdk`](https://www.npmjs.com/package/@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

```bash theme={null}
npm install @veil-cash/sdk
# or: yarn add @veil-cash/sdk / pnpm add @veil-cash/sdk
```

For global CLI access:

```bash theme={null}
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

```bash theme={null}
# 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
```

<Info>
  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).
</Info>

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

```bash theme={null}
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](/intro/verified-users) path—see [0xbow Screening](/intro/verified-users/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](/veil-cash-pools/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](/intro/verified-users/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.

```bash theme={null}
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):

```text theme={null}
root key → slot → child key → child deposit key → forwarder
```

```bash theme={null}
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](/technical/subaccounts) 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](/build-with-veil/private-x402) 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`)

<Warning>
  `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`.
</Warning>

## Error handling

Errors are standardized JSON with machine-readable codes so scripts can detect failures reliably:

```json theme={null}
{
  "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`.

<Note>
  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](https://github.com/veildotcash/veildotcash-sdk).
</Note>