x402 Facilitator

Introduction

In an x402 flow, a resource server answers unpaid requests with 402 Payment Required and a set of payment terms. The client signs an EIP-3009 TransferWithAuthorization and retries with the signed payload. The resource server then forwards that payload to a facilitator — this service — which validates it against on-chain state and, on request, settles it by broadcasting transferWithAuthorization to the USDC contract.

The resource server never touches a private key, an RPC endpoint, or any chain-specific logic. The facilitator exposes exactly two payment operations:

Deployed verify-only, the service holds no keys at all. Deployed with a wallet, the key stays on your machine — settlement is gasless for the payer by design of EIP-3009.

Quickstart

Requires Python 3.12+. The service is configured entirely through environment variables.

# Install
git clone <repo-url> && cd x402-facilitator
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Configure
cat > .env << 'EOF'
WALLET_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
NETWORKS=eip155:11155111=https://sepolia.drpc.org
EOF

# Run — export env so it survives --reload restarts
set -a && source .env && set +a
uvicorn x402_facilitator.app:create_app --factory --host 127.0.0.1 --port 8788

Confirm the facilitator is up and see which scheme/network pairs it registered:

curl http://localhost:8788/supported

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:11155111",
      "extra": {
        "name": "USDC",
        "version": "2",
        "assetTransferMethods": ["eip-3009"]
      }
    }
  ],
  "extensions": [],
  "signers": {}
}

Open http://localhost:8788/ in a browser with MetaMask or Rabby installed for a full end-to-end wallet flow: connect, sign an EIP-3009 authorization, verify, and settle on Sepolia.

Configuration

All configuration is read from the process environment at startup. Two formats are supported for declaring networks.

Environment variables

Example

WALLET_PRIVATE_KEY=0xabc123…
NETWORKS=eip155:11155111=https://sepolia.drpc.org,eip155:84532=https://sepolia.base.org

API Reference

Validate a payment payload without any on-chain state change. This is the endpoint a resource server calls before serving paid content — a valid response means the signature is authentic, the terms match, the window is live, the nonce is fresh, and the payer holds sufficient USDC.

Request body

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": { "url": "https://api.example.com/data" },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:11155111",
      "amount": "1000000",
      "asset": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "payTo": "0xMerchant…",
      "maxTimeoutSeconds": 60
    },
    "payload": {
      "signature": "0x5f3a…",
      "authorization": {
        "from": "0xPayer…",
        "to": "0xMerchant…",
        "value": "1000000",
        "validAfter": "1754000000",
        "validBefore": "1754000060",
        "nonce": "0x9c1e…"
      }
    }
  },
  "paymentRequirements": { /* same terms as accepted */ }
}

Response

{
  "isValid": true,
  "invalidReason": null,
  "payer": "0x7a3F8c2D91eB4f5A6c0E3d7F1b9A8b2E4c5D6e7F"
}

Failure reasons

invalidReason is one of the following, in the order the checks run:

Execute on-chain settlement. The facilitator signs and broadcasts transferWithAuthorization to the USDC contract from its own EOA, paying gas itself; the payer's USDC moves directly to payTo. The request body is identical to /verify.

Response

{
  "success": true,
  "errorReason": null,
  "payer": "0x7a3F8c2D91eB4f5A6c0E3d7F1b9A8b2E4c5D6e7F",
  "transaction": "0x9f2c…a41b",
  "network": "eip155:11155111",
  "amount": "1000000"
}

Discovery endpoint. Returns every (scheme, network) pair the facilitator registered at startup, plus protocol extensions and signer addresses. Resource servers should call this at boot to confirm their intended network is active.

Bazaar discovery. Returns the discoverable x402-enabled resources served through this facilitator. Currently returns an empty set ({ "resources": [] }); the shape is reserved for spec-compliant discovery.

Liveness probe. Returns { "status": "ok" }. Suitable for container health checks and uptime monitors.

Verification pipeline

Every /verify call runs the same ordered checks against the authorization and the chain. The first failure short-circuits the pipeline and becomes the invalidReason.

Replay protection uses an in-memory nonce store scoped per (payer, chain). Because EIP-3009 nonces are single-use on-chain as well, a nonce that passes check 6 can never settle twice — the store exists to fail fast and to protect against repeated verify-then-settle races.

Schemes & networks

Supported schemes

Known USDC deployments

Contract addresses are built in for the chains below; override with FACILITATOR_USDC_<chainId> if needed. A chain is active only when present in NETWORKS.

Error reference

Domain errors are returned with a consistent envelope — an error code plus a human-readable message:

{
  "error": "scheme_not_found",
  "message": "No facilitator for scheme=exact network=eip155:999"
}

Malformed JSON bodies fail FastAPI/Pydantic validation first and return the standard 422 validation detail instead of the envelope above.

Deployment

Docker

docker compose up --build

The compose stack bundles an Anvil fork of Base Sepolia for local end-to-end testing alongside the facilitator service.

Public access via Tailscale Funnel

tailscale serve reset
tailscale funnel --bg --set-path / http://127.0.0.1:8788

The service is then reachable at https://<your-node>.<tailnet>.ts.net/.

Testing

# Unit & integration — 29 tests
pytest tests/ -v

# End-to-end against a local Anvil fork (2 tests)
docker compose up anvil -d
pytest tests/test_e2e.py -v

E2E tests are skipped automatically when no Anvil instance is reachable, so the suite stays green in minimal CI environments.