# Polymarket Trade Intelligence: Order Book and Prices (`scrapemint/polymarket-scraper`) Actor

Bulk pull Polymarket prediction markets by category, keyword, tag, slug, or condition ID. One row per market with outcomes, YES and NO prices, 24h volume, liquidity, end date, plus optional order book, recent trades, and price history. No third party API key. Pay per row.

- **URL**: https://apify.com/scrapemint/polymarket-scraper.md
- **Developed by:** [Ken M](https://apify.com/scrapemint) (community)
- **Categories:** Developer tools, Automation, News
- **Features:** Limited permissions
- **Stats:** 99 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

$5.00 / 1,000 polymarket market rows

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 Trade Intelligence: Markets, Order Book, Price History

Bulk pull Polymarket prediction markets at scale. Filter by category, keyword, tag, or fetch direct slugs and condition IDs. Each row ships with the full market metadata: question, outcomes, current YES and NO prices, 24h and lifetime volume, on book liquidity, end date, plus optional CLOB order book depth, recent trades, and a YES price history time series. JSON, CSV, or Excel. No third party API key. Pay per row.

**Built for** quant teams modeling event probabilities, hedge funds piping prediction signals into trading models, sports analytics shops correlating Polymarket prices with sportsbook lines, political research desks tracking election odds, crypto traders watching token launch markets, content teams powering odds widgets, and AI builders training event probability models on a clean cross market dataset.

**Keywords this actor ranks for:** polymarket scraper, polymarket api, prediction market data, polymarket order book, polymarket trades, polymarket price history, prediction market dataset, polymarket json, polymarket csv, polymarket condition id, polymarket gamma api, polymarket clob api, election odds api, sports prediction markets, crypto prediction markets, event probabilities api.

***

### Why this actor

| Other prediction market tools | **This actor** |
|---|---|
| Require a paid API key (Kalshi, PredictIt third party feeds) | Hits the public Polymarket Gamma + CLOB APIs directly. No third party key. |
| Surface only the headline price | One row per market with full metadata: outcomes, prices, 24h volume, lifetime volume, liquidity, start and end dates, tags, image |
| No order book depth | Optional CLOB book per outcome with bids and asks at configurable depth |
| No trade feed | Optional recent trades per market with side, size, price, timestamp, and trader wallet |
| Single point in time only | Optional YES price history time series at 1h, 6h, 1d, 1w, 1m, or max windows |
| Slug input only | Search query, category, tag ID, slug, and condition ID inputs all work in the same run |
| No deduplication | Per condition ID dedupe across runs, persisted in a key value store |

***

### How it works

```mermaid
flowchart LR
    A[searchQueries<br/>categories<br/>tagIds<br/>marketSlugs<br/>conditionIds] --> B[Source resolver]
    B --> C[Gamma /markets<br/>list endpoint]
    B --> D[Gamma /markets?slug<br/>direct lookup]
    B --> E[Gamma /markets?condition_ids<br/>direct lookup]
    C --> F[Numeric filters<br/>min volume / liquidity]
    D --> F
    E --> F
    F --> G{Enrichment<br/>requested?}
    G -->|orderbook| H[CLOB /book<br/>token_id]
    G -->|trades| I[Data API /trades<br/>conditionId]
    G -->|history| J[CLOB /prices-history<br/>token_id + interval]
    G -->|none| K[Skip enrichment]
    H --> L[One row per market<br/>with optional nested data]
    I --> L
    J --> L
    K --> L
    L --> M[(JSON CSV API)]
```

The Gamma API serves the same JSON the Polymarket web client consumes. Markets ship with `conditionId`, `slug`, `outcomes`, `outcomePrices`, `volume24hr`, `liquidity`, `endDate`, and the two `clobTokenIds` (one ERC1155 token per outcome). Order book + price history live on the CLOB API keyed by token ID. Trades live on the Polymarket data API keyed by condition ID. Everything stitches into a single row.

***

### What you get per row

```mermaid
flowchart LR
    R[Market row] --> R1[Identity<br/>conditionId slug url]
    R --> R2[Question<br/>description category tags]
    R --> R3[Status<br/>active closed resolved]
    R --> R4[Outcomes<br/>YES NO prices]
    R --> R5[Volume<br/>24h + lifetime + liquidity]
    R --> R6[Dates<br/>start + end]
    R --> R7[orderbook<br/>bids and asks per outcome]
    R --> R8[recentTrades<br/>side size price trader]
    R --> R9[priceHistory<br/>time series]
```

Toggle `includeOrderbook` and every outcome ships a `bids` and `asks` array trimmed to `orderbookDepth` levels. Toggle `includeRecentTrades` and each row carries up to `recentTradesLimit` of the most recent fills with side, size, price, timestamp, and trader wallet. Toggle `includePriceHistory` and the YES outcome gets a time series at the chosen interval.

***

### Quick start

**Top 25 active markets across politics + sports right now**

```json
{
  "categories": ["politics", "sports"],
  "status": "active",
  "sortBy": "volume24hr",
  "maxItemsTotal": 25
}
```

**Search by keyword, drop thin markets**

```json
{
  "searchQueries": ["fed rate cut", "bitcoin", "election"],
  "minVolume24h": 1000,
  "minLiquidity": 5000,
  "maxItemsTotal": 50
}
```

**Direct market with full enrichment**

```json
{
  "marketSlugs": ["russia-ukraine-ceasefire-before-gta-vi-554"],
  "includeOrderbook": true,
  "orderbookDepth": 20,
  "includeRecentTrades": true,
  "recentTradesLimit": 100,
  "includePriceHistory": true,
  "priceHistoryInterval": "1w"
}
```

**Pull every active crypto market into a dataset**

```json
{
  "categories": ["crypto"],
  "status": "active",
  "sortBy": "liquidity",
  "maxItemsTotal": 500,
  "maxItemsPerSource": 500
}
```

**Build a research dataset across closed markets**

```json
{
  "categories": ["elections"],
  "status": "closed",
  "minTotalVolume": 10000,
  "includePriceHistory": true,
  "priceHistoryInterval": "max",
  "maxItemsTotal": 200
}
```

***

### Sample output row

```json
{
  "conditionId": "0x9c1a953fe92c8357f1b646ba25d983aa83e90c525992db14fb726fa895cb5763",
  "slug": "russia-ukraine-ceasefire-before-gta-vi-554",
  "question": "Russia Ukraine Ceasefire before GTA VI?",
  "category": "politics",
  "tags": ["politics", "geopolitics"],
  "endDate": "2026-07-31T12:00:00Z",
  "active": true,
  "closed": false,
  "outcomes": ["Yes", "No"],
  "outcomePrices": [0.535, 0.465],
  "volume24h": 3210.37,
  "totalVolume": 1626624.45,
  "liquidity": 65737.39,
  "url": "https://polymarket.com/event/russia-ukraine-ceasefire-before-gta-vi-554",
  "clobTokenIds": ["8501497159...", "2527312495..."],
  "orderbook": {
    "Yes": {
      "timestamp": "2026-04-30T03:09:51.054Z",
      "bids": [{"price": 0.53, "size": 1500.0}, {"price": 0.52, "size": 800.5}],
      "asks": [{"price": 0.54, "size": 2200.0}, {"price": 0.55, "size": 950.0}]
    }
  },
  "recentTrades": [
    {"side": "BUY", "outcome": "Yes", "price": 0.535, "size": 250.0, "timestamp": "2026-04-30T02:48:00Z", "trader": "0x3b5a..."}
  ],
  "priceHistory": [
    {"timestamp": "2026-04-29T00:00:03Z", "yesPrice": 0.535},
    {"timestamp": "2026-04-29T01:00:04Z", "yesPrice": 0.535}
  ],
  "scrapedAt": "2026-04-30T03:09:51.123Z"
}
```

***

### Pricing

Pay per row, no subscription. First 2 rows per run are free so you can verify the schema before scaling up. After that you pay per market row delivered to the dataset, regardless of which enrichment fields are attached.

| Run shape | Free rows | Paid rows | Cost |
|---|---|---|---|
| 20 row dry run | 20 | 0 | $0.00 |
| 100 row research pull | 20 | 80 | $0.40 |
| 500 row category sweep | 20 | 480 | $2.40 |
| 2000 row dataset build | 20 | 1980 | $9.90 |

Apify platform usage (proxy + compute) is billed separately and charged at cost.

***

### Common questions

**Where do I find a market slug?**
The Polymarket URL after `/event/` is the slug. For example `https://polymarket.com/event/will-trump-win-2024` -> slug is `will-trump-win-2024`.

**Where do I find a condition ID?**
Open the market, then check the network tab for the Gamma API response. The `conditionId` field is a 0x prefixed hex string. You can also find it via the slug input on this actor and read it off the first row.

**Why is `priceHistory` only for YES?**
The two outcome tokens sum to 1 by construction (NO price = 1 - YES price). Pulling YES alone halves the API cost.

**Is the order book live?**
Yes. The CLOB book is the live order book the Polymarket front end uses. The `timestamp` field on each book snapshot reflects when CLOB returned the data.

**How fresh is the data?**
Gamma metadata is real time. Order book is real time. Trades are within a second of execution. Price history is sampled by Polymarket within the requested window.

**Can I pull every market in one run?**
Yes, set `maxItemsTotal` to 0 (unlimited) and pick one or more categories. Expect a few minutes per thousand rows when no enrichment is enabled.

***

### Disclaimer

This actor uses the public Polymarket Gamma, CLOB, and data APIs. Polymarket may change endpoint shapes or rate limits at any time without notice; if a request shape changes the actor degrades gracefully and logs a warning rather than failing the run. Polymarket access is not available in every jurisdiction; comply with your local regulations.

### Related actors

- [Prediction Market Arbitrage: Kalshi vs Polymarket vs PredictIt](https://apify.com/scrapemint/prediction-market-odds-comparison): Polymarket against Kalshi and PredictIt, with locked-in arbitrage
- [Polymarket Prediction Market Tracker by Category](https://apify.com/scrapemint/polymarket-market-monitor): watchlists and alerts on price moves and volume
- [Polymarket Whale Tracker: Big Bets and Smart Money](https://apify.com/scrapemint/polymarket-whale-tracker): large bets and the wallets behind them
- [Kalshi Trades: Live Tape, Whale Trades and Price History](https://apify.com/scrapemint/kalshi-trades-tracker): the Kalshi side of the same questions
- [Betting Odds Comparison: Best Price & Arbitrage Finder](https://apify.com/scrapemint/sports-odds-scraper): sportsbook lines to compare with sports markets

# Actor input Schema

## `searchQueries` (type: `array`):

Keyword search across market questions and descriptions. Each query runs separately and results merge.

## `categories` (type: `array`):

Top level Polymarket categories. Resolves to internal tag IDs.

## `tagIds` (type: `array`):

Direct numeric tag IDs from Polymarket (advanced). Useful when a category is not in the dropdown.

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

Direct market slugs to scrape, e.g. "will-trump-win-2024". Found in the Polymarket URL after /event/.

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

Direct hex condition IDs (0x...). Bypasses search and pulls the exact market.

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

Active = currently trading. Closed = no longer accepting orders. Resolved = outcome decided.

## `minVolume24h` (type: `number`):

Drop markets below this 24h trading volume.

## `minTotalVolume` (type: `number`):

Drop markets below this lifetime volume.

## `minLiquidity` (type: `number`):

Drop markets below this on book liquidity. Useful for filtering thin markets.

## `sortBy` (type: `string`):

Order applied before maxItemsTotal cap.

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

Pull the live CLOB order book per outcome (top bids and asks with size). Adds 1 request per outcome.

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

Max number of bid + ask levels to keep per outcome.

## `includeRecentTrades` (type: `boolean`):

Pull the most recent trades for each market from the public data API. Adds 1 request per market.

## `recentTradesLimit` (type: `integer`):

Max number of recent trades to attach per market.

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

Pull the YES outcome price history time series for each market. Adds 1 request per market.

## `priceHistoryInterval` (type: `string`):

Time window for price history. Polymarket samples within the window.

## `maxItemsPerSource` (type: `integer`):

Hard cap per (search query, category, tag) combination. Stops paging once reached.

## `maxItemsTotal` (type: `integer`):

Hard cap on rows pushed per run across all sources. 0 means unlimited.

## `dedupe` (type: `boolean`):

Skip condition IDs already pushed in previous runs. Persisted in a key value store. Turn off to refresh. Off by default so a repeated query returns its full result set. Turn it on to poll for new items only.

## `concurrency` (type: `integer`):

Number of enrichment requests fetched in parallel.

## `proxyConfiguration` (type: `object`):

Apify proxy. Polymarket public APIs work fine on datacenter or unproxied; residential is only needed if you hit aggressive rate limits. Polymarket answers from datacenter IPs, so leave this off unless you are blocked.

## Actor input object example

```json
{
  "searchQueries": [
    "election"
  ],
  "categories": [],
  "tagIds": [],
  "marketSlugs": [],
  "conditionIds": [],
  "status": "active",
  "minVolume24h": 0,
  "minTotalVolume": 0,
  "minLiquidity": 0,
  "sortBy": "volume24hr",
  "includeOrderbook": false,
  "orderbookDepth": 10,
  "includeRecentTrades": false,
  "recentTradesLimit": 25,
  "includePriceHistory": false,
  "priceHistoryInterval": "1d",
  "maxItemsPerSource": 100,
  "maxItemsTotal": 200,
  "dedupe": false,
  "concurrency": 4,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "searchQueries": [
        "election"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapemint/polymarket-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 = {
    "searchQueries": ["election"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapemint/polymarket-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 '{
  "searchQueries": [
    "election"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapemint/polymarket-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapemint/polymarket-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/SxI39uRGmutJdU0hI/builds/crw9yeF9wkNS2WGZm/openapi.json