# Polymarket Scraper — Prediction Markets, Odds & Events (`foxlabs/polymarket-prediction-markets`) Actor

Polymarket data as clean rows: prediction markets with implied probability, best bid/ask, last trade price, spread, volume windows and liquidity; grouped events with their child markets and open interest; and free-text search. No API key, no login.

- **URL**: https://apify.com/foxlabs/polymarket-prediction-markets.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Business, News, Sports
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 prediction 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 — Prediction Markets, Odds & Events 📈

**foXLabs market data:** Polymarket prediction markets · implied probability · order book · volume & liquidity

🎉 Turn Polymarket into clean, structured data: every prediction market with its **implied probability**, **best bid/ask**, **last trade price**, **spread**, **volume** and **liquidity** — plus grouped **events** with their child markets and **open interest**, and free-text **search**. No API key, no login, no wallet. Built for traders and quants, researchers and journalists, and AI agents.

### 🔍 What is the Polymarket Scraper — and when should you use it?

Pick a mode and get rows you can filter, export or feed to a model, a spreadsheet or an AI agent:

- **Markets** — one row per prediction market: the question, each outcome with its price (= implied probability), best bid/ask, last trade price, spread, volume windows and liquidity.
- **Events** — grouped events (e.g. "2028 Democratic Nominee" with 100+ candidate markets), each with open interest, total volume, tags and its child markets nested in the row.
- **Search** — free-text query ("election", "bitcoin", "super bowl") that returns the matching events with their markets.

**Use it when you need:** a live odds/probability feed for a dashboard or bot; a snapshot of the whole active market set sorted by volume or liquidity; or every market under one theme (crypto, politics, sports) in a single pull.

**Use something else when** you need on-chain trade history or the live CLOB order book tick-by-tick — this actor delivers the gamma market snapshot (prices, volume, liquidity), not a streaming trade tape.

### 🤖 Use with AI agents

**Already on the Apify MCP server?** Ask for it by name: `foxlabs/polymarket-prediction-markets`.

**Your agent can pay for its own runs** — pay-per-event with agentic payments over **x402 (USDC on Base)** or **Skyfire**, with no Apify account of its own. Billing is per delivered record, never for errors or empty results.

Paste into Claude, ChatGPT, Cursor or any MCP assistant:

```
Use the Apify Actor `foxlabs/polymarket-prediction-markets`.
Input: `mode` = markets | events | search; `status` = active | closed | all;
`order` = volume | volume24hr | liquidity | openInterest | newest;
`tag` filters by slug (politics, crypto, sports); `search` is the query for search mode;
`maxResults` caps rows.
Start with: { "mode": "markets", "status": "active", "order": "volume", "maxResults": 50 }
```

**Things you can ask your agent:**

- "What are the highest-volume active prediction markets right now, with their implied probabilities?"
- "Find Polymarket events about the election and show each candidate's price."
- "List all active crypto markets sorted by liquidity."

**Machine-readable output:** every run writes a JSON dataset you can pull from the Apify API or the `.json` dataset endpoint.

### 📋 Overview

The Polymarket Scraper reads Polymarket's public, keyless gamma API live on every run and returns clean, camelCase rows. There is nothing to configure: no API key, no login, no wallet, no proxies to buy.

**Why teams pick this actor:**

- 🧱 **Three jobs, one actor** — individual markets, grouped events and search in a single tool.
- 🎯 **Prices as probability** — each outcome carries its price (0–1), which on Polymarket *is* the implied probability, plus bid/ask and spread.
- 🔑 **Zero setup** — no API key, no login, no wallet.
- ♻️ **Fresh every run** — reads the source live, so prices, volume and liquidity stay current.
- 🤝 **Agent-ready** — MCP + x402, billed per delivered record.

### ✨ Features

