> ## Documentation Index
> Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# How x402 Works
> The HTTP 402 Payment Required protocol that powers faremeter.
x402 is a payment protocol built on the HTTP `402 Payment Required` status code. It enables programmatic payments between any HTTP client and server without accounts, sessions, or custom authentication.
## The payment flow
```
Client Resource Server Facilitator Blockchain
| | | |
|--- GET /resource ------->| | |
| | | |
| |--- POST /accepts ------->| |
| |<-- Enriched requirements | |
| | | |
|<-- 402 Payment Required -| | |
| | | |
| (Client prepares payment)| | |
| | | |
|--- GET + payment header ->| | |
| | | |
| |--- POST /settle -------->| |
| | |--- Submit tx --------->|
| | |<-- Confirmation -------|
| |<-- { success, tx hash } -| |
| | | |
|<-- Protected Resource ---| | |
| | | |
```
Four parties participate in every x402 payment:
* **Client** -- Makes requests and signs payments locally. Never talks to the facilitator directly.
* **Resource Server** -- Protects endpoints with middleware. Makes two API calls to the facilitator (`POST /accepts` and `POST /settle`) but never holds keys or interacts with the blockchain.
* **Facilitator** -- Verifies payment proofs and settles transactions on-chain. Handles all blockchain interaction.
* **Blockchain** -- The settlement layer (Solana or EVM).
### Step by step
**1. Initial request**
The client makes a standard HTTP request to a protected resource.
```
GET /api/data HTTP/1.1
Host: api.example.com
```
**2. Payment required**
The server's middleware calls the facilitator's `/accepts` endpoint with partial payment requirements. The facilitator enriches them with blockchain-specific details:
* **Solana**: Fee payer address, token decimals, recent blockhash
* **EVM**: EIP-712 domain parameters (name, version, chainId, verifyingContract)
The server returns `402 Payment Required` with the enriched requirements in the response body:
```json theme={null}
{
"x402Version": 1,
"accepts": [
{
"scheme": "exact",
"network": "solana-devnet",
"asset": "USDC",
"maxAmountRequired": "10000",
"payTo": "7xKX...",
"resource": "https://api.example.com/api/data",
"description": "API access",
"mimeType": "application/json",
"maxTimeoutSeconds": 60
}
]
}
```
**3. Payment construction**
The client inspects the requirements, selects a compatible payment method, and constructs a payment proof:
* **Solana**: Creates and partially signs a transaction that transfers tokens to the merchant
* **EVM**: Signs an EIP-3009 `transferWithAuthorization` using EIP-712 typed data
The proof is signed locally using the client's wallet. No tokens leave the wallet at this stage.
**4. Retry with payment**
The client retries the original request with the payment proof attached:
```
GET /api/data HTTP/1.1
Host: api.example.com
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwi...
```
The payment header contains a base64-encoded JSON payload with the payment proof. v1 uses `X-PAYMENT`; v2 uses `PAYMENT-SIGNATURE`. See [Protocol Versions](/concepts/protocol-versions) for the full header mapping.
**5. Verification and settlement**
The server's middleware calls the facilitator's `/settle` endpoint with the payment header and the original requirements. The facilitator:
1. Validates the payment payload structure
2. Verifies cryptographic signatures
3. Checks amounts, addresses, and nonces
4. Submits the transaction on-chain:
* **Solana**: Co-signs as fee payer and submits to Solana RPC
* **EVM**: Calls `transferWithAuthorization` on the token contract and pays gas
5. Returns `{ success: true, transaction, network }`
Legacy v1 implementations may return these fields as `txHash` and `networkId`. Spec-compliant v1 and v2 both use `transaction` and `network`. See [Protocol Versions](/concepts/protocol-versions) for details.
**6. Resource delivery**
Once the payment is confirmed, the server returns the requested resource with a `200 OK` response.
If a payment settles but the client loses the connection before receiving the
full response, retrying the request would trigger a second charge. To avoid
this, design your server to grant time-limited access upon payment rather than
delivering the resource in a single response. This lets the client retry or
resume without paying again.
## Payment requirements
A payment requirement describes what the server accepts. Key fields:
| Field | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `scheme` | Payment method (e.g., `"exact"`) |
| `network` | Blockchain network identifier on the wire (e.g., `"solana-devnet"`, `"base-sepolia"`). The `@faremeter/info` helpers accept shorter cluster names like `"devnet"` and expand them automatically. |
| `asset` | Token to pay with (e.g., `"USDC"`) |
| `maxAmountRequired` | Maximum payment amount (in smallest unit) |
| `payTo` | Recipient address |
| `resource` | The URL being paid for |
| `maxTimeoutSeconds` | How long the payment proof is valid |
A server can accept multiple payment methods simultaneously. The client chooses one it can fulfill.
## Payment payload
The `X-PAYMENT` header contains a base64-encoded JSON object:
| Field | Description |
| ------------- | ---------------------------------------------------- |
| `x402Version` | Protocol version (`1` or `2`) |
| `scheme` | Which scheme was used |
| `network` | Which network was used |
| `payload` | Scheme-specific proof (signatures, transaction data) |
## Protocol versions
x402 version 1 sends the payment proof in the `X-PAYMENT` header as a base64-encoded JSON payload. Version 2 uses the `PAYMENT-SIGNATURE` header instead, aligning with the evolving x402 specification. **Version 2 is preferred for new integrations.** Faremeter supports both versions. See the [Protocol Versions](/concepts/protocol-versions) guide for a detailed comparison and migration instructions.
## Further reading
* [Facilitators](/concepts/facilitators) -- How payment verification and settlement works.
* [Payment Schemes](/concepts/payment-schemes) -- The specific payment methods available.