Veil

Veil

This skill wraps the @veil-cash/sdk CLI to make Veil operations agent-friendly.

Supported Assets

What it does

• Key management: generate and store a Veil keypair locally
• Status check: verify configuration, registration, and relay health
• Balances: veil balance (queue + private) — supports --pool eth|usdc
• Deposits via Bankr: build Bankr-compatible unsigned transactions and ask Bankr to sign & submit (handles ERC20 approve + deposit for USDC)
• Private actions: withdraw, transfer, merge for ETH or USDC — executed locally using VEIL_KEY (ZK/proof flow)

File locations (recommended)

• Veil keys: ~/.clawdbot/skills/veil/.env.veil (chmod 600)
• Bankr API key: ~/.clawdbot/skills/bankr/config.json

Quick start

1) Install the Veil SDK

Option A: Global npm install (recommended)

npm install -g @veil-cash/sdk

Option B: Clone from GitHub

mkdir -p ~/.openclaw/workspace/repos
cd ~/.openclaw/workspace/repos
git clone https://github.com/veildotcash/veildotcash-sdk.git
cd veildotcash-sdk
npm ci && npm run build

2) Configure Base RPC (recommended)

Veil queries a lot of blockchain data (UTXOs, merkle proofs, etc.), so public RPCs will likely hit rate limits. A dedicated RPC from Alchemy, Infura, or similar is recommended.

Put RPC_URL=... in one of these:

• ~/.clawdbot/skills/veil/.env (preferred)
• or the SDK repo .env (less ideal)

Example:

mkdir -p ~/.clawdbot/skills/veil
cat > ~/.clawdbot/skills/veil/.env << 'EOF'
RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
EOF
chmod 600 ~/.clawdbot/skills/veil/.env

3) Make scripts executable

