# Polymarket Real-Time Data — Live Market Intel (`b2b_leads/polymarket-real-time-data-scraper`) Actor

Live Polymarket prediction-market intelligence: market search, event details, live trade tape, wallet activity, open positions, and trader profiles. Structured JSON streams to your dataset in real time.

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

## Pricing

from $0.10 / 1,000 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/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 Real-Time Data — Live Prediction-Market Intelligence

**Live Polymarket market data for traders, researchers, and agents:** market search, full event details, live trade tape, wallet activity, open positions, and trader profiles. Structured JSON streams to your dataset row-by-row while the run is still working — results start appearing in seconds.

> ⚠️ **Free Apify plan notice:** Free-tier accounts are limited to **2 results per run**. Upgrade to any paid Apify plan for unlimited exports. This is stated here, in the Actor input form, and in the run log — it is a policy limit, not an error.

### Who this is for

- **Prediction-market traders** tracking odds moves, spreads, and fresh markets across crypto, politics, sports, and macro
- **Copy-trading and wallet-intelligence teams** scoring real traders by resolved activity, not leaderboard hype
- **Newsrooms and event researchers** monitoring live probabilities around elections, Fed decisions, and finals
- **Market makers and pricing bots** watching live tape, size, and momentum per market
- **AI agents & automations** that need structured prediction-market data via the Apify MCP server

### What you can do with it

- **Discover live markets in seconds** — search "bitcoin", "fed rate decision", "super bowl", or "election" and get questions, prices, volume, and liquidity instantly.
- **Follow the tape** — pull recent trades per market with side, size, price, outcome, and trader for flow and whale watching.
- **Score real wallets** — fetch full trade ledgers, live open positions with unrealized PnL, and public trader profiles to find specialists in weather, crypto, sports, or macro niches.
- **Track odds over time** — schedule runs and diff outcome prices, volume, and spreads for signals and alerts.
- **Pipe alerts anywhere** — every saved row can also POST to Slack, Discord, Zapier, Make, n8n, or your trading bot the moment it is saved.

### Features

| Feature | What it does | Output (`featureType`) |
|---|---|---|
| 🔍 **Market Search** | Live keyword search across prediction markets | `market_search` |
| ✨ **Full Details Enrichment** | Adds outcomes, prices, volume, liquidity, and event context **to the same search row** | `market_search` (`detailsFetched: true`) |
| 📊 **Market / Event Details** | Full record for specific markets/events by slug, condition ID, or URL; optional live book snapshot | `market_details` |
| ⚡ **Live Market Trades** | Recent tape per market — side, size, price, outcome, trader | `market_trades` |
| 👛 **Wallet Activity** | Trade-by-trade ledger per wallet — buys, sells, redeems | `wallet_activity` |
| 💼 **Wallet Open Positions** | Live exposure per wallet — entry, current value, unrealized PnL | `wallet_positions` |
| 👤 **Trader Profile** | Public identity — pseudonym, volume signals, account context | `wallet_profile` |
| 🔗 **Scrape By URL** | Direct processing of any Polymarket event, market, or profile URL | `scrape_by_url` |

**Enrichment, not filtering:** when **Enrich with full market details** is on, every search result stays **one row** and gains deep fields in place (`detailsFetched: true`). No duplicate rows, no dropped markets — every discovered item always reaches the dataset, so your run cost stays predictable. Enrichment adds a little extra time per market.

### Quick start (10 results in seconds)

The Actor comes prefilled for an instant demo run:

1. Click **Start** — no configuration needed.
2. Defaults: Market Search on, queries `bitcoin`, `fed rate decision`, `super bowl`, **10 markets per query**.
3. Watch the dataset fill row-by-row in real time.

#### Example searches that work well

| Goal | Queries | Notes |
|---|---|---|
| Crypto odds | `bitcoin`, `ethereum`, `solana` | High-volume price markets |
| Macro / Fed | `fed rate decision`, `cpi`, `recession` | Scheduled-release markets |
| Sports | `super bowl`, `nba finals`, `world cup` | Game and futures markets |
| Politics | `election`, `president`, `senate` | Long-horizon probability tracking |
| Culture / tech | `oscars`, `iphone`, `spacex` | Niche event discovery |

### Full input reference

#### 🔍 Market Search (`enableMarketSearch`, default **on**)

