01 Protocol Pattern

HTTP 402 Paywall

It’s 2028. Priya’s phone agent needs real-time satellite imagery for her farm’s irrigation planner. The API costs 0.001 USDC per call. Her agent doesn’t open a billing dashboard or enter a credit card — it sends a single HTTP request, gets back a 402 Payment Required, signs a payment envelope with her post-quantum key, and re-sends. The image lands in her planner 800 milliseconds later. She never knew it happened.

That’s the x402 paywall — the simplest pattern in switchboard. One middleware, five parameters, and any HTTP route becomes a paid API that agents can call without human intervention.

Play this scene → Read the docs Open simulator

How It Works

Payment Flow

A four-step handshake between caller and gate. No SDK on the caller side — just an HTTP header.

Request → 402 → Sign → Verify → 200

Agent A
caller

GET /agent-only

402

x402 Gate
middleware

accepts[] envelope

Agent A
signs X-PAYMENT

X-PAYMENT header

✓

Verified
200 OK

Metrics

Performance & Config

Performance

Sub-millisecond verification

Signature verification happens in-process with no external calls. A single-thread FastAPI instance handles 4,200+ verified requests/sec.

Throughput	4,200 req/s
P99 Latency	0.8 ms
Overhead vs unguarded	+0.3 ms
Memory footprint	~2 MB

Configuration

Five parameters, done

Point the middleware at a treasury, an asset, a network, a price, and a set of paths. Everything else is handled.

pay_to	treasury address
asset	token contract
network	base-sepolia, lux-c, ...
price	amount per call
paths	['/agent-only']

Implementation

Quick Start

Gate any HTTP route behind on-chain payment in under 10 lines.

from fastapi import FastAPI
from switchboard.x402_middleware import X402Middleware

app = FastAPI()
app.add_middleware(
    X402Middleware,
    pay_to="0xYourTreasury...",
    asset="0x036CbD53842c5426634e7929541eC2318f3dCF7e",  # USDC on Base Sepolia
    network="base-sepolia",
    price="1000",           # 0.001 USDC per call
    paths=["/agent-only"],
)

@app.get("/agent-only")
def agent_only():
    return {"ok": True, "payload": "this cost the caller 0.001 USDC"}

Deep Dive

Signature Verification

The middleware accepts both classical ECDSA and post-quantum signatures. The caller declares which algorithm it used; the gate verifies accordingly.

Accepted Algorithms

Dual-mode by default

ecdsa-secp256k1	default
dilithium3	default
falcon-512	opt-in
sphincs+-256f	opt-in

Wire Format

x402 Standard Envelope

The X-PAYMENT header carries the full x402 envelope: pay_to, asset, network, amount, nonce, deadline, signature_alg, and signature. The gate verifies all fields before passing the request through.

x402.org open standard