# Polymarket Scraper & API – Odds, Volume, Price History (`gazidev/polymarket-data`) Actor

Polymarket prediction market data from the official public API: live yes/no odds, outcomes, volume, 24h volume, liquidity, close dates, rules and links, optional price history and a monitor mode for new markets or big price moves. Search by keyword, tag or URL. No login. $0.002 per market.

- **URL**: https://apify.com/gazidev/polymarket-data.md
- **Developed by:** [Cemal Atakli](https://apify.com/gazidev) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 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 Scraper & API – Odds, Volume, Price History

Get **Polymarket prediction market data as a clean, flat dataset**: live YES/NO odds (implied probabilities), all outcomes, total and 24h volume, liquidity, best bid/ask, 24h price change, close date, resolution rules and links. You can add a **price history time series** per market, and use **monitor mode** to output only new markets or big odds moves.

- **Official public APIs only.** The Actor uses Polymarket's Gamma API and the CLOB `/prices-history` endpoint. There is no login, no API key, no browser and no HTML scraping.
- **Search any way you like.** Find markets by keyword, tag, event or market URL, slug or ID, sorted by 24h volume, total volume, liquidity, closing date or newest.
- **$2 per 1,000 markets.** Price history costs $0.003 per market, and a run costs $0.0001 to start. Monitor mode outputs only new markets and markets whose odds moved.

### Quick start

This is the prefilled input: the top 4 open markets by 24h volume, in seconds, for about $0.008. Raise `maxMarkets` (up to 5,000) for more.

```json
{ "maxMarkets": 4 }
```

#### Sample output (illustrative values)

| question | yes\_price | volume\_usd | volume\_24h\_usd | close\_time |
|---|---|---|---|---|
| Will the Fed cut rates by 25 bps in December 2026? | 0.62 | 9,000,000 | 300,000 | 2026-12-31 |
| Will the Fed hold rates in December 2026? | 0.30 | 6,000,000 | 200,000 | 2026-12-31 |

#### Price comparison (Apify Store, September 2026)

| Actor | Price per 1,000 markets | Monthly users |
|---|---|---|
| **Polymarket Scraper & API (this Actor)** | **$2** | new |
| scrapemint/polymarket-market-monitor | $12 | 32 |

**Related Actors:** [Google News Scraper](https://apify.com/gazidev/google-news-scraper) for the news behind the odds, and [SEC EDGAR MCP Server & API](https://apify.com/gazidev/sec-edgar-mcp) for company fundamentals.

### What can this Polymarket scraper do?

- **Top markets in one click.** The prefilled input returns the 4 open markets with the highest 24h volume. With no input at all, the Actor returns the top 20.
- **Keyword and tag search.** For example `fed rate`, `bitcoin`, `election` or `recession`, with tags such as `politics`, `crypto`, `economy` or `sports`.
- **Status and sorting.** Choose open, closed/resolved, or all markets. Sort by 24h volume, total volume, liquidity, closing soonest or newest.
- **Market details by URL or ID.** Accepts Polymarket event URLs (all markets of the event), market URLs, slugs, numeric IDs and condition IDs.
- **Price history.** Optional YES-price time series for the last day, week or month, or the full history (daily points).
- **Monitor mode.** Schedule the Actor, for example hourly. Each run outputs only markets that are **new** or whose YES probability **moved by at least X points** since the last run. State is kept in a named key-value store.

### Use cases

- **Trading research.** Find the most active and liquid markets, spreads and 24h moves, and export them to Sheets or BI tools.
- **News and media.** Show "what the markets say" about elections, Fed decisions, crypto and sports, with links.
- **Alerts.** Run monitor mode hourly and connect Apify integrations (Slack, email, webhooks, Make, Zapier) to hear when odds move 5+ points.
- **Data science and backtesting.** Use price history for calibration studies, forecasting benchmarks and dashboards.
- **AI agents.** Give an LLM grounded, current probabilities for real-world events.

### Input example

```json
{
  "search": "fed",
  "status": "open",
  "sortBy": "volume24h",
  "maxMarkets": 20,
  "includePriceHistory": true,
  "historyRange": "1w"
}
```

Specific markets:

```json
{ "marketIds": ["https://polymarket.com/event/fed-decision-in-december", "will-bitcoin-reach-150000-by-december-31-2026"] }
```

Monitor mode (schedule it):

```json
{ "search": "election", "monitorMode": true, "priceMoveThresholdPct": 5, "monitorStoreName": "election-odds" }
```

### Output example

```json
{
  "platform": "polymarket",
  "market_id": "500011",
  "event_id": "901",
  "event_title": "Fed decision in December?",
  "question": "Will the Fed cut rates by 25 bps in December 2026?",
  "category": "Economy",
  "outcomes": [
    { "name": "Yes", "price": 0.62, "probability": 0.62 },
    { "name": "No", "price": 0.38, "probability": 0.38 }
  ],
  "yes_price": 0.62, "no_price": 0.38, "best_bid": 0.61, "best_ask": 0.63, "last_price": 0.62,
  "price_change_24h": 0.015,
  "volume_usd": 9000000, "volume_24h_usd": 300000, "liquidity_usd": 12345.6,
  "status": "open", "open_time": "2026-01-01T00:00:00Z", "close_time": "2026-12-31T00:00:00Z",
  "url": "https://polymarket.com/event/fed-decision-december/market-11",
  "platform_ids": { "slug": "market-11", "event_slug": "fed-decision-december", "condition_id": "0x…", "clob_token_ids": ["…", "…"] },
  "rules": "This market will resolve to \"Yes\" if …",
  "price_history": [{ "t": "2026-09-27T00:00:00Z", "ts": 1790467200, "p": 0.51 }],
  "price_history_points": 168
}
```

Field notes:

- Prices and probabilities range from 0 to 1, as displayed by Polymarket. Volume and liquidity are in USD (USDC).
- Multi-outcome markets (for example team A vs team B) list every outcome in `outcomes`. For these, `yes_price` and `no_price` are the first and second outcome.
- Monitor runs add `monitor_change` (`new` / `price_move`), `previous_yes_price` and `yes_change_pp`.
- A run summary (counts, errors, request count) is saved to the `OUTPUT` record of the key-value store.

### Pricing

Pay per event. You pay only for results:

| Event | Price |
|---|---|
| Run start | $0.0001 |
| Market saved | $0.002 ($2 per 1,000 markets) |
| Price history fetched (per market, only if data was returned) | $0.003 |

Examples: the prefilled run (top 4 markets) costs about **$0.008**, and the top 20 markets cost about $0.04. 100 markets with a week of price history cost $0.50. Set a **maximum cost per run** in Apify. The Actor checks your remaining budget before each market, skips history it can't afford, and stops cleanly.

#### Why this Actor

Prediction-market Actors on the Store have about 230 monthly users combined, and at least one popular Actor shows a run success rate of around 15%. This one is built for reliability:

- official JSON APIs only, with no HTML scraping that breaks
- retries with backoff
- a time budget, so searches always return the best results found so far
- per-input errors recorded instead of crashing
- a flat, documented schema

### Use with AI agents (Apify MCP)

Add this Actor to the Apify MCP server (`https://mcp.apify.com`) in Claude, ChatGPT, Cursor or any MCP client. An agent can then ask *"What are the current Polymarket odds that the Fed cuts in December?"* and get compact, structured JSON. The inputs are plain strings, numbers and booleans, so they're easy for LLMs to fill in.

```python
from apify_client import ApifyClient
run = ApifyClient("<TOKEN>").actor("gazidev/polymarket-data").call(run_input={"search": "bitcoin", "maxMarkets": 10})
```

### Data source, terms and attribution

- **Endpoints:** `gamma-api.polymarket.com` (`/markets`, `/events`, `/public-search`) and `clob.polymarket.com/prices-history`. These are public, read-only and need no authentication, as documented at docs.polymarket.com. The Actor never places orders and never touches user or wallet endpoints.
- **Rate limits:** Polymarket enforces per-IP limits through Cloudflare. Gamma allows roughly 300 `/markets` and 500 `/events` requests per 10 seconds. A typical run makes 1–30 requests.
- **Terms:** Polymarket's Terms of Use (polymarket.com/tos) apply to your use of the data. Polymarket's API docs don't set a specific attribution or redistribution rule for public market data. When you publish odds, please credit "Source: Polymarket". Polymarket trading isn't available in some jurisdictions. This Actor only reads public market data.
- Data is provided as-is and may be delayed. **This is informational data, not trading or investment advice.**

### FAQ

**Do I need a Polymarket account or API key?**
No. Only public market-data endpoints are used.

**Why does a keyword search return fewer markets than I asked for?**
Polymarket has no full-text market filter, so the Actor combines Polymarket's public search with a scan of events sorted by your chosen field, within `discoveryTimeoutSecs` / `maxEventsToScan`. Raise those for exhaustive scans, or use a broader keyword.

**Monitor mode: what counts as a price move?**
The absolute change in YES probability since the previous run, in percentage points (40% → 45% is 5 points). The first run outputs everything as `new` unless you turn off `monitorEmitOnFirstRun`.

**Some inputs failed. Was I charged?**
No. Unknown IDs and API errors are listed in the `OUTPUT` summary and aren't charged. Price history is charged only when points were returned.

**Is it affiliated with Polymarket?**
No. This is an independent tool that uses Polymarket's public API.

# Actor input Schema

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

Only markets whose question / event title contains ALL these words (case-insensitive), e.g. "fed rate", "bitcoin", "election". Leave empty for the top markets.

## `category` (type: `string`):

Optional Polymarket tag, e.g. politics, crypto, economy, sports (tag slug).

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

Open (trading now), closed/resolved, or all.

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

Ranking used to pick the top N markets per platform.

## `maxMarkets` (type: `integer`):

How many markets to return (each saved market is one billable event).

## `minVolumeUsd` (type: `integer`):

Skip thin markets (total traded volume in USD/USDC).

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

Get details for specific markets instead of searching: Polymarket event or market URLs, market/event slugs, numeric market ids or condition ids (0x…).

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

Adds a YES-price time series (Polymarket CLOB) to every market (extra event per market with data: price-history).

## `historyRange` (type: `string`):

1d = 10-minute points, 1w hourly, 1m 4-hourly, max daily since the market opened.

## `monitorMode` (type: `boolean`):

Schedule this Actor: each run outputs only markets that are new since the last run or whose YES price moved by at least the threshold. State is kept in a named key-value store.

## `priceMoveThresholdPct` (type: `integer`):

E.g. 5 = report a market when its YES probability moved 5+ points (e.g. 40% → 45%) since the previous run.

## `monitorStoreName` (type: `string`):

Named key-value store that remembers prices between runs. Use different names for different monitors.

## `monitorEmitOnFirstRun` (type: `boolean`):

If off, the first run only records a baseline and outputs nothing.

## `maxEventsToScan` (type: `integer`):

Keyword/category searches scan events sorted by the chosen field and filter locally. Higher = more exhaustive but slower.

## `discoveryTimeoutSecs` (type: `integer`):

Scanning stops after this time and the best markets found so far are returned.

## Actor input object example

```json
{
  "status": "open",
  "sortBy": "volume24h",
  "maxMarkets": 4,
  "minVolumeUsd": 0,
  "includePriceHistory": false,
  "historyRange": "1w",
  "monitorMode": false,
  "priceMoveThresholdPct": 5,
  "monitorStoreName": "prediction-markets-monitor",
  "monitorEmitOnFirstRun": true,
  "maxEventsToScan": 3000,
  "discoveryTimeoutSecs": 45
}
```

# Actor output Schema

## `markets` (type: `string`):

No description

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

No description

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

// Prepare Actor input
const input = {
    "maxMarkets": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("gazidev/polymarket-data").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 = { "maxMarkets": 4 }

# Run the Actor and wait for it to finish
run = client.actor("gazidev/polymarket-data").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 '{
  "maxMarkets": 4
}' |
apify call gazidev/polymarket-data --silent --output-dataset

```

## MCP server setup

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

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/NhK4XdXraIehX5aXY/builds/wJCGwcBbScq8y95O3/openapi.json