feat(t33+t34): MCP server + x402 paid catalog

backend/app/api/v1/__init__.py

@@ -49,9 +49,8 @@ from app.api.v1.public.scanner import router as scanner_router  # noqa: E402
 
 api_v1_router.append(scanner_router)
 
-from app.api.v1.x402.payments import router as x402_payments_router  # noqa: E402
-
-api_v1_router.append(x402_payments_router)
+# x402 moved to app.domain.x402 (T34 v2)
+# Old app/api/v1/x402/payments.py removed to avoid model conflicts
 
 from app.api.v1.rag.search import router as rag_v2_router  # noqa: E402
 

backend/app/api/v1/mcp/__init__.py

@@ -1,4 +1,4 @@
-"""Model Context Protocol routes.
+"""MCP v1 routes."""
+from .router import router
 
-Target: tool catalog for AI agents, JSON-RPC endpoint.
-"""
+__all__ = ["router"]

backend/app/api/v1/mcp/router.py

@@ -0,0 +1,120 @@
+"""T33 MCP Server — HTTP wrapper for SSE transport.
+
+Per v4.0 §T33. Endpoints:
+  POST /mcp                  JSON-RPC 2.0 endpoint
+  GET  /mcp/tools            Tool catalog
+  POST /mcp/call/{tool_id}   Direct tool execution (no JSON-RPC)
+
+The server speaks the Model Context Protocol natively. Claude Desktop
+and Cursor connect via:
+  {"mcpServers": {"rugmunch": {"url": "https://mcp.rugmunch.io/mcp", "transport": "sse"}}}
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from app.mcp.server import TOOL_CATALOG, call_tool
+
+router = APIRouter(prefix="/mcp", tags=["mcp"])
+log = logging.getLogger(__name__)
+
+
+class JsonRpcRequest(BaseModel):
+    jsonrpc: str = "2.0"
+    method: str
+    params: dict[str, Any] = {}
+    id: int | str | None = None
+
+
+class JsonRpcResponse(BaseModel):
+    jsonrpc: str = "2.0"
+    result: Any | None = None
+    error: dict | None = None
+    id: int | str | None = None
+
+
+@router.post("")
+async def jsonrpc_handler(req: JsonRpcRequest) -> dict:
+    """JSON-RPC 2.0 endpoint for MCP clients.
+
+    Methods:
+      - initialize           → returns server info
+      - tools/list            → returns tool catalog
+      - tools/call            → dispatches to backend
+      - resources/list        → empty
+      - prompts/list          → empty
+    """
+    if req.jsonrpc != "2.0":
+        return {"jsonrpc": "2.0", "error": {"code": -32600, "message": "invalid jsonrpc version"}, "id": req.id}
+
+    if req.method == "initialize":
+        return {
+            "jsonrpc": "2.0",
+            "result": {
+                "protocolVersion": "2024-11-05",
+                "serverInfo": {
+                    "name": "rugmunch-intelligence",
+                    "version": "4.0.0",
+                    "description": "Crypto intelligence platform — 13+ chains, 8 MCP tools, x402 paid tier",
+                },
+                "capabilities": {"tools": {}, "resources": {}, "prompts": {}},
+            },
+            "id": req.id,
+        }
+
+    if req.method == "tools/list":
+        return {
+            "jsonrpc": "2.0",
+            "result": {"tools": TOOL_CATALOG},
+            "id": req.id,
+        }
+
+    if req.method == "tools/call":
+        name = req.params.get("name", "")
+        arguments = req.params.get("arguments", {})
+        if not name:
+            return {"jsonrpc": "2.0", "error": {"code": -32602, "message": "tool name required"}, "id": req.id}
+        result = await call_tool(name, arguments)
+        return {
+            "jsonrpc": "2.0",
+            "result": {
+                "content": [{"type": "text", "text": json.dumps(result, default=str)[:50000]}],
+                "isError": "error" in result,
+            },
+            "id": req.id,
+        }
+
+    if req.method == "resources/list":
+        return {"jsonrpc": "2.0", "result": {"resources": []}, "id": req.id}
+
+    if req.method == "prompts/list":
+        return {"jsonrpc": "2.0", "result": {"prompts": []}, "id": req.id}
+
+    if req.method == "notifications/initialized":
+        return {"jsonrpc": "2.0", "result": {}, "id": req.id}
+
+    return {
+        "jsonrpc": "2.0",
+        "error": {"code": -32601, "message": f"method not found: {req.method}"},
+        "id": req.id,
+    }
+
+
+@router.get("/tools")
+async def list_tools() -> dict:
+    """Plain JSON endpoint (for direct integration, no JSON-RPC)."""
+    return {"server": "rugmunch-intelligence", "version": "4.0.0", "tools": TOOL_CATALOG}
+
+
+@router.post("/call/{tool_id}")
+async def direct_call(tool_id: str, request: Request) -> dict:
+    """Direct tool execution (no JSON-RPC). For curl/scripts."""
+    body = await request.json() if request.headers.get("content-type", "").startswith("application/json") else {}
+    arguments = body.get("arguments", body) if isinstance(body, dict) else {}
+    result = await call_tool(tool_id, arguments)
+    return result

backend/app/domain/x402/__init__.py

@@ -1,4 +1,10 @@
-"""x402 domain — auto-registers its health check."""
+"""x402 domain — auto-registers its health check + HTTP routes.
+
+T34 from v4.0. Sovereign-first x402 payment layer for AI agents.
+
+Re-exports the legacy models (PaymentFacilitator, X402Tier) for backward
+compatibility with v1 routers that import from app.domain.x402.
+"""
 from __future__ import annotations
 
 from app.core import health as health_mod
@@ -6,14 +12,13 @@ from app.core.health import DomainHealth
 
 
 async def _health_check() -> DomainHealth:
-    """x402 health: catalog routers + enforcement available."""
+    """x402 health: catalog + middleware available."""
     try:
-        from app.routers.x402_catalog import list_tools_catalog
-        from app.routers.x402_enforcement import router
+        from app.domain.x402.middleware import PRICING
         return DomainHealth(
             name="x402",
             healthy=True,
-            details={"catalog": "available", "enforcement": "available"},
+            details={"tools": len(PRICING), "middleware": "available"},
         )
     except Exception as e:
         return DomainHealth(name="x402", healthy=False, error=str(e))
@@ -22,25 +27,19 @@ async def _health_check() -> DomainHealth:
 health_mod.register_health_check("x402", _health_check)
 
 
-# Public API
-from app.domain.x402.models import (  # noqa: F401
-    PaymentFacilitator,
-    PaymentReceipt,
-    PaymentRequest,
-    ToolCatalog,
-    ToolCatalogEntry,
-    ToolPricing,
-    X402Tier,
-)
-from app.domain.x402.service import X402Service  # noqa: F401
-
-__all__ = [
-    "ToolCatalog",
-    "ToolCatalogEntry",
-    "ToolPricing",
-    "PaymentFacilitator",
-    "PaymentReceipt",
-    "PaymentRequest",
-    "X402Tier",
-    "X402Service",
-]
+# Re-export legacy models for backward compat with v1 routers
+try:
+    from app.domain.x402.models import (  # noqa: F401
+        PaymentFacilitator,
+        X402Tier,
+        PaidTool,
+        X402Receipt,
+    )
+except Exception:
+    pass
+
+
+# Re-export the new T34 router
+from app.domain.x402.router import router  # noqa: E402
+
+__all__ = ["router", "PaymentFacilitator", "X402Tier", "PaidTool", "X402Receipt"]

backend/app/domain/x402/middleware.py

@@ -0,0 +1,263 @@
+"""T34 x402 Payment Middleware.
+
+Per v4.0 §T34. HTTP 402 'Payment Required' repurposed for AI agents.
+
+Flow:
+  1. Agent calls paid endpoint without X-Payment header
+  2. Server returns 402 with payment challenge (signed invoice)
+  3. Agent's wallet pays on-chain, gets tx_hash
+  4. Agent re-calls with X-Payment: <base64(tx_hash + signature)>
+  5. Server verifies on-chain payment via web3, fulfills request
+
+Pricing (per v4.0):
+  Free:   5 calls/day
+  Pro:    $0.01/call (1000 calls/day)
+  Ent:    $0.001/call (unlimited)
+
+For v1, we use a simplified flow:
+  - Track calls per agent in Redis (sliding window)
+  - Receipts logged to x402_receipts table
+  - Payment verification stubbed (returns True for now)
+  - The 402 challenge includes a payment_url the agent hits
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import time
+from datetime import datetime, UTC
+from typing import Any, Optional
+from uuid import uuid4
+
+from fastapi import HTTPException, Request
+
+log = logging.getLogger(__name__)
+
+
+# ── Pricing per v4.0 §T34 ───────────────────────────────────────────
+PRICING: dict[str, dict[str, Any]] = {
+    # free_tier: bool, pro_cents: int (USD cents), ent_cents: int
+    "get_token_risk":            {"free_tier": True,  "pro_cents": 1,    "ent_cents": 1,    "description": "Real-time token risk score"},
+    "get_wallet_analysis":       {"free_tier": True,  "pro_cents": 1,    "ent_cents": 1,    "description": "Wallet activity + reputation"},
+    "get_deployer_reputation":   {"free_tier": False, "pro_cents": 2,    "ent_cents": 1,    "description": "Deployer reputation score"},
+    "get_news_sentiment":        {"free_tier": True,  "pro_cents": 1,    "ent_cents": 1,    "description": "Latest news + sentiment"},
+    "generate_report":           {"free_tier": False, "pro_cents": 500,  "ent_cents": 400,  "description": "Full AI research report"},
+    "query_catalog":             {"free_tier": False, "pro_cents": 5,    "ent_cents": 3,    "description": "Natural language catalog query"},
+    "find_similar_tokens":       {"free_tier": False, "pro_cents": 3,    "ent_cents": 2,    "description": "Vector-similar tokens"},
+    "resolve_entity":            {"free_tier": False, "pro_cents": 10,   "ent_cents": 5,    "description": "Cross-chain entity resolution"},
+    "search_rag":                {"free_tier": True,  "pro_cents": 1,    "ent_cents": 1,    "description": "RAG semantic search"},
+    "bulk_ingest":               {"free_tier": False, "pro_cents": 10,   "ent_cents": 5,    "description": "Bulk RAG ingestion"},
+}
+
+# Free tier daily limit
+FREE_DAILY_LIMIT = 5
+
+
+def get_tool_price_usd(tool: str) -> float:
+    """Get pro tier price in USD. Returns 0 for free tools."""
+    p = PRICING.get(tool, {})
+    if p.get("free_tier", False):
+        return 0.0
+    return p.get("pro_cents", 0) / 100.0
+
+
+def get_tool_metadata(tool: str) -> dict:
+    """Public-facing tool metadata for /api/v1/x402/catalog."""
+    p = PRICING.get(tool, {})
+    return {
+        "name": tool,
+        "free_tier": p.get("free_tier", False),
+        "free_daily_limit": FREE_DAILY_LIMIT if p.get("free_tier") else 0,
+        "price_pro_usd": p.get("pro_cents", 0) / 100.0,
+        "price_ent_usd": p.get("ent_cents", 0) / 100.0,
+        "description": p.get("description", ""),
+    }
+
+
+# ── Rate limit tracking (Redis) ───────────────────────────────────
+def _agent_id_from_request(request: Optional[Request]) -> str:
+    """Extract agent id from headers. Defaults to 'anon:ip' for anonymous."""
+    if not request:
+        return "anon:unknown"
+    agent_id = request.headers.get("X-Agent-Id") or request.headers.get("X-Api-Key")
+    if agent_id:
+        return f"key:{agent_id}"
+    client = request.client
+    if client:
+        return f"anon:{client.host}"
+    return "anon:unknown"
+
+
+async def _check_rate_limit(redis, agent_id: str) -> None:
+    """Sliding-window rate limit: 5 free calls/day, 1000 pro, unlimited ent.
+
+    For v1, we use Redis with a daily counter. Per-second limits are
+    enforced at the proxy level (nginx/Caddy).
+    """
+    if not redis:
+        return
+    try:
+        day = datetime.now(UTC).strftime("%Y%m%d")
+        key = f"x402:rl:{agent_id}:{day}"
+        count = await redis.incr(key)
+        if count == 1:
+            await redis.expire(key, 86400)
+        if count > FREE_DAILY_LIMIT:
+            raise HTTPException(
+                status_code=429,
+                detail={
+                    "error": "rate_limit_exceeded",
+                    "agent_id": agent_id,
+                    "daily_count": count,
+                    "limit": FREE_DAILY_LIMIT,
+                    "next_action": "Send X-Payment header with valid tx_hash to upgrade tier",
+                },
+            )
+    except HTTPException:
+        raise
+    except Exception as e:
+        log.warning(f"rate_limit_check_fail: {e}")
+
+
+# ── Payment challenge ─────────────────────────────────────────────
+def create_invoice(tool: str, agent_id: str) -> dict:
+    """Create a payment challenge (signed invoice) for an agent to pay.
+
+    In v1, the signature is a HMAC placeholder. In production, the
+    invoice is signed by the platform's key and the agent verifies it
+    before paying.
+    """
+    invoice_id = uuid4().hex
+    amount_usd = get_tool_price_usd(tool)
+    invoice = {
+        "id": invoice_id,
+        "tool": tool,
+        "agent_id": agent_id,
+        "amount_usd": amount_usd,
+        "amount_wei": int(amount_usd * 1e18 / 3000),  # assume ETH = $3000
+        "pay_to": "0xRMI_PLATFORM_WALLET",  # placeholder
+        "chain": "base",  # L2 for low fees
+        "created_at": datetime.now(UTC).isoformat(),
+        "expires_at": (datetime.now(UTC).timestamp() + 3600),
+    }
+    # HMAC placeholder signature (real impl: sign with platform key)
+    msg = json.dumps(invoice, sort_keys=True).encode()
+    invoice["signature"] = base64.b64encode(
+        hashlib.sha256(msg + b"RMI_PLATFORM_HMAC_KEY").digest()
+    ).decode()
+    return invoice
+
+
+def verify_payment_header(x_payment: str, expected_amount_usd: float) -> tuple[str, str] | None:
+    """Decode the X-Payment header. Returns (tx_hash, signature) or None.
+
+    Format: base64({"tx_hash": "...", "signature": "..."})
+    """
+    if not x_payment:
+        return None
+    try:
+        decoded = base64.b64decode(x_payment).decode()
+        data = json.loads(decoded)
+        return data.get("tx_hash", ""), data.get("signature", "")
+    except Exception:
+        return None
+
+
+async def verify_payment_on_chain(tx_hash: str, expected_amount_usd: float) -> bool:
+    """Verify an on-chain payment. v1 stub — returns True for valid-format hashes.
+
+    Production: web3.py to query the chain, check recipient + amount.
+    """
+    if not tx_hash or not tx_hash.startswith("0x") or len(tx_hash) != 66:
+        return False
+    # Real impl: check tx exists, recipient matches, amount >= expected
+    return True
+
+
+async def record_receipt(catalog, tx_hash: str, tool: str, agent_id: str, amount_usd: float) -> bool:
+    """Log the payment receipt to x402_receipts table."""
+    if not catalog._health.postgres:
+        return False
+    try:
+        async with catalog._pg_pool.acquire() as conn:
+            await conn.execute(
+                """INSERT INTO x402_receipts (tx_hash, agent_id, tool, amount_usd, chain, paid_at, tier)
+                   VALUES ($1, $2, $3, $4, $5, NOW(), $6)
+                   ON CONFLICT (tx_hash) DO NOTHING""",
+                tx_hash, agent_id, tool, amount_usd, "base", "pro",
+            )
+        return True
+    except Exception as e:
+        log.warning(f"receipt_record_fail: {e}")
+        return False
+
+
+# ── Main middleware ────────────────────────────────────────────────
+async def require_payment(
+    tool: str,
+    request: Optional[Request] = None,
+    catalog=None,
+) -> dict:
+    """Verify x402 payment. Returns payment context dict.
+
+    Raises HTTPException 402 if payment is required but not provided.
+    Raises HTTPException 429 if rate limit is exceeded.
+    """
+    agent_id = _agent_id_from_request(request)
+    if not catalog or not catalog._health.redis:
+        # No rate limiting available — log and pass
+        log.debug(f"x402_no_redis: {tool} by {agent_id}")
+    else:
+        await _check_rate_limit(catalog._redis, agent_id)
+
+    # Free tool — no payment required
+    if get_tool_price_usd(tool) == 0:
+        return {"agent_id": agent_id, "tool": tool, "tier": "free", "paid_via_x402": None}
+
+    # Paid tool — check X-Payment header
+    if request is None:
+        invoice = create_invoice(tool, agent_id)
+        raise HTTPException(
+            status_code=402,
+            detail={
+                "error": "payment_required",
+                "invoice": invoice,
+                "payment_url": f"https://pay.rugmunch.io/{invoice['id']}",
+                "instructions": "Pay on-chain, then retry with X-Payment header (base64 of {tx_hash, signature})",
+            },
+        )
+
+    x_payment = request.headers.get("X-Payment")
+    if not x_payment:
+        invoice = create_invoice(tool, agent_id)
+        raise HTTPException(
+            status_code=402,
+            detail={
+                "error": "payment_required",
+                "invoice": invoice,
+                "payment_url": f"https://pay.rugmunch.io/{invoice['id']}",
+                "instructions": "Pay on-chain, then retry with X-Payment header (base64 of {tx_hash, signature})",
+            },
+        )
+
+    decoded = verify_payment_header(x_payment, get_tool_price_usd(tool))
+    if not decoded:
+        raise HTTPException(status_code=402, detail="invalid X-Payment format")
+    tx_hash, _sig = decoded
+    if not await verify_payment_on_chain(tx_hash, get_tool_price_usd(tool)):
+        raise HTTPException(status_code=402, detail="invalid payment proof")
+
+    # Record the receipt
+    if catalog:
+        await record_receipt(
+            catalog, tx_hash, tool, agent_id, get_tool_price_usd(tool)
+        )
+
+    return {
+        "agent_id": agent_id,
+        "tool": tool,
+        "tier": "pro",
+        "paid_via_x402": tx_hash,
+    }

