Skip to main content
The x402 protocol lets clients pay for HTTP resources (APIs, endpoints, content) via blockchain transactions (with fiat support in progress). A server responds with HTTP 402 (“Payment Required”), the client pays, and the server grants access. No subscription, API key, or manual onboarding is required.

​
1. Components

ComponentRoleExample / note
ClientRequests a resource & paysBrowser, AI agent, mobile SDK
Resource ServerProtects endpoint, issues-402, verifies paymentAPI or web service
FacilitatorOptional verification + settlement layerOffloads blockchain logic oai_citation:1‡QuickNode
Payment SchemeDefines chain, token, network, and formate.g., USDC on Polygon, ERC-3009 scheme

​
2. Payment Flow Sequence

The typical sequence for one request:
  1. Client → Resource Server: HTTP GET /endpoint
  2. Resource Server → Client: HTTP 402 Payment Required, body includes PaymentRequirements describing required payment.
  3. Client selects a requirement, builds a PaymentPayload, encodes it (e.g., Base64) in header X-PAYMENT and retries request.
  4. Resource Server verifies the payload (either locally or via the Facilitator).
  5. Facilitator / Resource Server settles payment onchain (if not already).
  6. Resource Server → Client: HTTP 200 OK, body includes the requested resource, header X-PAYMENT-RESPONSE contains receipt details.
Steps 2-3 can be skipped if the client already knows the payment requirement ahead of time.

​
3. Implementation Snapshot

​
Server (Seller Side)

  • Protect endpoint with middleware (e.g.,
    paymentMiddleware("0xYourAddress", { "/path": { price:"$0.01", network:"polygon" } })).
  • On first unauthorized request: respond 402 with JSON: 
    {
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "erc-3009",
      "network": "polygon",
      "token": "USDC_address",
      "maxAmountRequired": "1000000",     // atomic units
      "description": "Access to premium API"
    }
  ],
  "error": null
}


On retry with X-PAYMENT header: verify using facilitator or your logic, then return 200 OK and include:

```http
X-PAYMENT-RESPONSE: <base64-encoded JSON receipt>
Full tutorial: x402 Quickstart for Sellers

​
Client (Buyer Side)

  • Send initial request → get 402 + payment info.
  • Build payment per the scheme (client signs, selects token/chain).
  • Retry request adding header: 
      X-PAYMENT: <base64-encoded payload>
  • Receive 200 OK and decode header X-PAYMENT-RESPONSE to confirm payment details.
Full tutorial: x402 Quickstart for Buyers

​
Facilitator (optional)

Provides endpoints such as /verify and /settle for payment payloads. 
POST /verify
{
  "x402Version":1,
  "paymentHeader": "<payload>",
  "paymentRequirements": { … }
}
Facilitators can implement their own logic to verify the payment payload and settle the payment onchain, and they can also choose how and when to settle - some will compile queues of settlements to do later, while others will settle instantly.

​
Key Design Goals and Benefits

  • HTTP-native: Uses standard HTTP codes and headers. No additional protocol layer.
  • Chain and token agnostic: Works across any chain or stablecoin (e.g., USDC).
  • Minimal integration: One-line middleware on the server side, or a few client calls on the buyer side.
  • Micropayments: Low friction and low cost, suitable for per-request pricing.
  • Autonomous agents: AI systems can transact without per-transaction human approval.

​
Known Limitations and Future Directions

  • Use the correct network label (e.g., "polygon-amoy" vs. "polygon"). Mismatches cause payment failures.
  • The protocol is still evolving. Some paid endpoints may require settlement delays.
  • For high-volume usage, consider deferred payment flows: aggregate many calls, then settle in batch.
  • Protocol governance is managed by an open community to prevent vendor lock-in.