# Polymarket Markets & Odds Scraper (`grit-77/polymarket-markets-odds-scraper`) Actor

Polymarket markets scraper for prediction-market research. Export market questions, outcomes, prices, volume and liquidity as JSON, with optional order books, price history and recent trades.

- **URL**: https://apify.com/grit-77/polymarket-markets-odds-scraper.md
- **Developed by:** [Grit](https://apify.com/grit-77) (community)
- **Categories:** AI, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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 & Odds Scraper

Polymarket scraper returns public market questions, outcomes, prices, volume, and liquidity. Polymarket API queries can also return order books, price history, and recent trades when requested.

### Input example

```json
{
  "searchQueries": [
    "bitcoin"
  ],
  "maxItems": 20
}
```

The input keys and allowed values follow [input_schema.json](.actor/input_schema.json).

### Output fields

| Field | Type | Example or excerpt from sample |
|---|---|---|
| `record_type` | string | `"market"` |
| `market_id` | string | `"601819"` |
| `condition_id` | string | `"0xdf8e2dc5860027decbe6164555c3c1c9645c3bd33e16b9dc57ca87125047d4a8"` |
| `slug` | string | `"will-luiz-incio-lula-da-silva-win-the-2026-brazilian-presidential-election"` |
| `url` | string | `"https://polymarket.com/event/brazil-presidential-election/will-luiz-incio-lula-da-si…` |
| `question` | string | `"Will Luiz Inácio Lula da Silva win the 2026 Brazilian presidential election?"` |
| `group_item_title` | string | `"Luiz Inácio Lula da Silva"` |
| `event_id` | string | `"45915"` |
| `event_slug` | string | `"brazil-presidential-election"` |
| `event_title` | string | `"Brazil Presidential Election"` |
| `tags` | array | `["Politics", "Macro Election 2", "Main Election", "Global Elections", "Brazil", "Worl…` |
| `description` | string | `"A presidential election is scheduled to take place in Brazil on October 4, 2026.\n\n…` |
| `resolution_source` | string or null | `null` |
| `outcomes` | array | `["Yes", "No"]` |
| `outcome_prices` | array | `[0.165, 0.835]` |
| `token_ids` | array | `["30630994248667897740988010928640156931882346081873066002335460180076741328029", "79…` |
| `yes_probability` | number | `0.165` |
| `no_probability` | number | `0.835` |
| `last_trade_price` | number | `0.17` |
| `best_bid` | number | `0.16` |
| `best_ask` | number | `0.17` |
| `spread` | number | `0.01` |
| `price_change_1h` | number or null | `-0.01` |
| `price_change_1d` | number | `-0.2` |
| `price_change_1w` | number | `-0.26` |
| `volume_total_usd` | number | `16965396.630232994` |
| `volume_24h_usd` | number | `2247216.9937190013` |
| `volume_1w_usd` | number | `4542325.957223994` |
| `liquidity_usd` | number | `895451.8545` |
| `start_date` | string | `"2025-09-18T20:07:59Z"` |
| `end_date` | string | `"2026-10-05T03:59:00Z"` |
| `created_at` | string | `"2025-09-17T18:40:08Z"` |
| `updated_at` | string | `"2026-10-05T10:57:06Z"` |
| `closed_at` | string or null | `null` |
| `active` | boolean | `true` |
| `closed` | boolean | `false` |
| `accepting_orders` | boolean | `true` |
| `resolution_status` | string or null | `null` |
| `resolved` | boolean | `false` |
| `winning_outcome` | string or null | `null` |
| `neg_risk` | boolean | `true` |
| `tick_size` | number | `0.01` |
| `min_order_size` | number | `5.0` |
| `image` | string | `"https://polymarket-upload.s3.us-east-2.amazonaws.com/will-luiz-incio-lula-da-silva-w…` |
| `order_book` | array | `[{"outcome": "Yes", "token_id": "3063099424866789774098801092864015693188234608187306…` |
| `source` | string | `"detail"` |
| `query` | string or null | `null` |
| `scraped_at` | string | `"2026-10-05T11:02:18Z"` |
| `outcome` | string | `"Yes"` |
| `token_id` | string | `"12403602920039269077597917340921667997547115084613238528792639013246536343316"` |
| `timestamp` | string | `"2026-10-04T12:00:28Z"` |
| `price` | number | `0.9595` |
| `side` | string | `"BUY"` |
| `size` | number | `5.68` |
| `usd_value` | number | `5.4528` |
| `transaction_hash` | string | `"0x0fb03f4acb1095187270f5f12d962fdabcf5e265dceb7b2f337890daf3c80530"` |

### Output example

Trimmed from [sample_output.json](sample_output.json); omitted fields remain available in the dataset.

```json
{
  "record_type": "market",
  "market_id": "601819",
  "condition_id": "0xdf8e2dc5860027decbe6164555c3c1c9645c3bd33e16b9dc57ca87125047d4a8",
  "slug": "will-luiz-incio-lula-da-silva-win-the-2026-brazilian-presidential-election",
  "url": "https://polymarket.com/event/brazil-presidential-election/will-luiz-incio-lula-da-silva-win-the-2026-brazilian-presidential-election",
  "question": "Will Luiz Inácio Lula da Silva win the 2026 Brazilian presidential election?",
  "group_item_title": "Luiz Inácio Lula da Silva"
}
```

### Limits

- Data is whatever Polymarket's public APIs return at run time; prices move constantly. `scraped_at` marks the fetch.
- `best_bid`, `best_ask`, `spread` come from Polymarket's market data and describe the first outcome (usually Yes). Use "Include order book" for both outcomes.
- Keyword search returns Polymarket's relevance order; `sortBy` applies to category and browse modes. With several keywords and a small `maxItems`, whichever keyword is read first can fill the cap.
- Price history for a very long window with a very fine resolution can come back thin or be rejected by Polymarket; use `historyFidelity` 1440 with `max`.
- Trades are the most recent ones the public data API serves; it is not a full archive.
- Polymarket rate-limits heavy callers; the actor retries with backoff on 429/5xx. Keep `maxConcurrency` low for very large runs.
- Not for trading. No orders, wallets or keys are used. This is not financial advice.

### FAQ

**What are the output limits?** `maxItems` caps emitted rows; history and trades can consume that cap. Public trade history is not a complete archive.

**Do I need a proxy or login?** Public read endpoints need no login, wallet, or proxy.

**How is this priced?** Proposed pay per event: $0.0012 per `market` row, $0.008 per block of 100 `history-point` rows per outcome series, and $0.0005 per `trade` row. Error rows are uncharged. These are proposals in [PRICING.md](PRICING.md); the owner must configure Store billing.

**How are rate limits handled?** The client limits work with `maxConcurrency` and backs off on HTTP 429 and server errors.

**How fresh is the data?** Market prices and availability can change between requests. `scraped_at` marks collection time. These are public market data, not trading instructions or financial advice.

### Use with AI agents / MCP

After the actor is published, connect your agent to the [Apify MCP server](https://docs.apify.com/integrations/mcp) with an Apify API token. Use `call-actor` with the published actor identifier and the JSON input shown above. Read the returned dataset with `get-dataset-items`; the run response itself contains status and storage IDs, not the result rows. Alternatively, use the [Apify API](https://docs.apify.com/api/v2) to start a run and read its default dataset. Keep the actor input bounded with `maxItems`, and inspect source links and any error fields before using results in an answer.

# Actor input Schema

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

Find markets by keyword, for example `bitcoin`, `fed rate`, `world cup`. Each keyword is a separate search; results are in Polymarket's relevance order.

## `markets` (type: `array`):

Polymarket URLs (`https://polymarket.com/event/<event>/<market>` or an event URL for all its markets), market slugs, market ids, or condition ids (`0x` + 64 hex characters). Filters below are not applied to markets you name here.

## `tags` (type: `array`):

Browse markets by Polymarket category slug, for example `politics`, `crypto`, `sports`, `economy`, `geopolitics`. Sorted by the sort option below.

## `browseAll` (type: `boolean`):

List markets across all categories, sorted by the sort option below (no keyword needed).

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

Open (tradable) markets, resolved/closed markets, or both.

## `minVolume` (type: `number`):

Keep markets with at least this much lifetime trading volume. 0 = no minimum.

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

Keep markets with at least this much volume in the last 24 hours. 0 = no minimum.

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

Keep markets with at least this much order-book liquidity. 0 = no minimum.

## `endDateFrom` (type: `string`):

Only markets whose end date is on or after this date, format YYYY-MM-DD.

## `endDateTo` (type: `string`):

Only markets whose end date is on or before this date (end of day, UTC), format YYYY-MM-DD.

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

Order for category and browse results. Keyword searches always keep Polymarket's relevance order.

## `sortAscending` (type: `boolean`):

Sort lowest first (for example soonest end date first).

## `includeOrderBook` (type: `boolean`):

Add live bids and asks for every outcome to each market row (one extra request per outcome). No extra charge.

## `orderBookDepth` (type: `integer`):

Price levels kept per side when the order book is included.

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

Also return the price history of every outcome as separate `history-point` rows (billed per 100 points).

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

How far back the price history goes: last hour, 6 hours, day, week, month, or the whole life of the market.

## `historyFidelity` (type: `integer`):

Minutes between price points: 60 = hourly, 1440 = daily. Very small values over long windows can be rejected or come back thin; use 1440 with `max`.

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

Also return the most recent trades of every market as separate `trade` rows (billed per trade).

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

Most recent trades returned for each market.

## `includeTraderIds` (type: `boolean`):

Trades are anonymous by default. Tick to add the public wallet address and pseudonym Polymarket shows for each trade.

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

Stop after this many market rows in total (you are billed per market). History points and trades are capped separately by the options above.

## `maxConcurrency` (type: `integer`):

How many API requests run at the same time. Keep low; Polymarket rate-limits heavy callers.

## Actor input object example

```json
{
  "searchQueries": [
    "bitcoin"
  ],
  "browseAll": false,
  "status": "active",
  "minVolume": 0,
  "minVolume24h": 0,
  "minLiquidity": 0,
  "sortBy": "volume24hr",
  "sortAscending": false,
  "includeOrderBook": false,
  "orderBookDepth": 5,
  "includePriceHistory": false,
  "historyInterval": "1w",
  "historyFidelity": 60,
  "includeTrades": false,
  "maxTradesPerMarket": 50,
  "includeTraderIds": false,
  "maxItems": 100,
  "maxConcurrency": 5
}
```

# Actor output Schema

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

Dataset with all result rows

# 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": [
        "bitcoin"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("grit-77/polymarket-markets-odds-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": ["bitcoin"] }

# Run the Actor and wait for it to finish
run = client.actor("grit-77/polymarket-markets-odds-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": [
    "bitcoin"
  ]
}' |
apify call grit-77/polymarket-markets-odds-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,grit-77/polymarket-markets-odds-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/9EXhPXYrtm8jGTenZ/builds/ZFjHQOxbSfZNcDE70/openapi.json