Skip to main content
HTTP 402, “Payment Required,” was reserved in HTTP/1.1 in 1997. No one implemented it. Internet commerce grew on top of card networks, and payment remained a separate layer on top of HTTP rather than part of the protocol itself. x402 implements it. When a server gates a resource behind payment, it returns a 402 with a machine-readable payload describing the price, accepted assets, and which network to pay on. The client reads those terms, signs a payment, and retries the request with the signed payload attached. No human clicks checkout. No pre-existing account is required between client and server.

​
Actors

Three roles participate in every x402 flow:
  • Client: the agent or application requesting the protected resource. The client signs the payment and retries the request.
  • Resource server: the server protecting the resource. It issues the 402, checks the payment, and returns the response only after the check passes.
  • Facilitator: a trusted third party that validates payment payloads and submits settlements on the resource server’s behalf. The resource server configures which facilitator to use. The client never contacts the facilitator directly.

​
The 402 response

When the resource server requires payment, it returns a 402 status with a PaymentRequirements payload. In x402 version 1, this arrives as a JSON body. In version 2, it comes as a base64-encoded payment-required response header. The payload contains an accepts array listing the payment options the server accepts. The client picks the option that matches its configured scheme and network, then constructs a signed payment from those terms. 
{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "4mica-credit",
      "network": "eip155:8453",
      "maxAmountRequired": "1000000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xRecipientAddress",
      "resource": "https://api.example.com/data",
      "description": "Access to premium market data",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 300
    }
  ]
}

​
Payment requirements fields

tokens are identified by their contract address in the asset field. identifies the blockchain network in the network field.
FieldTypeDescription
schemestringPayment scheme. 4mica-credit for 4Mica guarantee flow; exact for direct transfer.
networkstringCAIP-2 chain identifier. eip155:8453 for Base mainnet.
maxAmountRequiredstringMaximum amount charged, in token base units.
assetstringERC-20 token contract address for the settlement asset.
payTostringRecipient wallet address.
resourcestringURL of the protected resource.
descriptionstringHuman-readable description of what the resource provides.
mimeTypestringMIME type of the response the client receives after paying.
maxTimeoutSecondsnumberMaximum seconds allowed between the client signing and settlement completing.
extraobjectOptional scheme-specific data, including V2 validation policy fields.
The server decides which schemes, networks, and prices to advertise. The client decides which options it can fulfill. The accepts array lists options; neither side is locked into a single payment method.

​
The general flow

If the client has payment requirements cached from a previous call to this resource, it can skip the initial 402 exchange and attach the signed payment to the first request directly.

​
The 4Mica credit flow

When the scheme is 4mica-credit, the payment is a signed guarantee backed by collateral held in 4Mica Core, not a direct on-chain token transfer.

​
The guarantee

The guarantee is a signed claim: the payer commits to a specific amount, recipient, asset, and request identifier. The resource server submits that claim to the facilitator at /settle. The facilitator passes it to Core, which locks the corresponding collateral and returns a BLS certificate. Each guarantee carries a unique reqId. Reusing the same signed identity is rejected, which ties every guarantee to one request and prevents replay. The BLS certificate is the payment authorization and settlement evidence. Payable guarantees enter clearing cycles, where obligations are netted before on-chain settlement.

​
Why not settle on-chain per request

The standard exact scheme settles every request with an individual on-chain transaction. That works at low volume. At the request rates agents generate, per-request chain writes exhaust block space and add settlement latency to every call. The 4mica-credit scheme separates authorization from settlement. The guarantee is an off-chain cryptographic commitment that signs and verifies in milliseconds, with no chain write required per request. Obligations accumulate across all participants and net in a clearing cycle. Only the net amounts settle on-chain.

​
Payment headers

HeaderDirectionContents
payment-requiredServer → ClientBase64-encoded JSON with x402Version, error, and accepts array (v2).
X-PAYMENTClient → ServerBase64-encoded PaymentPayload with signed guarantee (v1).
PAYMENT-SIGNATUREClient → ServerSigned payment for v2 flows.
payment-responseServer → ClientBase64-encoded settlement receipt on a successful 200 response.

​
Verify vs settle

POST /verify checks the payment payload without issuing a guarantee or contacting Core. Use it as a preflight before doing expensive work. If it fails, return a new 402 with the reason rather than a 400. POST /settle validates and submits the guarantee to Core. The facilitator returns the BLS certificate on success. Call this once you are ready to accept the guarantee as payment. For inexpensive resources, skip /verify and call /settle directly. For compute-heavy or high-value responses, verify first to avoid doing work for a payment that fails.

​
Builder guidance

As a resource server:
  • Return the 402 response before doing any work. Never serve content before the payment is verified.
  • Set maxAmountRequired in token base units: for USDC (6 decimals), $1.00 is "1000000".
  • Set maxTimeoutSeconds to the time you are willing to wait between the client signing and your /settle call. 300 seconds is a reasonable starting point.
  • Persist the BLS certificate from /settle and connect it to the request and delivery record.
As a client:
  • Generate a unique reqId for every guarantee. Never reuse a signed request identity.
  • If the server returns a new 402 on the retry, read invalidReason before signing again.
See Transaction lifecycle for how guarantees move through Core and into clearing cycles.