rmi-backend/plans/x402-multi-facilitator-expansion.md

x402 Multi-Facilitator Expansion Plan

For Hermes: Execute directly — build facilitator modules then integrate.

Goal: Expand x402 payment system from 1 facilitator (PayAI) to 8+ facilitators with smart routing, multi-chain settlement, fiat off-ramp (EUR/SEPA), TRON, Bitcoin, and universal EVM support.

Architecture: Replace the hardcoded FACILITATOR_CONFIGS dict with a modular facilitator registry. Each facilitator is a pluggable module with verify/settle endpoints. A smart router picks the best facilitator per request based on chain, token, amount, health, and cost.

Tech Stack: Python 3.11+, aiohttp, eth_account, FastAPI, Redis

---

Current State (Before)

System: 1 facilitator (PayAI), 7 chains, 2 gateways
Facilitators: FACILITATOR_CONFIGS hardcoded in x402_middleware.py
Verification: Local EIP-712 (primary) + PayAI HTTP (fallback)
Settlement: None (verify only, no on-chain settlement)
Gateway: Base CF Worker + Solana CF Worker

Target State (After)

System: 8+ facilitators, 12+ chains, 4+ gateways
Facilitators: Modular registry with smart routing
Verification: Multi-facilitator with automatic fallback
Settlement: Hosted (CDP, PayAI, AsterPay) + Self-hosted (x402-rs)
Gateway: Base, Solana, TRON, Bitcoin + self-hosted

---

Task Inventory

Phase 1: Facilitator Registry Foundation

Task 1.1: Create facilitator base class and registry

• File: app/facilitators/__init__.py
• File: app/facilitators/base.py
• Abstract base with verify(), settle(), health() methods
• Registry pattern for loading/discovering facilitators

Task 1.2: Create facilitator config schema

• File: app/facilitators/config.py
• YAML/JSON schema for facilitator configuration
• Environment variable mapping
• Health check intervals, timeouts, retry policies

Task 1.3: Create smart router

• File: app/facilitators/router.py
• Routes payments to best facilitator
• Factors: chain support, token support, fees, latency, health
• Automatic fallback when primary fails

Phase 2: Hosted Facilitator Modules

Task 2.1: Coinbase CDP facilitator

• File: app/facilitators/coinbase_cdp.py
• Base + Base Sepolia with instant settlement
• Uses CDP SDK for on-chain USDC settlement
• Verify via CDP API

Task 2.2: PayAI facilitator (refactor existing)

• File: app/facilitators/payai.py
• Extract from x402_middleware.py
• Base, Solana support
• Deferred settlement

Task 2.3: Cloudflare x402 facilitator

• File: app/facilitators/cloudflare_x402.py
• x402.org official facilitator
• Base/Ethereum with deferred settlement
• Used as fallback for Base Sepolia

Task 2.4: BNB Chain Pieverse facilitator

• File: app/facilitators/pieverse.py
• BNB Chain with instant settlement
• USDT, USDC on BSC
• Verify via Pieverse API

Task 2.5: AsterPay facilitator (EUR/SEPA)

• File: app/facilitators/asterpay.py
• European x402 with EUR off-ramp via SEPA Instant
• MiCA compliant, ERC-8004 ready
• Fiat conversion for European users

Task 2.6: MERX x402 for TRON facilitator

• File: app/facilitators/merx_tron.py
• TRON mainnet: USDT, USDC, USDD
• Sub-3-second confirmation for micropayments
• TRON-specific verification

Task 2.7: Primev FastRPC facilitator

• File: app/facilitators/primev.py
• Ethereum mainnet fee-free
• Sub-200ms settlement via mev-commit preconfirmations
• ERC-8004 registered (Agent #23175)

Task 2.8: Satoshi Facilitator (Bitcoin)

• File: app/facilitators/satoshi.py
• Bitcoin-focused pay-per-call
• Base, Base Sepolia, Solana Mainnet/Devnet
• Multi-chain settlement from Bitcoin payments

Phase 3: Self-Hosted Facilitator

Task 3.1: x402-rs facilitator Docker deployment

• File: app/facilitators/x402_rs.py (client module)
• File: docker/x402-rs/docker-compose.yml
• File: docker/x402-rs/config.yaml
• Production-grade Rust facilitator
• Multi-chain configuration
• REST API endpoints (/verify, /settle)

Phase 4: Universal EVM (EIP-7702)

Task 4.1: EIP-7702 universal EVM facilitator

• File: app/facilitators/eip7702.py
• Support for ALL EVM blockchains (BNB, Polygon, Avalanche, etc.)
• ALL tokens (USDT, DAI, WBTC, etc.)
• ALL native coins (POL, AVAX, etc.)
• Uses EIP-7702 for delegated execution

Phase 5: Integration

Task 5.1: Refactor x402_middleware.py to use facilitator registry

• Replace FACILITATOR_CONFIGS with registry calls
• Backward compatible — existing API unchanged
• Add facilitator health dashboard endpoint

Task 5.2: Add new chains to x402_enforcement.py

• TRON (USDT, USDC, USDD)
• Bitcoin (via Satoshi facilitator)
• BNB Chain native
• AVAX, Fantom, Gnosis via EIP-7702

Task 5.3: Update gateway discovery response

• Expose all facilitators in /.well-known/x402
• Show facilitator health status
• Multi-facilitator payment requirements

Task 5.4: Create TRON gateway worker

• File: x402-gateway/tron/index.ts
• TRON-specific x402 gateway
• MERX facilitator integration
• TRC-20 USDT/USDC payment verification

Task 5.5: Create Bitcoin gateway worker

• File: x402-gateway/bitcoin/index.ts
• Bitcoin x402 gateway (Satoshi facilitator)
• Multi-chain settlement from BTC payments

Task 5.6: Update dashboard with facilitator metrics

• Per-facilitator success rate, latency, volume
• Facilitator health status
• Cost comparison (which facilitator is cheapest per chain)

Phase 6: Environment & Config

Task 6.1: Update .env.example with new vars

• CDP API keys
• AsterPay credentials
• MERX TRON config
• Primev endpoint
• Satoshi API keys
• EIP-7702 RPC URLs

Task 6.2: Update generate_env.py

• New facilitator environment variables
• Chain RPC URLs for new chains

---

Implementation Order (Priority)

1. Phase 1 — Foundation (facilitator registry, base class, router) — CRITICAL PATH
2. Phase 2 — Hosted facilitators (CDP, PayAI refactor, BNB, AsterPay, TRON, Primev, Bitcoin) — CAN PARALLELIZE
3. Phase 3 — Self-hosted x402-rs
4. Phase 4 — Universal EIP-7702
5. Phase 5 — Integration (refactor middleware, update gateways, dashboard)
6. Phase 6 — Environment config