MCP Server

Connect Claude, GPT, or any MCP-compatible AI agent directly to live Resolved Markets data. The server exposes orderbooks, snapshots, market metadata, and Hyperliquid perps as MCP tools — your agent can call them just like any other function.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external data and tools. Once configured, your agent can ask things like "compare the BTC 5m spread on Polymarket to the BTC perp on Hyperliquid right now" and the agent will call the right tools automatically — no glue code needed.

Two ways to connect

Both paths require a Resolved Markets API key. Tier limits (Free = BTC only + 24h history; Pro = all crypto + Hyperliquid + 500 rpm; Enterprise = everything + 3000 rpm) are enforced server-side against the key's owner.

1. Hosted endpoint (recommended)

Connect any MCP client to https://mcp.resolvedmarkets.com/mcp and pass your key in the X-API-Key header. Zero install, always up to date, billing attaches to your account.

For Claude Desktop or Claude Code, bridge 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.

2. Self-hosted / local (npm)

Run the package locally — the stdio process reads the key once from HF_API_KEY. Best for offline tooling or multi-tenant agents that manage keys themselves.

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. When a call hits 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

Used only for the self-hosted/local install. The hosted endpoint needs none 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_...`). Required for authenticated tools.
`MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`MCP_PORT`	`3002`	HTTP port (when using HTTP transport)

Security

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 constant-time comparison — a request that arrives on an existing session with a mismatched key is rejected as a hijack attempt.
Sessions auto-expire 30 minutes after initialize. After that, clients must re-initialize. mcp-remote handles this transparently.
Never paste your key into a shared MCP config or commit it to a repo — treat it like a password.

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, run the local server in HTTP mode:

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

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