MathWallet Agent CLI

中文

A multi-chain Web3 wallet CLI designed for AI agent automation. One BIP39 mnemonic derives keys for EVM (Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, Avalanche, and more), Solana, Bitcoin, TRON, SUI, and TON. Supports CAIP-2 chain identifiers, balance queries with USD values, token transfers, transaction history, offline signing, MathSwap token swap, the x402 HTTP payment protocol, and an A2A (Agent-to-Agent) JSON-RPC server for inter-agent integration.

Requirements

| Dependency | Version | |------------|---------| | Node.js | ≥ 20.0.0 | | pnpm | 8+ recommended |

Installation

# Install from npm
npm install -g @mathwallet/agent-cli

# Or build from source
pnpm install && pnpm build
cd packages/mathwallet-cli && npm link

Initialize Wallet

Run once per machine before any other command:

mathwallet init

Creates ~/.mathwallet/ with:

• .encryption-key — 32-byte machine-bound AES key (permission 0600)
• wallet.enc — BIP39 mnemonic encrypted with AES-256-GCM (0600)

The mnemonic is never shown in the terminal. To migrate to a new machine, copy both wallet.enc and .encryption-key together.

Chain Identifiers (CAIP-2)

--chain accepts three equivalent formats:

| Format | Example | Notes | |--------|---------|-------| | CAIP-2 | eip155:1 | Recommended — unambiguous | | Alias | ethereum | Human-readable shorthand | | Chain ID | 1 | EVM-only numeric form |

Type keywords (evm, solana, bitcoin, tron, sui, ton) match all chains of that type.

Commands

Most commands accept --json to return structured JSON output instead of human-readable text. The format is always:

{ "success": true,  "data": { ... } }
{ "success": false, "error": "Error message" }

Exit code is 1 on error. CAIP-2 identifiers are included where applicable (e.g. "caip2": "eip155:1"). The export command is interactive-only and does not support --json.

status — Check wallet state

mathwallet status
mathwallet status --json

Reports whether wallet.enc and .encryption-key exist. Call this before any wallet operation.

export — Export mnemonic (interactive only)

mathwallet export

Requires interactive TTY and explicit EXPORT confirmation. Not available in --json.

chain — Manage chain configuration

mathwallet chain list                # List all chains (CAIP-2 + alias + type + symbol)
mathwallet chain list --json

# Update RPC endpoint
mathwallet chain rpc --chain eip155:1 --rpc https://mainnet.infura.io/v3/YOUR_KEY
mathwallet chain rpc --chain ethereum  --rpc https://mainnet.infura.io/v3/YOUR_KEY

# Set API key (TON, TRON nodes that require authentication)
mathwallet chain apikey --chain ton --key YOUR_TONCENTER_KEY

# Add a custom EVM chain
mathwallet chain add \
  --name     mychain \
  --chain-id 999 \
  --rpc      https://rpc.mychain.com \
  --symbol   XYZ \
  --type     evm \
  --explorer https://explorer.mychain.com

address — Show wallet addresses

mathwallet address                   # One address per chain type
mathwallet address --chain ethereum  # Single chain
mathwallet address --chain eip155:1  # Same, CAIP-2 format
mathwallet address --json

With --chain, outputs a plain address string — useful in shell scripts:

ADDR=$(mathwallet address --chain ethereum)

balance — Token balances with USD values

Default (no flags): Queries 10 common chains — EVM: ethereum, bsc, base, polygon, arbitrum; non-EVM: bitcoin, solana, sui, ton, tron.

mathwallet balance                                      # Default 10 chains
mathwallet balance --chain ethereum                     # Single chain
mathwallet balance --chain ethereum,base                # Multiple chains
mathwallet balance --chain ethereum --chain base        # Same (repeated flag)
mathwallet balance --chain evm                          # All EVM chains in config
mathwallet balance --all                                # Every configured chain (slow, avoid)
mathwallet balance --chain ethereum --sort-by-value --json
mathwallet balance --refresh                            # Force refresh token list cache

# Query a specific token contract (requires one concrete --chain)
mathwallet balance --chain eip155:1 --token-contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 --json

| Flag | Required | Description | |------|----------|-------------| | --chain | No | One or more chains. Repeatable or comma-separated. Type keyword evm matches all EVM chains | | --all | No | Query every chain in config. Very slow — use --chain instead | | --token-contract | No | Query a specific contract. Requires exactly one concrete --chain | | --sort-by-value | No | Sort output by USD value descending | | --refresh | No | Force re-fetch token list, bypass cache |

When the Assets API is unavailable, falls back to cached token list. If no cache, returns native coin only.

Bitcoin balance includes unconfirmed (mempool) UTXOs — send requires confirmed UTXOs only.

Per-chain failures are non-fatal: errors print to stderr, other chains continue.

send — Send tokens or call contracts

# Always dry-run first to verify the fee
mathwallet send --chain ethereum --to 0xRecipient --token native --amount 0.1 --dry-run