| Field | Type | Default | Notes |
|---|---|---|---|
| `searchQueries` | string list | 3 examples | Required when search is on. Any market topic. |
| `searchMaxResults` | integer | **10** | Max markets per query (1–100). |
| `searchIncludeClosed` | boolean | `false` | Off = live tradeable markets only. On = include closed/resolved for backtests. |
| `searchFetchFullDetails` | boolean | `false` | **Enrich with full market details** — merges outcomes, prices, volume, liquidity, and event context into the same row. |

#### 📊 Market / Event Details (`enableMarketDetails`, default off)

| Field | Type | Notes |
|---|---|---|
| `marketSlugs` | string list | e.g. `bitcoin-above-on-february-23`. |
| `conditionIds` | string list | Hex `0x...` IDs. Shared with Live Trades. |
| `marketUrls` | string list | Full `polymarket.com/event/...` or `/market/...` URLs. |
| `includeOrderBook` | boolean | Adds a best-effort live book snapshot. Unavailable for closed markets, which still return full fields. |

#### ⚡ Live Market Trades (`enableMarketTrades`, default off)

| Field | Type | Default | Notes |
|---|---|---|---|
| `conditionIds` | string list | — | Required. Hex `0x...` IDs. |
| `tradesMaxPerMarket` | integer | **30** | Max recent trades per market (1–200). |

#### 👛 Wallet Activity (`enableWalletActivity`, default off)

| Field | Type | Default | Notes |
|---|---|---|---|
| `walletAddresses` | string list | — | Required. `0x...` addresses. Shared by Activity, Positions, and Profile. |
| `activityMaxPerWallet` | integer | **50** | Max rows per wallet (1–500). |

#### 💼 Wallet Open Positions (`enableWalletPositions`, default off)

| Field | Type | Default | Notes |
|---|---|---|---|
| `walletAddresses` | string list | — | Required. Same list as Activity. |
| `positionsMaxPerWallet` | integer | **50** | Max positions per wallet (1–200). |

#### 👤 Trader Profile (`enableWalletProfile`, default off)

| Field | Type | Notes |
|---|---|---|
| `walletAddresses` | string list | Required. Same list as Activity. |

#### 🔗 Scrape By URL (`enableScrapeByUrl`, default off)

| Field | Type | Notes |
|---|---|---|
| `scrapeUrls` | string list | Any Polymarket event, market, or profile URL. Auto-detects page type. |

#### 🔔 Delivery

| Field | Type | Default | Notes |
|---|---|---|---|
| `webhookUrl` | string | — | Optional additional push per record. Dataset write always happens first. |
| `webhookFormat` | select | `json` | `json` = full record; `slack` = Slack-friendly message. |

#### 🌐 Connection

| Field | Type | Default | Notes |
|---|---|---|---|
| `proxyConfiguration` | proxy | Residential US | Residential recommended at scale. |

### Output field reference

Every row carries `featureType`, `scrapedAt`, and `url`. Filter dataset views by `featureType`.

- **market_search**: `question`, `outcomes`, `outcome_prices`, `last_trade_price`, `best_bid`, `best_ask`, `spread`, `volume`, `liquidity`, `active`, `closed`, `end_date`, `event_title`, `tags`, `position`, `detailsFetched`
- **market_details**: above + `volume_24h`, `volume_1wk`, `volume_1mo`, `accepting_orders`, `start_date`, `description`, `resolution_source`, `order_book` (when requested and available)
- **market_trades**: `condition_id`, `question`, `outcome`, `side`, `price`, `size`, `usdc_size`, `timestamp`, `trader`, `trader_pseudonym`, `transaction_hash`
- **wallet_activity**: `wallet`, `trade_type`, `side`, `question`, `outcome`, `price`, `size`, `usdc_size`, `timestamp`, `transaction_hash`
- **wallet_positions**: `wallet`, `question`, `outcome`, `avg_price`, `current_price`, `current_value`, `cash_pnl`, `percent_pnl`, `size`, `redeemable`
- **wallet_profile**: `wallet`, `pseudonym`, `display_name`, `bio`, `verified`, `taker_tier_name`, `weighted_volume`, `created_at`
- **scrape_by_url**: `pageType` + the fields of the detected type

### Webhook guide

Set `webhookUrl` to receive each saved row as it streams:

- **JSON mode**: the full record object is POSTed with `Content-Type: application/json`.
- **Slack mode**: a compact message with question, price, volume, outcome, and a link back to Polymarket.
- Delivery is fire-and-forget with a 15-second timeout. Failures are logged once and never stop the run — the dataset write always succeeds first.

### MCP / AI-agent usage

This Actor works with the Apify MCP server. Example questions your agent can answer:

- "Search Polymarket for bitcoin markets and show the top 5 by volume with current Yes prices."
- "Pull the last 50 trades for condition 0x… and summarize buy vs sell pressure."
- "Fetch wallet 0x…'s recent activity and open positions — what are they exposed to right now?"

Point the agent at this Actor, run it with the relevant inputs, then read the dataset views (`search`, `trades`, `wallet_activity`, `wallet_positions`).

### FAQ

- **Do I need to supply keys?** No. Authentication is handled on the backend — you just pick features and run.
- **Which proxy should I use?** Residential US default. Match region only if you target region-specific availability.
- **How fresh is the data?** Every run collects live at execution time; each row carries `scrapedAt` so you can diff across scheduled runs.
- **What does the free tier include?** Free Apify plans get **2 results per run** as a trial. Paid plans are uncapped up to your per-feature limits.
- **Do closed markets work?** Yes — turn on "Include closed / resolved markets" for backtests. Live book snapshots are best-effort and only available on open markets.
- **Will partial results ever be dropped?** No. Every discovered market, trade, and wallet entry is saved. Enrichment adds fields to the same row instead of creating a second one.

# Actor input Schema

## `enableMarketSearch` (type: `boolean`):

Live search across Polymarket prediction markets — crypto prices, elections, sports, Fed decisions, culture. On by default and prefilled so you can click Start and get results in seconds.

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

One or more search terms, e.g. "bitcoin", "fed rate", "super bowl". Required when Market Search is on.

## `searchMaxResults` (type: `integer`):

Maximum markets to return for each query (1–100). Default 10 — perfect for instant demo runs.

## `searchIncludeClosed` (type: `boolean`):

When off (default), only live tradeable markets are returned. Turn on for backtests and resolved-outcome research.

## `searchFetchFullDetails` (type: `boolean`):

When on, each search result stays ONE row (featureType market_search, detailsFetched=true) but is enriched with outcomes, prices, volume, liquidity, and event context. Adds a little extra time per market. When off, you get fast search cards with question, prices, and volume. Every discovered market is always saved — never filtered out.

## `enableMarketDetails` (type: `boolean`):

Full record for specific Polymarket markets or events by slug, condition ID, or URL.

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

Polymarket slugs, e.g. "bitcoin-above-on-february-23", "will-trump-win-2028".

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

Hex condition IDs (0x...) shared by Market Details and Live Trades. Live Trades may be left empty when Market Search is on — it then reuses the markets just discovered.

## `marketUrls` (type: `array`):

