a2a-wallet

Use the a2a-wallet CLI to interact with A2A agents — send messages, stream responses, and manage tasks. Also supports x402 payment signing and local wallet m...

Security Scan

The skill is internally consistent with its stated purpose (a CLI wrapper for A2A agent messaging and x402 payment signing), but the installation method and the fact it manages plaintext local private keys are notable risks that require user caution.

Purpose & Capability

Name, description, and runtime instructions all describe using an external a2a-wallet CLI to send messages, sign x402 payments, and manage wallets. The actions and files referenced (local wallet files, CLI commands, agent cards) align with the stated purpose.

Instruction Scope

SKILL.md instructs the agent to run the CLI and to manage local wallets whose private keys are stored as plain files (~/.a2a-wallet/). That behavior is expected for a local-wallet feature, but it creates sensitive data exposure (agent runtime and other processes can read the key file). The skill includes explicit warnings and legal disclaimers, which is good, but the instructions inherently require filesystem access to private keys — a high-impact capability that users must accept deliberately.

Install Mechanism

INSTALL.md recommends installing via a curl | sh pipeline: curl -fsSL https://raw.githubusercontent.com/planetarium/a2a-x402-wallet/main/scripts/install.sh | sh. Executing remote install scripts is a risk because arbitrary code from a third party will be executed. The URL is GitHub raw content (a common distribution method) but piping to sh remains a higher-risk install pattern and should prompt verification of the script and release signatures.

Credentials

The skill declares no required environment variables or credentials. It does mention a custodial option that delegates signing to a third-party service (Privy), which is appropriate for a custodial flow; no unrelated credentials are requested by the skill itself.

Persistence & Privilege

The skill is instruction-only, has no install hooks in the bundle, and is not marked always:true. It does not request persistent platform privileges in the metadata.

Assessment

This skill appears to do what it claims (it's a guide to using the a2a-wallet CLI), but be cautious before proceeding: (1) Do not run the curl | sh install command without reviewing the install script and verifying the release/tag — prefer signed releases or manual installation when possible. (2) Local wallets store private keys as plaintext under ~/.a2a-wallet/ — do not create or import wallets holding significant assets and restrict file permissions; consider using a hardware wallet or alternative for real funds. (3) Custodial wallets delegate key management to third parties (Privy) — only use for small/test funds and accept third-party risk. (4) Because the CLI requires filesystem access to signing keys, an agent with access could read or exfiltrate keys; only enable this skill for agents/contexts you trust. If you want higher assurance, ask to see the install.sh script contents, verify GitHub release artifacts, and inspect the CLI binary before installing.

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, search
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

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. 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:

1. Send a message → agent replies with task.status = input-required and metadata["x402.payment.status"] = "payment-required" plus metadata["x402.payment.required"] containing PaymentRequirements
2. 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)
   

3. 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.

Custodial Wallet Risk

The custodial wallet delegates key management to Privy and the a2a-wallet web service. This project cannot guarantee custodial wallet security.

• Do NOT store significant amounts of assets in the custodial wallet.
• Key management is outside the user's direct control. The user bears full responsibility for any loss due to third-party service incidents or misconfigurations.

Both wallet types 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 supports two wallet types:

• Local wallet — private key stored locally (wallet create / wallet import). No login required. Key is stored as a plain file — use only for small amounts.
• Custodial wallet — signing delegated to the web service. Requires login via wallet connect. Security depends on a third-party provider — use only for small amounts.

Switch the active wallet with:

a2a-wallet wallet use <name>       # set a local wallet as default
a2a-wallet wallet use --custodial  # switch to the custodial wallet

Check current status at any time:

a2a-wallet status

Custodial wallet login

a2a-wallet wallet connect           # opens browser for login
a2a-wallet wallet connect --poll <device-code>  # complete login (headless)

Note for users upgrading from v0.3.3 or earlier

In v0.3.3 and below, the wallet was always managed by the web service (custodial). If you want to continue using that same wallet address after upgrading, you must activate the custodial wallet:

a2a-wallet wallet connect           # log in to the web service
a2a-wallet wallet use --custodial   # set custodial as the default

Recommendation: consider migrating to a local wallet. Local wallets sign entirely offline with no dependency on the web service. To switch, run wallet create and use the new address going forward.

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
• 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