profunding-mcp 0.2.0__tar.gz

profunding_mcp-0.2.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+.venv/
+
+# Node
+node_modules/
+.next/
+out/
+npm-debug.log*
+
+# Environment
+.env
+.env.local
+.env.prod
+secrets.txt
+
+# Skills / local agent files
+.agents/
+.claude/skills/
+.claude/settings.local.json
+skills-lock.json
+backend/skills-lock.json
+
+# Windows artifacts
+nul
+backend/nul
+
+# Local files
+SALES_PITCH.md
+video/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Database
+*.db
+*.sqlite
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.log

profunding_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: profunding-mcp
+Version: 0.2.0
+Summary: MCP server for ProFunding — AI-powered funding rate arbitrage across 20+ perp DEXes
+Project-URL: Homepage, https://profunding.pro
+Project-URL: Repository, https://github.com/Desperate10/dex_funding_dashboard
+License-Expression: MIT
+Keywords: arbitrage,defi,delta-neutral,funding-rate,mcp,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# ProFunding MCP Server
+
+MCP server for [ProFunding](https://profunding.pro) — AI-powered funding rate arbitrage across 20+ perpetual DEXes.
+
+Analyze delta-neutral opportunities, check real-time liquidity, run backtests, and get deep analytics directly from your AI assistant.
+
+## Installation
+
+```bash
+pip install profunding-mcp
+```
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add profunding profunding-mcp -e PROFUNDING_API_KEY=pfk_your_key_here
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "profunding": {
+      "command": "profunding-mcp",
+      "env": {
+        "PROFUNDING_API_KEY": "pfk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PROFUNDING_API_KEY` | No | (none) | API key. Free tier works without key. |
+| `PROFUNDING_API_URL` | No | `https://profunding.pro/api/api` | API base URL |
+
+## Tools (20)
+
+### Free Tier
+
+| Tool | Description |
+|------|-------------|
+| `get_opportunities` | Live funding rate arbitrage opportunities across all DEXes |
+| `get_exchanges` | List connected DEXes with status and funding interval |
+| `get_historical_rates` | Historical funding rates for a symbol on one exchange |
+| `run_backtest` | Backtest a delta-neutral trade with real historical data |
+| `get_rate_chart_data` | Funding rate spread over time between two exchanges |
+
+### Paid Tier — Analysis
+
+| Tool | Description |
+|------|-------------|
+| `analyze_pair` | Full end-to-end analysis: funding + backtest + risk + depth on both legs + price spread — one call |
+| `compare_exchanges` | Side-by-side comparison of same symbol across exchanges: rates, spread, depth, volume |
+| `find_best_trade` | Best trade you can open RIGHT NOW at your position size — ranked by composite score |
+| `get_smart_opportunities` | Opportunities ranked by tradability (APR x stability x depth x data confidence) |
+| `check_liquidity` | Real-time order book depth + slippage estimates at $1k/$5k/$10k |
+| `get_pair_intelligence` | Risk scores, backtested APR, smart ranking, depth tiers for all pairs |
+| `get_price_spread_data` | Mark price divergence between two exchanges (price risk analysis) |
+
+### Paid Tier — Analytics
+
+| Tool | Description |
+|------|-------------|
+| `get_live_alpha` | Top 5 deduplicated opportunities |
+| `get_still_paying` | Pairs above 50% APR for 24h+ still active now |
+| `get_top_holders` | Pairs holding high APR the longest |
+| `get_momentum_movers` | Biggest funding spread jumps in last 6 hours |
+| `get_weekly_recap` | Best ROI pair, best DEX combo, most stable pair |
+| `get_unbroken_streaks` | Consecutive hours above APR threshold |
+| `get_record_roi` | Best single trade by ROI in a period |
+
+## Example Queries
+
+Once connected, ask your AI assistant:
+
+- "What's the best trade I can open right now with $5k?"
+- "Analyze MEGA/USDC on Extended/Aster — is it worth entering?"
+- "Compare ETH funding rates across Hyperliquid, dYdX, and Aster"
+- "Check liquidity for SOL on Paradex — can I fill $10k?"
+- "Run a 30-day backtest on XMR long Nado short dYdX"
+- "Which pairs have been paying above 50% for 3+ days straight?"
+- "What moved the most in the last 6 hours?"
+
+## Get an API Key
+
+Visit [profunding.pro](https://profunding.pro) to get your API key.

profunding_mcp-0.2.0/README.md

@@ -0,0 +1,95 @@
+# ProFunding MCP Server
+
+MCP server for [ProFunding](https://profunding.pro) — AI-powered funding rate arbitrage across 20+ perpetual DEXes.
+
+Analyze delta-neutral opportunities, check real-time liquidity, run backtests, and get deep analytics directly from your AI assistant.
+
+## Installation
+
+```bash
+pip install profunding-mcp
+```
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add profunding profunding-mcp -e PROFUNDING_API_KEY=pfk_your_key_here
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "profunding": {
+      "command": "profunding-mcp",
+      "env": {
+        "PROFUNDING_API_KEY": "pfk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PROFUNDING_API_KEY` | No | (none) | API key. Free tier works without key. |
+| `PROFUNDING_API_URL` | No | `https://profunding.pro/api/api` | API base URL |
+
+## Tools (20)
+
+### Free Tier
+
+| Tool | Description |
+|------|-------------|
+| `get_opportunities` | Live funding rate arbitrage opportunities across all DEXes |
+| `get_exchanges` | List connected DEXes with status and funding interval |
+| `get_historical_rates` | Historical funding rates for a symbol on one exchange |
+| `run_backtest` | Backtest a delta-neutral trade with real historical data |
+| `get_rate_chart_data` | Funding rate spread over time between two exchanges |
+
+### Paid Tier — Analysis
+
+| Tool | Description |
+|------|-------------|
+| `analyze_pair` | Full end-to-end analysis: funding + backtest + risk + depth on both legs + price spread — one call |
+| `compare_exchanges` | Side-by-side comparison of same symbol across exchanges: rates, spread, depth, volume |
+| `find_best_trade` | Best trade you can open RIGHT NOW at your position size — ranked by composite score |
+| `get_smart_opportunities` | Opportunities ranked by tradability (APR x stability x depth x data confidence) |
+| `check_liquidity` | Real-time order book depth + slippage estimates at $1k/$5k/$10k |
+| `get_pair_intelligence` | Risk scores, backtested APR, smart ranking, depth tiers for all pairs |
+| `get_price_spread_data` | Mark price divergence between two exchanges (price risk analysis) |
+
+### Paid Tier — Analytics
+
+| Tool | Description |
+|------|-------------|
+| `get_live_alpha` | Top 5 deduplicated opportunities |
+| `get_still_paying` | Pairs above 50% APR for 24h+ still active now |
+| `get_top_holders` | Pairs holding high APR the longest |
+| `get_momentum_movers` | Biggest funding spread jumps in last 6 hours |
+| `get_weekly_recap` | Best ROI pair, best DEX combo, most stable pair |
+| `get_unbroken_streaks` | Consecutive hours above APR threshold |
+| `get_record_roi` | Best single trade by ROI in a period |
+
+## Example Queries
+
+Once connected, ask your AI assistant:
+
+- "What's the best trade I can open right now with $5k?"
+- "Analyze MEGA/USDC on Extended/Aster — is it worth entering?"
+- "Compare ETH funding rates across Hyperliquid, dYdX, and Aster"
+- "Check liquidity for SOL on Paradex — can I fill $10k?"
+- "Run a 30-day backtest on XMR long Nado short dYdX"
+- "Which pairs have been paying above 50% for 3+ days straight?"
+- "What moved the most in the last 6 hours?"
+
+## Get an API Key
+
+Visit [profunding.pro](https://profunding.pro) to get your API key.

profunding_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "profunding-mcp"
+version = "0.2.0"
+description = "MCP server for ProFunding — AI-powered funding rate arbitrage across 20+ perp DEXes"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["mcp", "funding-rate", "arbitrage", "defi", "trading", "delta-neutral"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://profunding.pro"
+Repository = "https://github.com/Desperate10/dex_funding_dashboard"
+
+[project.scripts]
+profunding-mcp = "profunding_mcp.server:main"

profunding_mcp-0.2.0/src/profunding_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ProFunding MCP Server — funding rate arbitrage data for AI assistants."""
+
+__version__ = "0.1.0"

profunding_mcp-0.2.0/src/profunding_mcp/client.py

@@ -0,0 +1,58 @@
+"""HTTP client for the ProFunding REST API."""
+
+import httpx
+from typing import Any, Optional
+
+from .config import API_URL, API_KEY
+
+
+class ProFundingClient:
+    """Thin wrapper around the ProFunding REST API."""
+
+    def __init__(self):
+        headers = {"Content-Type": "application/json"}
+        if API_KEY:
+            headers["X-API-Key"] = API_KEY
+        self._client = httpx.AsyncClient(
+            base_url=API_URL,
+            headers=headers,
+            timeout=30.0,
+        )
+        self._tier: Optional[str] = None
+
+    async def validate_key(self) -> dict:
+        """Validate the API key at startup and cache the tier."""
+        if not API_KEY:
+            self._tier = "free"
+            return {"valid": True, "tier": "free"}
+        resp = await self._client.get("/mcp/validate")
+        resp.raise_for_status()
+        data = resp.json()
+        self._tier = data.get("tier", "free")
+        return data
+
+    @property
+    def tier(self) -> str:
+        return self._tier or "free"
+
+    def is_paid(self) -> bool:
+        return self._tier == "paid"
+
+    async def get(self, path: str, params: Optional[dict] = None) -> Any:
+        """GET request to the API."""
+        resp = await self._client.get(path, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def post(self, path: str, json: Optional[dict] = None) -> Any:
+        """POST request to the API."""
+        resp = await self._client.post(path, json=json)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def close(self):
+        await self._client.aclose()
+
+
+# Singleton
+client = ProFundingClient()

profunding_mcp-0.2.0/src/profunding_mcp/config.py

@@ -0,0 +1,9 @@
+"""Configuration from environment variables."""
+
+import os
+
+
+# Double /api/api: nginx rewrites /api/* → /* but backend routes are mounted at /api,
+# so external callers need /api/api to reach /api/* on the backend.
+API_URL = os.getenv("PROFUNDING_API_URL", "https://profunding.pro/api/api")
+API_KEY = os.getenv("PROFUNDING_API_KEY", "")

profunding_mcp-0.2.0/src/profunding_mcp/server.py

@@ -0,0 +1,906 @@
+"""ProFunding MCP Server — funding rate arbitrage tools for AI assistants."""
+
+from contextlib import asynccontextmanager
+from mcp.server.fastmcp import FastMCP
+from .client import client
+
+
+@asynccontextmanager
+async def _lifespan(server):
+    """Validate API key on startup."""
+    try:
+        info = await client.validate_key()
+        tier = info.get("tier", "free")
+    except Exception:
+        tier = "free"
+    yield
+    await client.close()
+
+
+mcp = FastMCP(
+    "ProFunding",
+    instructions="Live funding rate arbitrage data across 20+ perpetual DEXes. "
+    "Find delta-neutral trading opportunities, run backtests, and get deep analytics.",
+    lifespan=_lifespan,
+)
+
+
+# ─── Helpers ──────────────────────────────────────────────────
+
+async def _ensure_validated():
+    """Lazy-validate the API key if not done yet."""
+    if client._tier is None:
+        try:
+            await client.validate_key()
+        except Exception:
+            client._tier = "free"
+
+
+async def _require_paid():
+    """Raise if the API key doesn't have paid tier."""
+    await _ensure_validated()
+    if not client.is_paid():
+        raise ValueError(
+            "This tool requires a paid ProFunding API key. "
+            "Visit profunding.pro to upgrade."
+        )
+
+
+def _fmt_opp(o: dict) -> str:
+    """Format a single opportunity for display."""
+    line = (
+        f"  {o['symbol']} — Long {o['long_exchange']} ({o['long_apr']:+.1f}%) / "
+        f"Short {o['short_exchange']} ({o['short_apr']:+.1f}%) — "
+        f"Net {o['net_apr']:.1f}% APR, breakeven {o.get('breakeven_days', '?')} days"
+    )
+    # Add liquidity info if available
+    tags = []
+    long_spread = o.get('long_spread_pct')
+    short_spread = o.get('short_spread_pct')
+    if long_spread is not None or short_spread is not None:
+        worst_spread = max(long_spread or 0, short_spread or 0)
+        tags.append(f"spread {worst_spread:.2f}%")
+    long_vol = o.get('long_volume_24h')
+    short_vol = o.get('short_volume_24h')
+    if long_vol is not None or short_vol is not None:
+        min_volume = min(long_vol or float('inf'), short_vol or float('inf'))
+        if min_volume < float('inf'):
+            tags.append(f"vol ${min_volume:,.0f}")
+    if tags:
+        line += f" [{', '.join(tags)}]"
+    return line
+
+
+# ─── FREE TIER TOOLS ─────────────────────────────────────────
+
+@mcp.tool()
+async def get_opportunities(
+    min_apr: float = 0,
+    symbol: str = "",
+    exchange: str = "",
+    limit: int = 20,
+) -> str:
+    """Get live funding rate arbitrage opportunities across all DEXes.
+
+    Args:
+        min_apr: Minimum net APR to filter (default 0)
+        symbol: Filter by trading pair (e.g. "ETH/USDC")
+        exchange: Filter by exchange name (e.g. "Hyperliquid")
+        limit: Max number of results (default 20)
+    """
+    params = {}
+    if min_apr > 0:
+        params["min_apr"] = min_apr
+    if symbol:
+        params["symbol"] = symbol
+
+    data = await client.get("/opportunities", params=params)
+
+    if exchange:
+        ex = exchange.lower()
+        data = [o for o in data if ex in o["long_exchange"].lower() or ex in o["short_exchange"].lower()]
+
+    data = sorted(data, key=lambda o: o["net_apr"], reverse=True)[:limit]
+
+    if not data:
+        return "No opportunities found matching your criteria."
+
+    lines = [f"Found {len(data)} opportunities:\n"]
+    for o in data:
+        lines.append(_fmt_opp(o))
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_exchanges() -> str:
+    """List all connected DEXes with their status and funding interval."""
+    data = await client.get("/exchanges")
+    exchanges = data.get("exchanges", [])
+
+    if not exchanges:
+        return "No exchanges connected."
+
+    lines = [f"{len(exchanges)} exchanges connected:\n"]
+    for ex in exchanges:
+        status = "online" if ex["connected"] else "offline"
+        lines.append(f"  {ex['name']} — {status}, {ex['funding_interval_hours']}h funding interval")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_historical_rates(
+    symbol: str,
+    exchange: str,
+    days: int = 7,
+) -> str:
+    """Get historical funding rates for a symbol on a specific exchange.
+
+    Args:
+        symbol: Trading pair (e.g. "ETH/USDC")
+        exchange: Exchange name (e.g. "Hyperliquid")
+        days: Lookback period in days (1-90, default 7)
+    """
+    data = await client.get("/rates/historical", params={
+        "symbol": symbol,
+        "exchange": exchange,
+        "days": days,
+    })
+
+    rates = data if isinstance(data, list) else data.get("rates", [])
+
+    if not rates:
+        return f"No historical data for {symbol} on {exchange} (last {days} days)."
+
+    # Summarize
+    aprs = [float(r.get("funding_rate_apr", 0)) for r in rates]
+    avg = sum(aprs) / len(aprs) if aprs else 0
+    mn, mx = min(aprs), max(aprs)
+
+    return (
+        f"{symbol} on {exchange} — last {days} days ({len(rates)} data points):\n"
+        f"  Avg APR: {avg:.1f}%\n"
+        f"  Min APR: {mn:.1f}%\n"
+        f"  Max APR: {mx:.1f}%"
+    )
+
+
+@mcp.tool()
+async def run_backtest(
+    symbol: str,
+    long_exchange: str,
+    short_exchange: str,
+    position_size: float = 1000,
+    days: int = 7,
+) -> str:
+    """Backtest a delta-neutral funding arbitrage trade with historical data.
+
+    Args:
+        symbol: Trading pair (e.g. "ETH/USDC")
+        long_exchange: Exchange to go long on
+        short_exchange: Exchange to go short on
+        position_size: Position size in USD (default 1000)
+        days: Backtest period in days (1-90, default 7)
+    """
+    data = await client.post("/backtest", json={
+        "symbol": symbol,
+        "long_exchange": long_exchange,
+        "short_exchange": short_exchange,
+        "position_size": position_size,
+        "days": days,
+        "execution_fee_bps": 10,
+    })
+
+    pnl = data.get("total_pnl", 0)
+    pnl_pct = data.get("pnl_percentage", 0)
+    funding = data.get("total_funding_received", 0)
+    fees = data.get("total_fees_paid", 0)
+    sharpe = data.get("sharpe_ratio", 0)
+
+    result = (
+        f"Backtest: {symbol} — Long {long_exchange} / Short {short_exchange}\n"
+        f"  Period: {days} days, Position: ${position_size:,.0f}\n"
+        f"  Total PnL: ${pnl:,.2f} ({pnl_pct:+.2f}%)\n"
+        f"  Funding received: ${funding:,.2f}\n"
+        f"  Fees paid: ${fees:,.2f}\n"
+        f"  Sharpe ratio: {sharpe:.2f}"
+    )
+
+    if data.get("has_price_data") and data.get("total_pnl_with_spread") is not None:
+        spread_pnl = data.get("spread_pnl", 0)
+        total_with_spread = data["total_pnl_with_spread"]
+        result += (
+            f"\n  Price spread PnL: ${spread_pnl:,.2f}"
+            f"\n  Total PnL (with spread): ${total_with_spread:,.2f}"
+        )
+
+    hist_slip = data.get("historical_slippage_bps")
+    if hist_slip is not None:
+        result += f"\n  Historical bid-ask slippage: {hist_slip:.1f} bps"
+
+    return result
+
+
+@mcp.tool()
+async def get_rate_chart_data(
+    symbol: str,
+    long_exchange: str,
+    short_exchange: str,
+    days: int = 30,
+) -> str:
+    """Get funding rate spread chart data for a pair across two exchanges.
+
+    Args:
+        symbol: Trading pair (e.g. "ETH/USDC")
+        long_exchange: First exchange
+        short_exchange: Second exchange
+        days: Lookback period (1-90, default 30)
+    """
+    data = await client.get("/rates/chart-data", params={
+        "symbol": symbol,
+        "long_exchange": long_exchange,
+        "short_exchange": short_exchange,
+        "days": days,
+    })
+
+    points = data if isinstance(data, list) else data.get("data", [])
+
+    if not points:
+        return f"No chart data for {symbol} ({long_exchange} vs {short_exchange})."
+
+    # Compute spread statistics
+    spreads = []
+    for p in points:
+        long_apr = p.get("long_apr", 0) or 0
+        short_apr = p.get("short_apr", 0) or 0
+        spreads.append(short_apr - long_apr)
+
+    avg_spread = sum(spreads) / len(spreads) if spreads else 0
+    max_spread = max(spreads) if spreads else 0
+    min_spread = min(spreads) if spreads else 0
+
+    return (
+        f"{symbol} spread ({long_exchange} vs {short_exchange}) — last {days} days:\n"
+        f"  Data points: {len(points)}\n"
+        f"  Avg spread: {avg_spread:.1f}% APR\n"
+        f"  Max spread: {max_spread:.1f}% APR\n"
+        f"  Min spread: {min_spread:.1f}% APR"
+    )
+
+
+# ─── PAID TIER TOOLS ─────────────────────────────────────────
+
+@mcp.tool()
+async def get_pair_intelligence() -> str:
+    """Get risk scores and backtested APR for all opportunity pairs.
+    Pre-computed every 5 minutes. Includes spread risk, 30d average, smart ranking.
+    [Requires paid API key]
+    """
+    await _require_paid()
+    data = await client.get("/analytics/pair-intelligence")
+
+    pairs = data.get("pairs", {})
+    if not pairs:
+        return "No pair intelligence data available."
+
+    lines = [f"Pair intelligence ({len(pairs)} pairs, {data.get('days', 30)}d window):\n"]
+
+    # Sort by smart score (combines APR, stability, liquidity, depth)
+    sorted_pairs = sorted(pairs.items(), key=lambda x: x[1].get("smart_score", 0), reverse=True)
+
+    for pair_key, info in sorted_pairs[:15]:
+        bt_apr = info.get("backtested_net_apr", info.get("backtested_apr", 0))
+        score = info.get("smart_score", 0)
+        stability = info.get("stability_pct", 0)
+        risk = info.get("risk_level", "?")
+        depth = info.get("depth_score")
+        days = info.get("data_days", 0)
+
+        depth_label = {1.0: "$10k+", 0.8: "$5-10k", 0.5: "$1-5k", 0.2: "<$1k"}.get(depth, "?")
+        lines.append(
+            f"  {pair_key} — score {score:.1f}, bt {bt_apr:.1f}% APR, "
+            f"stability {stability:.0f}%, depth {depth_label}, risk {risk}, {days:.0f}d data"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_price_spread_data(
+    symbol: str,
+    long_exchange: str,
+    short_exchange: str,
+    days: int = 7,
+) -> str:
+    """Get hourly mark prices and spread between two exchanges for price risk analysis.
+    [Requires paid API key]
+
+    Args:
+        symbol: Trading pair (e.g. "ETH/USDC")
+        long_exchange: First exchange
+        short_exchange: Second exchange
+        days: Lookback period (1-30, default 7)
+    """
+    await _require_paid()
+    data = await client.get("/prices/chart-data", params={
+        "symbol": symbol,
+        "long_exchange": long_exchange,
+        "short_exchange": short_exchange,
+        "days": days,
+    })
+
+    points = data if isinstance(data, list) else data.get("data", [])
+    if not points:
+        return f"No price data for {symbol} ({long_exchange} vs {short_exchange})."
+
+    spreads = [p.get("spread_pct", 0) for p in points if p.get("spread_pct") is not None]
+    if not spreads:
+        return "Price data available but no spread calculations."
+
+    avg = sum(spreads) / len(spreads)
+    mx = max(spreads)
+    high_hours = sum(1 for s in spreads if s > 0.5)
+
+    return (
+        f"{symbol} price spread ({long_exchange} vs {short_exchange}) — last {days} days:\n"
+        f"  Data points: {len(spreads)}\n"
+        f"  Avg spread: {avg:.4f}%\n"
+        f"  Max spread: {mx:.4f}%\n"
+        f"  Hours > 0.5% spread: {high_hours}"
+    )
+
+
+@mcp.tool()
+async def get_record_roi(period: str = "day") -> str:
+    """Best single trade by ROI in a given period.
+    [Requires paid API key]
+
+    Args:
+        period: "day" for last 24h or "week" for last 7 days
+    """
+    await _require_paid()
+    query = f"record_roi_{period}"
+    data = await client.get(f"/social/run/{query}")
+    result = data.get("data", {})
+
+    if not result:
+        return f"No ROI data for period: {period}"
+
+    return (
+        f"Record ROI ({period}):\n"
+        f"  {result.get('symbol', '?')} — "
+        f"Long {result.get('long_exchange', '?')} / Short {result.get('short_exchange', '?')}\n"
+        f"  APR: {result.get('apr', 0):.1f}%\n"
+        f"  ROI on $1000: ${result.get('roi_1k', 0):.2f}"
+    )
+
+
+@mcp.tool()
+async def get_still_paying() -> str:
+    """Pairs above 50% APR for 24h+ that are still active right now.
+    [Requires paid API key]
+    """
+    await _require_paid()
+    data = await client.get("/social/run/still_paying")
+    results = data.get("data", [])
+
+    if not results:
+        return "No pairs currently on a 24h+ streak above 50% APR."
+
+    lines = ["Active streaks (50%+ APR for 24h+):\n"]
+    for r in results[:10]:
+        lines.append(
+            f"  {r.get('symbol', '?')} — {r.get('long_exchange', '?')}/{r.get('short_exchange', '?')} — "
+            f"{r.get('hours', 0)}h streak, {r.get('apr', 0):.1f}% APR"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_top_holders(days: int = 7) -> str:
+    """Top pairs holding 50%+ APR longest.
+    [Requires paid API key]
+
+    Args:
+        days: Lookback period — 7 or 14 days
+    """
+    await _require_paid()
+    query = "top_holders" if days <= 7 else "top_holders_14d"
+    data = await client.get(f"/social/run/{query}")
+    results = data.get("data", [])
+
+    if not results:
+        return f"No pairs held 50%+ APR in the last {days} days."
+
+    lines = [f"Top holders (50%+ APR, last {days} days):\n"]
+    for r in results[:5]:
+        lines.append(
+            f"  {r.get('symbol', '?')} — {r.get('long_exchange', '?')}/{r.get('short_exchange', '?')} — "
+            f"{r.get('hours', 0)}h above threshold"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_momentum_movers() -> str:
+    """Biggest funding spread jumps in the last 6 hours vs prior 6 hours.
+    [Requires paid API key]
+    """
+    await _require_paid()
+    data = await client.get("/social/run/momentum_movers")
+    results = data.get("data", [])
+
+    if not results:
+        return "No significant momentum changes in the last 6 hours."
+
+    lines = ["Momentum movers (last 6h):\n"]
+    for r in results[:10]:
+        lines.append(
+            f"  {r.get('symbol', '?')} — {r.get('long_exchange', '?')}/{r.get('short_exchange', '?')} — "
+            f"{r.get('change', 0):+.1f}% APR change"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_weekly_recap(days: int = 7) -> str:
+    """Weekly recap: best ROI pairs, best DEX combos, most stable pair.
+    [Requires paid API key]
+
+    Args:
+        days: Period — 7 or 14 days
+    """
+    await _require_paid()
+    query = "weekly_recap" if days <= 7 else "weekly_recap_14d"
+    data = await client.get(f"/social/run/{query}")
+    result = data.get("data", {})
+
+    if not result:
+        return f"No recap data for the last {days} days."
+
+    lines = [f"Weekly recap (last {days} days):\n"]
+
+    if result.get("best_roi"):
+        roi = result["best_roi"]
+        lines.append(f"  Best ROI: {roi.get('symbol', '?')} — {roi.get('apr', 0):.1f}% APR")
+
+    if result.get("best_dex_combo"):
+        combo = result["best_dex_combo"]
+        lines.append(f"  Best DEX combo: {combo.get('long', '?')}/{combo.get('short', '?')}")
+
+    if result.get("most_stable"):
+        stable = result["most_stable"]
+        lines.append(f"  Most stable: {stable.get('symbol', '?')} — {stable.get('std', 0):.1f}% std dev")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_unbroken_streaks(mode: str = "top5") -> str:
+    """Consecutive hours above APR threshold — multiple viewing modes.
+    [Requires paid API key]
+
+    Args:
+        mode: "spotlight" (random long streak), "top5" (longest 5), "fresh" (started <24h ago), "elite" (100%+ APR)
+    """
+    await _require_paid()
+    query_map = {
+        "spotlight": "unbroken_streak",
+        "top5": "unbroken_streak_top5",
+        "fresh": "unbroken_streak_fresh",
+        "elite": "unbroken_streak_elite",
+    }
+    query = query_map.get(mode, "unbroken_streak_top5")
+    data = await client.get(f"/social/run/{query}")
+    results = data.get("data", [])
+
+    if isinstance(results, dict):
+        results = [results]
+
+    if not results:
+        return f"No unbroken streaks found (mode: {mode})."
+
+    lines = [f"Unbroken streaks ({mode}):\n"]
+    for r in results[:10]:
+        lines.append(
+            f"  {r.get('symbol', '?')} — {r.get('long_exchange', '?')}/{r.get('short_exchange', '?')} — "
+            f"{r.get('hours', 0)}h streak at {r.get('apr', 0):.1f}% APR"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_live_alpha() -> str:
+    """Top 5 live funding rate arbitrage opportunities, deduplicated by symbol.
+    [Requires paid API key]
+    """
+    await _require_paid()
+    data = await client.get("/social/run/live_alpha")
+    results = data.get("data", [])
+
+    if not results:
+        return "No live alpha opportunities right now."
+
+    lines = ["Live alpha (top 5):\n"]
+    for r in results[:5]:
+        lines.append(
+            f"  {r.get('symbol', '?')} — Long {r.get('long_exchange', '?')} / "
+            f"Short {r.get('short_exchange', '?')} — {r.get('apr', 0):.1f}% APR"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def find_best_trade(
+    position_size: float = 1000,
+    min_apr: float = 30,
+    limit: int = 5,
+) -> str:
+    """Find the best delta-neutral trade you can open RIGHT NOW.
+    Combines live funding rates + 30d backtest + spread risk + real-time order book depth.
+    Returns fully-analyzed, tradeable opportunities ranked by composite risk/reward score.
+    [Requires paid API key]
+
+    Args:
+        position_size: How much USD you want to deploy (default 1000)
+        min_apr: Minimum net APR filter (default 30)
+        limit: Max results (default 5)
+    """
+    await _require_paid()
+    data = await client.get("/smart-opportunities", params={
+        "position_size": position_size,
+        "min_apr": min_apr,
+        "limit": limit,
+    })
+
+    opps = data.get("opportunities", [])
+    if not opps:
+        return f"No tradeable opportunities found at ${position_size:,.0f} with ≥{min_apr}% APR."
+
+    lines = [f"Best trades for ${position_size:,.0f} ({len(opps)} found):\n"]
+
+    for i, o in enumerate(opps, 1):
+        depth = o.get("depth", {})
+        entry_cost = o.get("entry_cost_pct", 0)
+        stability = o.get("stability_pct", 0)
+        risk = o.get("risk_level", "unknown")
+        bt_apr = o.get("backtested_apr", 0)
+        days = o.get("data_days", 0)
+
+        lines.append(f"  #{i} {o['symbol']} — Long {o['long_exchange']} / Short {o['short_exchange']}")
+        lines.append(f"     Live APR: {o['net_apr']:.1f}% | 30d backtested: {bt_apr:.1f}% | Stability: {stability:.0f}%")
+        lines.append(f"     Entry cost: {entry_cost:.4f}% slippage | Breakeven: {o['breakeven_days']:.1f} days")
+        lines.append(f"     Risk: {risk} | Price spread: {o.get('spread_risk_pct', 0):.3f}% | Data: {days:.0f} days")
+        lines.append(f"     Score: {o['score']:.1f}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def get_smart_opportunities(
+    position_size: float = 1000,
+    min_apr: float = 50,
+    limit: int = 10,
+) -> str:
+    """Get opportunities ranked by composite score (APR × stability × liquidity).
+    Unlike get_opportunities, this checks real order book depth and filters out
+    pairs you can't actually trade at your position size.
+    [Requires paid API key]
+
+    Args:
+        position_size: Position size in USD (default 1000)
+        min_apr: Minimum net APR (default 50)
+        limit: Max results (default 10)
+    """
+    await _require_paid()
+    data = await client.get("/smart-opportunities", params={
+        "position_size": position_size,
+        "min_apr": min_apr,
+        "limit": limit,
+    })
+
+    opps = data.get("opportunities", [])
+    if not opps:
+        return f"No tradeable opportunities at ${position_size:,.0f} with ≥{min_apr}% APR."
+
+    lines = [f"Smart opportunities for ${position_size:,.0f} ({len(opps)} results):\n"]
+    for o in opps:
+        risk_emoji = {"low": "safe", "medium": "moderate", "high": "risky", "unknown": "no data"}.get(o.get("risk_level", "unknown"), "?")
+        lines.append(
+            f"  {o['symbol']} — {o['long_exchange']}/{o['short_exchange']} — "
+            f"{o['net_apr']:.1f}% APR, {o.get('entry_cost_pct', 0):.3f}% entry cost, "
+            f"risk: {risk_emoji}, score: {o['score']:.1f}"
+        )
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def check_liquidity(
+    exchange: str,
+    symbol: str,
+    position_size: float = 1000,
+) -> str:
+    """Check real-time order book liquidity for a symbol on a specific exchange.
+    Returns bid-ask spread, depth analysis at multiple position sizes, and slippage estimates.
+    [Requires paid API key]
+
+    Args:
+        exchange: Exchange name (e.g. "Hyperliquid")
+        symbol: Trading pair (e.g. "ETH/USDC")
+        position_size: Position size in USD for slippage estimate (default 1000)
+    """
+    await _require_paid()
+    data = await client.get(f"/liquidity/{exchange}", params={
+        "symbol": symbol,
+        "position_size": position_size,
+    })
+
+    if not data.get("available"):
+        return f"No order book data for {symbol} on {exchange}: {data.get('message', 'unavailable')}"
+
+    lines = [f"Liquidity: {symbol} on {data['exchange']}\n"]
+    lines.append(f"  Spread: {data['spread_pct']:.4f}% ({data['bid_levels']} bid / {data['ask_levels']} ask levels)")
+    lines.append(f"  Best bid: {data['best_bid']}  Best ask: {data['best_ask']}")
+
+    if data.get("volume_24h"):
+        lines.append(f"  24h volume: ${data['volume_24h']:,.0f}")
+    if data.get("open_interest"):
+        lines.append(f"  Open interest: ${data['open_interest']:,.0f}")
+
+    depth = data.get("depth", {})
+    if depth:
+        lines.append("\n  Depth analysis:")
+        for size_label, sides in depth.items():
+            buy = sides.get("buy", {})
+            sell = sides.get("sell", {})
+            buy_slip = f"{buy['slippage_pct']:.4f}%" if buy.get("slippage_pct") is not None else "insufficient depth"
+            sell_slip = f"{sell['slippage_pct']:.4f}%" if sell.get("slippage_pct") is not None else "insufficient depth"
+            buy_fill = buy.get("filled_pct", 0)
+            sell_fill = sell.get("filled_pct", 0)
+            lines.append(f"    {size_label}: Buy slippage {buy_slip} ({buy_fill}% filled) | Sell slippage {sell_slip} ({sell_fill}% filled)")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def analyze_pair(
+    symbol: str,
+    long_exchange: str,
+    short_exchange: str,
+    position_size: float = 1000,
+) -> str:
+    """Full end-to-end analysis of a specific delta-neutral pair.
+    Combines: current funding rates, 7d backtest, pair intelligence (30d risk/stability),
+    live order book depth on both legs, and price spread risk — all in one call.
+    [Requires paid API key]
+
+    Args:
+        symbol: Trading pair (e.g. "ETH/USDC")
+        long_exchange: Exchange to go long on
+        short_exchange: Exchange to go short on
+        position_size: Your intended position size in USD (default 1000)
+    """
+    await _require_paid()
+    import asyncio
+
+    # Fetch everything in parallel
+    opps_task = client.get("/opportunities", params={"symbol": symbol})
+    backtest_task = client.post("/backtest", json={
+        "symbol": symbol,
+        "long_exchange": long_exchange,
+        "short_exchange": short_exchange,
+        "position_size": position_size,
+        "days": 7,
+        "execution_fee_bps": 10,
+    })
+    intel_task = client.get("/analytics/pair-intelligence")
+    long_liq_task = client.get(f"/liquidity/{long_exchange}", params={
+        "symbol": symbol, "position_size": position_size,
+    })
+    short_liq_task = client.get(f"/liquidity/{short_exchange}", params={
+        "symbol": symbol, "position_size": position_size,
+    })
+    spread_task = client.get("/prices/chart-data", params={
+        "symbol": symbol,
+        "long_exchange": long_exchange,
+        "short_exchange": short_exchange,
+        "days": 7,
+    })
+
+    results = await asyncio.gather(
+        opps_task, backtest_task, intel_task,
+        long_liq_task, short_liq_task, spread_task,
+        return_exceptions=True,
+    )
+    opps, backtest, intel_data, long_liq, short_liq, price_spread = results
+
+    lines = [f"═══ Analysis: {symbol} — Long {long_exchange} / Short {short_exchange} ═══\n"]
+
+    # 1. Current funding rates
+    lines.append("── Current Funding ──")
+    if not isinstance(opps, Exception):
+        found = None
+        for o in (opps if isinstance(opps, list) else []):
+            if (o.get("long_exchange") == long_exchange and
+                o.get("short_exchange") == short_exchange and
+                o.get("symbol") == symbol):
+                found = o
+                break
+        if found:
+            lines.append(f"  Long APR: {found['long_apr']:+.1f}% | Short APR: {found['short_apr']:+.1f}%")
+            lines.append(f"  Net APR: {found['net_apr']:.1f}% | Breakeven: {found.get('breakeven_days', '?')} days")
+        else:
+            lines.append(f"  Pair not found in current opportunities")
+    else:
+        lines.append(f"  Failed to fetch rates")
+
+    # 2. Backtest
+    lines.append("\n── 7-Day Backtest ──")
+    if not isinstance(backtest, Exception):
+        lines.append(f"  PnL: ${backtest.get('total_pnl', 0):,.2f} ({backtest.get('pnl_percentage', 0):+.2f}%)")
+        lines.append(f"  Funding: ${backtest.get('total_funding_received', 0):,.2f} | Fees: ${backtest.get('total_fees_paid', 0):,.2f}")
+        lines.append(f"  Sharpe: {backtest.get('sharpe_ratio', 0):.2f}")
+        if backtest.get("has_price_data") and backtest.get("spread_pnl") is not None:
+            lines.append(f"  Price spread PnL: ${backtest['spread_pnl']:,.2f}")
+        hist_slip = backtest.get("historical_slippage_bps")
+        if hist_slip is not None:
+            lines.append(f"  Historical slippage: {hist_slip:.1f} bps")
+    else:
+        lines.append(f"  Backtest failed")
+
+    # 3. Pair intelligence
+    lines.append("\n── 30-Day Intelligence ──")
+    if not isinstance(intel_data, Exception):
+        pair_key = f"{symbol}|{long_exchange}|{short_exchange}"
+        intel = intel_data.get("pairs", {}).get(pair_key, {})
+        if intel:
+            depth_label = {1.0: "$10k+", 0.8: "$5-10k", 0.5: "$1-5k", 0.2: "<$1k"}.get(
+                intel.get("depth_score"), "unknown")
+            lines.append(f"  Smart score: {intel.get('smart_score', 0):.1f}")
+            lines.append(f"  Backtested APR: {intel.get('backtested_net_apr', 0):.1f}%")
+            lines.append(f"  Stability: {intel.get('stability_pct', 0):.0f}% of hours profitable")
+            lines.append(f"  Risk level: {intel.get('risk_level', 'unknown')}")
+            lines.append(f"  Depth tier: {depth_label}")
+            lines.append(f"  Data: {intel.get('data_days', 0):.1f} days of history")
+        else:
+            lines.append(f"  No intelligence data for this pair")
+    else:
+        lines.append(f"  Intelligence fetch failed")
+
+    # 4. Live liquidity — both legs
+    for side, liq, ex_name in [("Long", long_liq, long_exchange), ("Short", short_liq, short_exchange)]:
+        lines.append(f"\n── {side} Leg: {ex_name} ──")
+        if isinstance(liq, Exception):
+            lines.append(f"  Liquidity check failed")
+            continue
+        if not liq.get("available"):
+            lines.append(f"  {liq.get('message', 'No order book data available')}")
+            continue
+        lines.append(f"  Spread: {liq['spread_pct']:.4f}% | Levels: {liq['bid_levels']} bid / {liq['ask_levels']} ask")
+        if liq.get("volume_24h"):
+            lines.append(f"  24h volume: ${liq['volume_24h']:,.0f}")
+        depth = liq.get("depth", {})
+        size_key = f"${int(position_size)}"
+        if size_key not in depth:
+            size_key = "$1000"  # fallback
+        if size_key in depth:
+            buy = depth[size_key].get("buy", {})
+            sell = depth[size_key].get("sell", {})
+            buy_slip = f"{buy['slippage_pct']:.4f}%" if buy.get("slippage_pct") is not None else f"{buy.get('filled_pct', 0):.0f}% filled"
+            sell_slip = f"{sell['slippage_pct']:.4f}%" if sell.get("slippage_pct") is not None else f"{sell.get('filled_pct', 0):.0f}% filled"
+            lines.append(f"  At {size_key}: buy slippage {buy_slip} | sell slippage {sell_slip}")
+
+    # 5. Price spread risk
+    lines.append("\n── Price Spread Risk (7d) ──")
+    if not isinstance(price_spread, Exception):
+        points = price_spread if isinstance(price_spread, list) else price_spread.get("data", [])
+        if points:
+            spreads = [p.get("spread_pct", 0) for p in points if p.get("spread_pct") is not None]
+            if spreads:
+                lines.append(f"  Avg divergence: {sum(spreads)/len(spreads):.4f}%")
+                lines.append(f"  Max divergence: {max(spreads):.4f}%")
+                lines.append(f"  Data points: {len(spreads)}")
+            else:
+                lines.append(f"  No spread data in response")
+        else:
+            lines.append(f"  No price history between these exchanges")
+    else:
+        lines.append(f"  Price spread fetch failed")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def compare_exchanges(
+    symbol: str,
+    exchanges: str = "",
+) -> str:
+    """Compare the same symbol across multiple exchanges — funding rates, spread, depth, volume.
+    Helps decide which exchange to use for each leg of a delta-neutral trade.
+    [Requires paid API key]
+
+    Args:
+        symbol: Trading pair (e.g. "ETH/USDC")
+        exchanges: Comma-separated exchange names to compare (e.g. "Hyperliquid,dYdX,Aster"). If empty, shows all exchanges that list this symbol.
+    """
+    await _require_paid()
+    import asyncio
+
+    # Get opportunities to find which exchanges list this symbol
+    opps = await client.get("/opportunities", params={"symbol": symbol})
+    if isinstance(opps, dict) and "detail" in opps:
+        return f"Error: {opps['detail']}"
+
+    # Collect unique exchanges and their raw funding rate for this symbol
+    # Raw rate: positive = longs pay shorts. short_apr = raw rate, long_apr = -raw rate.
+    exchange_set = set()
+    exchange_rates = {}
+    for o in (opps if isinstance(opps, list) else []):
+        if o.get("symbol") != symbol:
+            continue
+        if o["long_exchange"] not in exchange_rates:
+            exchange_rates[o["long_exchange"]] = -o["long_apr"]  # negate: long_apr is PnL when long
+        if o["short_exchange"] not in exchange_rates:
+            exchange_rates[o["short_exchange"]] = o["short_apr"]  # short_apr = raw rate
+        exchange_set.add(o["long_exchange"])
+        exchange_set.add(o["short_exchange"])
+
+    if exchanges:
+        filter_set = {e.strip() for e in exchanges.split(",")}
+        exchange_set = exchange_set & filter_set
+        if not exchange_set:
+            return f"None of [{exchanges}] list {symbol}. Available: {', '.join(sorted(exchange_rates.keys()))}"
+
+    if not exchange_set:
+        return f"No exchanges found for {symbol}"
+
+    # Fetch liquidity for each exchange in parallel
+    liq_results = await asyncio.gather(
+        *[client.get(f"/liquidity/{ex}", params={"symbol": symbol, "position_size": 5000})
+          for ex in sorted(exchange_set)],
+        return_exceptions=True,
+    )
+
+    lines = [f"═══ {symbol} — Exchange Comparison ═══\n"]
+
+    for ex, liq in zip(sorted(exchange_set), liq_results):
+        apr = exchange_rates.get(ex)
+        apr_str = f"{apr:+.1f}%" if apr is not None else "?"
+
+        lines.append(f"  {ex}")
+        lines.append(f"    Funding APR: {apr_str}")
+
+        if isinstance(liq, Exception) or not liq.get("available"):
+            lines.append(f"    Liquidity: no data")
+        else:
+            lines.append(f"    Spread: {liq['spread_pct']:.4f}%")
+            if liq.get("volume_24h"):
+                lines.append(f"    24h volume: ${liq['volume_24h']:,.0f}")
+            depth = liq.get("depth", {})
+            d5k = depth.get("$5000", {}).get("buy", {})
+            if d5k.get("slippage_pct") is not None:
+                lines.append(f"    $5k buy slippage: {d5k['slippage_pct']:.4f}%")
+            elif d5k.get("filled_pct") is not None:
+                lines.append(f"    $5k fill: {d5k['filled_pct']:.0f}%")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+# ─── Server entry point ──────────────────────────────────────
+
+def main():
+    """Run the MCP server (stdio transport)."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()