Polymarket Odds Snapshot

Docs & recipes: pricing math, use-case playbooks and copy-paste API/MCP snippets · practical guide

Get structured, analysis-ready Polymarket odds in one call — one flat row per market (illustrative example):

{
  "question": "Will Bitcoin go Up or Down on August 4?",
  "market_slug": "bitcoin-up-or-down-on-august-4-2026",
  "condition_id": "0x80942ae6...",
  "outcomes": ["Up", "Down"],
  "outcome_prices": [0.9995, 0.0005],
  "price_by_outcome": {"Up": 0.9995, "Down": 0.0005},
  "yes_price": null,
  "best_bid": 0.999,
  "best_ask": 1.0,
  "spread": 0.001,
  "last_trade_price": 0.999,
  "volume_24h_usd": 1581410.95,
  "volume_total_usd": 74636359.98,
  "liquidity_usd": 23679.26,
  "end_date": "2026-08-05T00:00:00Z",
  "url": "https://polymarket.com/market/bitcoin-up-or-down-on-august-4-2026",
  "snapshot_utc": "2026-08-04T06:10:00+00:00"
}

History mode adds a recent price time series per market (straight from the public CLOB), so you get both the current snapshot and how the odds moved. The cheapest way to put live prediction-market probabilities and price history into a spreadsheet, dashboard, model, or AI agent — no blockchain knowledge, no API keys.

Three ways to select markets

1. By slug list — pass market_slugs and get exactly those markets (great for monitoring a fixed watchlist).
2. By category — category: "crypto" (or politics, sports, economy, tech, world, any Polymarket tag slug) returns the highest-volume open markets in that vertical.
3. Top of the whole exchange — leave both empty and get all open markets ordered by 24h volume, optionally with a min_volume_24h floor.

A zero-config {} run works: the top 100 open markets by 24h volume.

Input

Field	Default	Description
mode	current	current or history (history caps markets at 25)
market_slugs	[] (none)	Explicit watchlist; overrides other filters. Slugs not found are listed in OUTPUT.market_slugs_not_found
category	"" (all)	Polymarket tag slug (crypto, politics, …)
min_volume_24h	0	Volume floor in USD
limit	100	Max markets (by 24h volume, descending; max 500)
history_interval	1d	1h, 6h, 1d, 1w, 1m, max
history_fidelity_minutes	10	Series resolution (1–1440 minutes)

Output fields

One row per market:

Field	Type	Meaning
question	string	Market question
market_slug / event_slug / condition_id	string	Market identity (slug = last path segment of the polymarket.com URL)
outcomes / outcome_prices / price_by_outcome	arrays / object	All outcomes with current prices
yes_price	number | null	Convenience price for Yes/No markets (null for Up/Down etc. — use price_by_outcome)
best_bid / best_ask / spread	number	Top of book
last_trade_price	number	Last fill
volume_24h_usd / volume_total_usd / liquidity_usd	number	Activity and depth
end_date	ISO date	Market close
active / closed	boolean	Market state flags
clob_token_ids	array	Outcome token IDs (for anyone going deeper into the CLOB)
url	url	Polymarket link
snapshot_utc	ISO date	Exact freshness timestamp on every row

In history mode each row additionally carries:

Field	Type	Meaning
history_interval / history_fidelity_minutes	string / number	Echo of the series parameters
price_history	object	{outcome: [{"t": unixSeconds, "p": price}, …]} for the market's first outcome token
price_history_points	integer	Series length

(Series covers the market's first outcome token; for binary markets the other side is simply 1 − p.)

The run's key-value OUTPUT record summarizes: mode, markets_returned, category, market_slugs_not_found, total_volume_24h_usd, snapshot_utc.

Use cases

Dashboards and spreadsheets

Schedule hourly, pipe the dataset to Google Sheets/BI, chart real-money probabilities over time.

Forecast benchmarking

Compare your model's probabilities (elections, sports, crypto, Fed decisions) against market consensus — and use history mode to score how the market converged.

Trading research

Spread + liquidity + 24h volume in one flat row makes screening for tradeable markets trivial.

Using from Claude / AI agents (MCP)

Add Apify's MCP server (https://mcp.apify.com) to Claude, Cursor, or any MCP-capable client and your agent can pull live odds and price history mid-conversation:

{
  "tool": "polymarket-odds-snapshot",
  "input": { "category": "politics", "mode": "history", "history_interval": "1w", "limit": 10 }
}

"What does Polymarket say about the next Fed cut, and how did it move this week?" — one call answers both halves.

Pricing

Pay per event: $0.02 per run + $0.001 per market row + $0.005 per market with price history. Worked math:

• 100-market current snapshot: $0.02 + 100 × $0.001 = $0.12
• 25-market snapshot with history: $0.02 + 25 × $0.001 + 25 × $0.005 = $0.17
• 10-slug watchlist, hourly schedule: ~$0.03/run → about $0.72/day

Honest limits

• History mode is capped at 25 markets per run (per-market CLOB series fetches); split large watchlists across runs.
• The price series covers the market's first outcome token only — for binary markets the complement is 1 − p; for multi-outcome markets pull the other tokens via clob_token_ids yourself.
• Snapshots are point-in-time (snapshot_utc on every row); this is not a streaming feed — schedule it at the cadence you need.

Data source and fair use

Only Polymarket's public, unauthenticated endpoints (Gamma market data + CLOB price history). No login, no keys. Snapshots are timestamped so downstream consumers always know data freshness.