Payment Schemes

Payment schemes define the payment semantics for a resource: exact is for fixed-price requests where the buyer authorizes the advertised amount, upto is for single-request usage-based billing where the buyer authorizes a maximum and the seller charges actual usage, and batch-settlement is for high-volume or repeated micropayments where per-request authorizations are accumulated against a reusable channel. Network implementations define how those semantics are encoded for EVM, SVM, TVM (TON), AVM, Stellar, Aptos, Hedera, Keeta, Concordium, NEAR, and XRPL; see SDK Features for current SDK support.

Schemes in a 402 Response

A protected resource advertises one or more payment requirements in its HTTP 402 Payment Required response. The scheme names the payment semantics and network names the network implementation.

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/weather",
    "description": "Weather data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "1000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0xYourEvmAddress",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    },
    {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "1000",
      "asset": "So11111111111111111111111111111111111111112",
      "payTo": "YourSolanaAddress",
      "maxTimeoutSeconds": 60,
      "extra": {
        "feePayer": "EwWqGE4ZFKLofuestmU4LDdK7XM1N4ALgdZccwYugwGd"
      }
    }
  ]
}

Servers register scheme implementations for the networks they advertise. Clients register scheme implementations for the networks they can pay on. When the client receives a 402 response, the SDK selects an accepts entry whose scheme and network match a registered implementation.

Payment flows

Every scheme declares which payment flows it supports per asset transfer method. A payment flow controls when verification and settlement happen relative to the resource handler:

Flow	Verify before handler	Settle before handler	Settle after handler	Description
`authorization`	✅	❌	✅	Verify the authorization signature before serving the response; charge after. Default for all current schemes.
`upfront`	❌	✅	❌	Settle before the handler runs; no after-handler settle. Payment is committed before the resource is served.
`escrow`	❌	✅	✅	Settle before the handler (deposit) and again after (claim). Settle hooks fire once per settle — see Lifecycle Hooks for how to branch on `phase`.

The server resolves the flow from the scheme’s paymentFlows table using the assetTransferMethod in the payment requirements. When the resolved flow is not authorization, the server signals it to clients via extra.paymentFlow in the 402 response. The exact scheme supports both authorization (default) and upfront flows on all networks. Servers opt in per route by setting extra.paymentFlow: "upfront" in the route’s accepts config. The upto and batch-settlement schemes support authorization only.

Specs

For scheme-level payload semantics, see the network-agnostic specifications. Each scheme page links to its currently implemented network specs.

Welcome

Getting Started

Core Concepts

Payment Schemes

Extensions

Advanced Concepts

Guides

Developer Tools

SDK Features

Payment Schemes

Schemes in a 402 Response

Payment flows

Specs

​Schemes in a 402 Response

​Payment flows

​Specs

Schemes in a 402 Response

Payment flows

Specs