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

2026-07-02 01:24:22 +07:00

19 KiB

Raw Blame History

Rug Munch Intelligence — X402 MCP Server Builders Guide

MUST READ for anyone building, maintaining, or debugging this system

Last updated: May 23, 2026 Maintainer: Crypto Rug Muncher — biz@rugmunch.io Entity: Rug Munch Media LLC — Wyoming, USA

Architecture Overview
Quick Start — 30 Seconds to Live
All Endpoints Reference
Tool System — How Tools Work
Payment Flow — How Money Works
Deployment Guide
Directory Listings & Discovery
Common Problems & Solutions
Adding New Tools
Social & Community Links

1. ARCHITECTURE OVERVIEW

┌──────────────────────────────────────────────────────────────┐
│                     THE INTERNET                              │
│  AI Bots (Claude, Cursor, GPT)  │  Humans (Browsers, Apps)   │
└─────────────┬──────────────────────┬─────────────────────────┘
              │                      │
              ▼                      ▼
┌─────────────────────────┐  ┌─────────────────────────┐
│  sol.rugmunch.io         │  │  base.rugmunch.io        │
│  Cloudflare Worker       │  │  Cloudflare Worker       │
│  64 RMI + 154 MCP tools  │  │  64 RMI + 154 MCP tools  │
│  x402 payments           │  │  x402 payments           │
└───────────┬─────────────┘  └───────────┬─────────────┘
            │                             │
            ▼                             ▼
┌──────────────────────────────────────────────────────────────┐
│              mcp-router.rugmunch.io                           │
│              28 data providers — 154 tools                    │
│              DexScreener, Jupiter, Helius, etc.              │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│              rugmunch.io (Docker)                             │
│              /root/backend/ → rmi-backend:8000               │
│              FastAPI — 80+ modules                            │
│              x402 enforcement, human payments, tools API      │
└──────────────────────────────────────────────────────────────┘

Key Facts

2 Cloudflare Workers — sol.rugmunch.io (Solana) + base.rugmunch.io (Base)
71 RMI tools per gateway — security, intelligence, market, social, analysis, launch, investigation
154 MCP tools from 28 data providers
10 payment facilitators — Coinbase CDP, PayAI, Cloudflare, Pieverse (BNB), AsterPay (EUR/SEPA), MERX (TRON), Primev (fee-free ETH), Satoshi (BTC), x402-rs (self-hosted), EIP-7702 (universal EVM)
13 payment chains — Base, Solana, Ethereum, BSC, Polygon, Arbitrum, Optimism, TRON, Bitcoin, Avalanche, Fantom, Gnosis, SEPA/EUR
1 Docker backend — FastAPI at /root/backend/, mounted to rmi-backend container
Smart router — Auto-picks best facilitator per chain/token with automatic fallback
Cloudflare Tunnel — rugmunch.io → rmi-backend:8000
Source code — github.com/Rug-Munch-Media-LLC/rugmuncher-backend

WORKER CODE LOCATION

/root/backend/x402-gateway/solana/    → Solana gateway
/root/backend/x402-gateway/base/      → Base gateway

Each has:

index.ts — THE ENTIRE WORKER (single file, ~3000 lines)
wrangler.toml — Environment bindings
smithery.json — Smithery directory listing
glama.json — Glama directory listing
dist/worker.js — Compiled JavaScript (uploaded to Cloudflare)

BACKEND CODE LOCATION

/root/backend/                        → Docker context
/root/backend/main.py                 → FastAPI entry point
/root/backend/app/routers/x402_tools.py      → x402 tools + human payment
/root/backend/app/routers/x402_enforcement.py → Payment middleware + smart router
/root/backend/app/facilitators/       → 10 facilitator modules (pluggable registry)
/root/backend/app/facilitators/router.py     → Smart router (auto-picks best facilitator)
/root/backend/docker/x402-rs/         → Self-hosted Rust facilitator Docker config

2. QUICK START — 30 SECONDS TO LIVE

For AI Bots (MCP Protocol)

# One command — no API key, no signup, no limits on trials
npx -y mcp-remote@latest https://sol.rugmunch.io/mcp

For Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "rmi-solana": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://sol.rugmunch.io/mcp"]
    }
  }
}

For Humans (Browser)

Go to https://rugmunch.io
Connect wallet (MetaMask, WalletConnect, Coinbase, Phantom)
Pick a tool, pay with USDC/SOL/ETH/USDT
Get results instantly

For Developers (curl)

