# Polymarket Markets Scraper (`indomitably_doctor/polymarket-markets-scraper`) Actor

Structured Polymarket prediction-market data: live prices, volume, liquidity and tags. Filter by keyword, tag or volume and get clean JSON for research, trading models and journalism.

- **URL**: https://apify.com/indomitably\_doctor/polymarket-markets-scraper.md
- **Developed by:** [Billy DC](https://apify.com/indomitably_doctor) (community)
- **Categories:** Automation, News, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 receive results

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/platform/actors/running/actors-in-store#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 Markets Scraper

Get clean, structured data about [Polymarket](https://polymarket.com) prediction markets: questions, live outcome prices, trading volume, liquidity, spreads, end dates and category tags. The actor reads Polymarket's public Gamma API — no login, no cookies, no proxies needed.

### Who is this for?

- **Researchers** studying forecasting accuracy and market-implied probabilities
- **Traders** screening for high-volume or mispriced markets
- **Journalists** tracking what odds markets assign to elections, geopolitics, sports and crypto events
- **Data teams** feeding dashboards or alerting pipelines with market probabilities

### Features

- Free-text search across markets (same search Polymarket's site uses)
- Filter by category tag (`politics`, `crypto`, `sports`, ...), active/closed status and minimum volume
- Sort by volume, liquidity, end date or creation date
- Parsed outcome prices (probabilities) instead of Polymarket's raw JSON-string encoding
- Automatic pagination, retries with exponential backoff, and partial results if the API hiccups mid-run

### Input

```json
{
    "searchQuery": "bitcoin",
    "active": true,
    "closed": false,
    "tagSlug": "crypto",
    "minVolume": 10000,
    "sortBy": "volume",
    "maxItems": 100
}
```

| Field | Type | Default | Notes |
|---|---|---|---|
| `searchQuery` | string | – | Free-text search. When set, `tagSlug` is ignored. |
| `active` | boolean | `true` | Only currently tradeable markets. |
| `closed` | boolean | `false` | Include resolved markets (set `active: false` too for purely historical data). |
| `tagSlug` | string | – | Category slug from polymarket.com URLs, e.g. `politics`. |
| `minVolume` | integer | `0` | Skip markets under this all-time USD volume. |
| `sortBy` | enum | `volume` | `volume`, `liquidity`, `endDate` (soonest first) or `newest`. |
| `maxItems` | integer | `100` | Hard cap 5000. |

### Output

One dataset item per market:

```json
{
    "id": "512263",
    "question": "US x Iran permanent peace deal by May 31, 2026?",
    "slug": "us-x-iran-permanent-peace-deal-by-may-31-2026",
    "url": "https://polymarket.com/event/us-x-iran-permanent-peace-deal-by-may-31-2026",
    "outcomes": [
        { "outcome": "Yes", "price": 0.045 },
        { "outcome": "No", "price": 0.955 }
    ],
    "volumeUsd": 82819486.16,
    "liquidityUsd": 947777.08,
    "endDate": "2026-05-31T12:00:00Z",
    "active": true,
    "closed": false,
    "tags": ["politics", "geopolitics"],
    "spread": 0.01,
    "dailyVolume": 152340.55,
    "bestBid": 0.04,
    "bestAsk": 0.05,
    "eventTitle": "US x Iran permanent peace deal by May 31, 2026?",
    "eventSlug": "us-x-iran-permanent-peace-deal-by-may-31-2026",
    "timestamp": "2026-07-24T12:00:00.000Z"
}
```

`outcomes[].price` is the current market price of that outcome share in USD, which doubles as the market-implied probability (0–1).

### Pricing

The actor charges per market returned (`result-item` event), so a run of 100 markets costs 100 events. You only pay for data you actually receive.

### Honest limitations

- **Prices are snapshots**, not a stream. Run the actor on a schedule if you need time series.
- Data comes from the Gamma API, which can lag the trading engine by a few seconds.
- `tags` are only available when the market's parent event exposes them; some markets have an empty tag list.
- Free-text search returns what Polymarket's own search ranks as relevant (roughly the top ~50 events), not an exhaustive keyword scan of every market.
- The Gamma API is public but unversioned; Polymarket may change fields without notice. The actor validates every item and skips malformed ones rather than failing the run.

### Usage tips

- Historical/resolved markets: `{ "active": false, "closed": true, "sortBy": "volume" }`
- Markets resolving soon: `{ "sortBy": "endDate", "minVolume": 50000 }`
- Everything Polymarket says about an election: `{ "searchQuery": "presidential election" }`

# Actor input Schema

## `searchQuery` (type: `string`):

Free-text search over market questions (uses Polymarket's own search). Leave empty to list markets by the filters below instead.

## `active` (type: `boolean`):

Return only markets that are currently active (tradeable).

## `closed` (type: `boolean`):

Return closed (resolved) markets. Set to true together with 'active: false' to fetch historical markets.

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

Filter by a Polymarket tag slug, e.g. 'politics', 'crypto', 'sports'. Find slugs in polymarket.com category URLs.

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

Skip markets whose all-time volume is below this many USD.

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

Order of returned markets.

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

Maximum number of markets to return (1-5000).

## Actor input object example

```json
{
  "searchQuery": "bitcoin",
  "active": true,
  "closed": false,
  "tagSlug": "politics",
  "minVolume": 0,
  "sortBy": "volume",
  "maxItems": 100
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("indomitably_doctor/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 = {}

# Run the Actor and wait for it to finish
run = client.actor("indomitably_doctor/polymarket-markets-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call indomitably_doctor/polymarket-markets-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=indomitably_doctor/polymarket-markets-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MXo1jQBBfISZAKvsI/builds/CcnlIsM5Th8unCxSx/openapi.json