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 /root/backend/scripts/test_all_tools.sh
python3 /root/scripts/rmi-status
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
- Add definition to
x402-gateway/base/index.ts (and solana if applicable)
- Add route handler to
x402_tools.py:@router.post("/my_new_tool")
async def my_new_tool(req: SomeRequest):
"""Description of what this tool does."""
- Restart backend:
docker restart rmi-backend
- Verify:
curl http://localhost:8000/api/v1/x402-tools/my_new_tool
- Check catalog auto-updated:
curl http://localhost:8000/api/v1/x402/tools-catalog
