SettleGrid x402 facilitator

What is an x402 facilitator?

The x402 protocol turns HTTP 402 Payment Required into a real settlement primitive: a tool returns 402 with a payment offer, the buyer's client signs an EIP-3009 authorization, and a facilitator verifies the signature and settles the on-chain transfer, waiting for a confirmed receipt before reporting success. SettleGrid runs one of these facilitators publicly — anyone can point their tool at https://facilitator.settlegrid.ai and have x402 payments cleared without standing up their own gas wallet, RPC subscription, or signature-verification stack.

Endpoints

Three endpoints under /v1 per the x402 v2 facilitator spec.

• POSThttps://facilitator.settlegrid.ai/v1/verify

  Validate an x402 payment payload (signature, nonce, balance, time window) without settling.

  curl -sS -X POST https://facilitator.settlegrid.ai/v1/verify \
    -H "Content-Type: application/json" \
    -d '{
      "paymentPayload": {
        "scheme": "exact",
        "network": "eip155:8453",
        "payload": { /* EIP-3009 transferWithAuthorization fields */ }
      }
    }'

• POSThttps://facilitator.settlegrid.ai/v1/settle

  Verify, then submit the settlement transaction on-chain via the SettleGrid gas wallet. Idempotent on payload SHA-256.

  curl -sS -X POST https://facilitator.settlegrid.ai/v1/settle \
    -H "Content-Type: application/json" \
    -d '{
      "paymentPayload": {
        "scheme": "exact",
        "network": "eip155:8453",
        "payload": { /* ... */ }
      },
      "paymentIdentifier": "your-idempotency-key"
    }'

• GEThttps://facilitator.settlegrid.ai/v1/supported

  Return the facilitator capabilities envelope (schemes, networks, extensions) per the x402 v2 spec.

  curl -sS https://facilitator.settlegrid.ai/v1/supported

Supported networks

Base mainnet and Base Sepolia on day one. We will add networks only after running an end-to-end settle from outside our development environment — the supported list is a guarantee, not a roadmap.

Calling an x402-protected endpoint

On the consumer side, use @settlegrid/client to call any x402-protected URL. The client intercepts the tool's 402 response, constructs the EIP-3009 signature with your wallet, and retries — the tool's own backend is what calls the facilitator to verify and settle, so this URL doesn't appear in your code:

import { createSettleGridClient } from '@settlegrid/client'

const client = createSettleGridClient({
  wallets: {
    x402: { /* viem wallet client on Base */ },
  },
  defaultMaxCostCents: 50,
})

const res = await client.call('https://api.example.com/some-tool', {
  method: 'POST',
  body: JSON.stringify({ query: 'hello' }),
})
console.log(await res.text())

On the tool-author side (the surface that does talk to the facilitator), point your @settlegrid/mcp wrap config at facilitatorUrl: 'https://facilitator.settlegrid.ai' when initializing the x402 adapter. See the adapter source for the option shape.

Report a bug

Open an issue at github.com/lexwhiting/settlegrid/issues with the request body, the timestamp (UTC), and the network. We respond on weekdays within 24 hours; for outage reports, ping founder@settlegrid.ai directly so it doesn't sit in the issue queue.