a2a-wallet Skill

If a command fails with a "command not found" error, refer to INSTALL.md in this directory and guide the user through installation.

Commands

Command	Description
`a2a`	A2A protocol client: `auth`, `list`, `disconnect`, `card`, `send`, `stream`, `tasks`, `cancel`
`registry`	Agent registry: `search` (find agents), `register` (register an agent by agent card URL)
`x402 sign`	Sign x402 PaymentRequirements → A2A message metadata (for paywalled agents)
`wallet`	Manage local wallets: `create`, `import`, `list`, `use`, `export`, `connect`, `disconnect`
`status`	Show default wallet address and web app URL
`config`	Get or set config values (`token`, `url`)
`balance`	Show USDC balance for the active wallet on a given network
`faucet`	Request testnet USDC (Base Sepolia) directly from the CLI — no browser or auth required
`update`	Update the CLI binary

Finding Agents

Use the registry search command to discover A2A agents by keyword or capability:

Examples:

a2a-wallet registry search --json "image generation"

The registry returns matching agents with their name, description, and agentCardUrl. You can pass the agentCardUrl directly to any agent command — no need to strip the path:

# Inspect before interacting
a2a-wallet a2a card https://my-agent.example.com/.well-known/agent-card.json

# Send a message using the agentCardUrl from registry search
a2a-wallet a2a send https://my-agent.example.com/.well-known/agent-card.json "Hello"

To register a new agent in the registry:

a2a-wallet registry register <agent-card-url>

Sending Messages

a2a-wallet a2a send <url|agentCardUrl> "message"     # wait for full response
a2a-wallet a2a stream <url|agentCardUrl> "message"   # stream response via SSE

<url|agentCardUrl> accepts either an agent base URL or an agent card URL (e.g. agentCardUrl from registry search).

Options (send and stream unless noted):

Option	Description
`--context-id <id>`	Continue an existing conversation context (omit to start a new one)
`--task-id <id>`	Target a specific task — required when resuming a paused task or submitting x402 payment (`send` only)
`--metadata <json>`	JSON metadata to attach (e.g. x402 payment payload) (`send` only)
`--file <path\|uri>`	Attach a file; repeatable. Local path → base64-embedded, `http(s)://` → URL reference
`--bearer <token>`	Bearer token for agent authentication
`--allow-x402`	Auto-sign and resubmit if agent responds with payment-required
`--json`	Machine-readable output

Agent Card Extensions

Before interacting with an A2A agent, inspect its card to check which extensions are declared:

# Base URL — appends /.well-known/agent-card.json automatically
a2a-wallet a2a card https://my-agent.example.com

# Full agent card URL (e.g. from registry search) — used as-is
a2a-wallet a2a card https://my-agent.example.com/.well-known/agent-card.json

The capabilities.extensions array in the card lists supported (and possibly required) extensions. The following extension is relevant to this CLI:

x402 Payments Extension

Extension URI: https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2

Agents declaring this extension monetize their services via on-chain cryptocurrency payments. If required: true, the client must implement the x402 flow.

How to detect: The agent card will contain:

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2",
        "required": true
      }
    ]
  }
}

Payment flow (automatic):

Use --allow-x402 with send or stream to handle the entire flow automatically — the CLI detects the payment request, signs it, and resubmits without any extra steps:

a2a-wallet a2a send --allow-x402 https://my-agent.example.com "Hello"
a2a-wallet a2a stream --allow-x402 https://my-agent.example.com "Hello"

Payment flow (manual):

Send a message → agent replies with task.status = input-required and metadata["x402.payment.status"] = "payment-required" plus metadata["x402.payment.required"] containing PaymentRequirements

Sign the requirements with x402 sign:

METADATA=$(a2a-wallet x402 sign \
  --scheme exact \
  --network base \
  --asset <token-address> \
  --pay-to <merchant-address> \
  --amount <amount> \
  --extra-name <eip712-domain-name> \
  --extra-version <eip712-domain-version> \
  --json)

Submit payment by sending back with --task-id and --metadata:

a2a-wallet a2a send \
  --task-id <task-id> \
  --metadata "$METADATA" \
  https://my-agent.example.com "Payment submitted"

SECURITY WARNING — READ BEFORE SETTING UP A WALLET

Always present the following warnings to the user before creating or importing any wallet.

Local Wallet Risk

The local wallet stores the private key as a plain file on disk (~/.a2a-wallet/). As an AI agent using this CLI, you have direct filesystem access — which means the key file is accessible to the agent runtime and any other process on the machine.

Do NOT create or use a local wallet that holds significant assets.
Do NOT import or restore a wallet that holds significant assets into this CLI.
If the key file is read by any unauthorized process or leaks for any reason, all assets are permanently unrecoverable. The user bears full responsibility.

Local wallets are intended for small micro-payments only. Always inform the user of these risks and confirm they accept responsibility before proceeding.

Legal Notice

[!CAUTION] This software is experimental and intended for testing and development purposes only. Do not use it with production funds or significant on-chain assets.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE AUTHORS, CONTRIBUTORS, AND OPERATORS OF THIS PROJECT SHALL NOT BE LIABLE FOR ANY LOSS OF FUNDS, LOSS OF DATA, UNAUTHORIZED ACCESS TO CRYPTOGRAPHIC KEYS, SERVICE INTERRUPTION, OR ANY OTHER DAMAGES ARISING FROM USE OF THIS SOFTWARE.

When setting up a wallet, confirm the user understands and accepts the following:

They are using experimental software at their own risk.
They will not store significant assets in any wallet managed by this tool.
Any loss is solely their responsibility — no compensation or recovery is possible.
The project maintainers provide no guarantees of security, uptime, or correctness.

Wallet selection

The CLI uses local wallets — private key stored locally (wallet create / wallet import). No login required. Key is stored as a plain file — use only for small amounts.

Switch the active wallet with:

a2a-wallet wallet use <name>   # set a local wallet as default

Check current status at any time:

a2a-wallet status

Agent usage tips

Use --json for machine-readable output
Errors → stderr, exit 0 = success, 1 = failure
Use a2a-wallet --help or a2a-wallet <command> --help to discover options at any time