Resolved Markets

Historical and live Polymarket order books for AI agents: order book snapshots since March 2026 (every 100 ms for crypto up/down), trades, OHLC, settlement…

CommunityOnlineAPI key requiredGlobalFreeRead-only

What it can do

  • List Categories: List every market category Resolved Markets tracks, with the number of currently active markets and the capture interval (how often new snapshots arrive) per category. WHEN TO USE: Ca
  • List Markets: List currently tracked (LIVE) prediction markets across every category, with conditionIds, token IDs, slugs, end dates, and expiry flags. WHEN TO USE: - To find an active market to query
  • List Historical Markets: List HISTORICAL (closed/past) markets that we have stored snapshots for. Use this to browse the dataset, pick a market to study, or build a backfill. WHEN TO USE: - mode="rece

What data it sees

Do you need an account

An API key from the service settings is required

Historical and live Polymarket order books for AI agents: order book snapshots since March 2026 (every 100 ms for crypto up/down), trades, OHLC, settlement results, plus Hyperliquid perp books. Free key covers crypto markets.

How to connect

How to connect Resolved Markets to Claude

The server address to paste into Claude settings:

https://resolved-markets--resolvedmarkets.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect Resolved Markets to ChatGPT

The server address to paste into ChatGPT settings:

https://resolved-markets--resolvedmarkets.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect Resolved Markets to Cursor

The server address to paste into Cursor settings:

https://resolved-markets--resolvedmarkets.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (14)

Raw names from tools/list. Only developers need these.

