Skip to main content

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.

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: 
{
  "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 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 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:
FieldDescription
schemePayment method (e.g., "exact")
networkBlockchain 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.
assetToken to pay with (e.g., "USDC")
maxAmountRequiredMaximum payment amount (in smallest unit)
payToRecipient address
resourceThe URL being paid for
maxTimeoutSecondsHow 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:
FieldDescription
x402VersionProtocol version (1 or 2)
schemeWhich scheme was used
networkWhich network was used
payloadScheme-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 guide for a detailed comparison and migration instructions.

​
Further reading