- 💹 **Live prices & probability** — each outcome's price (= implied probability), best bid, best ask, last trade price and spread.
- 📊 **Volume & liquidity** — total volume plus 24h / 1-week / 1-month windows, and current liquidity.
- 🗂️ **Grouped events** — open interest, total volume, tags, and every child market nested in the event row.
- 🔎 **Search & filter** — free-text search, tag/category filter, and sort by volume, 24h volume, liquidity, open interest or newest.
- 🕑 **Status control** — active (open), closed (resolved) or all.
- 📦 **Clean export** — camelCase rows, ready for CSV/Excel/JSON.

### 🎬 Quick Start

```bash
curl -X POST "https://api.apify.com/v2/acts/foxlabs~polymarket-prediction-markets/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "markets", "status": "active", "order": "volume", "maxResults": 50}'
```

### 🚀 Getting Started (3 steps)

1. **Pick a mode** — `markets` for individual markets, `events` for grouped events, `search` for a free-text query.
2. **Set the scope** — `status` (active/closed/all), `order` to sort, `tag` to filter by category, `maxResults` to cap rows.
3. **Run and export** — download the dataset as JSON, CSV or Excel, or pull it from the API.

### 📥 Input

```json
{
  "mode": "markets",
  "status": "active",
  "order": "volume",
  "tag": "",
  "search": "",
  "maxResults": 100
}
```

| Field | Type | Description |
|---|---|---|
| `mode` | string | `markets` (default), `events`, or `search`. |
| `status` | string | `active` (open), `closed` (resolved), or `all`. |
| `order` | string | Sort, highest first: `volume`, `volume24hr`, `liquidity`, `openInterest` (events), `newest`. |
| `tag` | string | Filter by a Polymarket tag slug (`politics`, `crypto`, `sports`, `elections`…). Markets/events modes. |
| `search` | string | Free-text query for `search` mode (`election`, `bitcoin`…). |
| `maxResults` | integer | Cap on delivered rows (0 = 100). |
| `proxyConfiguration` | object | Apify datacenter by default — no setup needed. |

### 📤 Output

**Market** (markets mode):

```json
{
  "type": "market",
  "id": "253591",
  "question": "Will the U.S. invade Iran before 2027?",
  "slug": "will-the-us-invade-iran-before-2027",
  "url": "https://polymarket.com/event/will-the-us-invade-iran-before-2027",
  "conditionId": "0x...",
  "outcomes": [
    { "name": "Yes", "price": 0.175, "impliedProbability": 0.175 },
    { "name": "No", "price": 0.825, "impliedProbability": 0.825 }
  ],
  "bestBid": 0.17, "bestAsk": 0.18, "lastTradePrice": 0.175, "spread": 0.01,
  "volume": 76613580.07, "volume24hr": 125430.2, "volume1wk": 980221.5, "liquidity": 412880.3,
  "oneWeekPriceChange": 0.02,
  "startDate": "2026-01-10T00:00:00Z", "endDate": "2026-12-31T12:00:00Z",
  "active": true, "closed": false,
  "source": "Polymarket (gamma)", "scrapedAt": "2026-11-02T10:00:00.000Z"
}
```

| Field | Type | Description |
|---|---|---|
| `question` | string | The market question. |
| `outcomes` | array | Each outcome with `name`, `price` (0–1) and `impliedProbability` (= price). |
| `bestBid` / `bestAsk` | number | Top of the order book. |
| `lastTradePrice` | number | Last traded price. |
| `spread` | number | Ask minus bid. |
| `volume` / `volume24hr` / `volume1wk` / `volume1mo` | number | Traded volume (USDC) over each window. |
| `liquidity` | number | Current liquidity. |
| `oneWeekPriceChange` | number | Price move over the last week. |
| `startDate` / `endDate` | string | Market open and resolution dates (ISO). |
| `active` / `closed` | boolean | Open vs resolved. |
| `url` | string | Public Polymarket page for the market's event. |

**Event** (events / search mode): `type: "event"`, `title`, `ticker`, `slug`, `url`, `volume`, `volume24hr`, `openInterest`, `liquidity`, `marketCount`, `tags[]`, `startDate`/`endDate`, and `markets[]` — each child market with `question`, `outcomes` (name + price), `bestBid`, `bestAsk`, `lastTradePrice` and `volume`. Every row also carries `source` and `scrapedAt`.

