Facilitator guide
Run a facilitator that verifies and settles x402interop payments over NEAR Intents.
Create the facilitator
import { createFacilitatorServer } from '@x402interop/facilitator'
const server = await createFacilitatorServer({
intentsClient: new MockOneClickClient(), // or HttpOneClickClient / ResilientOneClickClient
store: new FileStore('./data/facilitator-store.json'),
marketplaceFees: {
registration: [
{ network: 'eip155:8453', asset: 'usdc', amount: '100000', treasury: '0xtreasury' },
],
},
})
server.listen(4030)
Exposed endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/health |
GET | Service health |
/supported |
GET | Supported kinds (scheme × network matrix) |
/verify |
POST | Verify a payment payload |
/settle |
POST | Settle a verified payment |
/interop/quote |
POST | Mint a 1Click quote per request |
/interop/status/:id |
GET | Quote status |
/mcp |
POST/GET | MCP discovery and payment tools |
/mcp/tools |
GET | List MCP tools |
Configuration
The canonical template is apps/facilitator/.env.example. Copy it to apps/facilitator/.env. Key variables:
| Variable | Purpose |
|---|---|
FACILITATOR_PORT |
HTTP listen port; defaults to 4020 |
X402INTEROP_API_KEYS |
Comma-separated apiKey=owner marketplace credentials |
MARKETPLACE_FEES_JSON |
Paid listing fees with treasury addresses and atomic amounts |
MARKETPLACE_FREE_LISTINGS |
Set true to allow free listings during testing; cannot be combined with paid fees |
FACILITATOR_STORE_PATH |
Local dev store path; PostgreSQL in production |
DATABASE_URL |
PostgreSQL connection string for production persistence |
X402INTEROP_INTENTS_CLIENT |
mock, simulator, live, sdk, or auto. simulator needs no API key. mock is the local default. |
ONECLICK_API_KEY |
Server-side 1Click partner key; never browser-exposed |
SLIPPAGE_BPS |
Slippage tolerance sent to 1Click, in basis points. Default 100 (1%) |
PUBLIC_FACILITATOR_URL |
Browser-safe facilitator URL used by the marketplace |
RATE_LIMIT_WINDOW_MS |
Rate-limit window for quote/verify/settle |
RATE_LIMIT_MAX |
Requests per window per client; empty disables |
EXPOSURE_LIMIT_PER_BUYER |
Atomic-unit on_deposit cap per buyer, per network+asset |
EXPOSURE_LIMIT_PER_SELLER |
Atomic-unit on_deposit cap per seller, per network+asset |
EXACT_FAMILIES |
Comma-separated sui, svm, near, stellar; only configured families are advertised |
RPC_URL_SUI_MAINNET |
Sui gRPC endpoint used by the exact verifier/settler |
RELAYER_KEY_SOLANA_MAINNET |
Solana fee-payer key for exact settlement |
NEAR_RELAYER_ACCOUNT_ID |
NEAR relayer account for sponsored exact settlement |
RELAYER_KEY_NEAR_MAINNET |
NEAR relayer secret key |
RPC_URL_STELLAR_MAINNET |
Stellar Soroban RPC endpoint |
RELAYER_KEY_STELLAR_MAINNET |
Stellar fee-bump signer secret |
DATABASE_URL is used when FACILITATOR_STORAGE=postgres (the production default). The app runs the migrations at startup and uses the PostgreSQL store for quotes, deposit mappings, consumed nonces, and marketplace listings. FACILITATOR_STORE_PATH selects the file store for local development.
Non-EVM families use exact; EVM keeps x402interop-evm. /supported only lists a family when its RPC and signer are configured. Exact supports on_deposit, on_success, and pending_push; on_deposit is deliverable when the origin deposit is seen, the other modes wait for SUCCESS. Refund state is exposed on /interop/status/:id; 1Click refunds to refundTo automatically. Rate limits and exposure caps are in-process and need a shared store for multi-instance deployments.
Rollout plan
- Single corridor, small amounts - for example Base to Sui. No NEAR Intents testnet exists, so use real funds in tiny amounts.
- Measure settlement times and failures; fill the test report.
- Add corridors one at a time, confirming each with
GET /v0/tokensfirst. - Enable discovery crawling and registration.
- Enable credit paths (Intents balance, then Lightning) with low caps.