# 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