x402 Protocol v2

Open payment standard enabling clients to pay for external resources over any transport layer (HTTP, MCP, A2A). Protocol version: 2.

Core Concepts

x402 has three architectural layers:

1. Types — PaymentRequirements, PaymentPayload, SettlementResponse, VerifyResponse (transport/scheme-agnostic)
2. Logic — Payment formation, verification, settlement (scheme+network specific, e.g. exact/EVM)
3. Representation — How payment data is transmitted (transport-specific: HTTP headers, JSON-RPC, etc.)

Payment Flow

1. Client requests a protected resource
2. Server responds with Payment Required + PaymentRequired JSON (contains accepts array)
3. Client picks a payment method, signs authorization, sends PaymentPayload
4. Server forwards to facilitator → verify → settle → returns resource + SettlementResponse

Three Actors

• Resource Server — Requires payment, delegates verification/settlement to facilitator
• Client — Signs payment authorizations (wallet-based)
• Facilitator — Verifies signatures, checks balances, broadcasts settlement transactions

PaymentRequired (Server → Client)

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.example.com/data",
    "description": "Premium data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x...",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USDC", "version": "2" }
    }
  ],
  "extensions": {}
}

Field Reference

PaymentRequirements Fields

PaymentPayload (Client → Server)

{
  "x402Version": 2,
  "resource": { "url": "...", "description": "...", "mimeType": "..." },
  "accepted": { /* chosen PaymentRequirements */ },
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "10000",
      "validAfter": "1740672089", "validBefore": "1740672154",
      "nonce": "0x..."
    }
  },
  "extensions": {}
}

EVM Exact Payload

SettlementResponse

{
  "success": true,
  "transaction": "0x...",
  "network": "eip155:8453",
  "payer": "0x..."
}

VerifyResponse

Facilitator API

Three HTTP REST endpoints:

POST /verify

Verifies payment authorization without settling. Request body: { paymentPayload, paymentRequirements }. Returns VerifyResponse.

POST /settle

Settles payment on-chain. Same request body as /verify. Returns SettlementResponse.

GET /supported

Returns supported schemes, networks, extensions, and signer addresses.

{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:8453" }
  ],
  "extensions": [],
  "signers": {
    "eip155:*": ["0x..."],
    "solana:*": ["CKP..."]
  }
}

Exact Scheme — EVM

Uses EIP-3009 transferWithAuthorization for gasless ERC-20 transfers (e.g. USDC).

Verification steps:

1. Validate EIP-712 signature
2. Check payer token balance
3. Validate amount ≥ required
4. Check time window (validAfter/validBefore)
5. Match parameters to payment requirements
6. Simulate transferWithAuthorization tx

Settlement: Call transferWithAuthorization on the ERC-20 contract.

EIP-3009 type structure:

const authorizationTypes = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" },
  ],
};

Exact Scheme — SVM (Solana)

Uses TransferChecked for SPL tokens. Key verification:

• Strict instruction layout: Compute Unit Limit → Compute Unit Price → TransferChecked
• Facilitator fee payer must NOT appear in instruction accounts or as transfer authority/source
• Compute unit price bounded to prevent gas abuse
• Destination ATA must match payTo/asset PDA
• Transfer amount must exactly equal PaymentRequirements.amount

Networks (CAIP-2 Format)

Extensions

Extensions are key-value maps in PaymentRequired and PaymentPayload:

• Each key = extension identifier
• Each value = { info: object, schema: object } where schema is JSON Schema for info
• Client must include at least the server-provided info; may append but cannot delete/overwrite

Discovery API (Bazaar)

GET /discovery/resources

Params: type (e.g. "http"), limit (1-100, default 20), offset (default 0).

Returns paginated list of x402-enabled resources with accepts arrays, lastUpdated timestamps, and optional metadata.

Error Codes

Security

• Replay prevention: 32-byte EIP-3009 nonce + smart contract nonce reuse protection + time windows
• Auth integration: Supports SIWE for authenticated/discounted pricing

Reference Implementation

See https://github.com/coinbase/x402 for the canonical implementation.

For detailed scheme-specific implementation, see the reference files:

• reference/exact-core.md — Core exact scheme specification
• reference/exact-evm.md — EVM implementation (EIP-3009)
• reference/exact-svm.md — Solana implementation
• reference/exact-sui.md — Sui implementation

For facilitator API examples and discovery API schemas, see reference/facilitator-api.md.

For x402 extension specifications, see the extension reference files:

• reference/extension-bazaar.md — Resource discovery and cataloging
• reference/extension-payment-identifier.md — Idempotency keys for deduplication
• reference/extension-sign-in-with-x.md — Wallet-based authentication (CAIP-122/SIWE)
• reference/extension-eip2612-gas-sponsoring.md — Gasless EIP-2612 permit flow
• reference/extension-erc20-gas-sponsoring.md — Gasless ERC-20 approval flow

Transport Support

x402 is transport-agnostic. Current transports:

• HTTP — 402 Payment Required status, base64-encoded headers (PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE). See reference/transport-http.md.
• MCP — Payment via _meta["x402/payment"] and _meta["x402/payment-response"], signaling via isError: true + structuredContent. See reference/transport-mcp.md.
• A2A — Task-based lifecycle with x402.payment.* metadata keys, AgentCard extension declaration, X-A2A-Extensions header activation. See reference/transport-a2a.md.

Framework Integration

Server-side: Express.js middleware (require_payment()), FastAPI, Hono, Next.js, ai/agents. Client-side: axios/fetch, httpx/requests, MCP clients, A2A clients.