> ## 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.

# x402 How It Works

> Conceptual explanation of the x402 protocol: components, payment flow, design goals, and known limitations.

The x402 protocol lets clients pay for HTTP resources (APIs, endpoints, content)
via blockchain transactions (with [fiat support in progress](https://github.com/coinbase/x402/pull/446)).

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

| Component           | Role                                            | Example / note                                                                                                                                                  |
| ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client**          | Requests a resource & pays                      | Browser, AI agent, mobile SDK                                                                                                                                   |
| **Resource Server** | Protects endpoint, issues-402, verifies payment | API or web service                                                                                                                                              |
| **Facilitator**     | Optional verification + settlement layer        | Offloads blockchain logic  [oai\_citation:1‡QuickNode](https://www.quicknode.com/guides/infrastructure/how-to-use-x402-payment-required?utm_source=chatgpt.com) |
| **Payment Scheme**  | Defines chain, token, network, and format       | e.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.

<Tip title="Note">
  Steps 2-3 can be skipped if the client already knows the payment
  requirement ahead of time.
</Tip>

***

## 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:
  ```json theme={null}
  {
    "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](./quickstart-sellers.mdx)

### Client (Buyer Side)

* Send initial request → get 402 + payment info.

* Build payment per the scheme (client signs, selects token/chain).

* Retry request adding header:
  ```http theme={null}
    X-PAYMENT: <base64-encoded payload>
  ```

* Receive 200 OK and decode header X-PAYMENT-RESPONSE to confirm payment details.

Full tutorial: [x402 Quickstart for Buyers](./quickstart-buyers.mdx)

### Facilitator (optional)

Provides endpoints such as `/verify` and `/settle` for payment payloads.

```http theme={null}
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.