chmod +x scripts/*.sh

4) Generate your Veil keypair

scripts/veil-init.sh
scripts/veil-keypair.sh

5) Check your setup

scripts/veil-status.sh

6) Find your Bankr Base address

scripts/veil-bankr-prompt.sh "What is my Base wallet address? Respond with just the address."

7) Check balances

# ETH pool (default)
scripts/veil-balance.sh --address 0xYOUR_BANKR_ADDRESS

# USDC pool
scripts/veil-balance.sh --address 0xYOUR_BANKR_ADDRESS --pool usdc

8) Deposit via Bankr (sign & submit)

# Deposit ETH
scripts/veil-deposit-via-bankr.sh ETH 0.011 --address 0xYOUR_BANKR_ADDRESS

# Deposit USDC (auto-handles approve + deposit)
scripts/veil-deposit-via-bankr.sh USDC 100 --address 0xYOUR_BANKR_ADDRESS

9) Withdraw (private to public)

scripts/veil-withdraw.sh ETH 0.007 0xYOUR_BANKR_ADDRESS
scripts/veil-withdraw.sh USDC 50 0xRECIPIENT

10) Transfer privately

scripts/veil-transfer.sh ETH 0.01 0xRECIPIENT
scripts/veil-transfer.sh USDC 25 0xRECIPIENT

11) Merge UTXOs

scripts/veil-merge.sh ETH 0.1
scripts/veil-merge.sh USDC 100

References

• SDK Reference — CLI commands, environment variables, error codes
• Troubleshooting — Common issues and debugging tips

Notes

• For Bankr signing, this skill uses Bankr's Agent API via your local ~/.clawdbot/skills/bankr/config.json.
• For USDC deposits via Bankr, the skill automatically submits the ERC20 approval transaction first, then the deposit transaction.
• For privacy safety: never commit .env.veil or .env files to git.

Veil skill

Wraps the @veil-cash/sdk CLI and optionally uses Bankr Agent API to sign & submit unsigned deposit/register transactions. Supports ETH and USDC privacy pools on Base.

Assumptions

• Veil SDK is installed via one of these methods:

Option A: Global npm install (recommended)

  npm install -g @veil-cash/sdk

This makes the veil CLI available globally.

Option B: Clone from GitHub

  mkdir -p ~/.openclaw/workspace/repos
  cd ~/.openclaw/workspace/repos
  git clone https://github.com/veildotcash/veildotcash-sdk.git
  cd veildotcash-sdk
  npm ci && npm run build

• Bankr skill is configured:
• ~/.clawdbot/skills/bankr/config.json

• Veil secrets are stored outside git:
• ~/.clawdbot/skills/veil/.env.veil (chmod 600)
• ~/.clawdbot/skills/veil/.env for RPC_URL (recommended — Veil queries a lot of blockchain data, so public RPCs will likely hit rate limits)

Usage

cd veil

# Generate keypair
scripts/veil-init.sh

# Print keypair JSON
scripts/veil-keypair.sh

# Ask Bankr for address
scripts/veil-bankr-prompt.sh "What is my Base wallet address? Respond with just the address."

# Check balances (ETH pool — default)
scripts/veil-balance.sh --address 0x...

# Check balances (USDC pool)
scripts/veil-balance.sh --address 0x... --pool usdc

# Deposit via Bankr — ETH (build unsigned tx + submit)
scripts/veil-deposit-via-bankr.sh ETH 0.011 --address 0x...

# Deposit via Bankr — USDC (auto-handles approve + deposit)
scripts/veil-deposit-via-bankr.sh USDC 100 --address 0x...

# Withdraw / transfer / merge (local VEIL_KEY required)
scripts/veil-withdraw.sh ETH 0.007 0x...
scripts/veil-withdraw.sh USDC 50 0x...
scripts/veil-transfer.sh ETH 0.001 0x...
scripts/veil-transfer.sh USDC 25 0x...
scripts/veil-merge.sh ETH 0.001
scripts/veil-merge.sh USDC 100

Notes

• veil-bankr-prompt.sh implements the same submit/poll loop as the Bankr skill, but localized here so this skill is self-contained.
• For USDC deposits via Bankr, veil-deposit-via-bankr.sh automatically submits the ERC20 approval transaction first, then the deposit transaction.
• All action scripts take asset as the first argument: ETH or USDC.

Veil SDK Reference

Full documentation: https://github.com/veildotcash/veildotcash-sdk

Installation

npm install -g @veil-cash/sdk
# or local: npm install @veil-cash/sdk  (yarn/pnpm equivalent)

Supported Assets

CLI Commands

veil init

Generate a new Veil keypair.

# Recommended for Bankr: derive from a pre-computed EIP-191 signature
veil init --json --signature 0x...

# Derive from wallet key (same keypair as frontend login)
veil init --json --sign-message --wallet-key 0x...

# Random keypair (no wallet derivation)
veil init --json

# Other options
veil init                                  # Interactive, saves to .env.veil
veil init --force                          # Overwrite existing without prompting
veil init --no-save                        # Print keypair without saving

JSON output:

{
  "veilKey": "0x...",
  "veilPrivateKey": "0x...",
  "depositKey": "0x...",
  "derivation": "provided-signature"
}

derivation can be: "wallet-signature", "provided-signature", or "random".

Note on key field names: veilKey and veilPrivateKey are the same value (the Veil private key). Both are included for backward compatibility; veil keypair uses veilPrivateKey. Scripts should prefer veilPrivateKey with a fallback: .veilPrivateKey // .veilKey.

veil keypair

Show current Veil keypair as JSON (from VEIL_KEY env).

veil keypair
# {"veilPrivateKey":"0x...","depositKey":"0x..."}

veil status

Check configuration and service status.

veil status

Output:

{
  "walletKey": { "found": true, "address": "0x..." },
  "veilKey": { "found": true },
  "depositKey": { "found": true, "key": "0x1234...abcd" },
  "rpcUrl": { "found": false, "url": "https://mainnet.base.org" },
  "registration": {
    "checked": true,
    "registered": true,
    "matches": true,
    "onChainKey": "0x..."
  },
  "relay": {
    "checked": true,
    "healthy": true,
    "status": "ok",
    "network": "mainnet"
  }
}

veil register

Register or update your deposit key on-chain.

veil register                              # Register (first time)
veil register --json                       # JSON output
veil register --unsigned --address 0x...   # Unsigned payload for agents

# Change deposit key (if already registered with a different key)
veil register --force                      # Change to local deposit key
veil register --force --unsigned           # Unsigned change payload for agents

If already registered with the same key, the command exits successfully. If registered with a different key (e.g. after veil init --sign-message), use --force to update it on-chain.

veil deposit <asset> <amount>

Deposit ETH or USDC into the privacy pool. For USDC, the CLI automatically handles ERC20 approval before depositing.

veil deposit ETH 0.1                    # Deposit ETH
veil deposit USDC 100                   # Approve + deposit USDC
veil deposit ETH 0.1 --unsigned         # Unsigned payload for agents
veil deposit USDC 100 --unsigned        # Unsigned: outputs [approve, deposit] array
veil deposit ETH 0.1 --quiet            # Suppress progress output

Output (signed mode):

{
  "success": true,
  "hash": "0x...",
  "asset": "ETH",
  "amount": "0.1",
  "blockNumber": "12345678",
  "gasUsed": "150000"
}

Output (--unsigned, ETH — single object):

{
  "step": "deposit",
  "to": "0x...",
  "data": "0x...",
  "value": "100000000000000000",
  "chainId": 8453
}

Output (--unsigned, USDC — array):

[
  {
    "step": "approve",
    "to": "0x...",
    "data": "0x...",
    "value": "0",
    "chainId": 8453
  },
  {
    "step": "deposit",
    "to": "0x...",
    "data": "0x...",
    "value": "0",
    "chainId": 8453
  }
]

veil balance

Show both queue and private balances.

veil balance                        # All pools (default)
veil balance --pool eth             # ETH pool only
veil balance --pool usdc            # USDC pool only
veil balance --quiet                # Suppress progress output

Output:

{
  "address": "0x...",
  "pool": "ETH",
  "symbol": "ETH",
  "depositKey": "0x...",
  "totalBalance": "0.15",
  "totalBalanceWei": "150000000000000000",
  "private": {
    "balance": "0.10",
    "balanceWei": "100000000000000000",
    "utxoCount": 2,
    "utxos": [
      { "index": 5, "amount": "0.05" },
      { "index": 8, "amount": "0.05" }
    ]
  },
  "queue": {
    "balance": "0.05",
    "balanceWei": "50000000000000000",
    "count": 1,
    "deposits": [
      { "nonce": 42, "amount": "0.05", "status": "pending" }
    ]
  }
}

veil withdraw <asset> <amount> <recipient>

Withdraw from the privacy pool to any public address.

veil withdraw ETH 0.05 0xRecipientAddress
veil withdraw USDC 50 0xRecipientAddress
veil withdraw ETH 0.05 0xRecipientAddress --quiet

Output:

{
  "success": true,
  "transactionHash": "0x...",
  "blockNumber": 12345678,
  "asset": "ETH",
  "amount": "0.05",
  "recipient": "0x..."
}

veil transfer <asset> <amount> <recipient>

Transfer privately to another registered Veil user.

veil transfer ETH 0.02 0xRecipientAddress
veil transfer USDC 25 0xRecipientAddress
veil transfer ETH 0.02 0xRecipientAddress --quiet

Output:

{
  "success": true,
  "transactionHash": "0x...",
  "blockNumber": 12345678,
  "asset": "ETH",
  "amount": "0.02",
  "recipient": "0x...",
  "type": "transfer"
}

veil merge <asset> <amount>

Consolidate multiple small UTXOs into one (self-transfer).

veil merge ETH 0.1
veil merge USDC 100
veil merge ETH 0.1 --quiet

Output:

{
  "success": true,
  "transactionHash": "0x...",
  "blockNumber": 12345678,
  "asset": "ETH",
  "amount": "0.1",
  "type": "merge"
}

Environment Variables

The CLI uses two config files:

Error Handling

Commands that fail output JSON with standardized error codes:

{
  "success": false,
  "errorCode": "VEIL_KEY_MISSING",
  "error": "VEIL_KEY required. Use --veil-key or set VEIL_KEY env"
}

Error Codes

For AI Agents

All commands output JSON and support non-interactive usage.

Key initialization (recommended: Bankr signature flow)

# 1. Get a personal_sign signature from Bankr's /agent/sign endpoint
#    (sign the VEIL_SIGNED_MESSAGE constant)

# 2. Derive keypair from that signature
veil init --json --signature 0x<BANKR_SIGNATURE>
# Returns: { "veilKey": "0x...", "veilPrivateKey": "0x...", "depositKey": "0x...", "derivation": "provided-signature" }

# Fallback: random keypair (no wallet derivation)
veil init --json

Parse the private key defensively: .veilPrivateKey // .veilKey

Unsigned transaction payloads

veil register --unsigned --address 0x...
veil deposit ETH 0.1 --unsigned
veil deposit USDC 100 --unsigned    # Outputs [approve, deposit] array

Use --unsigned to get Bankr-compatible transaction payloads:

veil deposit ETH 0.1 --unsigned
# {"step":"deposit","to":"0x...","data":"0x...","value":"100000000000000000","chainId":8453}

veil deposit USDC 100 --unsigned
# [{"step":"approve","to":"0x...","data":"0x...","value":"0","chainId":8453},{"step":"deposit","to":"0x...","data":"0x...","value":"0","chainId":8453}]

Querying

veil balance --quiet
veil balance --pool usdc --quiet
veil withdraw ETH 0.05 0xRecipient --quiet

Use --quiet to suppress progress output for clean JSON parsing.

Troubleshooting

Common Issues

RPC Rate Limits

Symptom: Requests failing, slow responses, or "rate limit exceeded" errors.

Cause: Veil queries a lot of blockchain data (UTXOs, merkle proofs, deposit queues). Public RPCs have strict rate limits.

Solution: Use a dedicated RPC from Alchemy, Infura, or similar:

mkdir -p ~/.clawdbot/skills/veil
echo "RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY" > ~/.clawdbot/skills/veil/.env
chmod 600 ~/.clawdbot/skills/veil/.env

VEIL_KEY_MISSING

Symptom: Error VEIL_KEY required

Solution: Run veil init to generate a keypair, or ensure your .env.veil file exists:

scripts/veil-init.sh

USER_NOT_REGISTERED

Symptom: Transfer fails with "recipient not registered"

Cause: The recipient address hasn't registered their deposit key with Veil.

Solution: The recipient must run veil register before they can receive private transfers.

NO_UTXOS

Symptom: Withdraw/transfer fails with "no UTXOs available"

Cause: Your deposits are still in the queue (pending) and haven't been processed into the privacy pool yet.

Solution: Wait for the Veil deposit engine to process your deposits. Check status with:

scripts/veil-balance.sh --address 0xYOUR_ADDRESS
scripts/veil-balance.sh --address 0xYOUR_ADDRESS --pool usdc

Look at the queue vs private balances in the output.

INSUFFICIENT_BALANCE

Symptom: Transaction fails due to insufficient balance

Solution: Check your balances and ensure you have enough in the private pool (not just the queue):

scripts/veil-balance.sh --address 0xYOUR_ADDRESS
scripts/veil-balance.sh --address 0xYOUR_ADDRESS --pool usdc

ERC20 Approval Failures (USDC)

Symptom: USDC deposit fails at the approval step.

Cause: The wallet may not have enough USDC balance, or there may be an existing allowance conflict.

Solution: 1. Verify you have sufficient token balance in your Bankr wallet. 2. If depositing via Bankr, the veil-deposit-via-bankr.sh script automatically sends the approval transaction first. Ensure the first (approve) transaction completes before the second (deposit) is submitted. 3. If using --unsigned directly, note that USDC returns a JSON array of two transactions — submit the step: "approve" tx first, wait for confirmation, then submit the step: "deposit" tx.

Wrong Pool / Asset Mismatch

Symptom: Balance shows zero but you know you deposited.

Cause: You may be checking the wrong pool. ETH deposits go to the ETH pool, USDC to the USDC pool, etc.

Solution: Specify the correct pool:

scripts/veil-balance.sh --address 0xYOUR_ADDRESS --pool usdc

Bankr API Errors

Symptom: apiKey missing or authentication errors

Solution: Ensure Bankr is configured:

cat ~/.clawdbot/skills/bankr/config.json
# Should contain: {"apiKey": "bk_...", "apiUrl": "https://api.bankr.bot"}

Scripts Not Executable

Symptom: Permission denied when running scripts

Solution:

chmod +x scripts/*.sh

Debugging Tips

1. Check balances first — Most issues stem from funds being in queue vs private pool 2. Check the right pool — Use --pool usdc to check USDC balances 3. Use `--quiet` flag — Suppresses progress output for cleaner JSON parsing 4. Check Bankr job status — If a deposit via Bankr hangs, the job ID is printed for manual status checks 5. Verify RPC connectivity — curl -s YOUR_RPC_URL -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' 6. ERC20 deposits need two txs — For USDC, ensure the approval tx confirms before the deposit tx is submitted

Getting Help

• Veil SDK: https://github.com/veildotcash/veildotcash-sdk
• Bankr: https://bankr.bot