# Send native coin
mathwallet send --chain ethereum --to 0xRecipient --token native --amount 0.1

# Send ERC-20 token (--token is the contract address)
mathwallet send --chain ethereum --to 0xRecipient \
  --token 0xdAC17F958D2ee523a2206206994597C13D831ec7 --amount 100

# Arbitrary contract call with calldata (EVM/TRON only)
mathwallet send --chain ethereum --to 0xContract --data 0x7ff36ab5... --value 0.1 --dry-run

| Flag | Required | Description | |------|----------|-------------| | --chain | Yes | CAIP-2, alias, or chainId | | --to | Yes | Recipient or contract address | | --token | Yes* | native, token symbol, or ERC-20 contract address. Optional when --data is set | | --amount | Yes | Amount in human-readable format (e.g. 0.1, 100). *Optional when --data is set | | --data | No | Hex calldata for contract calls (EVM/TRON only). When set, --token/--amount are optional | | --value | No | Native coin to attach alongside --data (e.g. "0.1" ETH). Default: 0 | | --max-fee | No | Fee cap in native coin units (semantics differ per chain — see note below) | | --dry-run | No | Estimate fee only, do not broadcast |

--max-fee semantics per chain:

• EVM / Bitcoin — hard cap on total fee; transaction aborts if estimated fee exceeds this.
• Solana — sets compute-unit price (priority fee); does not enforce a hard fee cap.
• TRON — sets energy feeLimit in TRX.
• SUI — sets gas budget in SUI (converted to MIST).
• TON — ignored (fee is always ~0.005 TON).

history — Transaction history

mathwallet history --chain ethereum           # Last 20 transactions
mathwallet history --chain eip155:1 --limit 50
mathwallet history --chain solana --token native --json
mathwallet history --chain ethereum --refresh

| Flag | Required | Description | |------|----------|-------------| | --chain | Yes | Specific chain only — cross-chain queries not supported | | --token | No | Filter by native, symbol (e.g. USDT), or contract address | | --limit | No | Number of records, 1–100 (default: 20) | | --refresh | No | Force re-fetch, bypass 5-min cache |

sign — Offline signing (no broadcast)

# EIP-712 structured data (EVM only)
mathwallet sign typed-data \
  --chain eip155:1 \
  --domain  '{"name":"MyApp","version":"1","chainId":1,"verifyingContract":"0x..."}' \
  --types   '{"Transfer":[{"name":"to","type":"address"},{"name":"amount","type":"uint256"}]}' \
  --message '{"to":"0x...","amount":"1000000"}' \
  --json

# Personal sign — EVM returns 0x hex, Solana returns base64
mathwallet sign message --chain ethereum --message "Hello" --json
mathwallet sign message --chain solana   --message "Hello" --json

# Sign raw transaction without broadcasting
mathwallet sign transaction --chain eip155:1 --tx '{"to":"0x...","value":"0x0",...}' --json
mathwallet sign transaction --chain solana   --tx "<base64 unsigned tx>" --json

swap — Token swap via MathSwap

Supports all chains in the MathSwap API. Full execution (swap exec) is EVM chains only. Quote, status, history, and token search work on all chains.

Native coin address: 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee represents the chain's native coin (ETH, BNB, etc.).

# List MathSwap supported chains
mathwallet swap chains --json

# List swappable tokens (with balance if wallet connected, otherwise default list)
mathwallet swap tokens --chain ethereum --json

# Search swappable tokens by symbol or contract address
mathwallet swap tokens --chain ethereum --search USDC --json

# Get a real-time quote
mathwallet swap quote \
  --chain  ethereum \
  --from   0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to     0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 0.1 --json

# Dry-run: all API steps, no tx broadcast
mathwallet swap exec \
  --chain  ethereum \
  --from   0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to     0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 0.1 --dry-run --json

# Execute swap
mathwallet swap exec \
  --chain  ethereum \
  --from   0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to     0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 0.1 --json

# Check an order (e.g. after exec timed out)
mathwallet swap status --chain ethereum --order <order_no> --json

# View swap history
mathwallet swap history --chain ethereum --json

swap exec parameters:

| Flag | Required | Description | |------|----------|-------------| | --chain | Yes | EVM chain (e.g. ethereum, bsc, base) | | --from | Yes | Sell token address (0xeee…eee for native coin) | | --to | Yes | Buy token address | | --amount | Yes | Sell amount in human-readable format (e.g. 0.1, 10) | | --slippage | No | Slippage tolerance in percent (e.g. 0.5). Default: auto | | --max-price-impact | No | Abort if price impact exceeds this percent (e.g. 5). Non-JSON mode warns automatically at >5% | | --dry-run | No | Run all API steps (incl. create_order) but skip all tx broadcasts |

swap exec automatically handles ERC-20 token approval: checks on-chain allowance, broadcasts approve tx if needed, waits for confirmation, then proceeds with the swap.

After broadcast, order status is polled every 3s for up to 60s. If still pending, use swap status to check later.

serve — A2A Agent Server

