Skip to main content

The x402 protocol

x402 uses the HTTP status code 402 Payment Required to ask for payment. A gated URL answers with a 402 whose body lists the payments it accepts. The client pays and requests the URL again with proof of payment. Xenarch uses x402 version 1. The 402 body is the version 1 envelope (x402Version: 1 plus an accepts array), followed by Xenarch fields. Xenarch does not send or read the version 2 headers PAYMENT-REQUIRED and PAYMENT-SIGNATURE.

What Xenarch’s 402 looks like

This is the body a gated page returns to a bot. It is the response of POST /v1/gates, passed through by your integration.
402 Payment Required
The WordPress and Joomla plugins and the Cloudflare Worker also send Link, X-Pay-Json and X-Xenarch headers with the 402. They point to the site’s /.well-known/pay.json. See pay.json.

Payment flow

1

Request and 402

An agent requests a gated URL. Your integration detects a bot, calls POST /v1/gates with the site token, and returns the 402 above. People and search crawlers get the page.
2

Sign

The agent signs an EIP-3009 transferWithAuthorization for USDC from its wallet to payTo for maxAmountRequired. The EIP-712 domain is USD Coin, version 2, chain ID 8453. Nothing is sent on chain yet.
3

Settle

The agent posts the signed authorization to a facilitator’s /settle endpoint. The MCP server and the CLI try the listed facilitators in order until one succeeds. The facilitator submits the transfer on Base, pays the gas, and returns the transaction hash. Xenarch never broadcasts a transaction.
4

Retry with proof

The agent requests the URL again with two headers: X-Xenarch-Gate-Id (the gate_id) and X-Xenarch-Tx-Hash (the transaction hash).
5

Verify and serve

Your integration calls POST /v1/gates/{gate_id}/verify with the hash. Xenarch fetches the receipt from Base, checks that the transaction succeeded, finds a USDC Transfer to the gate’s seller wallet for at least the price, and records the payment. Your integration serves the content.

Agents that speak plain x402

An agent that knows only x402 can retry with a standard X-PAYMENT header instead (base64 JSON, x402Version: 1, scheme exact, network base). The WordPress and Joomla plugins and the Cloudflare Worker forward it to POST /v1/gates/{gate_id}/settle-x402. Xenarch hands the authorization to a facilitator from the default stack, then verifies the resulting Transfer the same way.

How access is re-checked

There is no access token. Every retry carries the gate id and the transaction hash, and your integration checks that pair.
  • Idempotent. Verifying the same gate id and transaction hash again returns the same payment record without new on-chain work.
  • One gate per transaction. A transaction hash recorded for one gate is refused for any other gate (HTTP 409).
  • Gate window. An unpaid gate expires 30 minutes after it is created. Verifying a payment against an expired gate returns HTTP 410, and the agent requests the URL again to get a new gate.
  • Caching. The Python middleware and the WordPress plugin cache a successful check for 5 minutes, so repeat requests do not call Xenarch each time.

What each party does

Publisher

  1. Register, add your site, and set prices in the dashboard at dash.xenarch.dev or with the CLI.
  2. Choose which of your verified wallets receives payments. Gates pay that wallet.
  3. Install an integration: WordPress, Joomla, a Cloudflare Worker, or FastAPI middleware. It detects bots, creates gates and verifies payments.

Agent

  1. Request a URL and read the 402 body.
  2. Sign an EIP-3009 USDC authorization to payTo.
  3. Settle it through a listed facilitator.
  4. Request the URL again with X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash.
The MCP server, the CLI and the Python SDK do these steps for you.

Architecture

USDC moves from the agent’s wallet to the seller’s wallet. Xenarch issues gates and verifies payments. It is not in the money path.

Security model

  • Non-custodial. Xenarch never holds funds and has no contract in the payment path.
  • Verified on chain. Xenarch reads each receipt from Base itself, so a facilitator cannot fake a settlement.
  • Seller wallet pinned. Each gate records the wallet it was created for. A later change of receiving wallet does not change where a pending gate pays.
  • Amount checked. A transfer below the gate price is rejected.
  • Replay protection. A transaction hash counts for one gate only.
  • Signed receipts. For gate payments, GET /v1/receipts/{tx_hash} returns an Ed25519-signed receipt. The public key is at https://api.xenarch.dev/.well-known/xenarch-facilitator-key.pem.

FAQ

HTTP 402 is the Payment Required status code. HTTP reserved it in 1997 and left it unused for decades. A server returns 402 to say that a resource needs payment first. Xenarch returns 402 with an x402 body that tells an agent how to pay in USDC on Base.
x402 is an open protocol for paying over HTTP. The server answers 402 with a list of accepted payments. The client signs a USDC transfer authorization (EIP-3009), a facilitator settles it on chain, and the client retries the request with proof of payment. Xenarch uses x402 version 1.
Your WordPress or Joomla plugin, Cloudflare Worker or FastAPI middleware detects bots. A bot without proof of payment gets HTTP 402 with the price and your wallet. The agent pays in USDC through a facilitator and retries with the X-Xenarch-Gate-Id and X-Xenarch-Tx-Hash headers. Your integration confirms the payment with Xenarch and serves the page. People and search crawlers pass free. Prices run from $0 to $1 per request, set per site, per page or per path.
Native USDC on Base mainnet (chain ID 8453), contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. The payment goes from the payer’s wallet to the seller’s wallet through a third-party x402 facilitator that pays the gas. The default facilitators are PayAI, xpay, Mogami, Heurist and Daydreams. Every payment is a USDC Transfer you can look up on Basescan.
Cloudflare pay per crawl is in closed beta for sites on Cloudflare. Cloudflare is the merchant of record: it bills the crawler and pays out to the publisher. With Xenarch the agent pays the publisher’s own wallet in USDC on Base. Xenarch takes no fee and never holds the funds, and gating works on WordPress, Joomla, Cloudflare Workers and FastAPI.