ZOA Wallet CLI

API-First Crypto Wallet for Developers & AI Agents

ZOA is a multi-chain crypto wallet designed for programmatic access. Manage wallets, check balances, send tokens, and more — all from your terminal or scripts.

Install

# Install globally
npm install -g zoa-wallet

# Or use directly with npx
npx zoa-wallet

# Or with pnpm
pnpm add -g zoa-wallet

# Or with yarn
yarn global add zoa-wallet

Quick Start

# Create a new wallet
zoa wallet create --password mypassword

# Check balances across all chains
zoa balance --password mypassword

# Send ETH on Base
zoa send --chain base --to 0x1234...abcd --amount 0.01 --password mypassword --yes

# Show receive addresses with QR codes
zoa receive --password mypassword

# View supported networks
zoa chains

# Check live token prices
zoa prices

# Link wallet to Agenteur (or other apps)
zoa link agenteur <YOUR_API_KEY>

Command Reference

wallet — Manage Wallets

# Create a new wallet
zoa wallet create [--label <name>] [--color <hex>] [--password <pw>] [--word-count 12|24]

# Import from recovery phrase
zoa wallet import [--label <name>] [--mnemonic "phrase ..."] [--password <pw>]

# List all wallets
zoa wallet list [--password <pw>]

# Switch active wallet
zoa wallet switch [id-or-label]

# Rename a wallet
zoa wallet rename <id> <new-label>

# Change wallet color
zoa wallet color <id> <hex>

# Remove a wallet
zoa wallet remove <id> [--yes]

# Show active wallet details
zoa wallet info [--password <pw>]

balance — Check Balances

zoa balance [--password <pw>] [--chain <chain>]

| Flag | Description | |------|-------------| | --password <pw> | Wallet password (skip prompt) | | --chain <chain> | Filter to a specific chain (base, ethereum, solana, etc.) |

send — Send Tokens

Interactive:

zoa send

One-liner:

zoa send --chain base --to 0x... --amount 0.01 --password pw --yes

| Flag | Description | |------|-------------| | --password <pw> | Wallet password | | --to <address> | Recipient address | | --amount <amount> | Amount to send | | --chain <chain> | Network (base, ethereum, arbitrum, optimism, bsc, solana) | | --token <symbol> | Token symbol (e.g. USDT, USDC). Defaults to native currency | | --max | Send maximum available balance (auto-deducts gas for native transfers) | | --batch <transfers> | Batch send: comma-separated address:amount[:token[:chain]] | | --yes | Skip confirmation prompt |

receive — Show Addresses & QR Codes

zoa receive [--password <pw>] [--chain <chain>]

history — Transaction History

zoa history [--password <pw>] [--chain <chain>] [--limit <n>]

export — Export Keys

# Export private key
zoa export --password pw --type key --chain evm

# Export recovery phrase
zoa export --password pw --type mnemonic

| Flag | Description | |------|-------------| | --password <pw> | Wallet password | | --type <type> | key or mnemonic | | --chain <chain> | evm or solana (for --type key) |

chains — List Supported Networks

zoa chains

prices — Token Prices

# Default price table
zoa prices

# Search for a specific token
zoa prices search bitcoin

# Browse popular tokens interactively
zoa prices browse

# Specify tokens
zoa prices list --tokens "ethereum,solana,bitcoin"

api — Manage API Keys

# Set API key
zoa api set <key>

# Show current key
zoa api show

# Remove key
zoa api remove

link — Link Wallet to External Apps

Connect your ZOA wallet to external apps like Agenteur using EIP-191 signed proof of ownership.

# Link to Agenteur — pass API key directly
zoa link agenteur ak_your_key_here

# Interactive (prompts for API key and password)
zoa link agenteur

# Fully non-interactive
zoa link agenteur ak_your_key_here --password mypassword

# Or with --api-key flag
zoa link agenteur --api-key ak_your_key_here --password mypassword

| Argument / Flag | Description | |------|-------------| | <app> | App name to link to (currently: agenteur) | | [api-key] | API key as a positional argument (simplest) | | --api-key <key> | API key via flag (alternative) | | --password <pw> | Wallet password (skip prompt) |

How it works:

1. Signs a structured message with your EVM key (EIP-191)
2. Sends your wallet addresses + cryptographic proof to the app's API
3. The app verifies the signature on-chain — no shared secrets needed
4. Stores the link in ~/.zoa/config.json for future reference

Web flow alternative: You can also link via the ZOA web app at wallet.zoa.fun/link?app=agenteur — paste your app's Link Code and approve.

config — Configuration

# Show config
zoa config show

# Set a value
zoa config set <key> <value>

One-Liner Reference

