x402 Protocol Skill

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:

• Client sends HTTP request → Server returns 402

• PAYMENT-REQUIRED header (base64 JSON)

• Client reads requirements, creates signed payment payload

• Client resubmits request with PAYMENT-SIGNATURE header (base64 JSON)

• Server verifies payment via facilitator POST /verify

• Server performs work, settles via facilitator POST /settle

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

npm install @x402/express @x402/core @x402/evm

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)

npm install @x402/fetch @x402/core @x402/evm viem

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

• Register schemes before wrapping fetch/axios — order matters.

• Two equivalent registration APIs:

• Function: registerExactEvmScheme(server) / registerExactEvmScheme(client, { signer })

• Method: server.register("eip155:84532", new ExactEvmScheme())

• V2 headers (current): PAYMENT-REQUIRED , PAYMENT-SIGNATURE , PAYMENT-RESPONSE . V1 headers (legacy): X-PAYMENT , X-PAYMENT-RESPONSE . SDK is backward-compatible.

• Price format: "$0.001" (dollar string) — SDK converts to atomic units (6 decimals for USDC).

• Python SDK uses V1 patterns only. Use TypeScript or Go for V2.

• Node.js v24+ required for the TypeScript SDK.

• Repo: https://github.com/coinbase/x402 — canonical examples in examples/typescript/ .

• Docs: https://docs.cdp.coinbase.com/x402/welcome and https://x402.gitbook.io/x402 .