backend/app/domain/x402/router.py

@@ -0,0 +1,155 @@
+"""T34 x402 Paid Tools Catalog.
+
+Per v4.0 §T34. Endpoints:
+  GET  /api/v1/x402/catalog    — list all tools with pricing tiers
+  GET  /api/v1/x402/usage      — per-agent usage stats
+  GET  /api/v1/x402/receipts/{tx_hash}  — payment receipt
+  POST /api/v1/x402/verify     — verify a payment header
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from app.catalog.service import get_catalog
+from app.domain.x402.middleware import (
+    PRICING,
+    get_tool_metadata,
+    get_tool_price_usd,
+    verify_payment_header,
+    verify_payment_on_chain,
+)
+
+router = APIRouter(prefix="/api/v1/x402", tags=["x402"])
+
+
+class CatalogResponse(BaseModel):
+    server: str = "rugmunch-intelligence"
+    version: str = "4.0"
+    tools: list[dict[str, Any]] = Field(default_factory=list)
+    payment_protocol: str = "x402"
+
+
+class UsageResponse(BaseModel):
+    agent_id: str
+    daily_calls: int
+    free_limit: int
+    paid_calls: int
+    total_usd: float
+    recent_receipts: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class ReceiptResponse(BaseModel):
+    tx_hash: str
+    tool: str
+    agent_id: Optional[str] = None
+    amount_usd: float
+    chain: Optional[str] = None
+    paid_at: Optional[str] = None
+    tier: Optional[str] = None
+
+
+@router.get("/catalog", response_model=CatalogResponse)
+async def catalog() -> CatalogResponse:
+    """List all paid tools with pricing tiers."""
+    return CatalogResponse(tools=[get_tool_metadata(t) for t in PRICING.keys()])
+
+
+@router.get("/usage", response_model=UsageResponse)
+async def usage(request: Request) -> UsageResponse:
+    """Per-agent usage stats: calls made, $ spent, top tools."""
+    catalog = get_catalog()
+    await catalog._init_stores()
+    agent_id = request.headers.get("X-Agent-Id") or request.headers.get("X-Api-Key") or "anon"
+    daily_calls = 0
+    paid_calls = 0
+    total_usd = 0.0
+    recent: list[dict] = []
+    if catalog._health.redis:
+        try:
+            from datetime import datetime, UTC
+            day = datetime.now(UTC).strftime("%Y%m%d")
+            key = f"x402:rl:{agent_id}:{day}"
+            daily_calls = int(await catalog._redis.get(key) or 0)
+        except Exception:
+            pass
+    if catalog._health.postgres:
+        try:
+            async with catalog._pg_pool.acquire() as conn:
+                rows = await conn.fetch(
+                    "SELECT tx_hash, tool, amount_usd, paid_at FROM x402_receipts "
+                    "WHERE agent_id = $1 ORDER BY paid_at DESC LIMIT 10",
+                    agent_id,
+                )
+            for r in rows:
+                paid_calls += 1
+                total_usd += float(r["amount_usd"] or 0)
+                recent.append({
+                    "tx_hash": r["tx_hash"],
+                    "tool": r["tool"],
+                    "amount_usd": float(r["amount_usd"] or 0),
+                    "paid_at": r["paid_at"].isoformat() if r["paid_at"] else None,
+                })
+        except Exception as e:
+            logging.getLogger(__name__).warning(f"usage_query_fail: {e}")
+    return UsageResponse(
+        agent_id=agent_id, daily_calls=daily_calls, free_limit=5,
+        paid_calls=paid_calls, total_usd=round(total_usd, 4),
+        recent_receipts=recent,
+    )
+
+
+@router.get("/receipts/{tx_hash}", response_model=ReceiptResponse)
+async def receipt(tx_hash: str) -> ReceiptResponse:
+    """Payment receipt for a specific on-chain tx."""
+    catalog = get_catalog()
+    await catalog._init_stores()
+    if not catalog._health.postgres:
+        raise HTTPException(503, "postgres unavailable")
+    try:
+        async with catalog._pg_pool.acquire() as conn:
+            r = await conn.fetchrow(
+                "SELECT * FROM x402_receipts WHERE tx_hash=$1", tx_hash
+            )
+        if not r:
+            raise HTTPException(404, "receipt not found")
+        d = dict(r)
+        return ReceiptResponse(
+            tx_hash=d["tx_hash"],
+            tool=d["tool"],
+            agent_id=d.get("agent_id"),
+            amount_usd=float(d.get("amount_usd", 0)),
+            chain=d.get("chain"),
+            paid_at=d["paid_at"].isoformat() if d.get("paid_at") else None,
+            tier=d.get("tier"),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"receipt_query_fail: {e}")
+
+
+@router.post("/verify")
+async def verify_payment(request: Request) -> dict:
+    """Verify an X-Payment header for a given tool."""
+    body = await request.json()
+    tool = body.get("tool", "")
+    x_payment = body.get("x_payment", "")
+    if tool not in PRICING:
+        raise HTTPException(404, f"unknown tool: {tool}")
+    if get_tool_price_usd(tool) == 0:
+        return {"valid": True, "tier": "free", "amount_usd": 0}
+    decoded = verify_payment_header(x_payment, get_tool_price_usd(tool))
+    if not decoded:
+        return {"valid": False, "reason": "invalid format"}
+    tx_hash, _ = decoded
+    valid = await verify_payment_on_chain(tx_hash, get_tool_price_usd(tool))
+    return {
+        "valid": valid,
+        "tool": tool,
+        "amount_usd": get_tool_price_usd(tool),
+        "tx_hash": tx_hash,
+    }

backend/app/mcp/__init__.py

@@ -0,0 +1,10 @@
+# MCP Server Modules
+# ==================
+# x402 gateways run on Cloudflare Workers (7 chains, 45 tools each)
+# The port 8001 local server was shut down - CF Workers handle everything
+# Backend is at /srv/rugmuncher-backend/backend/ (Docker container rmi_backend)
+
+# Legacy reference only - do not import for production use
+# from .x402_mcp_server import X402MCPServer, X402ToolManager
+
+__all__ = []

backend/app/mcp/server.py

@@ -0,0 +1,266 @@
+"""T33 MCP Server — exposes 8 tools to AI agents at mcp.rugmunch.io.
+
+Per v4.0 §T33. JSON-RPC over SSE (the protocol Claude/Cursor speak).
+
+Tools (per v4.0):
+  1. get_token_risk        — Real-time risk score (FREE 5/day or $0.01)
+  2. get_wallet_analysis   — Wallet activity + reputation
+  3. get_deployer_reputation — Deployer reputation (0-100)
+  4. get_news_sentiment    — Latest news + sentiment
+  5. generate_report       — Full AI research report ($5)
+  6. query_catalog         — Natural language catalog query
+  7. find_similar_tokens   — Vector-similar tokens
+  8. resolve_entity        — Cross-chain entity resolution
+
+Backend implementations: app/catalog/* + app/domain/reports/generator.py
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+# Tool catalog — inputSchema follows JSON Schema 2020-12
+TOOL_CATALOG: list[dict[str, Any]] = [
+    {
+        "name": "get_token_risk",
+        "description": "Real-time risk score for any token across 13+ chains. Returns score (0-100), tier (low/medium/high/critical), and risk factors. Free tier: 5 calls/day, $0.01 thereafter.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "chain": {"type": "string", "enum": ["solana", "ethereum", "base", "arbitrum", "optimism", "polygon", "bsc", "tron", "bitcoin", "avalanche", "fantom", "gnosis"]},
+                "address": {"type": "string", "description": "Token contract address"},
+            },
+            "required": ["chain", "address"],
+        },
+    },
+    {
+        "name": "get_wallet_analysis",
+        "description": "Wallet activity, balance, transaction history, and reputation. Returns wallet profile + risk flags.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "chain": {"type": "string"},
+                "address": {"type": "string"},
+            },
+            "required": ["chain", "address"],
+        },
+    },
+    {
+        "name": "get_deployer_reputation",
+        "description": "Deployer reputation score 0-100 (100=clean, 0=serial rugger). Deterministic from on-chain history + news + RAG findings. Cached 1h.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "chain": {"type": "string"},
+                "address": {"type": "string"},
+            },
+            "required": ["chain", "address"],
+        },
+    },
+    {
+        "name": "get_news_sentiment",
+        "description": "Latest news for a token or wallet with sentiment classification. Returns articles + composite sentiment score.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "subject_id": {"type": "string", "description": "chain:address, or 'all' for general news"},
+                "since_hours": {"type": "integer", "default": 24, "minimum": 1, "maximum": 720},
+                "limit": {"type": "integer", "default": 10, "minimum": 1, "maximum": 50},
+            },
+        },
+    },
+    {
+        "name": "generate_report",
+        "description": "Full AI research report on a token or wallet. 7 sections composed in parallel via LLM. $5/report. Returns full Markdown.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "subject_type": {"type": "string", "enum": ["token", "wallet"]},
+                "subject_id": {"type": "string", "description": "chain:address"},
+            },
+            "required": ["subject_type", "subject_id"],
+        },
+    },
+    {
+        "name": "query_catalog",
+        "description": "Natural language catalog query. Returns matching tokens, wallets, deployers, news, RAG findings. $0.05/query.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Natural language question"},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "find_similar_tokens",
+        "description": "Vector-similar tokens to a given token. Returns tokens with cosine similarity >= 0.85. $0.03/query.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "chain": {"type": "string"},
+                "address": {"type": "string"},
+                "limit": {"type": "integer", "default": 10, "maximum": 50},
+            },
+            "required": ["chain", "address"],
+        },
+    },
+    {
+        "name": "resolve_entity",
+        "description": "Cross-chain entity resolution. Given a wallet, find all linked wallets across chains via SAME_AS / FUNDED_BY_SAME / CLONE_OF / BEHAVIORAL_MATCH edges. $0.10/query.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "wallet_id": {"type": "string", "description": "chain:address"},
+            },
+            "required": ["wallet_id"],
+        },
+    },
+]
+
+
+# ── Tool implementations ──────────────────────────────────────────
+async def call_tool(name: str, arguments: dict) -> dict:
+    """Dispatch a tool call to the appropriate backend."""
+    from app.catalog.service import get_catalog
+
+    catalog = get_catalog()
+    await catalog._init_stores()
+
+    if name == "get_token_risk":
+        from app.catalog.models import Chain
+        try:
+            c = Chain(arguments["chain"])
+        except ValueError:
+            return {"error": f"unknown chain: {arguments['chain']}"}
+        result = await catalog.get_token_risk(c, arguments["address"])
+        return {"result": result, "tier": "free_or_pro"}
+
+    if name == "get_wallet_analysis":
+        from app.catalog.models import Chain
+        try:
+            c = Chain(arguments["chain"])
+        except ValueError:
+            return {"error": f"unknown chain: {arguments['chain']}"}
+        w = await catalog.get_wallet(c, arguments["address"])
+        if not w:
+            return {"error": "wallet not found in catalog"}
+        return {"result": w.model_dump(mode="json")}
+
+    if name == "get_deployer_reputation":
+        from app.catalog.models import Chain
+        try:
+            c = Chain(arguments["chain"])
+        except ValueError:
+            return {"error": f"unknown chain: {arguments['chain']}"}
+        w = await catalog.get_wallet(c, arguments["address"])
+        if not w:
+            return {"error": "deployer wallet not found", "reputation_score": 50}
+        # Compute reputation deterministically
+        from app.catalog.reputation import compute_deployer_reputation
+        from app.catalog.models import Deployer
+        deployer = Deployer(
+            wallet_id=w.wallet_id, chain=w.chain, address=w.address,
+            first_seen=w.first_seen, last_seen=w.last_seen,
+            tx_count=w.tx_count, total_volume_usd=w.total_volume_usd,
+            is_deployer=True, reputation_score=w.reputation_score,
+            deployments=getattr(w, "deployments", []),
+            rug_count=getattr(w, "rug_count", 0),
+        )
+        score = await compute_deployer_reputation(deployer, catalog)
+        return {"result": {"reputation_score": score, "tier": _tier_from_score(score)}}
+
+    if name == "get_news_sentiment":
+        subject = arguments.get("subject_id", "all")
+        since = int(arguments.get("since_hours", 24))
+        limit = int(arguments.get("limit", 10))
+        if not catalog._health.postgres:
+            return {"error": "postgres unavailable", "articles": []}
+        try:
+            async with catalog._pg_pool.acquire() as conn:
+                rows = await conn.fetch(
+                    """SELECT news_id, title, summary, source, published_at, sentiment_score
+                       FROM news_items
+                       WHERE published_at > NOW() - ($1 || ' hours')::interval
+                       ORDER BY published_at DESC LIMIT $2""",
+                    str(since), limit,
+                )
+            articles = [
+                {
+                    "news_id": r["news_id"],
+                    "title": r["title"],
+                    "summary": (r["summary"] or "")[:200],
+                    "source": r["source"],
+                    "published_at": r["published_at"].isoformat(),
+                    "sentiment_score": r["sentiment_score"],
+                }
+                for r in rows
+            ]
+            avg_sent = sum(a["sentiment_score"] or 0 for a in articles) / max(1, len(articles))
+            return {"result": {
+                "subject": subject,
+                "article_count": len(articles),
+                "avg_sentiment": round(avg_sent, 3),
+                "articles": articles,
+            }}
+        except Exception as e:
+            return {"error": f"news_query_fail: {e}"}
+
+    if name == "generate_report":
+        from app.domain.reports.generator import generate_token_report, generate_wallet_report
+        chain, address = arguments["subject_id"].split(":", 1)
+        try:
+            if arguments["subject_type"] == "token":
+                report = await generate_token_report(catalog, chain, address)
+            else:
+                report = await generate_wallet_report(catalog, chain, address)
+            from app.domain.reports.generator import save_report
+            await save_report(catalog, report)
+            return {"result": {
+                "report_id": report.report_id,
+                "risk_score": report.risk_score,
+                "risk_tier": report.risk_tier.value,
+                "markdown": report.to_markdown(),
+                "paid_via_x402": None,  # MCP doesn't enforce payment in v1
+            }}
+        except Exception as e:
+            return {"error": f"report_fail: {e}"}
+
+    if name == "query_catalog":
+        # NL query -> RAG search
+        q = arguments.get("query", "")
+        hits = await catalog.rag_search(query=q, top_k=5)
+        return {"result": {"query": q, "hits": hits, "count": len(hits)}}
+
+    if name == "find_similar_tokens":
+        from app.catalog.models import Chain
+        try:
+            c = Chain(arguments["chain"])
+        except ValueError:
+            return {"error": f"unknown chain: {arguments['chain']}"}
+        # Use token's rag_embedding_id to find similar via Qdrant
+        token = await catalog.get_token(c, arguments["address"])
+        if not token or not token.rag_embedding_id:
+            return {"error": "token not in catalog or no RAG embedding", "similar": []}
+        # Use RAG to search for similar by querying with the token's content
+        rag_hits = await catalog.rag_search(query=token.symbol or "token", top_k=int(arguments.get("limit", 10)))
+        return {"result": {"subject": arguments["address"], "similar": rag_hits[:10]}}
+
+    if name == "resolve_entity":
+        result = await catalog.resolve_entity(arguments["wallet_id"])
+        return {"result": result}
+
+    return {"error": f"unknown tool: {name}"}
+
+
+def _tier_from_score(score: int) -> str:
+    if score < 25:
+        return "low"
+    if score < 50:
+        return "medium"
+    if score < 75:
+        return "high"
+    return "critical"

backend/app/mcp/x402_mcp_server.py

@@ -0,0 +1,785 @@
+#!/usr/bin/env python3
+"""
+RMI x402 MCP Server v5.0 - COMPLETE SYSTEM
+==========================================
+
+Complete x402 micropayment gateway with:
+- Free/Trial/Premium tier system
+- Multi-chain support (Base + Solana)
+- AI Guard middleware integration
+- 15+ tool bundles with intelligence suite
+- Solana & Ethereum MCP server integration
+"""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Any
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+logger = logging.getLogger("x402_mcp_server")
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+
+# ============================================================
+# AI GUARD INTEGRATION (works even without app.security module)
+# ============================================================
+
+
+class AIGuardWrapper:
+    """AI Guard that works standalone or with app.security."""
+
+    def __init__(self):
+        self.active = False
+        self.blocked_patterns = [
+            "drop table",
+            "delete from",
+            "insert into",
+            "--",
+            "/*",
+            "xp_",
+            "union select",
+            "exec(",
+            "eval(",
+            "<script",
+            "javascript:",
+            "onload=",
+            "onerror=",
+            "document.cookie",
+            "localStorage",
+            "SELECT * FROM",
+            "DROP TABLE",
+            "INSERT INTO",
+            "DELETE FROM",
+        ]
+        self._load_external_guard()
+
+    def _load_external_guard(self):
+        """Try to load RugMunch's actual AI Guard if available."""
+        try:
+            import sys
+
+            sys.path.insert(0, "/srv/rugmuncher-backend/backend/app")
+            from security.ai_guard import AIGuard
+
+            self._guard = AIGuard()
+            self.active = True
+            logger.info("✅ AI Guard loaded from RugMunch security module")
+        except Exception as e:
+            logger.warning(f"⚠️ Using standalone AI Guard (external module unavailable: {e})")
+            self._guard = None
+            self.active = True  # Standalone still works
+
+    async def check_request(self, request: Request) -> tuple[bool, str | None]:
+        """Check request for security violations."""
+        # Check headers
+        user_agent = request.headers.get("User-Agent", "").lower()
+        if any(bot in user_agent for bot in ["sqlmap", "nikto", "nmap", "masscan", "zgrab"]):
+            return False, "Security scanner detected"
+
+        # Check body for POST/PUT/PATCH
+        if request.method in ("POST", "PUT", "PATCH"):
+            try:
+                body = await request.body()
+                body_str = body.decode("utf-8", errors="ignore").lower()
+                for pattern in self.blocked_patterns:
+                    if pattern in body_str:
+                        return False, f"Malicious pattern detected: {pattern}"
+            except:
+                pass
+
+        return True, None
+
+
+# ============================================================
+# DATA MODELS
+# ============================================================
+
+
+@dataclass
+class X402Bundle:
+    """Complete x402 tool bundle definition."""
+
+    bundle_id: str
+    name: str
+    description: str
+    category: str
+    endpoints: list[dict[str, Any]] = field(default_factory=list)
+    price_usd: float = 0.0
+    tier: str = "standard"  # free, trial, standard, premium, enterprise
+    is_premium: bool = False
+    requires_payment: bool = True
+
+    @property
+    def base_eth(self) -> str:
+        return f"{self.price_usd / 3000:.6f} ETH"
+
+    @property
+    def solana_usdc(self) -> str:
+        return f"{self.price_usd:.2f} USDC"
+
+    def dict(self) -> dict[str, Any]:
+        return {
+            "bundle_id": self.bundle_id,
+            "name": self.name,
+            "description": self.description,
+            "category": self.category,
+            "endpoints": self.endpoints,
+            "endpoint_count": len(self.endpoints),
+            "price_usd": self.price_usd,
+            "tier": self.tier,
+            "is_premium": self.is_premium,
+            "requires_payment": self.requires_payment,
+            "pricing": {"base": self.base_eth, "solana": self.solana_usdc},
+        }
+
+
+# ============================================================
+# FACILITATOR CONFIG
+# ============================================================
+
+
+class MultiChainFacilitator:
+    """Multi-chain payment facilitator."""
+
+    base_config = {
+        "name": "RugMunch Intelligence x402 Gateway",
+        "network": "BASE",
+        "wallet_address": os.environ.get("X402_BASE_WALLET", "0x1E3AC01d0fdb976179790BDD02823196A92705C9"),
+        "token_symbol": "ETH",
+        "token_decimals": 18,
+        "rpc_url": "https://mainnet.base.org",
+        "explorer": "https://basescan.org",
+    }
+
+    solana_config = {
+        "name": "RugMunch Intelligence x402 Gateway",
+        "network": "SOLANA",
+        "wallet_address": os.environ.get("X402_SOLANA_WALLET", "Gix4P9AmwcZRGzr2hCEME5m2QAvY86dBfm8c7e7MpFzv"),
+        "token_symbol": "USDC",
+        "token_decimals": 6,
+        "rpc_url": "https://api.mainnet-beta.solana.com",
+        "explorer": "https://solscan.io",
+    }
+
+    third_party = {
+        "base": "https://mcp.rugmunch.io",
+        "solana": "https://mcp.rugmunch.io",
+    }
+
+
+# ============================================================
+# TOOL MANAGER - COMPLETE CATALOG
+# ============================================================
+
+
+class X402ToolManager:
+    """Manages all x402 tool bundles including free/trial/premium."""
+
+    def __init__(self):
+        self._bundles = self._load_all_bundles()
+        self._index = {b.bundle_id: b for b in self._bundles}
+        self._index.update({b.name.lower(): b for b in self._bundles})
+
+    def _load_all_bundles(self) -> list[X402Bundle]:
+        """Load complete catalog: free, trial, standard, premium."""
+
+        return [
+            # ========== FREE TIER ==========
+            X402Bundle(
+                bundle_id="free-health",
+                name="Free Health Check",
+                description="Free system health and status endpoints",
+                category="free",
+                endpoints=[
+                    {"method": "GET", "path": "/health", "description": "System health"},
+                    {"method": "GET", "path": "/status", "description": "System status"},
+                    {"method": "GET", "path": "/version", "description": "API version"},
+                ],
+                price_usd=0.0,
+                tier="free",
+                is_premium=False,
+                requires_payment=False,
+            ),
+            X402Bundle(
+                bundle_id="free-discovery",
+                name="Free Tool Discovery",
+                description="Discover all available tools without payment",
+                category="free",
+                endpoints=[
+                    {"method": "GET", "path": "/.well-known/x402", "description": "x402 discovery"},
+                    {"method": "GET", "path": "/v1/bundles", "description": "List all bundles"},
+                    {"method": "GET", "path": "/v1/bundles/{id}", "description": "Bundle details"},
+                ],
+                price_usd=0.0,
+                tier="free",
+                is_premium=False,
+                requires_payment=False,
+            ),
+            # ========== TRIAL TIER ==========
+            X402Bundle(
+                bundle_id="trial-security",
+                name="Trial Security Suite",
+                description="7-day trial of premium security tools",
+                category="trial",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/scan/contract",
+                        "description": "Smart contract scan",
+                    },
+                    {"method": "POST", "path": "/scan/token", "description": "Token risk scan"},
+                    {"method": "POST", "path": "/scan/wallet", "description": "Wallet risk scan"},
+                ],
+                price_usd=0.0,
+                tier="trial",
+                is_premium=False,
+                requires_payment=False,
+            ),
+            X402Bundle(
+                bundle_id="trial-intelligence",
+                name="Trial Intelligence Suite",
+                description="7-day trial of market intelligence tools",
+                category="trial",
+                endpoints=[
+                    {"method": "GET", "path": "/market/pulse", "description": "Token pulse"},
+                    {"method": "GET", "path": "/market/trends", "description": "Market trends"},
+                    {"method": "GET", "path": "/market/whales", "description": "Whale tracking"},
+                ],
+                price_usd=0.0,
+                tier="trial",
+                is_premium=False,
+                requires_payment=False,
+            ),
+            # ========== STANDARD TIER ==========
+            X402Bundle(
+                bundle_id="token-pulse",
+                name="Token Pulse",
+                description="Real-time market momentum, volume, whale alerts",
+                category="market",
+                endpoints=[
+                    {"method": "GET", "path": "/tokens", "description": "Token listings"},
+                    {"method": "GET", "path": "/tokens/{address}", "description": "Token details"},
+                    {
+                        "method": "GET",
+                        "path": "/lp/{address}",
+                        "description": "Liquidity pool analysis",
+                    },
+                ],
+                price_usd=0.01,
+                tier="standard",
+            ),
+            X402Bundle(
+                bundle_id="url-scam-detector",
+                name="URL Scam Detector",
+                description="Detect phishing sites, fake docs, malicious redirects",
+                category="security",
+                endpoints=[
+                    {"method": "POST", "path": "/scan/url", "description": "URL scan"},
+                    {"method": "POST", "path": "/scan/domain", "description": "Domain analysis"},
+                ],
+                price_usd=0.01,
+                tier="standard",
+            ),
+            X402Bundle(
+                bundle_id="wallet-profiler",
+                name="Wallet Profiler",
+                description="Full wallet analysis with persona detection",
+                category="wallet",
+                endpoints=[
+                    {"method": "POST", "path": "/wallet/profile", "description": "Profile wallet"},
+                    {
+                        "method": "POST",
+                        "path": "/wallet/history",
+                        "description": "Transaction history",
+                    },
+                ],
+                price_usd=0.05,
+                tier="standard",
+            ),
+            X402Bundle(
+                bundle_id="social-sentiment",
+                name="Social Sentiment",
+                description="Cross-platform sentiment analysis",
+                category="market",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/sentiment/analyze",
+                        "description": "Analyze sentiment",
+                    },
+                    {
+                        "method": "GET",
+                        "path": "/sentiment/trends",
+                        "description": "Trending topics",
+                    },
+                ],
+                price_usd=0.03,
+                tier="standard",
+            ),
+            # ========== PREMIUM TIER ==========
+            X402Bundle(
+                bundle_id="suspicious-transfers",
+                name="Suspicious Transfers Scanner",
+                description="Cross-chain anomaly detection with RugMunch intelligence",
+                category="security",
+                endpoints=[
+                    {"method": "POST", "path": "/scan/transfers", "description": "Scan transfers"},
+                    {"method": "GET", "path": "/scan/results", "description": "Get results"},
+                    {"method": "POST", "path": "/scan/anomaly", "description": "Anomaly detection"},
+                ],
+                price_usd=0.15,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="wallet-labeler",
+                name="Wallet Labeler",
+                description="Behavioral reputation engine (Arkham+Nansen+Alchemy)",
+                category="security",
+                endpoints=[
+                    {"method": "POST", "path": "/label/wallet", "description": "Label wallet"},
+                    {"method": "GET", "path": "/label/history", "description": "Label history"},
+                    {
+                        "method": "POST",
+                        "path": "/label/cluster",
+                        "description": "Cluster detection",
+                    },
+                ],
+                price_usd=0.20,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="memory-bank",
+                name="Memory Bank",
+                description="Unified agent knowledge store with GCS export",
+                category="ai",
+                endpoints=[
+                    {"method": "POST", "path": "/memory/store", "description": "Store knowledge"},
+                    {"method": "GET", "path": "/memory/query", "description": "Query knowledge"},
+                    {"method": "POST", "path": "/memory/export", "description": "Export to GCS"},
+                ],
+                price_usd=0.12,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="deep-contract-audit",
+                name="Deep Contract Audit",
+                description="Smart contract audit, honeypot detection, hidden mint functions",
+                category="security",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/audit/contract",
+                        "description": "Full contract audit",
+                    },
+                    {"method": "POST", "path": "/audit/honeypot", "description": "Honeypot check"},
+                    {
+                        "method": "POST",
+                        "path": "/audit/proxy",
+                        "description": "Proxy pattern check",
+                    },
+                ],
+                price_usd=0.05,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="token-forensics",
+                name="Token Forensics",
+                description="Deep forensics from DexScreener, GeckoTerminal, CoinGecko",
+                category="forensics",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/forensics/token",
+                        "description": "Token forensics",
+                    },
+                    {
+                        "method": "POST",
+                        "path": "/forensics/report",
+                        "description": "Generate report",
+                    },
+                ],
+                price_usd=0.10,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="whale-decoder",
+                name="Whale Decoder",
+                description="Advanced whale wallet analysis across chains",
+                category="wallet",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/whale/decode",
+                        "description": "Decode whale strategy",
+                    },
+                    {"method": "GET", "path": "/whale/positions", "description": "Track positions"},
+                ],
+                price_usd=0.15,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="darkroom-security",
+                name="Darkroom Security Suite",
+                description="Advanced security analysis, threat detection, forensics",
+                category="security",
+                endpoints=[
+                    {"method": "POST", "path": "/security/scan", "description": "Security scan"},
+                    {
+                        "method": "POST",
+                        "path": "/security/threats",
+                        "description": "Threat database",
+                    },
+                    {
+                        "method": "POST",
+                        "path": "/security/forensics",
+                        "description": "Forensic analysis",
+                    },
+                ],
+                price_usd=0.20,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="solana-mcp",
+                name="Solana MCP Server",
+                description="Native Solana blockchain queries via MCP protocol",
+                category="mcp",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/mcp/solana/balance",
+                        "description": "Get SOL balance",
+                    },
+                    {
+                        "method": "POST",
+                        "path": "/mcp/solana/transaction",
+                        "description": "Get transaction",
+                    },
+                    {
+                        "method": "POST",
+                        "path": "/mcp/solana/tokens",
+                        "description": "Get token accounts",
+                    },
+                    {
+                        "method": "POST",
+                        "path": "/mcp/solana/simulate",
+                        "description": "Simulate transaction",
+                    },
+                ],
+                price_usd=0.08,
+                tier="premium",
+                is_premium=True,
+            ),
+            X402Bundle(
+                bundle_id="ethereum-mcp",
+                name="Ethereum MCP Server",
+                description="Native Ethereum blockchain queries via MCP protocol",
+                category="mcp",
+                endpoints=[
+                    {
+                        "method": "POST",
+                        "path": "/mcp/eth/balance",
+                        "description": "Get ETH balance",
+                    },
+                    {
+                        "method": "POST",
+                        "path": "/mcp/eth/transaction",
+                        "description": "Get transaction",
+                    },
+                    {"method": "POST", "path": "/mcp/eth/call", "description": "Call contract"},
+                    {"method": "POST", "path": "/mcp/eth/logs", "description": "Get event logs"},
+                    {"method": "POST", "path": "/mcp/eth/ens", "description": "Resolve ENS"},
+                ],
+                price_usd=0.08,
+                tier="premium",
+                is_premium=True,
+            ),
+        ]
+
+    def list_bundles(self, tier: str | None = None) -> list[X402Bundle]:
+        """List all or filtered bundles."""
+        if tier:
+            return [b for b in self._bundles if b.tier == tier]
+        return self._bundles
+
+    def get_bundle(self, identifier: str) -> X402Bundle | None:
+        return self._index.get(identifier.lower())
+
+    @property
+    def free_bundles(self) -> list[X402Bundle]:
+        return [b for b in self._bundles if b.tier == "free"]
+
+    @property
+    def trial_bundles(self) -> list[X402Bundle]:
+        return [b for b in self._bundles if b.tier == "trial"]
+
+    @property
+    def premium_bundles(self) -> list[X402Bundle]:
+        return [b for b in self._bundles if b.is_premium]
+
+    @property
+    def total_endpoints(self) -> int:
+        return sum(len(b.endpoints) for b in self._bundles)
+
+
+# ============================================================
+# MAIN X402 SERVER
+# ============================================================
+
+
+class X402MCPServer:
+    """Complete x402 MCP server v5.0."""
+
+    def __init__(self):
+        self._tool_manager = X402ToolManager()
+        self._facilitator = MultiChainFacilitator()
+        self._ai_guard = AIGuardWrapper()
+        self._app = None
+
+        b = self._tool_manager
+        logger.info("🎉 x402 MCP v5.0 initialized")
+        logger.info(f"   Bundles: {len(b.list_bundles())}")
+        logger.info(
+            f"   Free: {len(b.free_bundles)} | Trial: {len(b.trial_bundles)} | Premium: {len(b.premium_bundles)}"
+        )
+        logger.info(f"   Endpoints: {b.total_endpoints}")
+        logger.info(f"   Revenue/call: ${sum(b.price_usd for b in b.list_bundles()):.2f}")
+        logger.info(f"   AI Guard: {'✅ Active' if self._ai_guard.active else '❌ Inactive'}")
+
+    def streamable_http_app(self) -> FastAPI:
+        if self._app is not None:
+            return self._app
+
+        app = FastAPI(
+            title="RugMunch Intelligence x402 Gateway v5.0",
+            description="Complete crypto security & intelligence x402 gateway with free/trial/premium tiers",
+            version="5.0.0",
+            docs_url="/",
+        )
+
+        self._add_system_endpoints(app)
+        self._add_discovery_endpoints(app)
+        self._add_middleware(app)
+
+        self._app = app
+        return app
+
+    def _add_system_endpoints(self, app: FastAPI):
+        """Health, status, version endpoints."""
+
+        @app.get("/health")
+        async def health():
+            b = self._tool_manager
+            return JSONResponse(
+                {
+                    "status": "healthy",
+                    "version": "5.0.0",
+                    "timestamp": datetime.utcnow().isoformat(),
+                    "statistics": {
+                        "bundles": len(b.list_bundles()),
+                        "free": len(b.free_bundles),
+                        "trial": len(b.trial_bundles),
+                        "standard": len([x for x in b.list_bundles() if x.tier == "standard"]),
+                        "premium": len(b.premium_bundles),
+                        "endpoints": b.total_endpoints,
+                    },
+                    "ai_guard": self._ai_guard.active,
+                    "chains": ["base", "solana"],
+                    "facilitator": {
+                        "base_wallet": self._facilitator.base_config["wallet_address"][:20] + "...",
+                        "solana_wallet": self._facilitator.solana_config["wallet_address"][:20] + "...",
+                    },
+                }
+            )
+
+        @app.get("/version")
+        async def version():
+            return JSONResponse(
+                {
+                    "version": "5.0.0",
+                    "name": "RugMunch Intelligence x402 Gateway",
+                    "chains": ["base", "solana"],
+                    "tiers": ["free", "trial", "standard", "premium"],
+                }
+            )
+
+    def _add_discovery_endpoints(self, app: FastAPI):
+        """x402 discovery and bundle listing."""
+
+        @app.get("/.well-known/x402")
+        async def discovery():
+            b = self._tool_manager
+            return JSONResponse(
+                {
+                    "version": "5.0.0",
+                    "name": "RugMunch Intelligence x402 Gateway",
+                    "description": "Complete crypto security & intelligence with free/trial/premium tiers",
+                    "facilitators": {
+                        "base": self._facilitator.base_config,
+                        "solana": self._facilitator.solana_config,
+                        "third_party": self._facilitator.third_party,
+                    },
+                    "bundles": [bundle.dict() for bundle in b.list_bundles()],
+                    "tiers": {
+                        "free": [bundle.dict() for bundle in b.free_bundles],
+                        "trial": [bundle.dict() for bundle in b.trial_bundles],
+                        "premium": [bundle.dict() for bundle in b.premium_bundles],
+                    },
+                    "statistics": {
+                        "total_bundles": len(b.list_bundles()),
+                        "total_endpoints": b.total_endpoints,
+                        "free_count": len(b.free_bundles),
+                        "trial_count": len(b.trial_bundles),
+                        "premium_count": len(b.premium_bundles),
+                        "max_revenue_usd": f"${sum(x.price_usd for x in b.list_bundles()):.2f}",
+                    },
+                    "mcp_servers": {
+                        "solana": "/mcp/solana",
+                        "ethereum": "/mcp/eth",
+                    },
+                    "documentation": "https://docs.rugmunch.io/x402-v5",
+                    "support": "support@rugmunch.io",
+                }
+            )
+
+        @app.get("/v1/bundles")
+        async def list_bundles(tier: str | None = None):
+            bundles = self._tool_manager.list_bundles(tier)
+            return JSONResponse(
+                {
+                    "success": True,
+                    "count": len(bundles),
+                    "tier_filter": tier,
+                    "bundles": [b.dict() for b in bundles],
+                }
+            )
+
+        @app.get("/v1/bundles/{bundle_id}")
+        async def get_bundle(bundle_id: str):
+            bundle = self._tool_manager.get_bundle(bundle_id)
+            if not bundle:
+                raise HTTPException(status_code=404, detail="Bundle not found")
+
+            return JSONResponse(
+                {
+                    "success": True,
+                    "bundle": bundle.dict(),
+                    "payment_requirements": {
+                        "base": self._get_payment_req(bundle, "base"),
+                        "solana": self._get_payment_req(bundle, "solana"),
+                    },
+                }
+            )
+
+    def _add_middleware(self, app: FastAPI):
+        """AI Guard + x402 payment middleware."""
+
+        @app.middleware("http")
+        async def security_and_payment_middleware(request: Request, call_next):
+            path = request.url.path
+
+            # Skip free endpoints
+            if any(
+                path.startswith(p) for p in ["/health", "/version", "/.well-known", "/docs", "/openapi", "/v1/bundles"]
+            ):
+                return await call_next(request)
+
+            # AI Guard check
+            if self._ai_guard.active:
+                is_safe, reason = await self._ai_guard.check_request(request)
+                if not is_safe:
+                    return JSONResponse(
+                        {
+                            "error": "Request blocked by AI Guard",
+                            "code": "AI_GUARD_BLOCKED",
+                            "reason": reason,
+                        },
+                        status_code=403,
+                    )
+
+            # x402 payment check for premium bundles
+            # Extract bundle from path
+            path_parts = path.split("/")
+            if len(path_parts) >= 2:
+                bundle_id = (
+                    path_parts[1]
+                    if not path_parts[1].startswith("v1")
+                    else path_parts[2]
+                    if len(path_parts) > 2
+                    else None
+                )
+
+                if bundle_id:
+                    bundle = self._tool_manager.get_bundle(bundle_id)
+                    if bundle and bundle.requires_payment and bundle.price_usd > 0:
+                        x402_header = request.headers.get("X-Payment")
+                        solana_payment = request.headers.get("X-Solana-Payment")
+
+                        if not x402_header and not solana_payment:
+                            return JSONResponse(
+                                content={
+                                    "error": "Payment required",
+                                    "code": "PAYMENT_REQUIRED",
+                                    "bundle": bundle_id,
+                                    "bundle_name": bundle.name,
+                                    "price_usd": bundle.price_usd,
+                                    "payment_options": {
+                                        "base": self._get_payment_req(bundle, "base"),
+                                        "solana": self._get_payment_req(bundle, "solana"),
+                                    },
+                                    "instructions": "Include X-Payment (Base) or X-Solana-Payment (Solana) header with transaction proof",
+                                },
+                                status_code=402,
+                                headers={
+                                    "X-Payment-Required": "true",
+                                    "X-Payment-Address-Base": self._facilitator.base_config["wallet_address"],
+                                    "X-Payment-Address-Solana": self._facilitator.solana_config["wallet_address"],
+                                    "X-Bundle-Name": bundle.name,
+                                    "X-Price-USD": str(bundle.price_usd),
+                                },
+                            )
+
+            return await call_next(request)
+
+    def _get_payment_req(self, bundle: X402Bundle, chain: str) -> dict[str, Any]:
+        facilitator = self._facilitator.base_config if chain == "base" else self._facilitator.solana_config
+
+        if chain == "solana":
+            amount_atomic = int(bundle.price_usd * 10**6)
+            symbol = "USDC"
+            decimals = 6
+        else:
+            amount_atomic = int(bundle.price_usd / 3000 * 10**18)
+            symbol = "ETH"
+            decimals = 18
+
+        return {
+            "chain": chain.upper(),
+            "network": facilitator["network"],
+            "amount_usd": bundle.price_usd,
+            "amount_atomic": amount_atomic,
+            "symbol": symbol,
+            "decimals": decimals,
+            "recipient_address": facilitator["wallet_address"],
+            "reference": f"bundle-{bundle.bundle_id}",
+            "valid_until": (datetime.utcnow() + timedelta(hours=1)).isoformat(),
+        }
+
+
+# Create global instance
+mcp = X402MCPServer()
+
+if __name__ == "__main__":
+    app = mcp.streamable_http_app()
+    uvicorn.run(app, host="0.0.0.0", port=8001)

backend/main.py

@@ -213,12 +213,14 @@ def _try_mount_v1_routers() -> int:
         "app.api.v1.public.token",
         "app.api.v1.public.scanner",
         "app.api.v1.rag.search",
-        "app.api.v1.x402.payments",
+        # x402 moved to app.domain.x402 (T34 v2) — old payments.py removed
         "app.api.v1.admin.alerts_webhook",
         "app.api.v1.catalog",
+        "app.api.v1.mcp",
         "app.domain.news",
         "app.domain.news.admin_router",
         "app.domain.reports",
+        "app.domain.x402",
     ]
 
     for module_path in v1_modules: