x402 and HTTP 402

HTTP reserves a status code for payments: 402 Payment Required. RFC 9110 marks it as reserved for future use. x402?An open standard that lets a web server ask for payment with the HTTP status 402 Payment Required, and lets a client pay and ask again. gives it a job. A server answers 402 with what it wants to be paid, the client pays, and the same request goes through.

z402 is a payment scheme for x402. It settles in shielded Zcash. Most of this page is plain x402 v2, which z402 uses as it is: the stock client and server code run unchanged, with one scheme registered. What z402 adds lists the differences.

Who is in the flow

The client never talks to the facilitator to pay. The resource server does, with an API key. That keeps chain access and payment logic out of every API that sells something.

One paid call

1. Ask

   The client sends the request with no payment.

2. Offer

   The server answers 402 and a PAYMENT-REQUIRED header that lists what it accepts.

3. Pay

   The client picks an offer, builds a payment for it, and repeats the request with a PAYMENT-SIGNATURE header.

4. Verify

   The server sends the payment and the offer it matched to the facilitator's /verify. Verify checks and reads. It commits no voucher and credits no deposit.

5. Serve

   If the payment is valid, the server runs its handler. A handler that fails with a status of 400 or more ends the flow here, and nothing is settled.

6. Settle

   The server calls /settle. The facilitator commits the payment. The server returns the handler's response with a PAYMENT-RESPONSE header.

This order, verify then handler then settle, is the x402 authorization flow. z402 uses it and nothing else. The SDK's default is the same, so a z402 scheme sets no paymentFlow key.

The three headers

Each value is the UTF-8 JSON of the object, encoded as standard base64. It is not base64url, and the decoder refuses other characters. A z402 server sends {} as the body of its 402: everything is in the header.

curl -s -D - -o /dev/null http://127.0.0.1:4021/chunk | tr -d '\r' \
  | awk -F': ' 'tolower($1) == "payment-required" { print $2 }' | base64 -d | jq '.accepts[0]'

import { decodePaymentRequiredHeader } from "@x402/core/http";

const res = await fetch("http://127.0.0.1:4021/chunk");
const header = res.headers.get("PAYMENT-REQUIRED");

if (res.status === 402 && header !== null) {
  const required = decodePaymentRequiredHeader(header);
  console.log(required.accepts[0]);
}

The offer: PaymentRequired

A server that wants payment sends one PaymentRequired object.

Each offer is a PaymentRequirements object:

This is a decoded PAYMENT-REQUIRED from the URL to markdown service, with the address shortened and the bazaar schema left out:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://markdown.example.com/v1/markdown",
    "description": "Fetches one public web page and returns its main content as clean markdown.",
    "mimeType": "application/json",
    "serviceName": "URL to markdown",
    "tags": ["web", "markdown", "scrape"]
  },
  "accepts": [
    {
      "scheme": "prepaid-voucher",
      "network": "zcash:regtest",
      "amount": "1000",
      "asset": "ZEC",
      "payTo": "uregtest1...",
      "maxTimeoutSeconds": 60,
      "extra": {
        "windowZat": "100000",
        "creditRatioBps": 2500,
        "creditCapZat": "200000",
        "zeroConfMinExpiryBlocks": 20,
        "termsVersion": "cb7f148af0fda19a"
      }
    }
  ],
  "extensions": {
    "bazaar": {
      "info": {
        "input": { "type": "http", "queryParams": { "url": "https://example.com" }, "method": "GET" },
        "output": { "type": "json", "example": { "title": "Example Domain", "length": 16 } }
      },
      "schema": "..."
    },
    "z402": { "unit": "page" }
  }
}

The payment: PaymentPayload

The client answers with a PaymentPayload in the PAYMENT-SIGNATURE header.

{
  "x402Version": 2,
  "payload": {
    "sessionKey": "7dc02259...2609",
    "cumulativeZat": "1000",
    "sig": "76b6ee6c...4a03",
    "depositTxid": "cd266215...0a50"
  },
  "accepted": { "scheme": "prepaid-voucher", "network": "zcash:regtest", "amount": "1000", "...": "as offered" },
  "resource": { "url": "https://markdown.example.com/v1/markdown" },
  "extensions": { "...": "as offered" }
}

