agent-payment-x402

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• let the agent pay for this API
• x402 payment for my agent
• agent wallet with spending limits

What it does

agent-payment-x402 is the payments skill in Affaan M’s everything-claude-code repo — see skills/agent-payment-x402. It extends HTTP 402 (Payment Required) into a machine-negotiable flow so an agent can call a paid API, get a 402 back, sign the right transaction, and retry — but only inside a SpendingPolicy set by the orchestrator before delegation.

The skill ships a decision tree mapping payment intent to integration path: agentwallet-sdk for Base / multi-chain buyer flows, OKX Agent Payments Protocol (okx/onchainos-skills) for X Layer x402, and language-specific OKX seller SDK docs for TypeScript, Go, Rust, and Java APIs that want to charge agents. The legacy okx-x402-payment alias is flagged as deprecated.

Spending controls layer four constraints on every payment tool call: per-task budget, per-session budget, allowlisted recipients, and rate limits. Wallets are ERC-4337 smart accounts — the agent holds its own keys, the orchestrator sets policy before delegating, and the agent can only spend within bounds. The fail-closed pattern is explicit: a missing key, an unreachable payment server, or a non-finite remaining field all block the paid action rather than degrade to unmetered access.

When to use it

• Adding paid-API access to an agent that’s currently calling free endpoints, where you want per-task spend caps before going live
• Agent-to-agent settlement where the seller charges via x402 and the buyer’s orchestrator sets a session budget
• Running a paid OKX X Layer flow (MPP, session payment, A2A charge) and you need the canonical dispatcher, not the deprecated alias
• Building a TypeScript / Go / Rust / Java seller API that needs to charge agents and you want the current per-runtime guide

When not to reach for it:

• Plain Stripe-style human-checkout flows — this skill is agent-to-API, not user-to-merchant
• Custodial wallet integrations where a central party holds keys — the whole point is non-custodial ERC-4337
• Networks outside Base or X Layer — verify agentwallet-sdk’s current network coverage before assuming

Install

From affaan-m/everything-claude-code at skills/agent-payment-x402/. Drop the folder into ~/.claude/skills/agent-payment-x402/. The skill itself is markdown, but the runtime depends on the agentwallet-sdk MCP server (pin the version — [email protected] in the upstream example) and a wallet private key in WALLET_PRIVATE_KEY. For OKX paths, reference the current okx/onchainos-skills repo and the matching language-specific SELLER.md from okx/payments. Pin every package — this server manages private keys.

What a session looks like

1. State the intent. “I want my research agent to call a paid news API at most ten times per task, max $0.50 per call, $5 total per session.”
2. Skill picks the path. Decision-tree maps buyer-side Base flow to agentwallet-sdk; for X Layer x402 it routes to okx-agent-payments-protocol.
3. Orchestrator sets policy. Before delegating, the orchestrator calls set_policy with per_task_budget, per_session_budget, allowlisted_recipients. Any failure here blocks delegation — the skill is explicit that silent failure means no controls.
4. Agent makes a paid call. The agent’s pre-tool hook calls check_spending, validates the response is well-formed (non-finite remaining throws), then proceeds. The four-path failure handler covers invalid input, transport failure, tool error, parse error, and budget exceeded — each as a distinct throw.
5. Audit trail in post-task hook. list_transactions logs what was spent and against which recipient.

The discipline that makes it work: policy is set by the orchestrator, not callable by the agent. Agents can’t escalate their own limits because set_policy is never exposed as an agent-callable tool — it lives in the orchestration layer or a pre-task hook.

Receipts

TODO — to be filled in from a real session. Once the skill has been used to make a live testnet payment, this section will capture: which network actually settled the transaction (Base Sepolia is the safe default for first run), the exact SpendingPolicy values that caught a misconfiguration (e.g. an unbounded per_task_budget rejected by policy validation), the gas + latency cost of one full 402 → sign → retry round-trip, and any agentwallet-sdk version mismatch surfaced by the pinned @6.0.0 install.

Source and attribution

From Affaan M’s everything-claude-code — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the orchestrator-policy boundary verbatim: “Spending policy is set by the orchestrator before delegating to the agent — not by the agent itself. This prevents agents from escalating their own spending limits.” The non-custodial wallet + orchestrator-set policy is the wedge — without it, a paid agent is just a more expensive prompt-injection target.