| Task | Command | |------|---------| | Send ETH on Base | zoa send --chain base --to 0x... --amount 0.01 --password pw --yes | | Send USDC on Ethereum | zoa send --chain ethereum --token USDC --to 0x... --amount 100 --password pw --yes | | Send max ETH | zoa send --chain base --to 0x... --max --password pw --yes | | Send SOL on Solana | zoa send --chain solana --to ABC... --amount 1.5 --password pw --yes | | Check balance (Base only) | zoa balance --chain base --password pw | | Export EVM private key | zoa export --type key --chain evm --password pw | | Link to Agenteur | zoa link agenteur ak_... --password pw | | Get JSON balances | zoa --json balance --password pw | | Get JSON prices | zoa --json prices --tokens "ethereum,solana" |

Batch Send

Send to multiple recipients, tokens, and chains in a single command.

Format: address:amount[:token[:chain]]

• token defaults to the native currency (ETH, SOL, BNB, etc.)
• chain defaults to the --chain flag value, or base if not specified

Examples

# Same chain, same token, multiple recipients
zoa send --chain base --batch "0xAAA...111:0.01,0xBBB...222:0.02,0xCCC...333:0.03" --password pw --yes

# Multiple tokens on the same chain
zoa send --chain ethereum --batch "0xAAA...111:100:USDC,0xBBB...222:50:USDT,0xCCC...333:0.1" --password pw --yes

# Multiple chains and tokens in one command
zoa send --batch "0xAAA...111:100:USDC:ethereum,4Jyn...abc:0.5:SOL:solana,0xBBB...222:50:USDT:base" --password pw --yes

Batch Output

• Each transfer executes sequentially with progress indicators
• Failed transfers do not stop remaining transfers
• A summary is shown at the end with success/failure counts
• JSON mode returns an array of results

JSON Mode for AI Agents

Every command supports --json for machine-readable output. Place the flag before the command name.

zoa --json <command> [options]

Example Outputs

Create wallet:

zoa --json wallet create --password "securepass"

{
  "address": "0x1234...abcd",
  "solanaAddress": "ABC...xyz",
  "label": "Wallet 1"
}

Get balances:

zoa --json balance --password pw

{
  "balances": [
    { "chain": "Base", "token": "ETH", "balance": "0.0542", "usd": "170.21" },
    { "chain": "Base", "token": "USDC", "balance": "100.0", "usd": "100.00" }
  ]
}

Send tokens:

zoa --json send --chain base --to 0x... --amount 0.01 --password pw --yes

{
  "status": "sent",
  "hash": "0xabc...def",
  "from": "0x1234...abcd",
  "to": "0x5678...efgh",
  "token": "ETH",
  "amount": "0.01",
  "chain": "Base",
  "explorerUrl": "https://basescan.org/tx/0xabc...def"
}

Batch send:

zoa --json send --batch "0xA:0.01,0xB:0.02" --chain base --password pw --yes

{
  "batch": true,
  "results": [
    { "to": "0xA...", "amount": "0.01", "token": "ETH", "chain": "Base", "status": "sent", "hash": "0x..." },
    { "to": "0xB...", "amount": "0.02", "token": "ETH", "chain": "Base", "status": "sent", "hash": "0x..." }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
}

Link wallet:

zoa --json link agenteur ak_your_key --password pw

{
  "app": "agenteur",
  "signer": "0x742d...abcd",
  "addresses": {
    "ethereum": "0x742d...abcd",
    "base": "0x742d...abcd",
    "polygon": "0x742d...abcd",
    "arbitrum": "0x742d...abcd",
    "optimism": "0x742d...abcd",
    "avalanche": "0x742d...abcd"
  },
  "linkedAt": 1709472000000
}

Get chains:

zoa --json chains

{
  "chains": [
    { "name": "Ethereum", "symbol": "ETH", "chainId": 1 },
    { "name": "Base", "symbol": "ETH", "chainId": 8453 },
    { "name": "Solana", "symbol": "SOL", "chainId": -1 }
  ]
}

Get prices:

zoa --json prices --tokens "ethereum,solana"

{
  "prices": [
    { "id": "ethereum", "symbol": "ETH", "price": 3245.67, "change24h": 2.34 },
    { "id": "solana", "symbol": "SOL", "price": 142.89, "change24h": -1.12 }
  ]
}

API Reference

The ZOA backend API provides programmatic access. All /v1 endpoints require an API key in the Authorization header.

Authentication

# Set your API key
zoa api set zoa_sk_your_key_here

# Use with curl
curl -H "Authorization: Bearer zoa_sk_your_key_here" https://api.zoa.fun/v1/chains

Endpoints

GET /v1/chains

List all supported blockchain networks.

curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/chains

{
  "data": {
    "chains": [
      { "id": 1, "name": "Ethereum", "symbol": "ETH", "type": "evm" },
      { "id": 8453, "name": "Base", "symbol": "ETH", "type": "evm" },
      { "id": 56, "name": "BNB Smart Chain", "symbol": "BNB", "type": "evm" },
      { "id": 42161, "name": "Arbitrum One", "symbol": "ETH", "type": "evm" },
      { "id": 10, "name": "Optimism", "symbol": "ETH", "type": "evm" },
      { "id": 0, "name": "Solana", "symbol": "SOL", "type": "non-evm" }
    ]
  }
}

POST /v1/wallets

Create a managed wallet. Requires write permission.

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Trading Bot"}' \
  https://api.zoa.fun/v1/wallets

GET /v1/wallets

List all wallets associated with your API key.

curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/wallets

GET /v1/wallets/{id}

Get a specific wallet by UUID.

curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/wallets/{id}

GET /v1/balances/{address}

Get token balances for an address. Optionally filter by chain.

curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/balances/0x1234...?chain=8453"

GET /v1/balances/{address}/all

Get balances across all supported chains.

curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/balances/0x1234.../all

POST /v1/transfer

Create a transfer. Requires write permission.

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_wallet_id": "uuid",
    "to_address": "0x...",
    "chain_id": 8453,
    "amount": "0.01",
    "token_address": null,
    "priority": "standard"
  }' \
  https://api.zoa.fun/v1/transfer

