Skip to main content

​
The x402 protocol

x402 uses HTTP status code 402 Payment Required to signal that content requires payment. When an AI agent hits a gated URL, the server returns a 402 response with payment instructions instead of content.

​
Payment flow

1

Gate creation

An AI agent requests a URL. The server detects the bot (via User-Agent), calls the Xenarch API to create a payment gate, and returns HTTP 402 with gate details: price, splitter contract address, publisher wallet, and a verify URL.
2

On-chain payment

The agent approves USDC and calls split(collector, amount) on the Xenarch splitter contract. The contract transfers USDC directly to the publisher wallet (minus any platform fee). A Split event is emitted on-chain.
3

Payment verification

The agent sends the transaction hash to the verify endpoint. Xenarch fetches the tx receipt from Base, parses the Split event, confirms the amount and recipient match, and returns a time-limited HMAC access token.
4

Content access

The agent re-requests the URL with Authorization: Bearer <access_token>. The server validates the token locally (no API call needed) and returns the content.

​
What each party does

​
Publisher (server-side)

  1. Register on Xenarch, add your site, set pricing
  2. Install middleware (Python SDK, WordPress plugin, or Cloudflare Worker)
  3. Middleware handles bot detection, gate creation, and token verification automatically

​
Agent (client-side)

  1. Request a URL, receive HTTP 402
  2. Parse the 402 response for payment details
  3. Send USDC on Base via the splitter contract
  4. Submit tx hash, receive access token
  5. Re-request with the token
Or use the SDK/MCP server and the flow is handled automatically.

​
Architecture

┌─────────┐     HTTP 402      ┌──────────────┐
│  Agent   │ ───────────────→ │  Publisher    │
│          │ ←─────────────── │  (middleware) │
│          │                  └──────┬───────┘
│          │                         │ create gate
│          │                  ┌──────▼───────┐
│          │                  │   Xenarch    │
│          │                  │   Platform   │
│          │                  └──────────────┘
│          │
│          │   USDC transfer   ┌──────────────┐
│          │ ────────────────→ │  Splitter    │
│          │                   │  Contract    │
│          │                   └──────┬───────┘
│          │                          │ split to publisher
│          │                   ┌──────▼───────┐
│          │                   │  Publisher   │
│          │                   │  Wallet      │
│          │                   └──────────────┘
│          │
│          │   verify tx_hash  ┌──────────────┐
│          │ ────────────────→ │   Xenarch    │
│          │ ←──────────────── │   Platform   │
│          │   access_token    └──────────────┘
└─────────┘

​
Security model

  • Non-custodial: Xenarch never holds funds. USDC goes directly from agent to publisher via the splitter contract.
  • On-chain verification: Every payment is verifiable on Basescan. No trust required.
  • Immutable fee cap: The splitter contract has a MAX_FEE_BPS = 99 constant (0.99%) that cannot be changed after deployment.
  • Replay protection: Each transaction hash can only be used once per gate. Duplicate submissions return the cached token.
  • Token expiry: Access tokens expire after 30 minutes by default. Tokens are HMAC-signed and verified locally by the publisher’s middleware — no API call needed.