Architecture

System Overview

┌──────────┐     ┌──────────┐     ┌─────────────┐     ┌──────────────┐
│  Client   │────▶│  Server  │────▶│ Facilitator │────▶│    Chain     │
│(x402-fetch)│◀───│(middleware)│◀───│  (OpenX402) │◀───│(Base/Mon/Sol)│
└──────────┘     └──────────┘     └─────────────┘     └──────────────┘

Components

Client (x402-fetch)

The client library wraps the standard fetch API. When it receives a 402 Payment Required response, it:

1. Parses the payment requirements from the response headers
2. Signs a payment authorization using the client's private key
3. Retries the request with payment headers

EVM (Base): Signs an EIP-3009 transferWithAuthorization — the client never sends a transaction, only signs an authorization that the facilitator later executes on-chain.

Solana: Builds and signs an SPL Token TransferChecked instruction. The facilitator acts as fee payer and submits the transaction.

Server (x402 Middleware)

The server uses x402-express, x402-hono, or similar middleware to protect routes. The middleware:

1. Checks incoming requests for payment headers
2. If no payment is present, returns 402 Payment Required with payment requirements
3. If payment headers are present, forwards them to the facilitator's /verify endpoint
4. On successful verification, allows the request through to the route handler
5. After serving the response, calls the facilitator's /settle endpoint to execute the payment

Facilitator (OpenX402)

The facilitator is the core of the system. It is served from a globally distributed edge network across 300+ locations at facilitator.openx402.ai for lower latency to your server. It handles:

• Verification — validates that the signed authorization matches the payment requirements (correct amount, recipient, asset, non-expired, valid signature)
• Settlement — executes transferWithAuthorization on the USDC contract (EVM) or submits the signed SPL transaction (Solana)
• Nonce Management — tracks used nonces in a durable store to prevent replay attacks
• Rate Limiting — prevents abuse (10 settle requests per minute per payer)
• Discovery — optional extension for sellers to register their resources
• Whitelist — payment receiver addresses must be registered

Settlement Index

OpenX402 indexes successful settlements directly inside the facilitator edge runtime. There is no separate always-on indexer service required for scanner data.

Indexed chains:

• Base — settlement records written at settle-time
• Monad — settlement records written at settle-time
• Solana — settlement records written at settle-time

Scanner

The web frontend at openx402.ai provides a real-time view of x402 transactions across chains, powered by the facilitator's built-in settlement index.

Payment Flow (Detailed)

Client                 Server                Facilitator           Chain
  │                      │                       │                   │
  │  GET /resource       │                       │                   │
  │─────────────────────▶│                       │                   │
  │                      │                       │                   │
  │  402 + requirements  │                       │                   │
  │◀─────────────────────│                       │                   │
  │                      │                       │                   │
  │  Sign authorization  │                       │                   │
  │  (local, no tx)      │                       │                   │
  │                      │                       │                   │
  │  GET /resource       │                       │                   │
  │  + payment headers   │                       │                   │
  │─────────────────────▶│                       │                   │
  │                      │  POST /verify         │                   │
  │                      │──────────────────────▶│                   │
  │                      │  { isValid: true }     │                   │
  │                      │◀──────────────────────│                   │
  │                      │                       │                   │
  │  200 + resource      │                       │                   │
  │◀─────────────────────│                       │                   │
  │                      │  POST /settle         │                   │
  │                      │──────────────────────▶│                   │
  │                      │                       │  transferWith     │
  │                      │                       │  Authorization()  │
  │                      │                       │──────────────────▶│
  │                      │                       │  tx confirmed     │
  │                      │                       │◀──────────────────│
  │                      │  { success, txHash }  │                   │
  │                      │◀──────────────────────│                   │

Supported Networks

Security Model

• The client's private key only signs authorizations — it never sends transactions (on EVM; on Solana the facilitator submits)
• The facilitator's private key is a hot wallet that pays gas and executes settlements
• Funds flow directly from payer to recipient — the facilitator never custodies funds
• Nonces are tracked in a durable nonce store to prevent replay attacks
• Signature verification happens off-chain before settlement to avoid wasting gas on invalid payments
• Whitelist ensures only registered receivers can accept payments