CLI Usage & Reference

Complete command reference for the a2a-wallet CLI.

Quick Start

Install, log in, and sign your first payment in three steps.

# 1. Install (macOS / Linux)$curl -fsSL https://raw.githubusercontent.com/planetarium/a2a-x402-wallet/main/scripts/install.sh | sh
# 2. Log in$a2a-wallet auth login
# 3. Sign an x402 payment$a2a-wallet x402 sign \  --scheme exact \  --network base \  --asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913 \  --pay-to 0xMerchantAddress \  --amount 120000000 \  --json

Authentication

Opens a browser-based login flow and saves the token automatically. Recommended for interactive use.

$a2a-wallet auth login$a2a-wallet auth login --token <jwt>   # inject token directly (CI)

Option	Description
`--url <url>`	Override the web app URL
`--token <jwt>`	Save a token directly without opening a browser

auth device start / poll

Two-step headless flow for AI agents. Step 1 prints the login URL immediately so the agent can relay it to the user before blocking. Step 2 polls until the user completes login.

# Step 1 — get the login URL (exits immediately)$a2a-wallet auth device start --json# → {"nonce":"abc123","loginUrl":"https://..."}
# Step 2 — poll for completion$a2a-wallet auth device poll --nonce abc123# → Token saved. You are now logged in.

Option	Description
`--json`	Output {"nonce":"…","loginUrl":"…"} to stdout
`--nonce <nonce>`	Nonce from device start (poll only, required)
`--url <url>`	Override the web app URL

auth logout

Removes the saved token from the config file.

$a2a-wallet auth logout

x402 Sign

Signs PaymentRequirements (HTTP 402) and outputs a PaymentPayload JSON to stdout.

$a2a-wallet x402 sign \  --scheme exact \  --network base \  --asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913 \  --pay-to 0xMerchantAddress \  --amount 120000000 \  --json

Option	Default	Description
`--scheme <scheme>`	`—`	Payment scheme (exact)
`--network <network>`	`—`	Blockchain network — see supported networks
`--asset <address>`	`—`	ERC-20 token contract address
`--pay-to <address>`	`—`	Merchant wallet address
`--amount <value>`	`—`	Max payment amount in token's smallest unit
`--valid-for <seconds>`	`3600`	Signature validity duration in seconds
`--json`	`—`	Output pure JSON to stdout (recommended for agent use)
`--token <jwt>`	`config`	One-time token override
`--url <url>`	`config`	Web app URL override

Output example

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xUserWallet",
      "to": "0xMerchantAddress",
      "value": "120000000",
      "validAfter": "0",
      "validBefore": "1234567890",
      "nonce": "0x..."
    }
  }
}

SIWE

Sign-In with Ethereum (EIP-4361). Generate, sign, encode, decode, verify, or run the full flow in one command.

siwe auth

All-in-one command. Resolves your wallet address, generates a SIWE message, signs it, and outputs a base64url token. Requires authentication.

$a2a-wallet siwe auth \  --domain app.example.com \  --uri https://app.example.com \  --ttl 1h

Option	Default	Description
`--domain <host>`	`—`	Domain (required)
`--uri <uri>`	`—`	URI (required)
`--ttl <duration>`	`7d`	Expiration — 30m, 1h, 7d, etc.
`--chain-id <n>`	`1`	EIP-155 chain ID
`--statement <text>`	`I accept the Terms of Service`	Statement text
`--json`	`—`	Output pure JSON

siwe prepare

Generates an EIP-4361 message and prints it to stdout. If --address is omitted, the wallet address is resolved automatically (requires auth).

$a2a-wallet siwe prepare \  --domain app.example.com \  --uri https://app.example.com \  --address 0xf39F... \  --ttl 7d

siwe encode

Encodes a SIWE message + signature into a base64url token. Does not require authentication.

$a2a-wallet siwe encode \  --signature 0xda0e85... \  --message-file /tmp/msg.txt

siwe decode

Decodes a base64url SIWE token and prints its fields. Does not require authentication.

$a2a-wallet siwe decode <token>$a2a-wallet siwe decode <token> --json

siwe verify

Recovers the signer address via EIP-191 and checks expiration. Exits 0 on success, 1 on failure.

$a2a-wallet siwe verify <token># stdout: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266

A2A

Interact with A2A-compatible agents.

a2a card

Fetches and displays an agent's AgentCard from /.well-known/agent.json.

$a2a-wallet a2a card <url>$a2a-wallet a2a card <url> --json

a2a send

Sends a message to an agent and prints the full response.

