# Polymarket API - Markets, Odds, Order Book & Trades (`feedsmith/polymarket-markets-scraper`) Actor

Live and historical Polymarket prediction market data as clean JSON: prices, implied probability, volume, liquidity, order book, trades and price history. No login or API key needed.

- **URL**: https://apify.com/feedsmith/polymarket-markets-scraper.md
- **Developed by:** [TRUONG VAN HOA](https://apify.com/feedsmith) (community)
- **Categories:** Automation, Developer tools, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 markets

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Polymarket Markets Scraper — prices, order book, trades & price history

Get **Polymarket prediction market data as clean JSON, CSV or Excel**: live YES/NO prices, implied probability, volume, liquidity, order book depth, trade fills and price-over-time history — for any market, event, tag/category, or the whole exchange.

- **No Polymarket account, login or API key needed.** Uses Polymarket's public Gamma, CLOB and Data APIs.
- **Stable numeric output.** Gamma returns `outcomes`, `outcomePrices` and `clobTokenIds` as JSON-encoded strings; this Actor parses them and always returns plain numbers and arrays.
- **Correctly sorted.** Exchange-wide and search scans query markets directly so results are genuinely ranked by 24h volume market-by-market — not just by the volume of the event they belong to.
- **Pay only for results.** No monthly rental. Order book / trades / price history are optional and charged only when you switch them on.

### What can you do with it?

| Use case | How |
| --- | --- |
| **Probability dashboards / newsletters** | `tagSlug: "politics"` or `search: "fed rate"` returns `impliedProbability` for every market |
| **Backtesting** | `status: "closed"` + `closedWithinDays: 365` + `includePriceHistory: true` gives the result and full price path per market |
| **Arbitrage & cross-venue comparison** (Polymarket vs Kalshi vs sportsbooks) | live `yesPrice`/`noPrice`/`orderbook` by market on a schedule |
| **Liquidity & flow research** | `includeTrades: true` for fills, `includeOrderbook: true` for depth |
| **Event research** | `eventSlugs: ["your-event-slug"]` returns every outcome market of one event, e.g. all brackets of an election or all props of a game |
| **AI agents** | Simple input, flat JSON output, works through the Apify MCP server |

### Input

Pick **any one** selector — or none to scan the whole exchange:

| Field | Example | Notes |
| --- | --- | --- |
| `marketSlugs` | `["xi-jinping-out-before-2027"]` | Exact markets. Status/date filters are ignored for these. Polymarket URLs are accepted too - the last path segment is used. |
| `marketIds` | `["4331478"]` | Exact markets by numeric Gamma ID |
| `conditionIds` | `["0x55f72d..."]` | Exact markets by on-chain condition ID (the ID used by the CLOB and Data API) |
| `eventSlugs` | `["xi-jinping-out-before-2027"]` | All outcome markets of one event. Polymarket URLs accepted too. |
| `tagSlug` | `"politics"` | Every live market under one Polymarket tag. Polymarket's tag list is large and free-form (thousands of tags, no fixed category list) - check polymarket.com for tag names. |
| `status` | `open` (default), `closed`, `all` | `closed` includes both trading-ended-awaiting-settlement and already-resolved markets |
| `search` | `"bitcoin 150000"` | All words must appear in question, event title, slug, description or tags |
| `closesWithinDays` | `7` | Live markets closing in the next N days |
| `closedWithinDays` | `30` | Markets that closed in the last N days (history / backtests) |
| `minVolume` | `1000` | Skip markets with lifetime volume below this many dollars |
| `minLiquidity` | `500` | Skip markets with current liquidity below this many dollars |
| `maxItems` | `100` | Hard cap on saved (and charged) markets |
| `includeOrderbook`, `orderbookDepth` | `true`, `10` | Current book per outcome |
| `includeTrades`, `maxTradesPerMarket`, `tradesLookbackHours` | `true`, `100`, `24` | Recent fills, public wallet address only |
| `includePriceHistory`, `historyInterval`, `historyFidelityMinutes` | `true`, `"1w"`, `60` | Price-over-time per outcome: `1h`, `6h`, `1d`, `1w`, `1m` or `max` |

#### Example: top 50 open markets by 24h volume

```json
{ "status": "open", "maxItems": 50 }
```

#### Example: liquid Bitcoin markets with live order books

```json
{ "search": "bitcoin", "minVolume": 1000, "includeOrderbook": true, "maxItems": 100 }
```

#### Example: one event with everything attached

```json
{
  "eventSlugs": ["xi-jinping-out-before-2027"],
  "includeOrderbook": true,
  "includeTrades": true,
  "includePriceHistory": true,
  "historyInterval": "1w"
}
```

### Output

One record per market. Prices are dollars between 0 and 1 (so they are also probabilities); volume/liquidity are dollars.

```json
{
  "conditionId": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
  "marketId": "559651",
  "slug": "xi-jinping-out-before-2027",
  "question": "Xi Jinping out before 2027?",
  "eventTitle": "Xi Jinping out before 2027?",
  "eventSlug": "xi-jinping-out-before-2027",
  "tags": ["hfc", "world-affairs", "geopolitics", "world", "earn-4", "macro-geopolitics"],
  "outcomes": [
    { "name": "Yes", "price": 0.0365, "impliedProbability": 0.0365, "tokenId": "32338220190071351435772801779725302244575775216413325951443816017994629993401" },
    { "name": "No", "price": 0.9635, "impliedProbability": 0.9635, "tokenId": "25659310674993675562345759665114759892400026242514633218387667107987341231962" }
  ],
  "yesPrice": 0.0365,
  "noPrice": 0.9635,
  "impliedProbability": 0.0365,
  "status": "open",
  "result": null,
  "volume": 13517120.788755992,
  "volume24h": 103739.77267399995,
  "liquidity": 428144.6475,
  "openInterest": null,
  "bestBid": 0.036,
  "bestAsk": 0.037,
  "spread": 0.001,
  "lastTradePrice": 0.036,
  "startTime": "2025-07-03T20:37:00.228Z",
  "closeTime": "2027-01-01T04:59:00Z",
  "resolutionSource": null,
  "description": "This market will resolve to \"Yes\" if China's General Secretary of the Communist Party, Xi Jinping, is removed from power for any length of time between July 3, 2025, and December 31, 2026, 11:59 PM ET. Otherwise, this market will resolve to \"No\".\n\n...",
  "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
  "scrapedAt": "2026-09-18T12:21:23.469Z"
}
```

Field notes:

- `outcomes` — one entry per outcome (2 for a normal Yes/No market, N for a genuine multi-outcome market). `yesPrice`/`noPrice`/`impliedProbability` are only populated for 2-outcome markets.
- `impliedProbability` — the YES price for a 2-outcome market; `null` for genuine multi-outcome markets, where a single "implied probability of YES" is not meaningful.
- `status` — `open`, `closed` (trading ended, not yet resolved) or `resolved`. Polymarket has no single status field; this is derived from `closed` plus whether an outcome has settled to a price of exactly 1.
- `result` — the winning outcome name once resolved, derived the same way. `null` until then.
- `openInterest` — Polymarket only exposes this per **event** (aggregated across every outcome), not per market; attached here for context.
- `tags` — the market's Polymarket tag slugs (category, sport, topic, etc.).
- `orderbook` (optional) — one entry per outcome: `bids`, `asks` (best first), `bestBid`, `bestAsk`, `bidDepth`, `askDepth`.
- `trades` (optional) — `proxyWallet` (public on-chain address only — no display name, bio or profile image), `side`, `outcome`, `outcomeIndex`, `tokenId`, `price`, `size`, `timestamp`, `transactionHash`.
- `priceHistory` (optional) — one entry per outcome: `name`, `tokenId`, `history: [{time, price}]`.

### Pricing

Pay per event — you are charged only for what is saved:

| Event | When |
| --- | --- |
| `market-record` | Each market saved to the dataset |
| `market-enrichment` | Each market that got order book and/or trades and/or price history attached (one charge per market, not per enrichment type) |

Filtered-out markets and failed requests are free. Set **Max total charge** on the run to cap spend; the Actor stops cleanly when the cap is reached.

### Scheduling & integrations

Run on a schedule (e.g. every 5 minutes for live prices), then pull results via the Apify API, webhooks, Google Sheets, Make, n8n or Zapier. Each record has `scrapedAt`, so scheduled runs can be appended into a time series.

### Limits & good citizenship

The Actor throttles itself to 8 requests/second across all three Polymarket APIs it uses, well under any documented limit, and retries on `429`/`5xx` with back-off. Data is public market data; trade fills are stripped of the wallet pseudonym, bio and profile-image fields Polymarket's API otherwise includes, leaving only the public on-chain address.

### Code example

A runnable Python script (only `requests` needed) that calls this Actor and writes a CSV: [polymarket/top\_markets\_to\_csv.py](https://github.com/ankaibua-spec/feedsmith-examples/blob/master/polymarket/top_markets_to_csv.py) — save the most traded open markets (odds, volume, liquidity) to CSV.

### FAQ

**Is this affiliated with Polymarket?** No. It is an independent tool that reads Polymarket's public APIs. Nothing here is trading advice.

**Why is a market's `tags` array sometimes empty?** Only markets fetched through a tag/category or event scan carry tag data directly from Polymarket; if you selected markets by slug/ID/condition ID, tags are still attached via an extra (free) query flag, but very new or unlisted markets may not have any tags assigned yet.

**I filtered by `tagSlug` and the results aren't perfectly sorted by volume.** Tag scans go through Polymarket's `/events` endpoint (the only one that filters by tag), which sorts by event-level volume; markets belonging to the same event are not individually re-sorted. Scans with no `tagSlug` query markets directly and are sorted market-by-market.

**I get zero results for a slug/ID.** Resolved markets are hidden when `status` is `open` (the default). Use `status: "closed"` or `"all"`, or pass the identifier in `marketSlugs`/`marketIds`/`conditionIds`, which ignore status entirely.

**Something wrong or missing?** Open an issue on the Actor's Issues tab — fixes usually ship within a day.

# Actor input Schema

## `marketSlugs` (type: `array`):

Specific markets by slug, e.g. lol-we-jdg-2026-09-18-game3. You can also paste a polymarket.com event/market URL - the last path segment is used.

## `marketIds` (type: `array`):

Specific markets by numeric Gamma market ID, e.g. 4331478.

## `conditionIds` (type: `array`):

Specific markets by on-chain condition ID (0x...), as used by the CLOB and Data API.

## `eventSlugs` (type: `array`):

Specific events, e.g. xi-jinping-out-before-2027. Returns every outcome market of the event. You can also paste a polymarket.com event URL.

## `tagSlug` (type: `string`):

Fetch every live market under one Polymarket tag, e.g. politics, crypto, sports, nfl, bitcoin, fed. Used only when no market/event selector above is given. Polymarket's tag list is large and free-form (no fixed category list); see polymarket.com for tag names. Leave all selectors empty to scan the whole exchange.

## `status` (type: `string`):

open = tradeable now. closed = trading ended (includes markets awaiting settlement and already-resolved ones). all = everything.

## `search` (type: `string`):

Keep only markets whose question, event title, slug, description or tags contain ALL of these words (case-insensitive). Example: bitcoin 150000

## `closesWithinDays` (type: `integer`):

Only markets closing within the next N days. Useful with status = open.

## `closedWithinDays` (type: `integer`):

Only markets that closed in the last N days. Use with status = closed or all to build a backtesting history.

## `minVolume` (type: `integer`):

Skip illiquid markets with lifetime volume below this many dollars.

## `minLiquidity` (type: `integer`):

Skip markets with current order book liquidity below this many dollars.

## `maxItems` (type: `integer`):

Stop after this many markets. You are only charged for markets actually saved. Default 100 keeps a first test run around $0.15; raise it for full exports.

## `includeOrderbook` (type: `boolean`):

Attach the current order book (bids, asks, best bid/ask, depth) for every outcome. Charged as one enrichment per market.

## `orderbookDepth` (type: `integer`):

Number of price levels to return per side of the book.

## `includeTrades` (type: `boolean`):

Attach the most recent trade fills for each market. Only the public on-chain wallet address is kept per trade - no names, bios or profile images.

## `maxTradesPerMarket` (type: `integer`):

Upper limit of trade fills attached to each market, newest first.

## `tradesLookbackHours` (type: `integer`):

Only trades from the last N hours. Leave empty for the most recent trades regardless of age.

## `includePriceHistory` (type: `boolean`):

Attach OHLC-free price-over-time history for every outcome.

## `historyInterval` (type: `string`):

Length of the history window.

## `historyFidelityMinutes` (type: `integer`):

Minutes between price points.

## Actor input object example

```json
{
  "marketSlugs": [],
  "eventSlugs": [],
  "status": "open",
  "minVolume": 0,
  "minLiquidity": 0,
  "maxItems": 100,
  "includeOrderbook": false,
  "orderbookDepth": 10,
  "includeTrades": false,
  "maxTradesPerMarket": 100,
  "includePriceHistory": false,
  "historyInterval": "1h",
  "historyFidelityMinutes": 60
}
```

# Actor output Schema

## `results` (type: `string`):

One record per Polymarket market: prices, implied probability, volume, liquidity, tags, event linkage and optional order book, trades and price history.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "marketSlugs": [],
    "eventSlugs": [],
    "tagSlug": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("feedsmith/polymarket-markets-scraper").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "marketSlugs": [],
    "eventSlugs": [],
    "tagSlug": "",
}

# Run the Actor and wait for it to finish
run = client.actor("feedsmith/polymarket-markets-scraper").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 '{
  "marketSlugs": [],
  "eventSlugs": [],
  "tagSlug": ""
}' |
apify call feedsmith/polymarket-markets-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,feedsmith/polymarket-markets-scraper"
        }
    }
}
```

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 <APIFY_API_TOKEN>` 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/Y7VhGranl8i6alP7L/builds/WpL9H3tNtn6YwcaNk/openapi.json