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. Polygon facilitators on mainnet and Amoy run x402 v2. See Migration: V1 to V2 if you have an existing V1 integration.

​
1. Components

ComponentRoleExample / note
ClientRequests a resource and paysBrowser, AI agent, mobile SDK
Resource ServerProtects endpoint, issues 402, verifies paymentAPI or web service
FacilitatorOptional verification and settlement layerPolygon: x402.polygon.technology
Payment SchemeDefines chain, token, network, and formate.g., USDC on Polygon via exact 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 with x402Version: 2 and an accepts array.
  3. Client selects a requirement, builds a payment payload, and retries with header PAYMENT-SIGNATURE.
  4. Resource Server verifies the payload (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 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 endpoints with v2 middleware using an x402ResourceServer, a facilitator client, and route config with an accepts array. On first unauthorized request, respond 402 with JSON like: 
{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:80002",
      "maxAmountRequired": "1000",
      "description": "Access to premium API"
    }
  ],
  "error": null
}
On retry with PAYMENT-SIGNATURE header: verify using the facilitator, then return 200 OK and include: 
PAYMENT-RESPONSE: <base64-encoded JSON receipt>
Full tutorial: x402 Quickstart for Sellers

​
Client (Buyer Side)

  • Send initial request → get 402 + payment info.
  • Create an x402Client, register ExactEvmScheme for "eip155:*", and use wrapFetchWithPayment or wrapAxiosWithPayment.
  • Retry request with header: 
    PAYMENT-SIGNATURE: <base64-encoded payload>
  • Receive 200 OK and read PAYMENT-RESPONSE via x402HTTPClient.getPaymentSettleResponse().
Full tutorial: x402 Quickstart for Buyers

​
Facilitator (optional)

Provides endpoints such as /verify and /settle for payment payloads. 
POST /verify
{
  "x402Version": 2,
  "paymentHeader": "<payload>",
  "paymentRequirements": { … }
}
Facilitators verify payment payloads and settle onchain. Some batch settlements; others settle instantly. Polygon facilitator URLs:
  • Amoy: https://x402-amoy.polygon.technology
  • Mainnet: https://x402.polygon.technology

​
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: Middleware on the server side; 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 CAIP-2 network IDs (eip155:80002 for Amoy, eip155:137 for mainnet). V1 strings like "polygon-amoy" cause payment failures on Polygon facilitators.
  • 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.