Whitechain x402 Facilitator

What is x402?

x402 is an open payment protocol built on the HTTP status code 402 Payment Required. A server answers an unpaid request with 402 and a machine-readable price. The client, typically an AI agent or another API, signs a payment for exactly that amount and retries the request with a PAYMENT-SIGNATURE header. The server asks a facilitator to verify the signature and, once the response has been produced, to settle it on chain. No accounts, no API keys, no invoices: one HTTP round trip, one on-chain transfer.

The facilitator is the only piece of infrastructure in that loop. This project is that piece for Whitechain: a standard x402 v2 facilitator with /verify, /settle and /supported endpoints, so the official x402 middleware and clients work on Whitechain without modification.

Why Whitechain for agent payments

How a paid request works

1. Agent calls your APIYour x402 middleware answers 402 with the price: token, amount, your payTo, network eip155:1874.
2. Agent signs, retriesThe client signs an EIP-3009 authorization for exactly that amount, valid for a short window, and resends the request with PAYMENT-SIGNATURE.
3. Facilitator verifiesYour middleware POSTs to /verify. The facilitator checks the signature, balance, nonce and expiry, then your handler runs.
4. Facilitator settlesAfter a successful response, /settle submits the authorization on chain. Tokens move from payer to you; the facilitator pays the gas.

Quickstart

Two sides, no contracts to deploy. The merchant adds the official x402 middleware with this facilitator's URL; the agent wraps fetch. Full, runnable versions live in the examples directory.

Merchant: sell an endpoint with Express

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const facilitator = new HTTPFacilitatorClient({ url: "https://x402-facilitator-production-ff5f.up.railway.app" });
const server = new x402ResourceServer(facilitator).register("eip155:1874", new ExactEvmScheme());

const app = express();
app.use(paymentMiddleware({
  "GET /weather": {
    accepts: {
      scheme: "exact",
      network: "eip155:1874",          // Whitechain Sepolia
      payTo: "0xYourMerchantAddress",
      price: {                           // 0.01 ITC (6 decimals)
        asset: "0x2E672dFE33EA977FD064E01aDe7d8c73B3Be7fBB",
        amount: "10000",
        extra: { name: "Inferit Test Credit", version: "1" },
      },
    },
    description: "Current weather, paid per request on Whitechain",
  },
}, server));

app.get("/weather", (_req, res) => res.json({ city: "Lisbon", temperatureC: 24 }));
app.listen(4021);

Hono is the same four lines with @x402/hono; Next.js uses @x402/next. Prices on Whitechain name the token explicitly (address, atomic amount, EIP-712 domain) because the x402 SDK has no "$" default asset for this chain yet.

Agent: pay with fetch

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:1874", client: new ExactEvmScheme(account) }],
  spendControls: {                     // allow the Whitechain token, cap each payment
    allowedAssets: [{ network: "eip155:1874", asset: "0x2E672dFE33EA977FD064E01aDe7d8c73B3Be7fBB", maxAmountPerPayment: "100000" }],
  },
});

const res = await fetchWithPayment("https://api.example.com/weather");
console.log(await res.json());      // paid: 402 -> signed -> 200

The agent needs ITC, not WBT: the facilitator pays the gas. Get test ITC from the token's public faucet and test WBT from the Whitechain faucet only if you run your own facilitator.

Supported networks and tokens

RPC https://rpc.testnet.whitechain.io · Explorer https://explorer.testnet.whitechain.io · Gas token WBT. Networks are configuration, not code: the mainnet entry is a JSON object with the chain id Whitechain publishes, its RPC and its explorer.

HTTP API

The wire format is x402 v2 exactly as @x402/core's HTTPFacilitatorClient sends it. You normally never call these yourself; the middleware does.

Policy refusals keep the x402 body shape with a non-2xx status, so HTTPFacilitatorClient surfaces them as typed errors: unsupported_scheme_network (400), invalid_api_key (401), address_denylisted (403), duplicate_settlement (409), rate_limit_exceeded and gas_budget_exceeded (429, with Retry-After), rpc_unavailable (503). Full request and response examples and the complete reason-code table are in the API reference.

Testnet policy: free, within limits

The public facilitator sponsors every settlement on Whitechain Sepolia. To keep that sustainable it enforces:

• Rate limits per client IP, per payer address and per payTo address (token buckets; defaults 120, 30 and 120 requests per minute), plus a facilitator-wide ceiling of 1,200 per minute.
• A daily gas budget per payTo and a global one, checked on verify as well as settle; a payment beyond the budget is refused with gas_budget_exceeded and a Retry-After that points at the 00:00 UTC reset.
• Optional merchant API keys (X-API-Key) with higher limits and their own budget.
• A sanctions denylist of addresses, sourced from the public OFAC SDN list, checked on both payer and payee.

Nothing is stored about you beyond counters and short-lived rate-limit keys. Signatures are never logged.

Security model

Found a vulnerability? See the security policy.

Roadmap

• Whitechain mainnet: enable the mainnet network entry with USDC.e once Whitechain publishes the chain id and the token is bridged.
• Permit2 and upto: Uniswap Permit2 is already deployed on Whitechain; the x402 Permit2 proxy contracts are not. The repo includes the deterministic-deployment check and script so they can land at their canonical addresses, which unlocks any ERC-20 and the upto (pay-what-you-use) scheme.
• Fees: the fee hook (basis points or flat, in the payment token) is implemented and off by default; mainnet operators can turn it on or run sponsored.
• Bazaar listing and discovery extensions once the ecosystem settles on them.

Built by

Sahil Massey at Inferit, where x402 on Whitechain already pays for open-weight LLM inference per request. The facilitator was split out so any merchant and any agent can use it. Contributions are welcome: see CONTRIBUTING.md.