### 💼 Use cases

- **Odds / probability dashboard**
  - *Input:* `{ "mode": "markets", "status": "active", "order": "volume", "maxResults": 200 }`
  - *Output:* the top active markets with live implied probabilities and volume.
  - *Use:* power a "what the market thinks" widget or a Slack/Discord bot.
- **Event deep-dive**
  - *Input:* `{ "mode": "search", "search": "2028 election" }`
  - *Output:* matching events with every candidate market and its price.
  - *Use:* a single call that maps a whole race's probabilities.
- **Theme tracker (crypto / politics / sports)**
  - *Input:* `{ "mode": "markets", "tag": "crypto", "order": "liquidity" }`
  - *Output:* every active crypto market sorted by liquidity.
  - *Use:* monitor one category, feed a model, or snapshot daily for history.

### 🔗 Integration

**JavaScript (Apify client):**

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('foxlabs/polymarket-prediction-markets').call({ mode: 'markets', status: 'active', order: 'volume', maxResults: 50 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**Python (Apify client):**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_TOKEN")
run = client.actor("foxlabs/polymarket-prediction-markets").call(run_input={"mode": "markets", "status": "active", "order": "volume", "maxResults": 50})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**n8n / Zapier / Make:** use the Apify connector, pick this actor, map `mode`, `status` and `maxResults`, then route the dataset into your sheet, database or webhook.

### 📊 Pricing

**Pay per result (PPE).** You are billed only for delivered records, never for errors or empty runs.

| Event | Price |
|---|---|
| `market` (one prediction market row) | $0.002 |
| `event` (a grouped event with its child markets) | $0.004 |

A 100-market pull costs about $0.20. An event row carries up to a hundred-plus child markets, so a handful of events delivers thousands of price points for a few cents. There is no monthly rental and no minimum.

### ❓ FAQ

#### Do I need an API key, a login or a wallet to scrape Polymarket?

No. You supply nothing: pick a mode and run. There is no API key to obtain, no account to connect and no crypto wallet needed. The actor reads Polymarket's public gamma API directly through Apify's free datacenter proxy.

#### What does a market row contain?

The market question, each outcome with its price and implied probability, the best bid and ask, last trade price and spread, traded volume over total / 24-hour / 1-week / 1-month windows, current liquidity, the one-week price change, the open and resolution dates, active/closed flags, and the public Polymarket URL. Every row is timestamped with `scrapedAt`.

#### Is the outcome price the same as the probability?

Yes. On Polymarket a share pays out $1 if the outcome happens, so its price sits between 0 and 1 and equals the market's implied probability. A "Yes" price of 0.175 means the market implies a 17.5% chance. We expose this as both `price` and `impliedProbability` so you can use whichever reads clearer in your pipeline.

#### How are markets, events and search different?

`markets` returns individual prediction markets, one per row, with full pricing. `events` returns grouped events — a single question family such as "2028 Democratic Nominee" that holds many candidate markets — with open interest, total volume and the child markets nested inside the row. `search` takes a free-text query and returns the matching events (with their markets), which is the fastest way to find everything about a topic.

#### How do I get all markets in one category, like crypto or politics?

Set `tag` to the category's slug (`crypto`, `politics`, `sports`, `elections`, and so on) in `markets` or `events` mode. The actor resolves the slug to Polymarket's tag id and returns only markets carrying that tag. If you pass a slug Polymarket doesn't recognise, the run ends with a clear message instead of silently returning unrelated markets.

#### Can I get closed or resolved markets, not just open ones?

Yes. Set `status` to `closed` for resolved markets or `all` for both. This is useful for backtesting: pull resolved markets to see how final prices tracked the actual outcome.

#### How current is the data?

Every run reads the gamma API live, so prices, volume, liquidity and open interest reflect the market at run time. Polymarket prices move continuously while a market is open, so a run is a snapshot — schedule the actor (hourly, daily) to build a time series.

#### How many child markets does an event row include?

All of them. A large event can hold a hundred or more candidate markets; the event row nests each one with its question, outcomes and prices, so a single event row can carry thousands of data points. Use `events` mode when you want the whole race in one row, and `markets` mode when you want each market as its own row.

#### Can I sort by what matters to me?

Yes. `order` sorts results highest-first by `volume`, 24-hour `volume24hr`, `liquidity`, `openInterest` (events) or `newest`. Combine it with `maxResults` to take, say, the 50 most liquid active markets.

#### Can I export to CSV, Excel or JSON?

Yes. Download the dataset as JSON, CSV or Excel from the Apify console, or pull it straight from the Apify API or the dataset's `.json` endpoint for a pipeline or an AI agent.

#### How is this different from a generic odds scraper?

A generic odds scraper gives you a single line per event. This actor gives you the full market microstructure: every outcome's price and implied probability, the order-book top (bid/ask), spread, multi-window volume, liquidity and open interest — the depth a trading or research workflow needs, plus the grouped-event view that keeps a whole race together.

### 🐛 Troubleshooting

- **Unknown tag** — the run ends with a message naming the problem; use a valid Polymarket slug such as `politics`, `crypto`, `sports` or `elections`.
- **Empty result in search mode** — `search` needs a non-empty `search` query; try a broader term.
- **Fewer rows than `maxResults`** — `maxResults` is a cap, not a target; a filter returns what the source currently has.
- **A nested market shows outcomes without a price** — some grouped-event responses omit per-child prices; use `markets` mode for the full priced row.

### ⚠️ Trademark

Independent, third-party tool. Not affiliated with, endorsed by or connected to Polymarket or any related entity. All marks belong to their owners and are used for identification only.

### ⚖️ Is it legal to scrape this data?

This actor reads publicly available, non-personal market data (questions, prices, volume and liquidity) that Polymarket already publishes for public viewing. It collects no private or personal data and requires no login. You are responsible for using the output in line with applicable laws and the terms of the sites you rely on. When in doubt, consult a lawyer.

### 🤝 Support & contact

- 🌐 **Website:** [data.foxlabs.com.tr](https://data.foxlabs.com.tr)
- 📧 **Email:** info@foxlabs.com.tr
- 🧰 **More clean data actors:** [Fox Labs on Apify](https://apify.com/foxlabs)

### Changelog

#### 0.1 — 2026-11-02

- Initial release: markets, events and search modes from Polymarket's keyless gamma API, with implied probability, order-book top, spread, multi-window volume, liquidity and open interest.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/polymarket-prediction-markets/changelog.md

# Actor input Schema

## `mode` (type: `string`):

markets = one row per prediction market (price, implied probability, bid/ask, volume); events = grouped events with their child markets and open interest; search = free-text search over events.

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

active = currently tradable (open) markets; closed = resolved/closed; all = both.

## `order` (type: `string`):

Order results, highest first. Applies to markets and events modes.

## `tag` (type: `string`):

Filter by a Polymarket tag slug, e.g. politics, crypto, sports, elections. Leave empty for all. Applies to markets and events modes.

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

Free-text query for search mode, e.g. "election", "bitcoin", "super bowl". Ignored in markets/events modes.

## `maxResults` (type: `integer`):

Cap on delivered rows (0 = 100).

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

Leave it on. Polymarket's API geo-blocks some IPs, so the Actor reaches it through Apify's free datacenter proxy; no setup is needed. You may switch to residential or your own proxy if you prefer.

## Actor input object example

```json
{
  "mode": "markets",
  "status": "active",
  "order": "volume",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `report` (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 = {
    "mode": "markets",
    "status": "active",
    "order": "volume",
    "maxResults": 100,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

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

# Prepare the Actor input
run_input = {
    "mode": "markets",
    "status": "active",
    "order": "volume",
    "maxResults": 100,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/polymarket-prediction-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 '{
  "mode": "markets",
  "status": "active",
  "order": "volume",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call foxlabs/polymarket-prediction-markets --silent --output-dataset

```

## MCP server setup

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