# x402 Protocol — Complete System Architecture ## MUST READ for all future RMI developers ### Auto-audited: May 23, 2026 — 59 tools, 7 chains, all endpoints verified --- ## SYSTEM OVERVIEW ``` INTERNET │ ▼ Cloudflare Tunnel (rmi-cloudflare) ┌─────────────────────────────┐ │ rugmunch.io │ │ mcp.rugmunch.io │ │ n8n.rugmunch.io │ └─────────────┬───────────────┘ │ ┌─────────────▼───────────────┐ │ nginx (:80, :443) │ │ Routes: │ │ /api/* → :8000 │ │ /.well-known/* → :8000 │ │ /mcp/* → :8000 │ │ /health → :8000 │ │ / → static │ └─────────────┬───────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌──────────┐ │ Backend │ │ Orchestrator│ │ n8n │ │ :8000 │ │ :8081 │ │ :5678 │ │ 59 tools│ │ 9 agents │ │ 2 flows │ └────┬────┘ └──────────┘ └──────────┘ │ ┌────┼────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────┐ ┌──────┐ ┌──────────┐ │Redis │ │Supabase│ │ Langfuse │ │:6379 │ │ (API) │ │ :3100 │ └──────┘ └──────┘ └──────────┘ ``` --- ## FILE MAP — Every x402 file and what it does ### Core Backend (Python/FastAPI) | File | Lines | Purpose | |------|-------|---------| | `app/routers/x402_enforcement.py` | 1290 | **Payment gatekeeper** — intercepts all `/api/v1/x402-tools/*`, verifies x402 payment headers, enforces trials, builds 402 Payment Required responses. 7-chain support. | | `app/routers/x402_tools.py` | 3581 | **Tool handlers** — 48 route implementations. Each `@router.post("/audit")` is a tool. Also serves AI framework adapters (OpenAI, Anthropic, Gemini, LangChain formats). | | `app/routers/x402_catalog.py` | 255 | **Auto-discovery** — parses gateway index.ts files + scans route decorators. Builds unified catalog. No hardcoded tool lists. | | `app/routers/x402_forensic_tools.py` | 237 | **Forensic bundles** — 3 premium tools: forensic_valuation, osint_identity_hunt, investigation_report | | `app/routers/x402_dashboard.py` | 493 | **Analytics** — usage tracking, revenue per tool, top users, trial exhaustion stats | | `app/routers/x402_middleware.py` | 685 | **Anti-abuse** — device fingerprinting, trial tracking per device/wallet, rate limiting | | `app/mcp/x402_mcp_server.py` | 682 | **MCP protocol server** — translates x402 tools into MCP format for Claude/Cursor/Windsurf | ### Cloudflare Workers (TypeScript) | File | Lines | Purpose | |------|-------|---------| | `x402-gateway/base/index.ts` | 2650 | **Base + EVM gateway** — Payment verification via PayAI facilitator. 44 tool definitions. Routes to backend. | | `x402-gateway/solana/index.ts` | 2650 | **Solana gateway** — Payment verification via PayAI facilitator. 35 tool definitions. Routes to backend. | | `x402-twitter-view/src/index.ts` | ~200 | **Twitter data worker** — profiles, timelines, search. Self-healing with failover. | ### GitHub Repos (public) | Repo | Purpose | |------|---------| | `rug-munch-intelligence-mcp` | Public pip package. Thin MCP wrapper around x402 API. | | `x402-gateway-solana` | Solana gateway source — deploys to Cloudflare Workers | | `x402-gateway-base` | Base + EVM gateway source — deploys to Cloudflare Workers | | `x402-twitter-view` | Twitter data worker source | --- ## PAYMENT FLOW — Step by step ``` 1. User/bot calls POST /api/v1/x402-tools/{tool} │ 2. x402_enforcement middleware intercepts ├── Check: Has user paid? (x-pay header with tx hash) ├── Check: Is trial available? (device fingerprint + wallet) ├── If unpaid AND no trials → build 402 Payment Required │ └── Returns: payment addresses per chain, amounts, timeout │ 3. If paid or trial available → forward to tool handler │ 4. Tool handler (x402_tools.py) executes ├── Call backend connectors (Helius, Etherscan, DeFiLlama, etc.) ├── Aggregate multi-source data └── Return JSON response │ 5. Payment verification (if paid): ├── Base/Solana → PayAI facilitator verifies USDC transfer └── ETH/BSC/ARB/OPT/POL → Self-verify via Etherscan on-chain check ``` ### Payment Addresses - **All EVM chains**: `0x1E3AC01d0fdb976179790BDD02823196A92705C9` - **Solana**: `Gix4P9AmwcZRGzr2hCEME5m2QAvY86dBfm8c7e7MpFzv` - **Token**: USDC on all chains - **Amounts**: $0.01 - $0.50 per tool (defined in gateway index.ts) --- ## TOOL DISCOVERY — How the catalog works ``` MCP Catalog (/api/v1/x402/tools-catalog) │ ├── Step 1: parse_gateway_tools() │ └── Reads x402-gateway/{base,solana}/index.ts │ └── Regex extracts each tool from RMI_TOOLS object │ └── Finds: name, description, price, category, trialFree, method │ └── Result: 44 tools (22 unique to base, 0 unique to solana) │ ├── Step 2: discover_route_tools() │ └── Scans x402_tools.py + x402_forensic_tools.py │ └── Finds @router.get/post decorators │ └── Extracts docstrings as descriptions │ └── Result: 5 unique tools not in gateways │ └── Step 3: Merge + Deduplicate └── Same tool ID = merge chains └── Result: 59 total tools ``` ### Output formats | Format | Endpoint | For | |--------|----------|-----| | Full catalog | `/api/v1/x402/tools-catalog` | Humans, dashboards | | x402 protocol | `/.well-known/x402` | AI agents, protocol discovery | | OpenAI | `/api/v1/x402-tools/openai-tools` | ChatGPT, OpenAI-compatible | | Anthropic | `/api/v1/x402-tools/anthropic-tools` | Claude, Cursor | | Gemini | `/api/v1/x402-tools/gemini-tools` | Google Gemini | | LangChain | `/api/v1/x402-tools/langchain-tools` | LangChain agents | --- ## PRICING & TRIALS | Tier | Calls | Requirement | |------|-------|-------------| | Anonymous | 1 free per tool | Device fingerprint | | Wallet connected | 3 free per tool | MetaMask/Phantom | | Paid | Unlimited | USDC payment per call | **Refund**: Full refund if tool returns no data. POST `/api/v1/x402/refund` with tx hash within 48h. **Anti-abuse**: Device fingerprinting survives VPN/incognito. Identity hierarchy: wallet > device_id > turnstile > fingerprint. --- ## CHAIN SUPPORT MATRIX | Chain | Network ID | USDC Address | Verification | |-------|-----------|-------------|--------------| | Base | eip155:8453 | 0x833589...a02913 | PayAI facilitator | | Solana | solana:5eykt4... | EPjFWdd5...TDt1v | PayAI facilitator | | Ethereum | eip155:1 | 0xA0b869...eB48 | Self-verify | | BSC | eip155:56 | 0x8AC76a...d580d | Self-verify | | Arbitrum | eip155:42161 | 0xaf88d0...5831 | Self-verify | | Optimism | eip155:10 | 0x0b2C63...Ff85 | Self-verify | | Polygon | eip155:137 | 0x3c499c...3359 | Self-verify | --- ## CONNECTOR APIS — What data we have | Connector | API Key | Status | Used By | |-----------|---------|--------|---------| | Helius | ✅ Working | Solana RPC, webhooks, transactions | wallet, cluster, whale, forensics | | Etherscan | ✅ Working | Contract source, ABI, TX history | contract_inspect, tx_decoder | | DeFiLlama | 🆓 Free | TVL, protocols, yields | protocol_research, yield_scanner | | Birdeye | ✅ Working | Trending, token data | trending_tokens | | CoinGecko | ✅ Working | Prices, categories, trending | market_price, market_sectors | | DexScreener | 🆓 Free | Pairs, liquidity, volume | dex_activity, market_price | | Moralis | ❌ Key invalid | Multi-chain wallet/token data | NOT USED | | GMGN | ❌ Access denied | KOL tracking, trending | NOT USED | | Arkham | ⚠️ Untested | Entity labeling | NOT USED | | Nansen | ⚠️ Untested | Smart money, token god mode | NOT USED | | Dune | ⚠️ Untested | Custom queries | NOT USED | --- ## TESTING ```bash # Test all 59 tools (expect 403 = x402 enforcement working): bash /root/backend/scripts/test_all_tools.sh # Status dashboard: python3 /root/scripts/rmi-status # Pre-commit check: bash /root/backend/scripts/pre-commit.sh ``` --- ## COMMON ISSUES & FIXES | Issue | Symptom | Fix | |-------|---------|-----| | Gateway files missing | Catalog shows 0 tools | Clone gateways to `/root/backend/x402-gateway/` | | Tool returns 403 | x402 enforcement active | Expected — tools require payment or trial | | Catalog stale after adding tools | Old count | Restart backend: `docker restart rmi-backend` | | Payment verification fails | 402 responses | Check USDC addresses, network config | | Self-signed cert on external | curl fails without -k | Cloudflare provides edge cert — use -k or browser | --- ## WHEN ADDING NEW TOOLS 1. Add definition to `x402-gateway/base/index.ts` (and solana if applicable) 2. Add route handler to `x402_tools.py`: ```python @router.post("/my_new_tool") async def my_new_tool(req: SomeRequest): """Description of what this tool does.""" # Implementation using existing connectors ``` 3. Restart backend: `docker restart rmi-backend` 4. Verify: `curl http://localhost:8000/api/v1/x402-tools/my_new_tool` 5. Check catalog auto-updated: `curl http://localhost:8000/api/v1/x402/tools-catalog`