x402-payments

# x402 Protocol Skill > Facts current as of July 2026 — verify pricing and model IDs against https://docs.claude.com, and protocol/package details against the x402 docs. ## Protocol Overview x402 embeds stablecoin payments into HTTP by using the 402 "Payment Required" status code. A server responds with payment requirements; the client signs a payment authorization, resubmits the request, and gets the resource after verification and settlement. **Payment flow:** 1. Client sends HTTP request → Server returns `402` + `PAYMENT-REQUIRED` header (base64 JSON) 2. Client reads requirements, creates signed payment payload 3. Client resubmits request with `PAYMENT-SIGNATURE` header (base64 JSON) 4. Server verifies payment via facilitator `POST /verify` 5. Server performs work, settles via facilitator `POST /settle` 6. Server returns `200` + resource + `PAYMENT-RESPONSE` header (contains txHash) **Key concepts:** - **Facilitators** verify and settle payments without holding funds. Use `https://x402.org/facilitator` for testnet, CDP facilitator for mainnet. - **Schemes**: `exact` (fixed price per request) is the production scheme. `upto` and `deferred` are proposed. - **Networks**: Identified by CAIP-2 format — `eip155:84532` (Base Sepolia), `eip155:8453` (Base Mainnet), `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` (Solana Devnet). - **EVM** uses EIP-3009 gasless `TransferWithAuthorization`. **Solana** uses SPL token transfers. ## Quick-Start: Protect an API Endpoint (Seller) ```bash npm install @x402/express @x402/core @x402/evm ``` ```typescript import express from "express"; import { paymentMiddleware } from "@x402/express"; import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server"; import { registerExactEvmScheme } from "@x402/evm/exact/server"; const app = express(); const payTo = process.env.PAY_TO!; const facilitatorClient = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator", }); const server = new x402ResourceServer(facilitatorClient); registerExactEvmScheme(server); app.use( paymentMiddleware( { "GET /weather": { accepts: [ { scheme: "exact", price: "$0.001", network: "eip155:84532", payTo }, ], description: "Get current weather data", mimeType: "application/json", }, }, server, ), ); app.get("/weather", (req, res) => { res.json({ weather: "sunny", temperature: 70 }); }); app.listen(4021, () => console.log("Server on :4021")); ``` ## Quick-Start: Pay for x402 Resources (Buyer/Agent) ```bash npm install @x402/fetch @x402/core @x402/evm viem ``` ```typescript import { wrapFetchWithPayment } from "@x402/fetch"; import { x402Client, x402HTTPClient } from "@x402/core/client"; import { registerExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); registerExactEvmScheme(client, { signer }); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment("http://localhost:4021/weather"); const data = await response.json(); console.log(data); // Read payment receipt const httpClient = new x402HTTPClient(client); const receipt = httpClient.getPaymentSettleResponse( (name) => response.headers.get(name), ); console.log("Tx:", receipt?.txHash); ``` ## Decision Tree | Decision | Choice | Packages | |----------|--------|----------| | **Server: Express** | `paymentMiddleware` from `@x402/express` | `@x402/express @x402/core @x402/evm` | | **Server: Next.js** | `paymentProxy` from `@x402/next` | `@x402/next @x402/core @x402/evm` | | **Server: Hono** | `paymentMiddleware` from `@x402/hono` | `@x402/hono @x402/core @x402/evm` | | **Client: fetch** | `wrapFetchWithPayment` | `@x402/fetch @x402/core @x402/evm viem` | | **Client: axios** | `wrapAxiosWithPayment` | `@x402/axios @x402/core @x402/evm viem axios` | | **Client: manual** | `x402Client` + `x402HTTPClient` from `@x402/core` | `@x402/core @x402/evm viem` | | **Chain: EVM** | `registerExactEvmScheme` | `@x402/evm` + `viem` | | **Chain: Solana** | `registerExactSvmScheme` | `@x402/svm` + `@solana/kit @scure/base` | | **Chain: both** | Register both schemes on same client/server | All chain deps | | **Env: testing** | Facilitator `https://x402.org/facilitator` | Base Sepolia / Solana Devnet | | **Env: production** | CDP facilitator + API keys | Base Mainnet / Solana Mainnet | | **Agent: MCP** | MCP server with `@x402/axios` | See `references/agentic-patterns.md` | | **Agent: Anthropic** | Tool-use with `@x402/fetch` | See `references/agentic-patterns.md` | ## Reference File Navigation | Task | Read this file | |------|---------------| | Headers, payloads, CAIP-2 IDs, facilitator API, V1→V2 changes | `references/protocol-spec.md` | | Express / Hono / Next.js middleware, multi-route, dynamic pricing | `references/server-patterns.md` | | Fetch / axios client, wallet setup, lifecycle hooks, error handling | `references/client-patterns.md` | | AI agent payments, MCP server, tool discovery, budget controls | `references/agentic-patterns.md` | | Testnet→mainnet migration, CDP keys, faucets, security, sessions | `references/deployment.md` | ## Critical Implementation Notes 1. **Register schemes before wrapping** fetch/axios — order matters. 2. **Two equivalent registration APIs**: - Function: `registerExactEvmScheme(server)` / `registerExactEvmScheme(client, { signer })` - Method: `server.register("eip155:84532", new ExactEvmScheme())` 3. **V2 headers** (current): `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`. V1 headers (legacy): `X-PAYMENT`, `X-PAYMENT-RESPONSE`. SDK is backward-compatible. 4. **Price format**: `"$0.001"` (dollar string) — SDK converts to atomic units (6 decimals for USDC). 5. **Python SDK** uses V1 patterns only. Use TypeScript or Go for V2. 6. **Node.js v24+** required for the TypeScript SDK. 7. **Repo**: `https://github.com/coinbase/x402` — canonical examples in `examples/typescript/`. 8. **Docs**: `https://docs.cdp.coinbase.com/x402/welcome` and `https://x402.gitbook.io/x402`.