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:

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)

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

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.