x402 Facilitator

The facilitator verifies payment signatures and settles transactions on-chain, enabling gasless payments for payers.

What is a Facilitator?

In the x402 protocol, a facilitator is a trusted service that bridges signed payment authorizations to on-chain settlement. Payers sign EIP-712 authorizations off-chain, and the facilitator submits the blockchain transaction — paying gas on behalf of the payer.

The facilitator:

1. Receives payment payloads from resource servers
2. Verifies EIP-712 signatures match payment requirements
3. Validates authorization parameters (amounts, time bounds, nonces)
4. Simulates the transaction to catch failures before submission
5. Executes the on-chain transfer
6. Returns settlement confirmation (tx hash, network, payer)

Primer Facilitator

Primer operates a public facilitator for Base, SKALE, and Robinhood Chain networks:

https://x402.primer.systems

Protocol Versions

The facilitator supports both x402 protocol versions:

• v1 — Simple network identifiers ("base", "base-sepolia")
• v2 — CAIP-2 network identifiers ("eip155:8453", "eip155:84532")

Both versions are fully supported. The SDK handles version negotiation automatically.

Supported Networks

API Reference

POST /verify

Verify a payment signature without settling on-chain. Use this to validate payments before granting resource access.

{
  "x402Version": 2,
  "paymentPayload": {
    "payload": {
      "authorization": { ... },
      "signature": "0x..."
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x..."
  }
}

{
  "isValid": true,
  "payer": "0x..."
}

{
  "isValid": false,
  "invalidReason": "invalid_signature",
  "invalidMessage": "Signature verification failed",
  "payer": "0x..."
}

POST /settle

Verify and execute payment on-chain. Returns the transaction hash on success.

{
  "success": true,
  "transaction": "0x...",
  "network": "eip155:8453",
  "payer": "0x..."
}

{
  "success": false,
  "errorReason": "insufficient_balance",
  "errorMessage": "Payer has insufficient token balance",
  "transaction": "",
  "network": "eip155:8453",
  "payer": "0x..."
}

GET /supported

List supported schemes, networks, and extensions.

{
  "x402Version": 2,
  "kinds": ["exact", "upto", "batch-settlement"],
  "extensions": {
    "eip3009": true,
    "permit2": true,
    "smartWallet": true
  },
  "signers": {
    "eip155:8453": ["0x..."]
  }
}

GET /health

Health check and version information.

{
  "status": "healthy",
  "version": "2.0.0",
  "networks": {
    "base": { "configured": true },
    "base-sepolia": { "configured": true },
    ...
  }
}

Batch Settlement Endpoints

Payment Schemes

exact

Per-request settlement where the payer authorizes a specific amount for each request. The most common scheme for simple pay-per-request APIs.

• Payer signs authorization for exact amount
• Server verifies and settles immediately
• Supports EIP-3009, Permit2, and Prism settlement methods

upto

Usage-based payments where the payer authorizes a maximum amount, and the server settles the actual consumption (≤ max). Ideal for metered billing like LLM tokens, compute time, or bandwidth.

• Payer signs authorization for maximum amount
• Server tracks usage during request
• Server settles actual amount consumed
• Uses Permit2 with a Witness containing: to, facilitator, validAfter

batch-settlement

Payment channels for high-frequency, low-value transactions. Payers deposit to an escrow, servers accumulate claims via signed vouchers, and funds are settled periodically.

• Payer deposits funds to channel (one-time gas)
• Server issues vouchers for each request (off-chain)
• Server claims and settles in batches
• Amortizes gas across many transactions

Token Support

EIP-3009 (Native Gasless)

Tokens implementing EIP-3009 support native gasless transfers via transferWithAuthorization. No approval required — the facilitator calls the token contract directly.

Supported tokens: USDC, EURC, PR, USDG

Permit2 (Official x402 Method)

For any ERC-20 token, the facilitator supports Permit2 — Uniswap's universal approval protocol. This is the standard method in the x402 specification.

1. Payer approves Permit2 contract once (one-time gas)
2. Payer signs EIP-712 PermitWitnessTransferFrom for each payment
3. Facilitator calls the appropriate x402 proxy contract

Prism (Primer Extension)

Primer's Prism contract provides an alternative ERC-20 settlement path:

1. Payer approves Prism contract once (one-time gas)
2. Payer signs EIP-712 authorization for each payment
3. Facilitator calls settleERC20() on Prism

The facilitator auto-detects the authorization type and routes accordingly.

Settlement Methods Summary

Smart Wallet Support

The facilitator supports smart contract wallets (account abstraction) via:

• EIP-1271 — On-chain signature validation for deployed wallets
• EIP-6492 — Signature validation for undeployed (counterfactual) wallets

Smart wallet signatures work with EIP-3009 and Permit2 settlement methods. The Prism method requires EOA signatures only.

Contract Addresses

All x402 protocol contracts use deterministic CREATE2 deployment — same address on all EVM chains.

x402 Protocol Contracts

Prism Contract (Primer)

Error Codes

Common error reasons returned by the facilitator:

Integration

The easiest way to integrate x402 payments is via the Primer x402 SDK, which provides preconfigured facilitator clients for use with the official x402 middleware.

import { primerFacilitator } from '@primersystems/x402';
import { paymentMiddleware } from '@x402/express';

const facilitator = primerFacilitator();

app.use(paymentMiddleware({
  '/api/premium': {
    price: '$0.01',
    network: 'eip155:8453',
    payTo: '0xYourWallet'
  }
}, { facilitator }));

See the TypeScript SDK or Python SDK documentation for complete integration guides.