# facilitator.x402cloud.ai

x402 payment facilitator — verify and settle USDC micropayments on-chain.

## What This Is

A hosted facilitator service for the x402 payment protocol. It verifies Permit2-signed USDC payments and settles them on-chain. Used by x402 middleware to handle payment verification without servers needing private keys.

Supports both exact (fixed-price) and upto (metered) payment schemes.

## Self-Host

This facilitator is also available as a Docker image for self-hosting:
docker run -e FACILITATOR_PRIVATE_KEY=0x... -e RPC_URL=https://mainnet.base.org -e NETWORK=eip155:8453 -p 3000:3000 ghcr.io/x402cloud/facilitator

## Network

- Network: eip155:84532
- Facilitator address: 0x207C6D8f63Bf01F70dc6D372693E8D5943848E88
- Token: USDC
- Schemes: exact, upto

## Endpoints

### GET /health
Health check. Returns {"status":"ok"}.

### GET /supported
Returns supported schemes, networks, and facilitator address. No auth required.

### POST /verify (auth required)
Verify an upto payment payload against requirements.
Request body:
```json
{ "payload": { ... }, "requirements": { ... } }
```
Returns: { "isValid": true } or { "isValid": false, "invalidReason": "..." }

### POST /settle (auth required)
Settle an upto payment on-chain.
Request body:
```json
{ "payload": { ... }, "requirements": { ... }, "settlementAmount": "1000000" }
```
Returns: { "success": true, "txHash": "0x..." } or { "success": false, "errorReason": "..." }

### POST /verify-exact (auth required)
Verify an exact (fixed-price) payment payload against requirements.
Request body:
```json
{ "payload": { ... }, "requirements": { ... } }
```
Returns: { "isValid": true } or { "isValid": false, "invalidReason": "..." }

### POST /settle-exact (auth required)
Settle an exact payment on-chain (full authorized amount).
Request body:
```json
{ "payload": { ... }, "requirements": { ... } }
```
Returns: { "success": true, "txHash": "0x..." } or { "success": false, "errorReason": "..." }

## Integration

Servers use @x402cloud/middleware with a facilitator URL:
```typescript
import { remoteExactPaymentMiddleware } from "@x402cloud/middleware";
app.use("/*", remoteExactPaymentMiddleware(routes, "https://facilitator.x402cloud.ai"));
```

The middleware calls /verify-exact on each request and /settle-exact after successful responses.

## Source

https://github.com/x402cloud/x402cloud