Documentation

x402-sandbox is a self-hostable payment gateway: it makes files, folders, and endpoints sellable for USDC over plain HTTP using the x402 protocol. The HTTP 402 Payment Required exchange is the checkout — no accounts, no card processor — so human buyers and AI agents pay the same way.

How a purchase works

A buyer requests a paid URL, e.g. GET /guides/soil.pdf
The gateway answers 402 with a machine-readable quote (price, receiving wallet, network) in the payment-required header
The buyer's client signs a USDC payment authorization and retries the request with an payment-signature header (older clients: X-PAYMENT)
A facilitator verifies and settles it on-chain; the gateway serves the content and returns a settlement receipt in the PAYMENT-RESPONSE header

The buyer needs no gas — payment authorizations are gasless (EIP-3009); the facilitator sponsors settlement.

Quick start (testnet, no real money)

git clone <repo> && cd x402-sandbox
npm install
cp .env.example .env   # set PAY_TO, ADMIN_PASSWORD, IP_SALT
npm start
# → http://127.0.0.1:8402/catalog

Or headless / agent-driven — a declarative config, no prompts:

echo '{"devWallet": true, "products": [
  {"sku":"lib","title":"Library","price":"$0.01","route":"GET /lib/*","contentDir":"./content/lib"}
]}' > setup.json
X402_ADMIN_PASSWORD=a-long-admin-password npm run setup -- --config setup.json --json

Exit codes: 0 ok (idempotent re-runs converge and never clobber secrets), 1 invalid config, 2 missing prerequisites. Secrets pass via environment only — never flags, never the config file.

Architecture in one paragraph

A single Node process (Hono) reads products.json, mints one paid route per product via @x402/hono's payment middleware, and serves everything else free: the store (/catalog), the public sales feed (/feed), these docs, and a Basic-auth admin. Every hit writes one row to SQLite (node:sqlite — zero external dependencies); settlements are recorded from the receipt header. The catalog hot-reloads on change; no restart for product edits.