How to use the Agent Payments via x402 agent skill

What does the agent-payment-x402 skill make an agent do?

x402 extends HTTP status 402 (Payment Required) into a flow a machine can handle. When a server replies with 402, the agent's payment tool checks the price, confirms it fits the budget, signs the transaction, and retries only within the policy and confirmation limits set by the operator.

The skill adds spending controls. Every payment tool call is checked against a spending policy with per-task budgets, per-session budgets, an allowlist of payees, and rate limits. The agent holds its own keys through an ERC-4337 smart account, and the operator sets the policy before delegating work, so the agent cannot raise its own limits.

• Per-task budget: the maximum spend for a single agent action
• Per-session budget: a cumulative cap across the whole session
• Allowlisted payees: limits which addresses or services the agent may pay
• Rate limits: maximum transactions per minute or hour

Choose the right integration route

The skill covers three routes. Pick one based on whether your agent is buying access to a paid API, or whether you are charging for your own API.

Route A uses the agentwallet-sdk package as an MCP payment server for Base and other agentwallet-supported chains. Route B uses the OKX agent payments protocol for X Layer. Route C uses upstream x402 client packages for Solana and EVM networks. The skill also lists seller-side guides for TypeScript, Python, Go, Rust and Java, so you can charge for an API.

• Agent pays a 402-gated API on Base: use agentwallet-sdk as an MCP server
• Agent pays a 402-gated API on X Layer: use the OKX agent payments protocol
• Agent pays on Solana or another x402 v2 network: wrap the HTTP client with the upstream @x402/fetch or @x402/axios package
• Your API charges agents: use the upstream x402 middleware or the OKX seller SDK guide for your framework

Install the skill (ZIP download or upload)

Download the ZIP of the skill from this page. The skill is a folder that contains a single file, SKILL.md. Unzip it into one of these locations.

For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

If you want the Base route, you also need to register the MCP server. Add the mcpServers block below to your agent harness's MCP configuration. The skill pins the package version, which you should keep pinned.

Trigger the skill with natural requests

You do not need a special command. Describe the job in plain language and mention paying, buying, budgets or spending. The agent should pick up the skill from its description.

Expect the agent to ask for confirmation before any payment action. The skill requires explicit user confirmation before wallet checks or payment actions, so payments should not run hidden behind a general tool call.

• Pay for one call to the weather API at the URL I give you, and stay under 0.01 USDC.
• Check how much budget is left in this session before you call the paid data endpoint.
• Show me the transaction log for all payments made in this task.
• Set up a payment client for my Solana and Base API calls, using a per-call cap and a payee allowlist.

Tools the agent can call on the Base route

On the Base route the agent gets four tools. get_balance checks the agent wallet balance. send_payment sends a payment to an address or ENS name. check_spending shows the remaining budget. list_transactions returns the audit trail of all payments.

The spending policy is set by the orchestrator, not the agent, and it should be set through set_policy in an orchestration layer or a pre-task hook. Do not expose set_policy as a tool the agent can call.

• get_balance
• send_payment
• check_spending
• list_transactions

Safety notes: scripts, network and keys

This skill runs scripts and uses the network. It manages private keys, so pin package versions. An unpinned npx install is a supply chain risk. Signer keys should live in the orchestrator's environment variables, never hardcoded and never writable by the agent.

On the upstream route, the client should allow only the resource origins you name, refuse redirects, and check amount, asset and network against the server's challenge before signing. Your own numbers do not prove a budget, because the amount comes from the server. The skill's notes say default x402.org facilitator endpoints are testnet only, so do not point production payments at them. Check live coverage at the facilitator's /supported endpoint.

• Pin every package version (for example agentwallet-sdk and @x402/fetch)
• Keep private keys in environment variables owned by the orchestrator
• Use the Base Sepolia testnet during development; treat Base mainnet as the production path
• Check facilitator coverage at /supported before going live

Tips for a safe first run

Start on a testnet with a funded test wallet. Set a small per-task budget and a small session cap, then add a payee allowlist before running anything with real funds. Read list_transactions after each run so you can see what was paid and to whom.

If you are building the payment code itself, get the current SDK documentation first. The skill warns that payment packages and facilitator behaviour can change quickly, so do not copy old examples.

• Begin with a testnet and a small session cap
• Set a payee allowlist before the first live call
• Review the audit trail after each run
• Fetch current SDK documentation before writing production code