RugMunchMedia/rmi-backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

merge: chore/cleanup-remove-bloat-and-secrets into main

Browse source
This commit is contained in:
Crypto Rug Munch 2026-07-02 01:24:22 +07:00
commit bde2f3a97d
1173 changed files with 437609 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

233
X402_ARCHITECTURE.md Normal file
View file

@ -0,0 +1,233 @@
# 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`