Full Polymarket URLs (https://polymarket.com/event/... or /market/...).

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

Adds best bid/ask depth per outcome on Market Details rows. Best-effort: unavailable for closed markets, which still return full Gamma fields.

## `enableMarketTrades` (type: `boolean`):

Recent tape per market — side, size, price, outcome, trader, timestamp. Essential for flow and whale-watch bots.

## `tradesMaxPerMarket` (type: `integer`):

Maximum recent trades to collect per market (1–200).

## `enableWalletActivity` (type: `boolean`):

Full trade history per wallet — buys, sells, redeems with size, price, and market context. Score real traders, not leaderboards.

## `walletAddresses` (type: `array`):

Ethereum wallet addresses (0x...). Shared by Wallet Activity, Open Positions, and Trader Profile.

## `activityMaxPerWallet` (type: `integer`):

Maximum activity rows to collect per wallet (1–500).

## `enableWalletPositions` (type: `boolean`):

Live open positions per wallet — current value, average entry, unrealized PnL. Uses the same walletAddresses list.

## `positionsMaxPerWallet` (type: `integer`):

Maximum open positions to collect per wallet (1–200).

## `enableWalletProfile` (type: `boolean`):

Public trader identity: pseudonym, volume, rank signals, and account context. Uses the same walletAddresses list.

## `enableScrapeByUrl` (type: `boolean`):

Paste any Polymarket URL — event, market, or trader profile page.

## `scrapeUrls` (type: `array`):

Any Polymarket event, market, or profile URL.

## `webhookUrl` (type: `string`):

Optional. Every record is always saved to the run dataset — this webhook is an ADDITIONAL real-time push. Each new row is also POSTed to this URL (Slack, Discord, Zapier, Make, n8n, custom trading bot).

## `webhookFormat` (type: `string`):

json = full record object; slack = Slack-friendly message payload.

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

Residential proxy recommended for reliable results at scale.

## Actor input object example

```json
{
  "enableMarketSearch": true,
  "searchQueries": [
    "bitcoin",
    "fed rate decision",
    "super bowl"
  ],
  "searchMaxResults": 10,
  "searchIncludeClosed": false,
  "searchFetchFullDetails": false,
  "enableMarketDetails": false,
  "marketSlugs": [],
  "conditionIds": [],
  "marketUrls": [],
  "includeOrderBook": false,
  "enableMarketTrades": false,
  "tradesMaxPerMarket": 30,
  "enableWalletActivity": false,
  "walletAddresses": [],
  "activityMaxPerWallet": 50,
  "enableWalletPositions": false,
  "positionsMaxPerWallet": 50,
  "enableWalletProfile": false,
  "enableScrapeByUrl": false,
  "scrapeUrls": [
    "https://polymarket.com/event/bitcoin-above-on-february-23"
  ],
  "webhookUrl": "",
  "webhookFormat": "json",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `allResults` (type: `string`):

Full dataset for this run (every featureType).

## `overview` (type: `string`):

Core fields across features, including detailsFetched for search rows.

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

featureType=market_search only. One market = one row; full details are merged when "Enrich with full market details" is enabled.

## `details` (type: `string`):

featureType=market_details — only from the Market Details feature (specific slugs/IDs/URLs), not from search enrichment.

## `trades` (type: `string`):

No description

## `wallet_activity` (type: `string`):

No description

## `wallet_positions` (type: `string`):

No description

## `wallet_profile` (type: `string`):

No description

## `scrape_by_url` (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 = {
    "enableMarketSearch": true,
    "searchQueries": [
        "bitcoin",
        "fed rate decision",
        "super bowl"
    ],
    "searchMaxResults": 10,
    "searchIncludeClosed": false,
    "searchFetchFullDetails": false,
    "enableMarketDetails": false,
    "marketSlugs": [],
    "conditionIds": [],
    "marketUrls": [],
    "includeOrderBook": false,
    "enableMarketTrades": false,
    "tradesMaxPerMarket": 30,
    "enableWalletActivity": false,
    "walletAddresses": [],
    "activityMaxPerWallet": 50,
    "enableWalletPositions": false,
    "positionsMaxPerWallet": 50,
    "enableWalletProfile": false,
    "enableScrapeByUrl": false,
    "scrapeUrls": [
        "https://polymarket.com/event/bitcoin-above-on-february-23"
    ],
    "webhookFormat": "json",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("b2b_leads/polymarket-real-time-data-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 = {
    "enableMarketSearch": True,
    "searchQueries": [
        "bitcoin",
        "fed rate decision",
        "super bowl",
    ],
    "searchMaxResults": 10,
    "searchIncludeClosed": False,
    "searchFetchFullDetails": False,
    "enableMarketDetails": False,
    "marketSlugs": [],
    "conditionIds": [],
    "marketUrls": [],
    "includeOrderBook": False,
    "enableMarketTrades": False,
    "tradesMaxPerMarket": 30,
    "enableWalletActivity": False,
    "walletAddresses": [],
    "activityMaxPerWallet": 50,
    "enableWalletPositions": False,
    "positionsMaxPerWallet": 50,
    "enableWalletProfile": False,
    "enableScrapeByUrl": False,
    "scrapeUrls": ["https://polymarket.com/event/bitcoin-above-on-february-23"],
    "webhookFormat": "json",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("b2b_leads/polymarket-real-time-data-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 '{
  "enableMarketSearch": true,
  "searchQueries": [
    "bitcoin",
    "fed rate decision",
    "super bowl"
  ],
  "searchMaxResults": 10,
  "searchIncludeClosed": false,
  "searchFetchFullDetails": false,
  "enableMarketDetails": false,
  "marketSlugs": [],
  "conditionIds": [],
  "marketUrls": [],
  "includeOrderBook": false,
  "enableMarketTrades": false,
  "tradesMaxPerMarket": 30,
  "enableWalletActivity": false,
  "walletAddresses": [],
  "activityMaxPerWallet": 50,
  "enableWalletPositions": false,
  "positionsMaxPerWallet": 50,
  "enableWalletProfile": false,
  "enableScrapeByUrl": false,
  "scrapeUrls": [
    "https://polymarket.com/event/bitcoin-above-on-february-23"
  ],
  "webhookFormat": "json",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call b2b_leads/polymarket-real-time-data-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,b2b_leads/polymarket-real-time-data-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/vMlCUnt6iZtuUZakx/builds/uVG9xul7MmLbzhE5Q/openapi.json