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`	Interact with A2A agents (`card`, `send`, `stream`, `tasks`, `cancel`)
`x402 sign`	Sign x402 PaymentRequirements → PaymentPayload (for paywalled agents)
`siwe`	SIWE token operations (`prepare`, `encode`, `decode`, `verify`, `auth`)
`auth`	Log in / out (`login`, `device start/poll`, `logout`)
`config`	Get or set config values (`token`, `url`)
`whoami`	Show authenticated user info
`balance`	Show wallet balance
`sign`	Sign an arbitrary message with the wallet
`faucet`	Request testnet tokens
`update`	Update the CLI binary

Agent Card Extensions

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

a2a-wallet a2a card https://my-agent.example.com

The capabilities.extensions array in the card lists supported (and possibly required) extensions. Two extensions are 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:

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"

SIWE Bearer Auth Extension

Extension URI: https://github.com/planetarium/a2a-x402-wallet/tree/main/docs/siwe-bearer-auth/v0.1

Agents declaring this extension require a wallet-signed auth token on every request. If required: true, messages cannot be sent without one.

How to detect: The agent card will contain:

{
  "extensions": [
    {
      "uri": "https://github.com/planetarium/a2a-x402-wallet/tree/main/docs/siwe-bearer-auth/v0.1",
      "required": true
    }
  ]
}

Usage:

Generate a token for the agent's domain:

TOKEN=$(a2a-wallet siwe auth \
  --domain my-agent.example.com \
  --uri    https://my-agent.example.com \
  --ttl    1h \
  --json | jq -r '.token')

Pass it via --bearer when sending messages:

a2a-wallet a2a send   --bearer "$TOKEN" https://my-agent.example.com "Hello"
a2a-wallet a2a stream --bearer "$TOKEN" https://my-agent.example.com "Hello"

Note: The token is tied to the agent's domain — a token issued for one agent will be rejected by another.

Agent usage tips

Use --json for machine-readable output
Errors → stderr, exit 0 = success, 1 = failure
Override token/URL per-call with --token / --url, or set A2A_WALLET_TOKEN env var
The CLI detects expired tokens before making network requests and prints guidance
Always run a2a card <url> first to check which extensions are required before sending messages
Use a2a-wallet --help or a2a-wallet <command> --help to discover options at any time