Start an HTTP server that exposes all wallet capabilities via the A2A (Agent-to-Agent) protocol (JSON-RPC 2.0). Other AI agents can discover and call wallet skills without knowing the CLI commands.

mathwallet serve                                  # Listen on 127.0.0.1:3000
mathwallet serve --port 8080                      # Custom port
mathwallet serve --auth                           # Enable auth (auto-generate token)
mathwallet serve --auth my-secret-token           # Enable auth (explicit token)
mathwallet serve --host 0.0.0.0 --auth            # All interfaces (with auth)
mathwallet serve --cors "http://localhost:5173"    # Allow specific CORS origin

| Flag | Required | Description | |------|----------|-------------| | --port | No | Port to listen on (default: 3000) | | --host | No | Host to bind (default: 127.0.0.1) | | --auth | No | Enable Bearer token authentication. Omit value to auto-generate, or pass an explicit token | | --cors | No | Allowed CORS origins (comma-separated). Default: same-origin only |

Endpoints:

• GET /.well-known/agent.json — Agent Card with 16 skill definitions (public, no auth required)
• POST / — JSON-RPC 2.0: tasks/send, tasks/get, tasks/cancel, tasks/sendSubscribe (SSE)

Example:

# Start server with authentication
mathwallet serve --auth
# stderr: [a2a] auth token: <generated-token>

# Discover skills (no auth needed)
curl http://localhost:3000/.well-known/agent.json | jq '.skills[].id'

# Call a skill (with auth)
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","method":"tasks/send","params":{"id":"t1","message":{"role":"user","parts":[{"type":"data","data":{"skill":"check_balance","params":{"chain":"ethereum"}}}]}},"id":1}'

Security:

• Default binding is 127.0.0.1 (localhost only). A warning is printed when binding to other addresses.
• Use --auth to require Bearer token authentication on all POST requests.
• CORS is restricted to same-origin by default. Use --cors to allow specific origins.
• All sensitive skills (send_token, send_contract, swap_exec, sign_message, sign_typed_data, sign_transaction) use input-required confirmation before execution.
• Rate limiting: 60 requests/minute per IP.

Full A2A skill reference: skills/SKILL.md

x402 — x402 HTTP Payment Protocol

Automatically handle HTTP 402 Payment Required using EIP-3009 off-chain authorization.

mathwallet x402 pay --url "https://api.example.com/protected" --json
mathwallet x402 pay --url "https://api.example.com/data" --chain eip155:8453 --json
mathwallet x402 pay --url "https://api.example.com/data" --method POST --body '{"q":"hello"}' --json

| Flag | Required | Description | |------|----------|-------------| | --url | Yes | Target URL. CLI handles the 402 challenge automatically | | --chain | No | Preferred payment chain. Auto-detected from 402 response if omitted | | --method | No | HTTP method (default: GET) | | --body | No | Request body JSON string (for POST) | | --header | No | Extra headers in Key:Value format. Repeatable |

cache — Manage local cache

mathwallet cache status
mathwallet cache status --json

mathwallet cache clear
mathwallet cache clear --type prices
mathwallet cache clear --type tokens --json

Supported Chains

EVM chains (all share the same 0x… address)

EVM chain list is loaded dynamically from the MathWallet API (24h cache). Run mathwallet chain list for the full up-to-date list.

| CAIP-2 | Alias | Symbol | |--------|-------|--------| | eip155:1 | ethereum | ETH | | eip155:56 | bsc | BNB | | eip155:137 | polygon | POL | | eip155:42161 | arbitrum | ETH | | eip155:10 | optimism | ETH | | eip155:8453 | base | ETH | | eip155:43114 | avalanche | AVAX | | (and many more — run mathwallet chain list) | | |

Non-EVM chains (static)

| CAIP-2 | Alias | Symbol | Address Format | |--------|-------|--------|----------------| | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d | solana | SOL | base58, ~44 chars | | bip122:000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f | bitcoin | BTC | bc1q… bech32 | | tron | tron | TRX | T… base58, 34 chars | | sui | sui | SUI | 0x… 64-char hex | | ton | ton | TON | UQ… base64url |

Troubleshooting

| Error | Fix | |-------|-----| | Wallet not initialized | Run mathwallet init | | Failed to read encryption key | chmod 0600 ~/.mathwallet/.encryption-key, or re-run mathwallet init (existing wallet unrecoverable) | | No confirmed UTXOs available (Bitcoin) | Wait for at least one block confirmation after funding | | bigint: Failed to load bindings on startup | Non-fatal warning from a native dependency, safe to ignore |

Security

• Machine-bound encryption — .encryption-key is tied to this machine. Copy both wallet.enc + .encryption-key to migrate.
• Private keys never touch disk — derived in memory per command, discarded immediately after use.
• File permissions — ~/.mathwallet/ is 0700; all wallet files are 0600.
• No password required — designed for AI agent automation with no interactive prompts.
• Always dry-run first — verify estimated fee with --dry-run before broadcasting any transaction.