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)

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"));