agent-wallet-cli

A CLI wallet for Ethereum and Solana. All commands return JSON with --format json. Always check "ok": true before proceeding.

Always invoke via npx to ensure the CLI is available without requiring a global install:

npx agent-wallet-cli <command> [options]

Create a Wallet

If no wallet exists yet, generate a strong random password and create a wallet:

npx agent-wallet-cli init --password "<generated-password>" --format json

After creating the wallet you MUST:

1. Store the password in a .env file (e.g. WALLET_PASSWORD=...) or another project-local secret store so you can use it for future unlock commands. Never hard-code it in source files.
2. Read the mnemonic_file from the response and present the mnemonic to the user.
3. Instruct the user to back up the mnemonic in a safe, offline location (e.g. written on paper, stored in a password manager).
4. Make clear that this mnemonic is the ONLY way to recover the wallet. It cannot be recovered by anyone — not by the CLI, not by any service, not by the developer. If it is lost, the funds are gone forever.
5. After the user confirms they have saved it, delete the mnemonic file.

Options: --word-count 12 (default) or --word-count 24 for a longer phrase.

Unlock

The wallet must be unlocked before use. Unlock creates a time-limited session token:

npx agent-wallet-cli unlock --password "$WALLET_PASSWORD" --format json

Response:

{ "ok": true, "token": "wlt_...", "expires_at": "..." }

Save the token value. Pass it to all subsequent commands with --token <token>, or set the environment variable:

export AGENT_WALLET_CLI_TOKEN="wlt_..."

Check Balance

Native balance:

npx agent-wallet-cli balance --token <token> --chain ethereum --network mainnet --format json

ERC-20 / SPL token balance (use alias or contract address):

npx agent-wallet-cli balance --token <token> --chain ethereum --network base --token-address usdc --format json

Send Funds

Native transfer:

npx agent-wallet-cli send --token <token> --chain ethereum --to <address> --amount <amount> --yes --format json

Token transfer:

npx agent-wallet-cli send --token <token> --chain ethereum --token-address usdc --to <address> --amount <amount> --yes --format json

Use --dry-run to simulate without sending. Always use --dry-run first when uncertain about amounts.

Gasless Relay

Token transfers on EVM chains automatically use a gasless relay when the wallet has no native tokens (ETH/MATIC) for gas. The relay fee (e.g. 0.01 USDC) is deducted from the token amount. Check the response for:

• "relay_used": true — relay was used
• "relay_fee" — fee deducted
• "amount_received" — net amount sent after fee

To disable the relay for a specific transfer, add --no-relay.

Show Addresses

Show all wallet addresses (Ethereum + Solana):

npx agent-wallet-cli address --token <token> --format json

Show a specific chain:

npx agent-wallet-cli address --token <token> --chain ethereum --format json

Sign Messages

Plain text message:

npx agent-wallet-cli sign --token <token> --chain ethereum --message "Hello World" --format json

EIP-712 typed data (JSON string or file path with @ prefix):

npx agent-wallet-cli sign --token <token> --chain ethereum --typed-data '{"types":...}' --format json
npx agent-wallet-cli sign --token <token> --chain ethereum --typed-data @typed-data.json --format json

Raw bytes (hex):

npx agent-wallet-cli sign --token <token> --chain ethereum --data 0xdeadbeef --format json

ERC-20 Approve & Allowance

Approve a spender:

npx agent-wallet-cli approve --token <token> --chain ethereum --token-address usdc --spender <address> --amount <amount> --yes --format json

Check allowance (no session token needed):

npx agent-wallet-cli allowance --chain ethereum --token-address usdc --owner <address> --spender <address> --format json

Delegated transfer (transferFrom):

npx agent-wallet-cli transfer-from --token <token> --chain ethereum --token-address usdc --from <owner> --to <recipient> --amount <amount> --yes --format json

x402 Payments (HTTP 402)

Make HTTP requests to x402-enabled endpoints with automatic stablecoin payment. When the server returns 402 Payment Required, the wallet signs an EIP-3009 TransferWithAuthorization and retries the request with the payment header.

Preview payment requirements (no payment):

npx agent-wallet-cli x402 https://example.com/api/paid-resource --token <token> --dry-run --format json

Make a paid request (auto-confirm):

npx agent-wallet-cli x402 https://example.com/api/paid-resource --token <token> --yes --format json

With a maximum payment cap:

npx agent-wallet-cli x402 https://example.com/api/paid-resource --token <token> --yes --max-amount 0.10 --format json

POST request with custom headers and body:

npx agent-wallet-cli x402 https://example.com/api/paid-resource --token <token> --method POST --header "Content-Type:application/json" --body '{"query":"data"}' --yes --format json

Read body from a file:

npx agent-wallet-cli x402 https://example.com/api/paid-resource --token <token> --method POST --body @request.json --yes --format json

Options:

• --method <method> — HTTP method (default: GET)
• --header <header...> — HTTP headers in Key:Value format (repeatable)
• --body <body> — Request body (prefix with @ to read from file)
• --account-index <index> — Account index (default: 0)
• --dry-run — Show payment requirements without paying
• --yes — Skip payment confirmation (required for non-interactive agent use)
• --max-amount <amount> — Maximum amount willing to pay in human-readable units (e.g. "0.10" for $0.10 USDC)

Response includes "paid": true with payment details and settlement info when a payment was made, or "paid": false if the endpoint did not require payment.

Always use --dry-run first to inspect payment requirements before committing to a payment. Use --max-amount as a safety cap to prevent overpaying.

Lock

Always lock the wallet when done:

npx agent-wallet-cli lock --format json

Token Aliases

Use short names instead of contract addresses:

Conventions

• Always use --format json and parse the JSON output.
• Always check "ok": true in the response before proceeding.
• Use --yes to skip interactive confirmation prompts (required for non-interactive agent use).
• Never send more than the user instructed. Always confirm amounts with the user first.
• Use --dry-run for send commands when uncertain about the amount or recipient.
• Use --network to specify the network (default: mainnet). Available: mainnet, sepolia, polygon, arbitrum, base, base-sepolia.
• Solana networks: mainnet, devnet.