# List all 218 tools
curl -X POST https://sol.rugmunch.io/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST https://sol.rugmunch.io/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"audit","arguments":{"address":"TOKEN_ADDRESS","chain":"solana"}}}'

3. ALL ENDPOINTS REFERENCE

Solana Gateway (sol.rugmunch.io)

Endpoint	Method	Description
`/health`	GET	Worker health + tool counts
`/mcp`	POST	MCP JSON-RPC protocol (tools/list, tools/call)
`/mcp-x402-docs`	GET	Full JSON bot documentation
`/llms.txt`	GET	AI agent discovery (plain text)
`/.well-known/x402`	GET	x402 payment discovery
`/frameworks`	GET	All framework formats (OpenAI, Anthropic, etc.)
`/openai-tools`	GET	OpenAI function-calling format
`/anthropic-tools`	GET	Anthropic tool format
`/gemini-tools`	GET	Gemini function declarations
`/langchain-tools`	GET	LangChain tool format
`/tools/{name}`	POST/GET	REST API for individual tools
`/pricing`	GET	HTML pricing page
`/tip`	GET	Donation wallet addresses
`/about`	GET	Organization info

Base Gateway (base.rugmunch.io)

Identical endpoints, different network (Base Mainnet / eip155:8453).

Backend (rugmunch.io)

Endpoint	Method	Description
`/health`	GET	Backend health
`/api/v1/x402/dashboard`	GET	Earnings + trial stats
`/api/v1/x402/tools-catalog`	GET	Tool catalog with pricing
`/api/v1/x402-tools/human-execute`	POST	Human wallet payment execution
`/api/v1/x402-tools/mcp-proxy`	POST	External MCP tool proxy

4. TOOL SYSTEM — HOW TOOLS WORK

RMI Tools (64 per gateway)

Defined in RMI_TOOLS object in index.ts. Each tool has:

{
  name: "audit",
  description: "Deep smart contract audit...",
  price: "$0.05",
  priceAtomic: "50000",       // USDC amount in smallest unit
  category: "security",
  trialFree: 1,                // Number of free calls
  method: "POST"               // HTTP method for REST endpoint
}

Tool Execution Flow

MCP tools/call → executeToolDirect() → specific execute function
REST /tools/{name} → executeToolDirect() → specific execute function

executeToolDirect() is a big switch statement in both worker files (~line 120). Each tool name maps to a specific async function that:

Fetches data from external APIs (DexScreener, CoinGecko, etc.)
Processes with fallback chains (if API 1 fails, try API 2)
Returns structured result

Adding a New Tool

Add entry to RMI_TOOLS object
Add else if case in executeToolDirect()
Create the execution function
Recompile: npx esbuild index.ts --bundle --format=esm --platform=neutral --target=es2022 --outfile=dist/worker.js --external:node:*
Upload to Cloudflare via REST API (see Deployment section)

MCP External Tools (154 across 28 services)

Fetched from mcp-router.rugmunch.io/tools at runtime. Cached for 5 minutes. Each service provides tool metadata with parameters and descriptions. Services: dexscreener, jupiter, pumpfun, raydium, defillama, dexpaprika, coincap, coinmarketcap, cryptopanic, cryptocompare, blockchair, blockchain, mempool, solana, helius, birdeye, coingecko, cryptoiz, blockrun, agentfi, moralis, gmgn, nansen, arkham, dune, solscan, quicknode, freeusdc

5. PAYMENT FLOW — HOW MONEY WORKS

Bot Payment (x402 Protocol — Multi-Chain)

Client calls tool → receives 402 Payment Required
402 response lists ALL 13 chains + 10 facilitators + accepted tokens
Client pays on ANY supported chain (USDC, USDT, BTC, EUR, etc.)
Client includes X-Pay header with payment proof (tx hash + signature)
Smart router detects chain/token from payload
Router picks best facilitator for that chain (auto-fallback if primary fails)
Payment verified → tool executes → result returned
Trial mode: first 1-5 calls per tool are FREE

Human Payment (Wallet Connect)

User connects wallet (MetaMask/WalletConnect/Coinbase/Phantom)
Selects tool + payment token (USDC-SOL, USDC-Base, SOL, ETH, USDT, BTC, TRX, EUR)
Signs transaction in wallet
Frontend sends tx_hash to /api/v1/x402-tools/human-execute
Backend verifies tx via appropriate facilitator (auto-routed)
If confirmed → executes tool via gateway → returns result
Payment logged in Supabase x402_payments table

Payment Addresses (ALL YOUR WALLETS)

