Resolved Markets MCP Server

MCP server for Resolved Markets — connect Claude, GPT, or any AI agent to live Polymarket prediction market orderbook data.

Two ways to use it

Both paths require your own Resolved Markets API key — get one at resolvedmarkets.com/api-keys. Tier limits (free = BTC only + 24h + 60 rpm; Pro = all crypto + Hyperliquid + 500 rpm; Enterprise = everything + 3000 rpm) are applied server-side against the key's owner.

1. Hosted (recommended) — https://mcp.resolvedmarkets.com/mcp

Connect any MCP client at the hosted endpoint and send your key in the X-API-Key HTTP header. Each session is bound to its own key, so your tier and quota attach to your account, not anyone else's.

Bridge into Claude Desktop / Claude Code via mcp-remote:

{
  "mcpServers": {
    "resolvedmarkets": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.resolvedmarkets.com/mcp",
        "--header", "X-API-Key: rm_your_api_key_here"
      ]
    }
  }
}

Authorization: Bearer rm_... is also accepted if your client prefers it.

Security behaviour of the hosted endpoint:

• Requests without a key (or with a malformed key) are rejected with 401 before a session is opened.
• The key is re-validated on every request using a constant-time comparison — a request that arrives on an existing session with a missing or mismatched key is rejected as a hijack attempt (and logged operator-side).
• Sessions auto-expire 30 minutes after initialize. After that your client must re-initialize and present its key again. mcp-remote handles this transparently — it forwards --header on every request and re-initializes when a session is rejected.

Best for the common case — zero npm install, you get the production-deployed MCP version, billing/quota goes to your account.

2. Self-hosted / local (npm install)

Run the npm package locally. The local stdio process reads the key once from the HF_API_KEY env var. Best if you want fully-offline tooling or you're building a multi-tenant agent that handles keys itself.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "resolvedmarkets": {
      "command": "npx",
      "args": ["-y", "@elcara-hq/resolvedmarkets-mcp"],
      "env": {
        "HF_API_URL": "https://api.resolvedmarkets.com",
        "HF_API_KEY": "rm_your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add resolvedmarkets -- npx -y @elcara-hq/resolvedmarkets-mcp
export HF_API_KEY=rm_your_api_key_here

One-off via npx

HF_API_KEY=rm_your_api_key_here npx @elcara-hq/resolvedmarkets-mcp

Tools

| Tool | Description | |------|-------------| | list_categories | Discover all tracked categories (crypto, sports, economics, weather, social, equities) with market counts | | list_markets | List currently-live markets, optionally filtered by category/subcategory | | list_historical_markets | List closed/past markets — recent (paginated) or full (everything ever stored) | | get_market | Resolve a market by slug (e.g. btc-updown-5m) into its conditionId + metadata | | get_orderbook | Live orderbook (bid/ask arrays, spread, depth) by conditionId or slug | | get_market_summary | 7-day aggregated stats (price range, spreads, per-side breakdown) | | get_snapshot | Historical orderbook state at a specific timestamp | | get_latest_snapshots | The 5 most recent snapshots — data-freshness check | | query_snapshots | Paginated time-series of snapshots for one market (the core analysis tool) | | get_exchange_orderbook | Live Hyperliquid perp orderbook (BTC/ETH/SOL/XRP) — Pro+ | | get_exchange_snapshots | Historical Hyperliquid perp snapshots — Pro+ | | get_system_stats | System-wide stats (live markets, snapshot throughput, crypto prices) |

Tier limits are enforced server-side (free tier = BTC only, 24h history). When a call fails on a tier/permission limit the tool returns a structured hint plus the HTTP status so the agent can explain the limit and suggest an upgrade.

Resources

| URI | Description | |-----|-------------| | markets://live | Currently active markets with token IDs and metadata | | prices://latest | Current cryptocurrency prices and dataset/exchange stats |

Environment Variables

Only used for the self-hosted/local install (option 2 above). The hosted endpoint at mcp.resolvedmarkets.com doesn't need any of these.

| Variable | Default | Description | |----------|---------|-------------| | HF_API_URL | http://localhost:3001 | Backend API URL. Use https://api.resolvedmarkets.com for production. | | HF_API_KEY | — | Your API key (rm_...). Get one at resolvedmarkets.com/api-keys. Required for authenticated tools; the backend enforces tier/limits against this key's owner. | | MCP_TRANSPORT | stdio | Transport mode: stdio or http | | MCP_PORT | 3002 | HTTP port (when using HTTP transport) |

Example Queries

Once connected, ask your AI agent:

• "What market categories does Resolved Markets track?"
• "What BTC prediction markets are live right now?"
• "Show me the live orderbook for btc-updown-5m"
• "What was the BTC 5m spread around 2026-03-02 10:42 UTC?"
• "Pull the last 500 snapshots for that market and analyze the spread trend"
• "Compare the Polymarket BTC price to the Hyperliquid BTC perp"
• "How's the data pipeline performing?"

HTTP Transport

For remote integrations or custom agents:

MCP_TRANSPORT=http MCP_PORT=3002 npx @elcara-hq/resolvedmarkets-mcp

Endpoint: POST http://localhost:3002/mcp

Links

• Website
• API Docs
• CLI Tool