# Polymarket Scraper — Markets, Odds & Prices API (`yadroo/polymarket-markets`) Actor Search Polymarket markets by keyword or tag, get top markets by volume, live outcome prices, 1h/24h/7d price changes, liquidity and end dates. Clean JSON per market. No API key required. - **URL**: https://apify.com/yadroo/polymarket-markets.md - **Developed by:** [Samat Makatov](https://apify.com/yadroo) (community) - **Categories:** AI, News, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 market returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Polymarket Scraper — Markets, Odds, Order Books & Price History Structured Polymarket data for analysts, traders, researchers and AI agents: search markets or whole events by keyword, category or tag, filter by volume / liquidity / price / end date, and optionally attach the live CLOB order book and price history for each market. Clean JSON per market or per event, straight from Polymarket's public Gamma and CLOB APIs. No API key, no proxy, no browser. Made by Yadroo. ### Use cases - **Odds dashboard** — pull the top events by 24h volume (`mode=events`) and show the leading outcome of each with one call. - **Movers alert** — `sortBy=change24h` + `minAbsChange24h` on a schedule to catch markets that moved ≥ 5 points in a day. - **Watchlist monitoring** — pass `slugs` / `eventSlugs` of the markets you care about; add `includeOrderBook` for depth and spread. - **Research datasets** — `status=closed` with `endDateFrom`/`endDateTo` to collect resolved markets and their outcomes for calibration studies. - **Macro / event risk** — `category=economy` or `tag=fed-rates` to feed rate-decision probabilities into a model or a report. - **New-market discovery** — `sortBy=newest` with `onlyNew=true` to get only markets created since the previous run. ### Input | Field | Type | Default | Notes | |---|---|---|---| | `mode` | `markets` | `events` | `markets` | One row per Yes/No market, or one row per event with nested markets. | | `query` | string | — | Keywords (AND, case-insensitive) in question / event title. Active markets use Polymarket's own search; closed ones are scanned locally (≤ 5,000). | | `queries` | string\[] | — | Several keyword phrases, kept when **any** matches (words inside a phrase are AND-ed). Max 20. | | `category` | enum | — | Curated tag shortcut, see Reference. Overrides `tag`/`tagId`. | | `categories` | enum\[] | — | Several curated categories in one run; results merged and deduped by id. | | `tag` | string | — | Any tag slug (e.g. `fed-rates`, `cpi-release`, `champions-league`). | | `tagId` | string | — | Numeric Gamma tag id. | | `tagIds` | string\[] | — | Several numeric Gamma tag ids, fanned out like `categories`. Max 20 tag scopes in total. | | `status` | `active` | `closed` | `all` | `active` | Closed rows include `resolvedOutcome` when detectable. | | `includeClosed` | boolean | `false` | Legacy alias for `status=all`. | | `slugs` / `ids` / `conditionIds` / `eventSlugs` | string\[] | — | Exact lookups; skip search entirely. | | `sortBy` | enum | `volume24hr` | `volume24hr`, `volume`, `volume7d`, `liquidity`, `endDate`, `startDate`, `newest`, `change24h`, `competitive`. | | `maxItems` (`limit`) | integer 1–1000 | `25` | Rows to return. | | `minVolume24h`, `minLiquidity`, `minTotalVolume` | integer USD | — | Threshold filters. | | `minAbsChange24h` | string 0–1 | — | Minimum absolute 24h Yes-price move, e.g. `"0.05"`. | | `minAbsChange7d` | string 0–1 | — | Minimum absolute 7-day Yes-price move (markets mode). | | `minAbsChange30d` | string 0–1 | — | Minimum absolute 30-day Yes-price move (markets mode). | | `yesPriceMin`, `yesPriceMax` | string 0–1 | `0` / `1` | Price band filter (drop near-certain markets). | | `endDateFrom`, `endDateTo` | date | — | End-date window (ISO). | | `endingWithinHours` | integer | — | Shortcut: `endDateTo = now + N h`. | | `excludeEndingWithinMinutes` | integer | — | Drop markets closing in the next N minutes (too late to trade). | | `excludeNegRisk` | boolean | `false` | Skip multi-outcome (neg-risk) markets. | | `includeOrderBook` / `orderBookDepth` | boolean / 1–50 | `false` / `5` | CLOB book for the Yes token: best bid/ask, mid, spread, depth in USD, top levels. | | `includePriceHistory` / `historyInterval` / `historyFidelityMinutes` | boolean / enum / 1–1440 | `false` / `1w` / `60` | Yes-price time series (`1h`, `6h`, `1d`, `1w`, `1m`, `max`) with first/last/min/max/change. | | `includeDescription` | boolean | `true` | Set `false` to drop the resolution-rules text. | | `fields` | string\[] | — | Keep only these top-level fields (`id`, `fetchedAt` always kept). | | `onlyNew` | boolean | `false` | Return only ids not pushed by previous runs (state in KV store `yadroo-polymarket-seen`). | ### Reference #### `category` values (curated tag shortcuts) | category | tag id | category | tag id | category | tag id | |---|---|---|---|---|---| | `politics` | 2 | `sports` | 1 | `crypto` | 21 | | `finance` | 120 | `geopolitics` | 100265 | `economy` | 100328 | | `elections` | 144 | `pop-culture` | 596 | `world` | 101970 | | `tech` | 1401 | `science` | 74 | `business` | 107 | | `ai` | 439 | `weather` | 84 | `earnings` | 1013 | | `games` | 100639 | `esports` | 64 | `middle-east` | 154 | | `trump` | 126 | `bitcoin` | 235 | `ethereum` | 39 | | `nfl` | 450 | `nba` | 745 | `mlb` | 100381 | | `soccer` | 100350 | `tennis` | 864 | `ufc` | 279 | Polymarket has ~10,000 tags; any of them works via `tag` (slug) or `tagId`. Find slugs in polymarket.com URLs or via `https://gamma-api.polymarket.com/tags?limit=100&offset=0` (paginate by 100) and `/tags/slug/{slug}`. Frequently useful: `fed-rates`, `fomc`, `cpi-release`, `jobs-report`, `us-presidential-election`, `global-elections`, `crypto-prices`, `hit-price`, `champions-league`, `oil`, `israel`, `iran`, `russia`, `ukraine`. #### Sort keys | `sortBy` | Gamma order | Direction | |---|---|---| | `volume24hr` | `volume24hr` | desc | | `volume` | `volumeNum` | desc | | `volume7d` | `volume1wk` | desc | | `liquidity` | `liquidityNum` | desc | | `endDate` | `endDate` | asc (ending soonest) | | `startDate` | `startDate` | desc | | `newest` | `createdAt` | desc | | `change24h` | `oneDayPriceChange` | desc | | `competitive` | `competitive` | desc (closest to 50/50 first) | ### Examples **Top 25 markets right now (default)** ```json {} ``` **Odds table of the biggest economy events** ```json { "mode": "events", "category": "economy", "maxItems": 20, "minVolume24h": 10000 } ``` **Daily movers alert (≥ 5 points, real volume, not already decided)** ```json { "sortBy": "change24h", "minAbsChange24h": "0.05", "minVolume24h": 5000, "yesPriceMin": "0.05", "yesPriceMax": "0.95", "maxItems": 50 } ``` **Multi-topic news desk: macro + crypto keywords across two categories, weekly movers only** ```json { "categories": ["economy", "crypto"], "queries": ["Fed", "CPI", "Bitcoin"], "minAbsChange7d": "0.1", "minVolume24h": 1000, "excludeEndingWithinMinutes": 60, "maxItems": 50 } ``` **Watchlist with depth and one-week history** ```json { "eventSlugs": ["fed-decision-in-september-762"], "includeOrderBook": true, "orderBookDepth": 10, "includePriceHistory": true, "historyInterval": "1w", "historyFidelityMinutes": 60 } ``` **Resolved markets of Q3 2026 for a calibration study** ```json { "status": "closed", "endDateFrom": "2026-07-01", "endDateTo": "2026-09-30", "sortBy": "volume", "maxItems": 1000, "includeDescription": false, "fields": ["question", "yesPrice", "resolvedOutcome", "volumeTotal", "endDate", "url"] } ``` **Everything ending in the next 48 hours with ≥ $50k liquidity** ```json { "endingWithinHours": 48, "minLiquidity": 50000, "sortBy": "endDate", "maxItems": 200 } ``` ### Output One item per market (`mode=markets`), trimmed: ```json { "id": "2252244", "question": "Will there be no change in Fed interest rates after the September 2026 meeting?", "slug": "will-there-be-no-change-in-fed-interest-rates-after-the-september-2026-meeting-615", "url": "https://polymarket.com/market/will-there-be-no-change-in-fed-…", "groupItemTitle": "No change", "event": { "id": "481717", "title": "Fed Decision in September?", "slug": "fed-decision-in-september-762", "url": "https://polymarket.com/event/fed-decision-in-september-762" }, "tags": ["fomc", "economic-policy", "fed-rates", "jerome-powell"], "category": "economy", "outcomes": [{ "name": "Yes", "price": 0.205, "tokenId": "5615…3721" }, { "name": "No", "price": 0.795, "tokenId": "9705…3724" }], "yesPrice": 0.205, "noPrice": 0.795, "impliedProbability": 20.5, "lastTradePrice": 0.2, "bestBid": 0.2, "bestAsk": 0.21, "spread": 0.01, "change1h": null, "change24h": 0.01, "change7d": -0.29, "change30d": -0.5, "volume24h": 2811872.76, "volume7d": 13555778.82, "volume30d": 29740350.19, "volumeTotal": 36597423.05, "liquidity": 1069021.85, "competitive": 0.92, "startDate": "2026-05-13T21:23:13Z", "endDate": "2026-09-16T00:00:00Z", "createdAt": "2026-05-13T17:23:05Z", "hoursToEnd": 72.4, "active": true, "closed": false, "archived": false, "acceptingOrders": true, "negRisk": true, "resolved": false, "resolvedOutcome": null, "conditionId": "0xa3b3…ec9a", "questionId": "0x128d…4c902", "clobTokenIds": ["5615…3721", "9705…3724"], "orderBook": { "bestBid": 0.2, "bestAsk": 0.21, "mid": 0.205, "spread": 0.01, "bidDepthUsd": 342747.01, "askDepthUsd": 512004.3, "bids": [{ "price": 0.2, "size": 120500 }], "asks": [{ "price": 0.21, "size": 98000 }], "tickSize": 0.01, "minOrderSize": 5, "timestamp": "2026-09-12T23:35:16.000Z" }, "priceHistory": { "interval": "1w", "fidelityMinutes": 60, "first": 0.495, "last": 0.205, "min": 0.19, "max": 0.51, "change": -0.29, "points": [{ "t": "2026-09-05T23:20:24.000Z", "p": 0.495 }] }, "description": "The FED interest rates are defined in this market by…", "sourceUrl": "https://gamma-api.polymarket.com/markets/2252244", "fetchedAt": "2026-09-12T23:35:14.991Z" } ``` | Field | Meaning | |---|---| | `yesPrice` / `noPrice` | Current outcome prices (0–1 = probability). `impliedProbability` = Yes in %. | | `bestBid` / `bestAsk` / `spread` | Top of book as reported by Gamma; `orderBook` holds the live CLOB snapshot when requested. | | `change1h/24h/7d/30d` | Yes-price change in probability points. | | `volume24h/7d/30d/Total`, `liquidity` | USD. | | `competitive` | 0–1, higher = closer to a coin-flip with two-sided interest. | | `hoursToEnd` | Hours until `endDate` at fetch time (negative once past). | | `negRisk` | Market is part of a multi-outcome (neg-risk) event. | | `resolved` / `resolvedOutcome` | For closed markets: winning outcome when one price is ≥ 0.99. | | `clobTokenIds` / `conditionId` / `questionId` | Identifiers for the CLOB / on-chain layers. | | `priceHistory.points[]` | `{t: ISO time, p: price}` for the Yes token. | `mode=events` rows: `id, title, slug, url, ticker, tags, category, seriesSlug, startDate, endDate, hoursToEnd, volume24h, volume7d, volumeTotal, liquidity, openInterest, competitive, commentCount, active, closed, negRisk, marketCount, topOutcome {title, yesPrice}, markets[] {id, question, groupItemTitle, slug, yesPrice, noPrice, volume24h, liquidity, closed}, resolutionSource, image, description, sourceUrl, fetchedAt`. ### Use it from code / agents **Apify API (curl)** ```bash curl -X POST "https://api.apify.com/v2/acts/yadroo~polymarket-markets/run-sync-get-dataset-items?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"mode":"events","category":"economy","maxItems":10}' ``` **JavaScript (`apify-client`)** ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('yadroo/polymarket-markets').call({ query: 'Fed', includeOrderBook: true, maxItems: 5 }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); ``` **Python (`apify-client`)** ```python from apify_client import ApifyClient client = ApifyClient(os.environ["APIFY_TOKEN"]) run = client.actor("yadroo/polymarket-markets").call(run_input={"sortBy": "change24h", "minAbsChange24h": "0.05", "maxItems": 20}) items = client.dataset(run["defaultDatasetId"]).list_items().items ``` **MCP** — add `https://mcp.apify.com` to your agent (Claude, Cursor, etc.) and call the `yadroo/polymarket-markets` tool with the same JSON input; the input schema is self-describing for the model. ### Pricing Pay per event: **$0.001 per run start + $0.002 per item** (market or event row). Typical runs: default top-25 ≈ $0.051; a 200-market movers scan ≈ $0.401; a 1,000-row research pull ≈ $2.001. Enrichment (order book / history) adds no per-item charge but makes runs slower — keep `maxItems` modest when enabled. ### Limits & FAQ - **Freshness** — live at fetch time; Gamma's `volume24hr`/price-change fields refresh roughly every minute. `fetchedAt` is on every row. - **Rate limits** — the actor paces itself (≤ 100 rows per request, ~8 req/s, exponential backoff on 429/5xx). Polymarket's public APIs are not aggressively limited, but 1,000-row runs with both enrichments take a few minutes. - **Keyword search on closed markets** scans up to 5,000 sorted markets locally; add a `tag`/`category` or a date window to narrow it. Polymarket's search only indexes active events. - **Missing `category`** — assigned only when one of the curated tags is attached to the event; `tags` always lists what Polymarket attached. - **Errors** — invalid input (unknown `category`, `sortBy`, bad price band) fails immediately with an explicit message; unreachable API fails after 4 retries instead of looping. Missing slugs are logged as warnings, not errors. - **Roadmap** — trades/holders per market, event-level price history, webhooks-ready diff output. *** Made by **Yadroo**. Related actors: [kalshi-markets](https://apify.com/yadroo/kalshi-markets) (US-regulated prediction markets), [crypto-sentiment](https://apify.com/yadroo/crypto-sentiment), [coingecko-markets](https://apify.com/yadroo/coingecko-markets), [google-news-search](https://apify.com/yadroo/google-news-search). # Actor input Schema ## `mode` (type: `string`): `markets`: one row per tradable Yes/No market (e.g. 'Will the Fed cut 25 bps in September?'). `events`: one row per event that groups several markets (e.g. 'Fed decision in September?' with 5 outcome markets) — best for dashboards and odds tables. ## `query` (type: `string`): Keywords matched against market questions and event titles (all words must match, case-insensitive), e.g. 'Fed', 'Bitcoin 100k', 'Ukraine ceasefire'. For active markets this uses Polymarket's own search; for closed markets it scans up to 5,000 sorted markets locally. ## `queries` (type: `array`): Several keyword phrases; a market is kept when ANY phrase matches (words inside one phrase are AND-ed). Combined with `query`. Max 20. Example: \['Fed', 'CPI', 'recession']. ## `category` (type: `string`): Most-used Polymarket tags as a dropdown. Overrides `tag`/`tagId`. For any other tag (there are ~10,000) use `tag` with the slug from the polymarket.com URL. ## `categories` (type: `array`): Fan out over several curated categories in one run (results merged, deduped). Combined with `category`/`tag`/`tagIds`. Max 20 scopes. ## `tag` (type: `string`): Any Polymarket tag slug, e.g. 'fed-rates', 'jerome-powell', 'cpi-release', 'us-presidential-election', 'champions-league'. Take it from polymarket.com URLs or the Gamma API `/tags` endpoint. ## `tagId` (type: `string`): Numeric Gamma tag id (e.g. '100196' = Fed Rates). Alternative to `tag` when you already have ids. ## `tagIds` (type: `array`): Several numeric Gamma tag ids to fan out over (merged, deduped), e.g. \['100196', '120']. ## `status` (type: `string`): Which markets to return. Closed markets include the resolved outcome when detectable. ## `includeClosed` (type: `boolean`): Deprecated alias for status=all. Ignored when `status` is set. ## `slugs` (type: `array`): Fetch exactly these markets by slug (the last part of a polymarket.com/market/... URL). Overrides search and filters except min\*/price filters. ## `ids` (type: `array`): Gamma market ids, e.g. \['2252244']. ## `conditionIds` (type: `array`): On-chain condition ids (0x…) — handy when you come from CLOB/Polygon data. ## `eventSlugs` (type: `array`): Event slugs (polymarket.com/event/...). In markets mode returns all markets of each event; in events mode returns the events. ## `sortBy` (type: `string`): Ordering of results. ## `maxItems` (type: `integer`): Maximum number of rows to return (markets or events). Billing is per item. ## `limit` (type: `integer`): Deprecated — same as maxItems; maxItems wins when both are set. ## `minVolume24h` (type: `integer`): Drop markets with less than this 24h trading volume. ## `minLiquidity` (type: `integer`): Drop markets with less order-book liquidity than this. ## `minTotalVolume` (type: `integer`): Drop markets with less lifetime volume than this. ## `minAbsChange24h` (type: `string`): Only markets whose Yes price moved at least this much in 24h, in probability points 0–1 (e.g. 0.05 = 5 points). Use with sortBy=change24h to find movers. ## `minAbsChange7d` (type: `string`): Only markets whose Yes price moved at least this much over 7 days, in probability points 0-1 (e.g. 0.1 = 10 points). Markets mode only. ## `minAbsChange30d` (type: `string`): Same as above over 30 days. Markets mode only. ## `yesPriceMin` (type: `string`): Exclude near-certain markets: e.g. 0.05 drops anything priced below 5%. ## `yesPriceMax` (type: `string`): E.g. 0.95 drops anything priced above 95%. ## `endDateFrom` (type: `string`): Only markets ending on/after this date (ISO, e.g. 2026-10-01). ## `endDateTo` (type: `string`): Only markets ending on/before this date. ## `endingWithinHours` (type: `integer`): Shortcut for endDateTo = now + N hours (e.g. 48 = resolving in the next two days). ## `excludeEndingWithinMinutes` (type: `integer`): Drop markets that close in the next N minutes (too late to act on), e.g. 60. Sets endDateFrom = now + N minutes when that is later. ## `excludeNegRisk` (type: `boolean`): Skip markets that belong to negative-risk multi-outcome events (candidate lists, brackets). ## `includeOrderBook` (type: `boolean`): Adds `orderBook` for the Yes token: best bid/ask, mid, spread, top N levels and USD depth per side. One extra request per market. ## `orderBookDepth` (type: `integer`): Levels per side to include in `orderBook`. ## `includePriceHistory` (type: `boolean`): Adds `priceHistory` for the Yes token: time series plus first/last/min/max/change. One extra request per market. ## `historyInterval` (type: `string`): Lookback window for `priceHistory`. ## `historyFidelityMinutes` (type: `integer`): Spacing of history points in minutes (e.g. 5 for 5-minute candles over 1h, 1440 for daily over max). ## `includeDescription` (type: `boolean`): Set false to drop the long resolution-rules text and keep rows compact. ## `fields` (type: `array`): Keep only the listed top-level output fields (id and fetchedAt are always kept), e.g. \['question','yesPrice','volume24h','url']. ## `onlyNew` (type: `boolean`): Monitoring mode: remembers pushed ids in a named key-value store ('yadroo-polymarket-seen') and returns only markets/events not seen in previous runs of this actor under your account. ## Actor input object example ```json { "mode": "markets", "query": "Fed", "status": "active", "includeClosed": false, "sortBy": "volume24hr", "maxItems": 25, "excludeNegRisk": false, "includeOrderBook": false, "orderBookDepth": 5, "includePriceHistory": false, "historyInterval": "1w", "historyFidelityMinutes": 60, "includeDescription": true, "onlyNew": false } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "query": "Fed" }; // Run the Actor and wait for it to finish const run = await client.actor("yadroo/polymarket-markets").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "query": "Fed" } # Run the Actor and wait for it to finish run = client.actor("yadroo/polymarket-markets").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "query": "Fed" }' | apify call yadroo/polymarket-markets --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,yadroo/polymarket-markets" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/NCz1Fw3EaDhkVgsCj/builds/ZphHeyIwIo6cxoEFg/openapi.json