list_categoriesList every market category Resolved Markets tracks, with the number of currently active markets and the capture interval (how often new snapshots arrive) per category. WHEN TO USE: Call this FIRST in any new conversation to discover what data is available before calling list_markets. It is cheap (1 credit) and tells you which categories your tier can actually see. BACKEND: GET /v1/categories INPUTS: none. OUTPUT: an array of objects with shape: [{ id, category, displayName, activeMarkets, captureIntervalMs, refreshIntervalMs }, ...] - Each row is one COLLECTION CONFIG, not one category — a category can span several rows. There are 24 configs across the 6 categories (verified against the live endpoint). Sum activeMarkets across rows sharing `category` for a category total. Breakdown: crypto = crypto-updown, crypto-hit-price sports = nba, nfl, epl, fifa-world-cup, tennis-atp, tennis-wta economics = fed-rates, nonfarm-payroll weather = hurricanes, global-weather, daily-temperature social = elon-tweets equities = indices, privates, earnings, stocks, commodities, forex, acquisitions, prediction-markets, ipos, kpis ← the widest category by far - category: one of "crypto", "sports", "economics", "weather", "social", "equities" - activeMarkets: live markets right now for that config. 0 is normal and NOT an error — seasonal configs (fifa-world-cup, nonfarm-payroll) are empty between events. - captureIntervalMs: how often the pipeline writes a snapshot for this config. Crypto up/down is the fastest; slower-moving categories (weather, economics) sample far less often. - TENNIS is live and is usually the largest sports bucket by market count (ATP + WTA, several hundred sub-markets each). Subcategories are "ATP" and "WTA". THIS LISTS LIVE COLLECTION ONLY. get_system_stats can report stored buckets with NO config here — cricket/IPL is the standing example: that data was BACKF
list_marketsList currently tracked (LIVE) prediction markets across every category, with conditionIds, token IDs, slugs, end dates, and expiry flags. WHEN TO USE: - To find an active market to query right now (get_orderbook, query_snapshots). - To verify a slug you have is still live before calling get_orderbook by slug. - For CLOSED / past markets use list_historical_markets instead — those will not appear here. BACKEND: GET /v1/markets/live INPUTS (all optional; filters AND together): - category: one of "crypto" | "sports" | "economics" | "weather" | "social" | "equities". Omit to return all categories you have access to. - subcategory: free-form string. Crypto: "BTC"/"ETH"/"SOL"/"XRP"/"DOGE"/"HYPE"/"BNB". Sports: "NBA"/"NFL"/"EPL"/"FIFA". Economics: "FOMC"/"NFP". Social: "Elon". Weather: a CITY NAME ("NYC", "Tokyo", "Hong Kong", "London", … ~50 cities) plus "Hurricane"/"Global"/"Arctic". Equities: "StockPrice"/"StockAbove"/"StockUpDown"/"StockEvent"/"Earnings"/ "Index"/"SPX"/"Private"/"Commodity"/"Forex"/"Acquisition"/"IPO"/"KPI"/"PredictionMarket". Case-sensitive. Call list_markets({ category }) once and read the distinct `subcategory` values if unsure. - crypto: one coin — "BTC" | "ETH" | "SOL" | "XRP" | "DOGE" | "HYPE" | "BNB". Only crypto markets carry this field, so it also excludes non-crypto categories. - timeframe: Free-form string; the exact values in use are discoverable via list_markets. Crypto up/down: "5m" | "15m" | "1h" | "4h" | "1d"; crypto strike ladders: "hit-price". Sports: "game". Economics: "rates" (Fed) | "monthly" (NFP). Social: "weekly". Weather: "daily-high" | "daily-low" (city temperature), "event" (hurricanes/global), "seasonal" (Arctic). Equities: "annual" | "monthly" | "daily" | "1d" | "event" | "earnings" | "quarterly" | "valuation" | "comparison" | "leaderboard". - limit / offset: window the result (limit 1..5000). Worth using — an unfiltered call on a full-access tier returns ~2,000 markets. Passing either
list_historical_marketsList HISTORICAL (closed/past) markets that we have stored snapshots for. Use this to browse the dataset, pick a market to study, or build a backfill. WHEN TO USE: - mode="recent" (default) — lightweight, paginated, replay-aware feed. Best for "show me what is browsable right now". Free-tier users get a `replay_quota` field showing the top-5-per-bucket they can replay. - mode="full" — every distinct market ever stored. Heavier; use only for dataset builds/backfills. - For currently-live markets, use list_markets instead. BACKEND: - mode="recent" → GET /v1/markets/history/recent (cached 10s) - mode="full" → GET /v1/markets/history (cached 30s) INPUTS (all optional): - mode: "recent" | "full". Default "recent". - crypto: "BTC" | "ETH" | "SOL" | "XRP" | "DOGE" | "HYPE" | "BNB". Crypto category only. - timeframe: Free-form string; the exact values in use are discoverable via list_markets. Crypto up/down: "5m" | "15m" | "1h" | "4h" | "1d"; crypto strike ladders: "hit-price". Sports: "game". Economics: "rates" (Fed) | "monthly" (NFP). Social: "weekly". Weather: "daily-high" | "daily-low" (city temperature), "event" (hurricanes/global), "seasonal" (Arctic). Equities: "annual" | "monthly" | "daily" | "1d" | "event" | "earnings" | "quarterly" | "valuation" | "comparison" | "leaderboard". - category, subcategory: same semantics as list_markets (weather subcategories are city names; equities span IPO/KPI/Commodity/Forex/Private/…). - limit: integer 1..500, default 100. Only used when mode="recent". Ignored when mode="full". OUTPUT: { total_markets, total_snapshots, live_count, closed_count, replay_quota: { unlimited: true } | { unlimited: false, tier: "free", perBucket: 5, allowedCount: N }, markets: [ { market_id, crypto, timeframe, first_seen, last_seen, snapshot_count, is_live, end_date, question }, ... ] } Hyperliquid exchange data appears with market_id like "exchange:hyperliquid_perp:BTC". TIER GATES: same category/cr
get_marketResolve a single market by its slug, partial slug, raw conditionId, or slug-with-timestamp. Returns the market_id (conditionId), category, timeframe, token IDs, and active/expired status. WHEN TO USE: when a user gives you a human-friendly slug ("btc-updown-5m") and you need the conditionId (0x...) that other tools require. Also useful to confirm a market is still active before calling get_orderbook. BACKEND: GET /v1/markets/by-slug/:slug SLUG FORMATS ACCEPTED (fuzzy matched in this order — exact → parsed pattern → substring prefix → substring contains). Works for EVERY category, not just crypto — any Polymarket slug we track resolves here. CRYPTO up/down: - 5m/15m/4h use the TICKER: "btc-updown-5m", "eth-updown-15m", "doge-updown-4h", "hype-updown-5m", "bnb-updown-15m" - Same with the window-start unix timestamp appended: "btc-updown-5m-1705000000" (that trailing epoch is the window START, not its expiry — never derive an expiry from a slug; read end_date) - 1h cadence uses the LONG coin name: "bitcoin-up-or-down-[YYYY-MM-DD]-et" - 1d cadence: "bitcoin-up-or-down-on-[YYYY-MM-DD]" CRYPTO strike ladders (timeframe "hit-price"): "what-price-will-bitcoin-hit-on-[month]-[day]" SPORTS: "will-[team]-win-…", "nba-2027-champion", and per-game moneyline slugs WEATHER: "highest-temperature-in-[city]-on-[month]-[day]", plus hurricane/global event slugs EQUITIES: "spx-hit-dec-2026", "what-price-will-[ticker]-hit-…", "[ticker]-up-or-down-on-…", IPO/valuation event slugs ECONOMICS: "how-many-fed-rate-cuts-in-2026", NFP slugs ANY: a raw conditionId starting with "0x..." (treated as an id, not a slug) — resolves closed markets too Crypto name aliases accepted: "bitcoin"→BTC, "ethereum"→ETH, "solana"→SOL, "dogecoin"→DOGE, "hyperliquid"→HYPE TIP: if you do not know the slug, do NOT guess — call list_markets (live) or list_historical_markets (closed) with a category/subcategory filter and read the `slug` field off a real row. INPUTS (re
get_market_metadataLook up durable market metadata AND HOW MARKETS SETTLED — resolved_outcome, resolution_status, final outcome_prices, resolved_at — for one market, a list of markets, or a whole category. WHEN TO USE: - THE ONLY TOOL THAT TELLS YOU WHO WON. Orderbook tools give you prices; this gives you the realised outcome. Essential for backtesting, calibration studies ("was the 0.80 favourite right 80% of the time?"), and P&L. - To browse settled history: filter by category/subcategory and resolution_status="resolved". - To reassemble a multi-leg event (an NBA champion market, a temperature strike ladder, a Fed-cut ladder) into one object with all its legs — use group_by_event. - Served from the durable market_metadata table, so it covers CLOSED markets the live feed has already dropped. get_market resolves ONE market's identity; this one filters in bulk and adds settlement. BACKEND: GET /v1/markets/metadata (cached 30s) INPUTS (all optional; filters AND together — but pass at least one or you get an arbitrary slice): - market_id: one conditionId, or several comma-separated ("0xaaa,0xbbb"). - neg_risk_id: the negRisk group id — returns every leg of one multi-outcome event. - slug: exact slug match (case-insensitive). Not fuzzy — use get_market for fuzzy slug resolution. - category / subcategory / crypto / timeframe: same semantics and values as list_markets. - resolution_status: "resolved" | "unresolved". Anything else is a 400. - limit: integer 1..1000, default 100. Rows come back ORDER BY end_date DESC (newest settling first). - group_by_event: boolean, default false. See OUTPUT. OUTPUT (group_by_event=false — the default): { count, markets: [ { market_id, slug, question, label, category, subcategory, crypto, timeframe, end_date, event_title, neg_risk_id, outcomes, token_ids, resolved_outcome, // e.g. "Yes" / "Up" / the winning label — null while unresolved resolution_status, // "resolved" | "unresolved"
get_tradesGet the paginated TRADE TAPE (actually executed prints) for one market — price, size, and side of every fill we captured. WHEN TO USE: - Real volume and flow analysis. query_snapshots shows QUOTED liquidity (what people were willing to do); this shows what actually TRADED. A market can have a tight book and near-zero trades. - Sizing/impact questions: how much volume printed, at what levels, buy- vs sell-initiated. - For orderbook state over time use query_snapshots; for aggregates use get_market_summary. BACKEND: GET /v1/markets/:id/trades INPUTS: - market_id (required): conditionId (0x...). Resolve via get_market if you only have a slug. - side (optional): "UP" | "DOWN". - from / to (optional): UTC bounds, "YYYY-MM-DD HH:MM:SS" or ISO 8601. When omitted the backend auto-fills the market's own first_seen/last_seen so ClickHouse can prune partitions. - limit (optional): integer 1..5000, default 500. - offset (optional): integer >= 0, default 0. - order (optional): "asc" | "desc". Default "desc" (newest first) — same as query_snapshots. OUTPUT: { market_id, total, limit, offset, data: [ { market_id, asset_id, price, size, side: "BUY"|"SELL", category, subcategory, timestamp, token_side: "UP"|"DOWN" }, ... ]} price is a 0..1 probability; size is a token quantity. GOTCHAS: - Trades are FAR sparser than snapshots. An empty `data` array on an illiquid market (deep OTM weather strikes, long-dated equities) is normal market structure, not a capture gap. - `side=` needs the market's UP/DOWN token ids, which the trade rows do not carry directly. If they cannot be resolved you get a 422 (side_unavailable) — retry WITHOUT side and read `token_side` per row. - 404 means we have no trade tape for that market at all (unknown id, or never captured). TIER GATES: 403 if the market's category is not on your tier. All tiers have unlimited history. ALSO RETURNED, previously undocumented: - transaction_hash: the Polygon tx
get_orderbookGet the LIVE orderbook for a prediction market. Returns bid/ask arrays, best bid/ask, mid price, spread, and total depth for BOTH the UP and DOWN tokens, plus the underlying crypto price. WHEN TO USE: - For real-time pricing of an active market right now. - For a CLOSED market or point-in-time history, use get_snapshot instead — this endpoint only serves live markets. BACKEND: - market_id → GET /v1/markets/:id/orderbook - slug → GET /v1/markets/by-slug/:slug/orderbook INPUTS — provide EXACTLY ONE of: - market_id: conditionId starting with 0x. Works for any market your tier allows. - slug: e.g. "btc-updown-5m". Active markets only; closed markets 404 here (use get_snapshot for those). Passing both is fine — market_id wins. Passing neither returns a validation error. OUTPUT: { market_id, category, subcategory, label, question, timeframe, slug, crypto, crypto_price, // CRYPTO markets only — omitted on weather/sports/economics/social/equities up: { tokenId, timestamp, eventTimestamp, captureTimestamp, sequenceNumber, category, subcategory, label, timeframe, outcomeIndex, bestBid, bestAsk, midPrice, spread, bidDepth, askDepth, bids: [{price,size}...], asks: [{price,size}...] }, down: { ... same shape, outcomeIndex 1 } } (The by-conditionId route also echoes legacy camelCase aliases marketId/cryptoPrice.) Prices are 0..1 probability units. Sizes are token quantities. A missing side (no bids or no asks) is normal near settlement and on deep out-of-the-money weather strikes: bestBid/bestAsk stay 0 for the unquoted side while midPrice/spread clamp to the outcome bound (absent bid→0, absent ask→1), matching Polymarket convention. TIER GATES: - 403 if the market's category is not allowed on your tier. - All tiers see full orderbook depth (no level cap). ALSO RETURNED, previously undocumented: - cryptoPriceAgeMs: how stale the reference spot price was when this book wa
get_market_summaryGet aggregated statistics for a single market over ITS ENTIRE LIFETIME: snapshot count, average/min/max mid price, average/min/max spread, average crypto price, average bid/ask depth, and per-side (UP / DOWN) sub-aggregates. WHEN TO USE: for a quick "how did this market behave" overview without paging through time-series rows. For raw rows use query_snapshots; for a single instant use get_snapshot. WINDOW: the backend resolves the market's real first_seen/last_seen bounds from market_stats and aggregates over exactly that span, so this works on CLOSED and backfilled markets from any period — not just recent ones. If those bounds are not in market_stats yet (a brand-new market), it falls back to the last 30 days. BACKEND: GET /v1/markets/:id/summary INPUTS (required): - market_id: the conditionId (0x...). Resolve a slug first via get_market if needed. OUTPUT: { market_id, crypto, timeframe, category, subcategory, label, question, snapshot_count, first_seen, last_seen, avg_mid_price, min_mid_price, max_mid_price, avg_spread, min_spread, max_spread, avg_crypto_price, min_crypto_price, max_crypto_price, // crypto markets only — omitted on sports/weather/etc. avg_bid_depth, avg_ask_depth, sides: [ { token_side: "UP", snapshots, avg_bid, avg_ask, avg_mid, max_bid, min_ask }, { token_side: "DOWN", ... } ] } TIER GATES: - 403 if the market's category is not allowed. - All tiers have unlimited history, so the market's whole lifetime feeds the averages on every tier. CREDIT COST: 3 credits (all tiers; free tier draws from its 5,000-credit monthly allowance). A non-2xx response (e.g. 404 no-data) is not charged. EXAMPLE: get_market_summary({ market_id: "0xabc..." })
get_snapshotGet the orderbook snapshot at (or just before) a specific UTC timestamp. Returns the point-in-time state of one market's UP and DOWN tokens, or the top-2 most recent snapshots across all markets if no market is specified. WHEN TO USE: - For point-in-time market state at a specific instant ("what was the orderbook at 14:30 yesterday?"). - The backend searches up to 1 HOUR BEFORE the requested timestamp — older queries will return null. For older history use query_snapshots with from/to. BACKEND: GET /api/snapshot (cached 5s) INPUTS: - timestamp (required): UTC. Accepts "YYYY-MM-DD HH:MM:SS[.mmm]" or ISO 8601 ("2026-05-30T14:30:00Z"). Naive timestamps are interpreted as UTC. - market_id (optional): conditionId (0x...). If provided, response is shaped { market_id, up, down }. If omitted, response is an array of the top 2 snapshots matching the other filters. - crypto (optional): "BTC" | "ETH" | "SOL" | "XRP" | "DOGE" | "HYPE" | "BNB". - timeframe (optional): Free-form string; the exact values in use are discoverable via list_markets. Crypto up/down: "5m" | "15m" | "1h" | "4h" | "1d"; crypto strike ladders: "hit-price". Sports: "game". Economics: "rates" (Fed) | "monthly" (NFP). Social: "weekly". Weather: "daily-high" | "daily-low" (city temperature), "event" (hurricanes/global), "seasonal" (Arctic). Equities: "annual" | "monthly" | "daily" | "1d" | "event" | "earnings" | "quarterly" | "valuation" | "comparison" | "leaderboard". - include_book (optional, default false): when true, includes full bids/asks arrays. Off by default to keep responses small. OUTPUT (with market_id): { market_id, timestamp, crypto_price, crypto, timeframe, // crypto/crypto_price omitted on non-crypto markets up: { token_side, best_bid, best_ask, mid_price, spread, bid_depth_total, ask_depth_total, bids?, asks? }, down: { ... } } OUTPUT (without market_id): array of up to 2 such snapshot objects (latest UP/DOWN pair). TIER GATES: - All tiers have unlimited hist
get_latest_snapshotsGet the 5 MOST RECENT snapshots across all markets (or filtered by crypto/timeframe). Bounded to the last 10 minutes server-side. WHEN TO USE: - Health/freshness check — confirm the pipeline is alive and how stale data is right now. - Quick "what is happening across markets" pulse. - For a specific market or timestamp use get_orderbook / get_snapshot. BACKEND: GET /api/snapshot/latest (cached 3s; LIMIT 5; last 10 minutes only) INPUTS (all optional): - crypto: "BTC" | "ETH" | "SOL" | "XRP" | "DOGE" | "HYPE" | "BNB". - timeframe: Free-form string; the exact values in use are discoverable via list_markets. Crypto up/down: "5m" | "15m" | "1h" | "4h" | "1d"; crypto strike ladders: "hit-price". Sports: "game". Economics: "rates" (Fed) | "monthly" (NFP). Social: "weekly". Weather: "daily-high" | "daily-low" (city temperature), "event" (hurricanes/global), "seasonal" (Arctic). Equities: "annual" | "monthly" | "daily" | "1d" | "event" | "earnings" | "quarterly" | "valuation" | "comparison" | "leaderboard". - include_book: boolean, default false. Off by default — leave off unless you need full depth. OUTPUT: an array of up to 5 snapshot rows: [{ crypto, timeframe, market_id, token_id, token_side: "UP"|"DOWN", timestamp, crypto_price, best_bid, best_ask, mid_price, spread, bid_depth_total, ask_depth_total, bids?, asks? }, ...] (crypto/crypto_price are omitted on non-crypto rows — they only mean anything on crypto markets.) TIER GATES: respects category/crypto allowlist for the caller's tier. ALSO RETURNED, previously undocumented: `subcategory` and `label` (the same identity fields every other snapshot route carries). BOOK ARRAYS: `bids`/`asks` are present ONLY when include_book is true. When it is false the keys are OMITTED, matching get_snapshot. They used to come back as empty arrays, which is indistinguishable from a genuinely empty book — do not treat a missing key as "no liquidity". CREDIT COST: 1 credit (all tiers; free tier draws from its 5
query_snapshotsQuery a paginated TIME-SERIES of orderbook snapshots for ONE market — the core tool for studying how price, spread, and depth evolved over time. WHEN TO USE: - Analytical workloads: chart price/spread history, compute volatility, backfill datasets. - For point-in-time use get_snapshot; for aggregated summary use get_market_summary. BACKEND: GET /v1/markets/:id/snapshots INPUTS: - market_id (required): conditionId (0x...). - side (optional): "UP" | "DOWN" — restrict to one token side. Also makes the query faster (~half the rows). - from (optional): UTC, "YYYY-MM-DD HH:MM:SS" or ISO 8601. Lower bound. - to (optional): UTC, same formats. Upper bound. If omitted on either side, the backend auto-populates from market_stats to allow partition pruning. - limit (optional): integer, default 500. Ceiling depends on mode: 5000 raw, 2000 with include_book=true, 50000 with interval=. Over the ceiling is a 400 naming it — the server never silently truncates a page, so the rows you get back always match the page you asked for. - offset (optional): integer ≥0. Default 0. Pagination cursor. - include_book (optional, default false): include full bids/asks arrays per row. Substantially heavier — only enable when needed. Cannot be combined with interval (400). - order (optional): "asc" | "desc". Default "desc" (newest first). - interval (optional): DOWNSAMPLE to OHLC candles instead of raw rows. One of "1s" | "5s" | "15s" | "30s" | "1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "1d". USE THIS FOR ANY WIDE TIME WINDOW: real markets hold 150k-355k raw snapshots (500ms cadence); interval="1m" turns a ~200k-row pull into a few thousand candles in ONE call (limit goes up to 50000 on this path, default 5000). Candles are computed server-side in ClickHouse and are cheap. OUTPUT (raw, no interval): { market_id, total, limit, offset, data: [ { timestamp, token_side: "UP"|"DOWN", outcome_index: 0|1, crypto, timeframe, crypto_price, best_bid, b
get_exchange_orderbookGet the most recent LIVE orderbook from a centralized exchange. Currently the only supported exchange is Hyperliquid perpetual futures, covering all seven collected coins (BTC/ETH/SOL/XRP/DOGE/HYPE/BNB). WHEN TO USE: - Compare Polymarket prediction prices to the underlying perp price/order flow. - Sanity-check that crypto-market prediction movement is reflecting spot/perp moves. - For history use get_exchange_snapshots. BACKEND: GET /v1/exchange/orderbook (cached 1s; last 10 seconds only) INPUTS (both required): - exchange: "hyperliquid_perp" (only allowed value today). - symbol: "BTC" | "ETH" | "SOL" | "XRP" | "DOGE" | "HYPE" | "BNB" (uppercase) — all seven collected coins. OUTPUT: { exchange, symbol, timestamp, best_bid, best_ask, mid_price, spread, bid_depth_total, ask_depth_total, bids: [{price,size}...], asks: [{price,size}...] } TIER GATES: Scale or above (Scale/Enterprise). Free and Pro are crypto-only and do not include exchange (Hyperliquid) access — they return 403. CREDIT COST: 1 credit (Scale/Enterprise; Free and Pro are blocked from exchange data). EXAMPLE: get_exchange_orderbook({ exchange: "hyperliquid_perp", symbol: "BTC" })
get_exchange_snapshotsGet HISTORICAL orderbook snapshots from a supported exchange (Hyperliquid perps). Lightweight rows: best_bid/ask, mid, spread, depth totals — NO full bids/asks arrays. CADENCE — SAMPLED ~1/sec, STORED ~5s. The collector samples about once a second, but a row is written only when the book CHANGED, so the spacing of STORED rows is longer and uneven. Measured on BTC perps (40 consecutive rows): median 5.26s, min 1.0s, max 6.1s. Do not assume a fixed 1s grid — derive spacing from the timestamps you get back, and expect quiet periods to be sparser than busy ones. WHEN TO USE: time-series of perp price/spread/depth alongside Polymarket data. Useful for cross-market regression and basis analysis. BACKEND: GET /v1/exchange/snapshots INPUTS: - exchange (required): "hyperliquid_perp". - symbol (required): "BTC" | "ETH" | "SOL" | "XRP" | "DOGE" | "HYPE" | "BNB" — all seven collected coins. - from (optional): UTC start. Defaults to 24 hours ago when omitted. - to (optional): UTC end. - limit (optional): integer 1..5000. Default 500. OUTPUT: { exchange, symbol, count, data: [ { exchange, symbol, timestamp, best_bid, best_ask, mid_price, spread, bid_depth_total, ask_depth_total }, ... ]} TIER GATES: Scale or above (Scale/Enterprise). Free and Pro are crypto-only and return 403 for exchange data. CREDIT COST: 1 credit per request (Scale/Enterprise; Free and Pro are blocked from exchange data). EXAMPLES: get_exchange_snapshots({ exchange: "hyperliquid_perp", symbol: "BTC" }) // last 24h, up to 500 rows get_exchange_snapshots({ exchange: "hyperliquid_perp", symbol: "ETH", from: "2026-05-30 00:00:00", to: "2026-05-30 12:00:00", limit: 5000 })
get_system_statsGet SYSTEM-WIDE statistics: pipeline health, dataset size, current crypto prices, and per-crypto breakdowns. Combines the authenticated /v1/stats with the public /v1/public-stats — either may be null/unavailable; the call still returns whichever side succeeded. WHEN TO USE: - "How healthy is the pipeline right now?" - "How big is the dataset?" - "What are current crypto prices?" (also available cheaper via the prices://latest resource). BACKEND: GET /v1/stats + GET /v1/public-stats (run in parallel). INPUTS: none. OUTPUT: { stats: { // authenticated /v1/stats, or { unavailable } uptime_seconds, active_markets, expired_markets, snapshot_buffer_depth, trade_buffer_depth, total_snapshots, total_distinct_markets, earliest_snapshot, latest_snapshot, prices: { BTC, ETH, SOL, XRP, DOGE, BNB, HYPE }, // all 7 collected coins per_crypto: [{ crypto, snapshots, markets }], pipeline: { capture_produced, ch_inserted, ch_errors, snapshot_flushes, trade_flushes } }, publicStats: { // public /v1/public-stats, or { unavailable } snapshot_count, active_markets, prices: { BTC, ETH, SOL, XRP, DOGE, BNB, HYPE }, // all 7 collected coins exchange: { snapshots_last_5min, latest_snapshot } } } TIER GATES: /v1/stats requires an API key (any tier). /v1/public-stats has no auth. CREDIT COST: 1 credit (for /v1/stats; public stats are free). EXAMPLE: get_system_stats({})