Chain	Address	Assets
Base/EVM	`0x1E3AC01d0fdb976179790BDD02823196A92705C9`	USDC, ETH, USDT
Solana	`Gix4P9AmwcZRGzr2hCEME5m2QAvY86dBfm8c7e7MpFzv`	USDC, SOL
TRON	(set X402_TRON_PAY_TO)	USDT, USDC, USDD
Bitcoin	(set X402_BTC_PAY_TO)	BTC
SEPA/EUR	(set ASTERPAY_SEPA_IBAN)	EUR

Refund Policy

Auto-refund if tool returns no data. Request within 48h via POST /api/v1/x402/refund.

6. DEPLOYMENT GUIDE

Deploying Gateway Workers

Method 1: REST API (use when wrangler auth fails)

CF_TOKEN="cfat_YOUR_TOKEN"
ACCT="8f9bd9165c1250b426c66dc1967deefd"

# 1. Compile TypeScript
cd /root/backend/x402-gateway/solana
npx esbuild index.ts --bundle --format=esm --platform=neutral \
  --target=es2022 --outfile=dist/worker.js --external:node:*

# 2. Upload to Cloudflare
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCT/workers/scripts/x402-sol" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -F 'metadata={"main_module":"worker.js","bindings":[...]};type=application/json' \
  -F "worker.js=@dist/worker.js;type=application/javascript+module"

Method 2: Wrangler (when auth works)

cd /root/backend/x402-gateway/solana
CLOUDFLARE_API_TOKEN=$CF_TOKEN npx wrangler deploy

WARNING: Wrangler requires Account Membership permissions. If you get error 9106 "Authentication failed on /memberships", use Method 1. API tokens with Workers:Edit permission work for the REST API but not wrangler.

Required Worker Bindings

BACKEND_API     = https://rugmunch.io
BACKEND_MCP     = https://mcp-router.rugmunch.io
NETWORK         = solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (or eip155:8453 for Base)
NETWORK_NAME    = Solana Mainnet (or Base Mainnet)
FACILITATOR     = https://facilitator.payai.network (or https://facilitator.x402.org)
ORGANIZATION    = Rug Munch Intelligence
PAY_TO          = Gix4P9AmwcZRGzr2hCEME5m2QAvY86dBfm8c7e7MpFzv (or 0x1E... for Base)
GW_URL          = https://sol.rugmunch.io (or base.rugmunch.io)
SOLANA_GATEWAY  = https://sol.rugmunch.io

Restarting Backend

docker restart rmi-backend
# Wait ~10 seconds for FastAPI to load all modules
curl http://localhost:8000/health  # Verify

Cloudflare Email Routing

Email for both rugmunch.io and cryptorugmunch.com routes to cryptorugmuncher@gmail.com. Managed via Cloudflare Dashboard → Email → Email Routing.

biz@rugmunch.io → cryptorugmuncher@gmail.com
info@rugmunch.io → cryptorugmuncher@gmail.com
*@cryptorugmunch.com → cryptorugmuncher@gmail.com (catch-all)

Custom Domain Routes

