Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt

Use this file to discover all available pages before exploring further.

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.