xpay Facilitator

xpay operates a public x402 facilitator service at https://facilitator.xpay.sh. It handles USDC payment verification and settlement on Base, supporting both mainnet and testnet.

What is a Facilitator?

In the x402 protocol, a facilitator is a trusted intermediary that:

1. Verifies payment authorizations are valid and well-formed
2. Settles payments by submitting transferWithAuthorization (EIP-3009) transactions on-chain
3. Reports which networks and tokens it supports

The facilitator never holds or custodies funds. Payments flow directly from buyer to seller via signed USDC authorization.

Endpoints

Base URL: https://facilitator.xpay.sh

GET /health

Returns the service status.

curl https://facilitator.xpay.sh/health

{
  "status": "ok"
}

GET /supported

Returns the networks and x402 protocol versions supported by this facilitator.

curl https://facilitator.xpay.sh/supported

{
  "supportedNetworks": [
    { "networkId": "eip155:8453", "version": "v2" },
    { "networkId": "eip155:84532", "version": "v2" },
    { "networkId": "base", "version": "v1" },
    { "networkId": "base-sepolia", "version": "v1" }
  ]
}

POST /verify

Verifies that a payment authorization is valid without executing it. Use this to confirm a buyer’s payment before granting access to a resource.

Request body: The x402 payment payload (as specified by the x402 protocol).

curl -X POST https://facilitator.xpay.sh/verify \
  -H "Content-Type: application/json" \
  -d '{ "payment": "...", "paymentPayload": { ... } }'

Response:

{
  "valid": true
}

Or on failure:

{
  "valid": false,
  "reason": "Payment authorization expired"
}

POST /settle

Settles a verified payment by submitting the transferWithAuthorization transaction on-chain. The USDC transfers directly from the buyer’s wallet to the seller’s wallet.

Request body: The x402 payment payload.

curl -X POST https://facilitator.xpay.sh/settle \
  -H "Content-Type: application/json" \
  -d '{ "payment": "...", "paymentPayload": { ... } }'

Response:

{
  "settled": true,
  "txHash": "0x..."
}

Supported Networks

Using the xpay Facilitator

In a Paywall Server

When building an x402-powered API, point your server to the xpay facilitator for payment verification and settlement:

import { wrapWithPaywall } from '@x402/express'
 
const app = express()
 
app.use(
  '/api/premium',
  wrapWithPaywall({
    price: '$0.10',
    network: 'base',
    facilitatorUrl: 'https://facilitator.xpay.sh',
    receivingAddress: '0xYourWalletAddress',
  })
)

In a Client

When making requests to x402-protected resources, the facilitator URL is provided in the 402 response. Your client library handles the rest:

import { withX402 } from '@x402/fetch'
 
const client = withX402(fetch, {
  walletPrivateKey: process.env.WALLET_KEY,
})
 
// The client automatically pays via the facilitator specified in the 402 response
const response = await client('https://api.example.com/premium-data')

Testing on Sepolia

Use Base Sepolia for development and testing. The xpay facilitator supports Sepolia with no configuration changes - just use Sepolia USDC and a Sepolia wallet.

app.use(
  '/api/test',
  wrapWithPaywall({
    price: '$0.01',
    network: 'base-sepolia',
    facilitatorUrl: 'https://facilitator.xpay.sh',
    receivingAddress: '0xYourTestWallet',
  })
)

Comparison with Other Facilitators

Rate Limits

• Verify: 100 requests/minute
• Settle: 50 requests/minute
• Health/Supported: No limit

Learn more about the x402 Protocol or explore the Paywall Service to monetize your APIs.