GET /v1/transactions/{address}

Get transaction history for an address.

curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/transactions/0x1234...?chain=8453&limit=10&offset=0"

GET /v1/transactions/hash/{hash}

Get a specific transaction by hash.

curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/transactions/hash/0xabc...?chain=8453"

GET /v1/prices

Get cached token prices.

curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/prices?tokens=ethereum,solana,bitcoin"

GET /v1/prices/{token_id}

Get price for a single token.

curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/prices/ethereum

GET /v1/gas/{chain_id}

Get gas estimates (slow/standard/fast) for a chain.

curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/gas/8453

{
  "data": {
    "chain_id": 8453,
    "slow": { "gwei": "0.001", "estimated_seconds": 30 },
    "standard": { "gwei": "0.002", "estimated_seconds": 15 },
    "fast": { "gwei": "0.005", "estimated_seconds": 5 }
  }
}

Key Management

# Create API key (requires admin permission)
curl -X POST -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Bot", "permissions": ["read", "write"], "rate_limit_per_min": 60}' \
  https://api.zoa.fun/v1/keys

# List API keys
curl -H "Authorization: Bearer $ADMIN_KEY" https://api.zoa.fun/v1/keys

# Revoke an API key
curl -X DELETE -H "Authorization: Bearer $ADMIN_KEY" https://api.zoa.fun/v1/keys/{id}

Supported Networks

| Network | Symbol | Chain ID | Type | Explorer | |---------|--------|----------|------|----------| | Ethereum | ETH | 1 | EVM | etherscan.io | | Base | ETH | 8453 | EVM | basescan.org | | BNB Smart Chain | BNB | 56 | EVM | bscscan.com | | Arbitrum One | ETH | 42161 | EVM | arbiscan.io | | Optimism | ETH | 10 | EVM | optimistic.etherscan.io | | Solana | SOL | — | Non-EVM | solscan.io | | Hyperliquid | HYPE | 999 | Non-EVM | — |

Known ERC-20 Tokens

Automatically detected in balance checks and available in the send token picker:

| Token | Ethereum | Base | Arbitrum | Optimism | BSC | |-------|----------|------|----------|----------|-----| | USDT | Yes | — | Yes | Yes | Yes | | USDC | Yes | Yes | Yes | Yes | Yes | | DAI | Yes | Yes | Yes | Yes | Yes | | WBTC | Yes | — | Yes | Yes | Yes | | LINK | Yes | — | — | — | — | | UNI | Yes | — | — | — | — | | WETH | — | Yes | — | — | — |

Security

• Encryption: Wallet data is encrypted with AES-256-GCM using PBKDF2 (600k iterations) key derivation
• Key isolation: Private keys are held in memory only during the active session
• Local storage: Vault is stored locally at ~/.zoa/vault.json — no cloud sync
• No telemetry: No data is sent to any server unless you explicitly use API features
• API keys: Scoped permissions (read/write/admin) with optional expiry and rate limits

Configuration

ZOA stores data in ~/.zoa/:

| File | Description | |------|-------------| | vault.json | Encrypted wallet data | | config.json | User preferences and settings | | wallets.json | Wallet metadata (labels, colors, active wallet) |

# View config
zoa config show

# Set default chain
zoa config set defaultChain base

# Set API URL
zoa config set apiUrl https://api.zoa.fun

# Set API key
zoa api set zoa_sk_your_key_here

License

MIT