$a2a-wallet a2a send <url> "your message"$a2a-wallet a2a send <url> "continue" --context-id <id>

Option	Description
`--context-id <id>`	Continue an existing conversation
`--bearer <token>`	Bearer token for agent auth
`--json`	Output raw JSON

a2a stream

Sends a message and streams the response via SSE. Text parts are written to stdout as they arrive.

$a2a-wallet a2a stream <url> "your message"

a2a tasks get

Fetch the current state and message history of a task by ID.

$a2a-wallet a2a tasks get <url> <taskId>$a2a-wallet a2a tasks get <url> <taskId> --history 10 --json

Option	Default	Description
`--history <n>`	`0`	Include last N messages from task history
`--bearer <token>`	`—`	Bearer token for agent authentication
`--json`	`—`	Output raw JSON (single line)

a2a cancel

Request cancellation of a running task. The agent may or may not honor the request.

$a2a-wallet a2a cancel <url> <taskId>

Sign

Signs an arbitrary message with your embedded wallet and prints the signature.

$a2a-wallet sign --message "hello world"$a2a-wallet sign --message "hello world" --json

Option	Description
`--message <string>`	Message to sign (required)
`--json`	Output pure JSON
`--token <jwt>`	One-time token override
`--url <url>`	Web app URL override

Whoami

Shows the authenticated user's Privy user ID and wallet address.

$a2a-wallet whoami$a2a-wallet whoami --json

Option	Description
`--json`	Output pure JSON
`--token <jwt>`	One-time token override
`--url <url>`	Web app URL override

Balance

Shows the USDC balance of the logged-in wallet on a given network.

$a2a-wallet balance$a2a-wallet balance --network base --json

Option	Default	Description
`--network <network>`	`base-sepolia`	Network to query — see supported networks
`--json`	`—`	Output pure JSON
`--token <jwt>`	`config`	One-time token override
`--url <url>`	`config`	Web app URL override

Faucet

Opens the web faucet for testnet USDC (Base Sepolia). The browser opens automatically if possible; otherwise the URL is printed to stdout.

$a2a-wallet faucet

Option	Description
`--url <url>`	Web app URL override

Update

Updates the a2a-wallet binary to the latest release from GitHub. Only applies to binary installations — npm / pnpm installs should reinstall from source.

$a2a-wallet update

Config

Settings are stored in ~/.a2a-wallet/config.json. Priority: CLI option > env var > config file > default.

$a2a-wallet config set token <jwt>$a2a-wallet config set url <url>$a2a-wallet config get$a2a-wallet config get url

Option	Description
`A2A_WALLET_TOKEN`	Access token (env var)
`A2A_WALLET_URL`	Web app base URL (env var)

Agent Integration

The CLI is designed for programmatic use by AI agents. Use --json for machine-readable output. Errors go to stderr; exit code 0 = success, 1 = failure.

Initial setup — one-time device flow

Use the two-step device flow for headless environments — no local server required. Once logged in, copy the token and inject it via A2A_WALLET_TOKEN.

# Step 1 — get the login URL (non-blocking)$a2a-wallet auth device start --json# → {"nonce":"abc123","loginUrl":"https://..."}
# Relay the URL to the user, then:# Step 2 — poll for completion$a2a-wallet auth device poll --nonce abc123# → Token saved. You are now logged in.

Invocation example

$A2A_WALLET_TOKEN=<jwt> a2a-wallet x402 sign \  --scheme exact \  --network base \  --asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bda02913 \  --pay-to 0xMerchantAddress \  --amount 120000000 \  --json

MCP tool definition

Example tool definition for use in an MCP-compatible agent framework.

{
  "name": "x402_sign",
  "description": "Sign an x402 PaymentRequirements to create a PaymentPayload.",
  "inputSchema": {
    "type": "object",
    "required": ["scheme", "network", "asset", "payTo", "amount"],
    "properties": {
      "scheme":   { "type": "string", "enum": ["exact"] },
      "network":  { "type": "string", "enum": ["base", "base-sepolia", "ethereum", "optimism", "arbitrum"] },
      "asset":    { "type": "string", "description": "ERC-20 token contract address" },
      "payTo":    { "type": "string", "description": "Merchant wallet address" },
      "amount":   { "type": "string", "description": "Max amount in token's smallest unit" },
      "validFor": { "type": "number", "description": "Validity in seconds (default: 3600)" }
    }
  }
}

Supported networks

Option	Description
`base`	8453
`base-sepolia`	84532
`ethereum`	1
`optimism`	10
`arbitrum`	42161