# agent-payment-x402

> A Claude Code skill from Affaan M's everything-claude-code repo that adds policy-gated x402 payment execution to AI agents. Wraps agentwallet-sdk (Base) or OKX Agent Payments Protocol (X Layer) behind MCP tools with per-task and per-session budgets, allowlisted recipients, and ERC-4337 non-custodial wallets.

**Use case**: Let an agent pay 402-gated APIs without giving it unbounded spend or pooled-custody risk

**Canonical URL**: https://agentcookbooks.com/skills/agent-payment-x402/

**Topics**: claude-code, skills, agents

**Trigger phrases**: "let the agent pay for this API", "x402 payment for my agent", "agent wallet with spending limits"

**Source**: [Affaan M](https://github.com/affaan-m/everything-claude-code/tree/main/skills/agent-payment-x402)

**License**: MIT

---

## What it does

`agent-payment-x402` is the payments skill in [Affaan M's everything-claude-code repo](https://github.com/affaan-m/everything-claude-code) — see [skills/agent-payment-x402](https://github.com/affaan-m/everything-claude-code/tree/main/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](https://github.com/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 — `agentwallet-sdk@6.0.0` 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](https://github.com/affaan-m/everything-claude-code/tree/main/skills/agent-payment-x402) — 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.