The hex values are shortened. A missing or undecodable PAYMENT-SIGNATURE is not an error to the server: it counts as no payment and gets a fresh 402.

The facilitator

A facilitator exposes three routes to resource servers.

A resource server reads /supported when it starts, and it refuses to start a route whose exact scheme and network the facilitator does not list. For that reason the facilitator starts before the API.

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "prepaid-voucher",
      "network": "zcash:regtest",
      "extra": {
        "windowZat": "100000",
        "creditRatioBps": 2500,
        "creditCapZat": "200000",
        "zeroConfMinExpiryBlocks": 20,
        "termsVersion": "cb7f148af0fda19a"
      }
    }
  ],
  "extensions": ["bazaar"],
  "signers": { "zcash:*": [] }
}

signers is empty because a z402 facilitator signs nothing on chain. The extra of a kind holds the terms that apply to every provider on the rail.

Once it accepts the API key, the z402 facilitator answers every /verify and /settle with HTTP 200, success or not, and puts the outcome in the body. A non-200 answer would leak its body into the client's error, and a /settle answer without transaction makes the stock server return 502.

What the client sees

The stock fetch wrapper returns a refused call as a 402 response. It does not throw, so a loop must check res.status. The wrapper makes one paid attempt, plus one recovery attempt when the scheme's hook asks for it. It never makes a third.

import { decodePaymentResponseHeader } from "@x402/core/http";
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { LightwalletdTxStatus, PrepaidVoucherScheme, ZalletRpcWallet } from "@z402-net/client";
import { createLightwalletdClient } from "@z402-net/lightwalletd";
import { parseSessionSnapshot } from "@z402-net/protocol";

// The endpoints and credentials of the local Z3 regtest stack
const lwd = createLightwalletdClient({ url: "http://127.0.0.1:28137" });
const scheme = new PrepaidVoucherScheme({
  wallet: new ZalletRpcWallet({ url: "http://127.0.0.1:50232", user: "zebra", password: "zebra" }),
  chain: new LightwalletdTxStatus(lwd),
});

const client = new x402Client();
client.register("zcash:regtest", scheme); // the one line that adds Zcash
const paidFetch = wrapFetchWithPayment(fetch, client);

const res = await paidFetch("http://127.0.0.1:4021/chunk");
const receipt = res.headers.get("PAYMENT-RESPONSE");
if (res.status === 200 && receipt !== null) {
  // The receipt carries the session's state next to the outcome
  const settled = decodePaymentResponseHeader(receipt);
  const session = parseSessionSnapshot(settled.extra?.["session"]);
  console.log(`paid ${settled.amount} zat, ${session?.headroomZat} zat of headroom left`);
} else {
  console.log(`refused with ${res.status}`);
}

await scheme.close();
lwd.close();

What z402 adds

Three differences matter when you read the SDK's docs for other schemes.

• Settle moves no money. The money moved earlier, in the agent's deposit. Settle credits that deposit once, records the voucher, and returns the session's state.
• The client keeps state. The scheme remembers a session per provider, serializes calls on it, and decides when to deposit. The stock client only hands it the offer and the outcome.
• A refusal carries data. When verify refuses a voucher, the server scheme adds the session's state to the new 402, as extra.session on the offer. The client reads it to resync and to decide what to do next.

The stock client's spend controls reject an asset that its scheme cannot price. The z402 scheme implements findDefaultAsset for ZEC, so the stock client accepts it.

z402 pins @x402/core, @x402/fetch, @x402/express and @x402/extensions to exactly 2.28.0.

References

• docs/research/x402-spec.md: the v2 objects, header encodings, status codes and facilitator duties, checked against SDK 2.28.0.
• docs/spec/protocol.md: sections 2, 3, 7 and 8, the z402 offer, payload, answers and codes.
• packages/protocol/src/constants.ts: the scheme id, the network ids and the asset.
• packages/server/src/scheme.ts: the server scheme and the corrective 402.
• packages/client/src/scheme.ts: PrepaidVoucherScheme and findDefaultAsset.
• apps/api/src/app.ts: a resource server with one paid route, GET /chunk.
• apps/agent/src/agent.ts: the stock client and the one register line.
• x402 specification v2: the objects and headers.
• x402 HTTP transport: header names, encodings and status codes.
• RFC 9110, 402 Payment Required: the HTTP status code.
• CAIP-2: the network id format.