Deployment
How to run the x402interop facilitator.
Components to run
- Facilitator service (HTTP API, quote router, status tracker).
- Database for quotes, receipts, credit accounts, and discovery entries.
- Background workers: status polling, webhook delivery, catalog crawling, health probes.
- Optional: Lightning node or service and a rebalancing worker.
- Optional: relayer wallets that pay origin-chain gas for gasless payments.
Prerequisites
- A NEAR Intents 1Click API key (JWT) from the partner portal. Unauthenticated use works but incurs a 0.2% fee.
- Access to origin-chain RPC endpoints for each enabled corridor.
- Funded relayer wallets (small balances) on each origin chain where the facilitator pays gas.
- A domain with TLS for the public endpoint and webhooks.
Configuration
The canonical template is apps/facilitator/.env.example. Copy it to apps/facilitator/.env; the facilitator start script loads that file automatically with Node’s --env-file-if-exists. Production deployments should inject the same variables through the platform’s secret/configuration manager. Discovery only needs the marketplace’s browser-safe PUBLIC_FACILITATOR_URL.
Each service owns its env file:
apps/facilitator/.envapps/marketplace/.envapps/interop/.env(optional, public URL only)examples/live-canary/.envexamples/resource/.envexamples/agent/.envtests/.env(shared test key only)
Start the local Postgres with the facilitator env file:
docker compose --env-file apps/facilitator/.env up -d --wait
| Variable | Purpose |
|---|---|
FACILITATOR_PORT |
HTTP listen port; defaults to 4020 |
X402INTEROP_API_KEYS |
Comma-separated apiKey=owner marketplace credentials |
FACILITATOR_STORE_PATH |
Local development store path; use PostgreSQL in production |
MARKETPLACE_FEES_JSON |
JSON fee configuration with treasury addresses and atomic amounts |
MARKETPLACE_FREE_LISTINGS |
Set true to allow free listings during testing; cannot be combined with MARKETPLACE_FEES_JSON |
DATABASE_URL |
PostgreSQL connection string for production persistence |
X402INTEROP_INTENTS_CLIENT |
mock, simulator, live, sdk, or auto. mock and simulator stay on this machine. live, sdk, and auto require ONECLICK_API_KEY |
ONECLICK_API_KEY |
Server-side 1Click partner key; never expose it to browsers. Not used by mock or simulator |
SLIPPAGE_BPS |
Slippage tolerance sent to 1Click, in basis points. Default 100 (1%) |
FACILITATOR_CORS_ORIGINS |
Browser origins allowed to call the facilitator. Unset allows the local marketplace and docs site; empty disables CORS |
RATE_LIMIT_WINDOW_MS |
Rate-limit window for quote/verify/settle; defaults to 60000 |
RATE_LIMIT_MAX |
Requests per window per client; leave empty to disable |
EXPOSURE_LIMIT_PER_BUYER |
Atomic-unit on_deposit exposure cap per buyer, per network+asset |
EXPOSURE_LIMIT_PER_SELLER |
Atomic-unit on_deposit exposure cap per seller, per network+asset |
EXACT_FAMILIES |
Comma-separated exact families to load: sui, svm, near, stellar. Only configured families are advertised |
RPC_URL_SUI_MAINNET |
Sui gRPC endpoint used by the exact verifier/settler |
RPC_URL_SOLANA_MAINNET |
Solana RPC endpoint used by the SVM exact signer |
RPC_URL_NEAR_MAINNET |
NEAR RPC endpoint used by the NEAR exact signer |
RPC_URL_STELLAR_MAINNET |
Stellar Soroban RPC endpoint; required for Stellar exact |
RELAYER_KEY_SOLANA_MAINNET |
Solana fee-payer key for exact settlement; leave empty to keep SVM off |
NEAR_RELAYER_ACCOUNT_ID |
NEAR relayer account for sponsored exact settlement |
RELAYER_KEY_NEAR_MAINNET |
NEAR relayer secret key; leave empty to keep NEAR off |
RELAYER_KEY_STELLAR_MAINNET |
Stellar fee-bump signer secret; leave empty to keep Stellar off |
DATABASE_URL is the PostgreSQL connection string used when FACILITATOR_STORAGE=postgres (required when NODE_ENV=production). The facilitator runs the SQL migrations at startup and stores quotes, deposit mappings, consumed nonces, and marketplace listings in PostgreSQL. FACILITATOR_STORE_PATH selects the JSON file store for local development. MARKETPLACE_FREE_LISTINGS=true is a testing switch; switch it off and configure paid fees before opening listings publicly. PUBLIC_FACILITATOR_URL belongs to apps/marketplace/.env, not this file. The names under “Names kept, not read” in the example, including REDIS_URL and BACKUP_BUCKET, are not loaded by the process.
Exact non-EVM rails
Sui, Solana, NEAR, and Stellar use the standard exact scheme. EVM keeps the existing x402interop-evm quote-binding path. /supported only advertises a family when its RPC and signer are configured.
- Sui needs only
RPC_URL_SUI_MAINNET; the buyer signs a complete transaction and the facilitator dry-runs and executes it over gRPC. - Solana needs a fee-payer key in
RELAYER_KEY_SOLANA_MAINNETand a small SOL balance. - NEAR needs
NEAR_RELAYER_ACCOUNT_IDplus a funded relayer key inRELAYER_KEY_NEAR_MAINNET. - Stellar needs a mainnet Soroban RPC URL and a funded fee-bump signer in
RELAYER_KEY_STELLAR_MAINNET.
Exact non-EVM supports on_deposit, on_success, and pending_push:
on_deposit:settleis deliverable as soon as the origin deposit is seen, or after the exact origin transaction executes.on_success: deliverable only after 1Click reportsSUCCESS.pending_push: the seller should return202and poll/interop/status/:id; deliverable only after success.- Refunds are automatic on the 1Click path to the quote’s
refundTo;/interop/status/:idexposes the refund state and address. Exact payments are non-custodial and refund on the origin chain. - Rate limits and exposure caps are in-process. Use a shared store such as Redis before running multiple facilitator instances.
Corridor caveats
- NEAR destination: 1Click now quotes a direct
DESTINATION_CHAINtransfer to an existing.nearaccount, and x402Interop always uses that route. The recipient account must exist; the direct quote includes a withdrawal fee for the finalft_transfer. NEAR as an origin is not quoted. - BNB Chain: 1Click applies a temporary minimum swap amount. On 5 November 2026 the API advertised $1,000; $1,000 and $1,000.01 failed, while $1,001 quoted in both directions. Do not hardcode the threshold; surface 1Click’s error and re-test. The x402 catalogue lists only BNB native on
eip155:56, so a BSC stablecoin is not a seller asset until a catalogue row is added. - Stellar: a destination needs a USDC trustline; Stellar as an origin currently fails with
Incorrect depositMode. - Monad: 1Click returns
Internal server error. - Check the 1Click route matrix before adding a corridor. The 1Click swap lifecycle documents the quote, deposit, status, and refund sequence.
Seller-side PAYMENT_REQUIRED_BODY=auto is the default: browsers get the full JSON requirements in the body, while API clients get the minimal x402.org-style {"error":"Payment required"} body. json forces full JSON for every client, error forces minimal, and empty omits the body. The full requirements are always in the PAYMENT-REQUIRED header.
There is no NEAR Intents testnet; every live send is a real mainnet transfer.
Rollout plan
- Single corridor, small amounts. For example Base to Sui. There is no NEAR Intents testnet, so use real funds in tiny amounts.
- Measure settlement times and failures; fill 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.
Monitoring
- Quote mint rate, success rate, and median/p95 settlement time per corridor.
- Refund and failure rate.
- Stuck swaps older than the quote
timeEstimateplus a safety margin. - Relayer balances and gas spend.
- Webhook delivery failures.
Backups and recovery
- Back up the database regularly; receipts and quote records are the audit trail.
- On restart, workers must resume polling all non-terminal swaps.
- Document key rotation and incident response before going live.
Hostnames and local HTTPS
Four sites, one set of routes in production and locally:
| Site | Production | Local (through Caddy) |
|---|---|---|
| Main project site | x402interop.xyz |
x402interop.localhost:8443 |
| Marketplace | marketplace.x402interop.xyz |
marketplace.x402interop.localhost:8443 |
| Docs | docs.x402interop.xyz (served from /docs) |
docs.x402interop.localhost:8443 |
| Facilitator API | facilitator.x402interop.xyz |
facilitator.x402interop.localhost:8443 |
*.localhost names resolve to your own machine in current browsers, so local HTTPS needs no DNS or hosts-file change. Each app keeps its own .env.example. Copy it to .env and use the local values.
Run the local edge. The proxy container reaches your services through the Docker host, so the marketplace and docs previews must listen on all interfaces:
pnpm --filter marketplace build && pnpm --filter marketplace preview:proxy
pnpm --filter interop build && pnpm --filter interop preview:proxy
docker compose --profile proxy up -d
Trust the local certificate once. Caddy signs local sites with its own root, so the browser warns until you trust it:
docker cp x402interop-proxy:/data/caddy/pki/authorities/local/root.crt ./caddy-local-root.crt
Install that file in your operating system or browser trust store. Delete it afterwards if you don’t need it.
Restart the facilitator with the local origins. It reads FACILITATOR_CORS_ORIGINS and MARKETPLACE_DOMAIN from its .env, so set the local values from apps/facilitator/.env.example and restart it. Until then, the marketplace cannot call it from its local HTTPS origin.
Check the local edge. The Astro apps inline PUBLIC_* at build time, so the marketplace and the docs site must be built from the local values in their .env.example files, not from 127.0.0.1 ports. The facilitator must allow https://marketplace.x402interop.localhost:8443.
pnpm --filter facilitator start
pnpm --filter marketplace build && pnpm --filter marketplace preview:proxy
pnpm --filter interop build && pnpm --filter interop preview:proxy
docker compose --profile proxy up -d
curl -kI https://x402interop.localhost:8443/
curl -kI https://marketplace.x402interop.localhost:8443/
curl -kI https://docs.x402interop.localhost:8443/
curl -kI https://facilitator.x402interop.localhost:8443/health
curl -kI https://x402interop.localhost:8443/docs
The first four answers are 200. The last is 301 to https://docs.x402interop.localhost:8443/docs. The docs root itself opens /docs/intro. Trust Caddy’s local root, as above, or curl -k will warn and the browser will too.
Production, once x402interop.xyz has DNS. deploy/Caddyfile.production serves the built sites from disk and reverse-proxies the facilitator. Set ACME_EMAIL and the three build roots in the deploy environment, and point DNS for all four hosts at the server. Leave that file in place even if the domain is not registered yet.
Railway, using Railway’s own hostnames. deploy/Caddyfile.railway is the same four sites. Railway’s edge already terminates TLS and sets PORT, so this file does not request a certificate and does not mention x402interop.xyz. Run Caddy as one service. Keep the interop app, the marketplace, and the facilitator as private services in the same project, and set:
| Variable | Value |
|---|---|
SITE_HOST |
x402interop.up.railway.app |
DOCS_HOST |
x402interop-docs.up.railway.app |
MARKETPLACE_HOST |
x402interop-marketplace.up.railway.app |
FACILITATOR_HOST |
x402interop-facilitator.up.railway.app |
INTEROP_UPSTREAM |
x402interop.railway.internal:$PORT |
MARKETPLACE_UPSTREAM |
x402interop-marketplace.railway.internal:$PORT |
FACILITATOR_UPSTREAM |
x402interop-facilitator.railway.internal:$PORT |
These public names are the ones to request. Each Railway-provided name is a single label under up.railway.app, so docs.x402interop.up.railway.app cannot be issued. The dotted form (docs.x402interop.xyz) waits for the custom domain. Docs is a second public name on the edge for the same site service. $PORT is the port that private service listens on.
Rebuild the Astro apps with https:// plus those hosts (PUBLIC_SITE_URL, PUBLIC_DOCS_URL, PUBLIC_FACILITATOR_URL, PUBLIC_MARKETPLACE_URL). Set FACILITATOR_CORS_ORIGINS to https:// plus MARKETPLACE_HOST. Railway only sends a hostname to this container when the hostname is attached to the Caddy service. Another service’s generated *.up.railway.app name stays on that service. Attach all four public names to the Caddy service, or publish each app on its own Railway URL and do not put this file in front.