sol.rugmunch.io/*   → x402-sol worker
base.rugmunch.io/*  → x402-base worker

These are set via Cloudflare Workers Routes in the dashboard. DNS CNAME records point to the workers.dev subdomains with proxy enabled.

7. DIRECTORY LISTINGS & DISCOVERY

Active Listings

Directory	Status	URL
Smithery	Active	smithery.ai/server/@cryptorugmunch/x402
Glama	Active	glama.ai/mcp/servers/rugmunch
mcp.so	Submitted	Sol UUID: 2102ac31
GitHub	Public	github.com/Rug-Munch-Media-LLC
Coinbase CDP	Register at	portal.cdp.coinbase.com (set CDP_API_KEY_ID + CDP_API_KEY_SECRET)

Discovery Files

File	Location	Purpose
`smithery.json`	Gateway root	Smithery listing
`glama.json`	Gateway root	Glama listing
`X402-SYSTEM.md`	/root/backend/x402-gateway/	Multi-facilitator system documentation
`BUILDERS-GUIDE.md`	/root/backend/x402-gateway/	This guide
README.md	Gateway root	Quick start

Bot Discovery Endpoints

Bots discover this service through:

/mcp-x402-docs — Full JSON docs with stats, endpoints, pricing, socials
/llms.txt — AI agent discovery standard
/.well-known/x402 — x402 payment protocol discovery
MCP tools/list — Standard MCP tool catalog
Directory listings (Smithery, Glama, mcp.so)

8. COMMON PROBLEMS & SOLUTIONS

"MCP tools show 0 on custom domains but 154 on workers.dev"

Cause: Cold start — MCP_TOOLS module variable not yet populated. Fix: Hit the health endpoint once. MCP tools cache for 5 minutes. The first request to a cold worker instance fetches from mcp-router.

"tools/call returns 'Method not found'"

Cause: Old worker version before tools/call was implemented. Fix: Redeploy with latest code (May 23, 2026 or newer).

"Wrangler deploy fails with 9106 auth error"

Cause: API token lacks Account Membership permissions. Fix: Use REST API deployment (Method 1 in Deployment section). Get a new token at dash.cloudflare.com → API Tokens with Workers:Edit.

"Backend returns 500 on human-execute"

Cause: x402 enforcement middleware blocking the endpoint. Fix: Ensure /api/v1/x402-tools/human-execute is in FREE_PATHS in x402_enforcement.py and the bot-agent check exempts it.

"Human-execute returns empty response"

Cause: Backend container just restarted, FastAPI still loading. Fix: Wait 10-15 seconds. Check /health endpoint first.

"Token expired / Invalid API Token"

Cause: Cloudflare API tokens can be revoked or expire. Fix: Generate new token at dash.cloudflare.com → API Tokens. Current working token stored in /root/.hermes/.env as CLOUDFLARE_API_TOKEN.

9. ADDING NEW TOOLS

Step-by-Step

Define the tool in RMI_TOOLS (~line 25 in index.ts):

my_new_tool: {
  name: "my_new_tool",
  description: "What this tool does",
  price: "$0.05",
  priceAtomic: "50000",
  category: "security",  // security, intelligence, market, analysis, social, launchpad
  trialFree: 2,
  method: "POST"
}

Add dispatch case in executeToolDirect (~line 120):

} else if (toolName === "my_new_tool") {
  return await executeMyNewTool(body?.address || "", body?.chain || "solana");
}

Create execution function after the dispatch:

async function executeMyNewTool(address: string, chain: string): Promise<any> {
  const result: any = { tool: "my_new_tool", address, chain, timestamp: new Date().toISOString(), sources_used: [] };
  try {
    const resp = await fetch("https://api.example.com/data/" + address);
    if (resp.ok) {
      const data = await resp.json();
      result.data = data;
      result.sources_used.push("example_api");
    }
  } catch (e) { console.debug("My tool failed:", e); }
  return result;
}

Compile + Upload + Verify:

npx esbuild index.ts --bundle --format=esm --platform=neutral --target=es2022 --outfile=dist/worker.js --external:node:*
# Upload via REST API (see Deployment section)
# Test:
curl -X POST https://sol.rugmunch.io/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"my_new_tool","arguments":{"address":"test"}}}'

Platform	Link	Purpose
X/Twitter	@cryptorugmunch	Main account
Telegram	t.me/cryptorugmunch	Main channel
Telegram Alerts	t.me/cryptorugmuncher	Scam alerts + updates
GitHub Org	Rug-Munch-Media-LLC	All repos
GitHub Backend	rugmuncher-backend	Main repo
Website	rugmunch.io	Web app
Email	biz@rugmunch.io	Business inquiries

Token & DAO

V2 token launch planned mid-2026
1:1 airdrop checker for v1 $CRM and $cryptorugmunch holders
Verify eligibility and claim tokens on launch day
Full DAO LLC transition under Wyoming state law within 12 months
Community governance via token-based voting

Trust & Transparency

Rug Munch Media LLC — Wyoming, USA
20-year teacher turned full-time crypto scam investigator
Bootstrapped. No VC. Revenue from tool calls only
Backend is open source
No API keys stored. Payments verified on-chain
Auto-refund if tool fails

QUICK REFERENCE CARD

DEPLOY:        esbuild → REST API PUT → verify health
RESTART:       docker restart rmi-backend → wait 10s → curl health
ADD TOOL:      RMI_TOOLS entry → dispatch case → function → compile → upload
TEST:          curl POST /mcp tools/list → tools/call
DEBUG:         docker logs rmi-backend --tail 50
TOKEN:         /root/.hermes/.env CLOUDFLARE_API_TOKEN
ACCOUNT ID:    8f9bd9165c1250b426c66dc1967deefd
ZONE rugmunch: 2c5c82d253dbfb7e091eb8b1dac4f0f8
ZONE cryptorug: 25168c58ff5783c51f047378eac525cb

This document is the single source of truth for the RMI x402 system. If you find something wrong, outdated, or missing — fix it here. Questions? biz@rugmunch.io | @cryptorugmunch on X

19 KiB Raw Blame History