# Polymarket Whale Tracker & Market Data (`apimie/polymarket-whales-tracker`) Actor

Track Polymarket whales and prediction-market data: see who bets big, which markets are heating up, and where smart money is flowing. 7 actions — top whales by volume, wallet positions & history, market lists and snapshots. Free, no setup; add a personal key for deeper, fresher data.

- **URL**: https://apify.com/apimie/polymarket-whales-tracker.md
- **Developed by:** [Apimie Apimie](https://apify.com/apimie) (community)
- **Categories:** Developer tools, Automation, Other
- **Features:** Limited permissions
- **Stats:** 50 total users, 0 monthly users, 82.1% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## 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 Market Data & Whale Tracker

> Live Polymarket prediction-market data — active markets with prices/volumes, full price history, and whale-wallet tracking. **How fresh your data is depends on your plan:** Free 6h · Pro 2h · Trader 15min.

### What this actor does

Queries a production PostgreSQL database populated automatically from Polymarket's CLOB data API. It identifies "whale" wallets (traders with large positions), tracks their open bets, and exposes full market price history.

**Use cases:**

- **Copy trading**: follow the biggest wallets before they move the price
- **Anomaly detection**: spot when whale concentration spikes before a resolution event
- **Market research**: download full price history for any market for backtesting
- **Portfolio analysis**: audit any wallet's complete Polymarket position book

***

### Access tiers & API key

This actor talks to a tiered API. Pass your key in the **`apiKey`** input. Without a key you run as **anonymous**.

| Tier | How | Calls/day | Data freshness | What you get |
|---|---|---|---|---|
| **Anonymous** | no key | 10 / IP | 6h | Free-level data, public actions only |
| **Free** | free key | 50 | 6h | Top 10 whales, market data, position **summaries**, 7-day whale history |
| **Pro** | paid key | 200 | 2h | Top 50 whales **+ win rate & bot flags**, **full** positions, **`market_whales`**, full history |
| **Trader** | trader key | 500 | 15min | Everything Pro has, refreshed every 15 minutes |

Notes:

- **`market_whales` requires a Pro or Trader key.** Free/anonymous calls to it return a 403 with an upgrade hint (the actor reports this as a non-fatal `locked` record, it does not fail the run).
- **Daily call limit (rate limiting).** Each tier has a daily call quota (see the table above), counted per key — or per IP for anonymous runs. The quota **resets at midnight UTC**. When you exceed it the run does **not** fail: the actor emits a single non-fatal record describing the limit, so you can detect it programmatically and show an upgrade prompt:

  ```json
  {
    "rate_limited": true,
    "message": "Daily limit of 200 calls reached (paid tier). Resets at midnight UTC.",
    "calls_today": 200,
    "limit": 200,
    "tier": "paid",
    "upgrade_url": "https://apimie.com/pricing"
  }
  ```

  The same fields are also written to the run's `OUTPUT` (`meta.rate_limited = true`). To raise your quota, use a higher-tier key or wait for the UTC reset.
- Several actions return **more fields and rows** on Pro/Trader (see the per-action notes below). The examples show the richest (Pro) shape.
- The dedicated 15-minute Trader endpoints are not exposed through this actor; a Trader key still raises your daily quota and unlocks all field-level data on the standard actions.
- Get a key at **https://apimie.com/pricing**.

***

### Actions

#### `list_markets` *(default)* — all tiers

Returns active Polymarket markets sorted by volume, with live prices, bid/ask spread, and AI-generated category tags.

**Inputs:**

| Field | Type | Default | Description |
|---|---|---|---|
| `limit` | number | 100 | Max records to return |
| `isActive` | boolean | true | Filter to only open (unresolved) markets |
| `minVolume` | number | — | Minimum total USDC volume |
| `category` | string | — | Macro category filter: `crypto`, `politics`, `sports`, `pop_culture`, `science_tech`, `economy`, `geopolitics`, `entertainment`, `other` |
| `subCategory` | string | — | Partial-match sub-category filter (e.g. `bitcoin`) |

**Example output record:**

```json
{
  "id": "553861",
  "question": "Will the Indiana Pacers win the 2026 NBA Finals?",
  "event_title": "2026 NBA Champion",
  "macro_category": "sports",
  "sub_category": "NBA",
  "last_trade_price": 0.12,
  "best_bid": 0.11,
  "best_ask": 0.13,
  "spread": 0.02,
  "volume_total": 182400.00,
  "volume_24h": 3200.00,
  "price_change_24h": -0.01,
  "is_active": true,
  "end_date": "2026-06-30T00:00:00.000Z"
}
```

***

#### `market_detail` — all tiers

Full metadata and latest snapshot for a single market.

**Inputs:**

| Field | Type | Required | Description |
|---|---|---|---|
| `marketId` | string | ✅ | Numeric market ID (find with `list_markets`) |

**Example output:**

```json
{
  "id": "553861",
  "condition_id": "0xe492ad9...",
  "question": "Will the Indiana Pacers win the 2026 NBA Finals?",
  "description": "Resolves Yes if the Pacers win the 2026 NBA Finals...",
  "outcomes": ["Yes", "No"],
  "is_binary": true,
  "macro_category": "sports",
  "last_trade_price": 0.12,
  "volume_total": 182400.00,
  "is_active": true,
  "end_date": "2026-06-30T00:00:00.000Z"
}
```

***

#### `market_history` — all tiers

Full price time series for a single market (one record per collection run).

**Inputs:**

| Field | Type | Required | Description |
|---|---|---|---|
| `marketId` | string | ✅ | Numeric market ID |
| `from` | string | — | ISO 8601 start date filter |
| `to` | string | — | ISO 8601 end date filter |
| `limit` | number | — | Max records |

**Example output record:**

```json
{
  "captured_at": "2026-03-10T12:00:00.000Z",
  "last_trade_price": 0.14,
  "best_bid": 0.13,
  "best_ask": 0.15,
  "volume_24h": 2800.00,
  "is_active": true
}
```

***

#### `whale_list` — all tiers *(richer on Pro/Trader)*

Returns whale wallets ranked by total trading volume.

- **Free / anonymous:** top **10** wallets; core volume fields only.
- **Pro / Trader:** top **50** wallets **plus `win_rate`, `wins`, `losses` and `is_likely_bot`**.

**Inputs:**

| Field | Type | Default | Description |
|---|---|---|---|
| `limit` | number | 50 | Max wallets (capped at 10 on Free/anonymous) |

**Example output record (Pro):**

```json
{
  "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
  "total_volume_usdc": 149850.00,
  "total_trades": 312,
  "buy_volume_usdc": 92400.00,
  "sell_volume_usdc": 57450.00,
  "win_rate": 0.64,
  "wins": 41,
  "losses": 23,
  "is_likely_bot": false,
  "last_movement_at": "2026-03-13T18:22:00.000Z"
}
```

On Free/anonymous, `win_rate`, `wins`, `losses` and `is_likely_bot` are omitted, and the response carries a `meta` block describing what Pro unlocks.

***

#### `whale_positions` — all tiers *(summary on Free, full on Pro/Trader)*

Open net positions for a specific whale wallet.

- **Free / anonymous:** a **summary** only (counts and total exposure), not the individual positions.
- **Pro / Trader:** the **full per-position breakdown**.

**Inputs:**

| Field | Type | Required | Description |
|---|---|---|---|
| `walletAddress` | string | ✅ | Proxy wallet address (0x…) |

**Example output record (Pro — full detail):**

```json
{
  "proxy_wallet": "0x204f72...",
  "condition_id": "0x9e145f...",
  "outcome_name": "Yes",
  "net_size_usdc": 3200.50,
  "avg_entry_price": 0.34,
  "last_trade_at": "2026-03-10T14:30:00.000Z",
  "question": "Will ETH close above $3000 on Apr 1?"
}
```

**Example output (Free — summary):**

```json
{
  "total_positions": 565,
  "open_markets_count": 312,
  "total_exposure_usdc": 1840200.00,
  "open_exposure_usdc": 990400.00,
  "last_trade_at": "2026-03-10T14:30:00.000Z"
}
```

***

#### `whale_history` — all tiers *(7-day window on Free)*

Daily trade timeline for a whale wallet.

- **Free / anonymous:** limited to the **last 7 days**.
- **Pro / Trader:** up to the requested `days` (max 365).

**Inputs:**

| Field | Type | Default | Description |
|---|---|---|---|
| `walletAddress` | string | ✅ | Proxy wallet address |
| `days` | number | 30 | Lookback window in days (clamped to 7 on Free/anonymous; max 365 on Pro/Trader) |

**Example output record:**

```json
{
  "trade_date": "2026-03-10T00:00:00.000Z",
  "trade_count": 12,
  "buy_volume_usdc": 45200.00,
  "sell_volume_usdc": 12800.00,
  "net_flow_usdc": 32400.00
}
```

***

#### `market_whales` — **Pro / Trader only**

All whale positions concentrated in one market. Useful for detecting one-sided concentration before resolution.

> Requires a **Pro or Trader** key. With a Free/anonymous key the actor emits a single non-fatal record `{ "locked": true, "required_tier": "pro", "message": "..." }` instead of market data.

**Inputs:**

| Field | Type | Required | Description |
|---|---|---|---|
| `marketId` | string | ✅ | Numeric market ID |

**Example output record (Pro):**

```json
{
  "proxy_wallet": "0xead152...",
  "outcome_name": "Yes",
  "net_size_usdc": 54098.00,
  "avg_entry_price": 0.53,
  "market_title": "Will ETH close above $3000 on Apr 1?"
}
```

***

### Input schema reference

| Parameter | Type | Default | Description |
|---|---|---|---|
| `action` | string | `list_markets` | Action to perform (see above) |
| `marketId` | string | — | Numeric market ID for market_detail, market_history, market_whales |
| `walletAddress` | string | — | Wallet address for whale_positions, whale_history |
| `limit` | number | — | Max records to return |
| `isActive` | boolean | `true` | Active markets only filter (list_markets) |
| `minVolume` | number | — | Minimum USDC volume filter (list_markets) |
| `category` | string | — | Macro category filter (list_markets) |
| `subCategory` | string | — | Sub-category partial match (list_markets) |
| `from` | string | — | ISO 8601 start date filter (market_history) |
| `to` | string | — | ISO 8601 end date filter (market_history) |
| `days` | number | `30` | Lookback days (whale_history) |
| `apiKey` | string | — | Your API key. Omit to run anonymously (10 calls/day, Free-level data). A Free key raises the limit to 50; a Pro/Trader key unlocks richer fields, full positions, `market_whales`, and fresher data. Get one at https://apimie.com/pricing |

***

### Architecture

```
Polymarket CLOB API (data-api.polymarket.com)
         │ collected on a schedule (automated)
         ▼
    n8n Automation Workflows
    ├── Market Data Collector  → pm_markets, pm_market_snapshots
    ├── Whale Identifier       → pm_raw_trades, pm_whale_wallets,
    │                            pm_whale_active_positions
    └── Tier-aware API endpoints (behind the apimie middleware)
         │
         ▼
    PostgreSQL Database
         │
         ▼
    apimie middleware (auth, tiering & rate limits)
         │
         ▼ (this actor)
    Apify Dataset
```

The backend endpoint URL is stored as a server-side environment variable (`API_BASE_URL`) and is **never exposed** in actor code, logs, or user-facing configuration. All authentication, tiering, and rate limiting are enforced by the apimie middleware — users interact only with this actor's public interface.

***

### Tech stack

| Component | Technology |
|---|---|
| Workflow automation | n8n (self-hosted) |
| Database | PostgreSQL |
| Data collection | Polymarket CLOB API |
| AI categorization | Mistral / DeepSeek |
| Actor | Apify SDK v3 (Node.js 18, ESM) |

***

### FAQ

#### Is there a Polymarket API?

Yes. This actor is a hosted Polymarket API — you call it and get JSON back, no scraping or browser automation. The data comes from Polymarket's official CLOB and Gamma APIs, collected on a schedule into a database.

#### What Polymarket data can I get?

Active markets with live prices, bid/ask spread and volume; the full price-history time series per market; and whale wallets ranked by traded volume, with their open positions and daily trade history.

#### Is it free?

Yes — 50 calls/day on a free key, or 10/day anonymously with no signup, on 6-hour-old data. The Pro and Trader tiers cut freshness to ~2h and ~15min and unlock fuller data.

#### Do I need an API key?

No. Run it anonymously to start. Add a free or paid key for higher daily limits and fresher, richer data.

#### What can I build with it?

Copy-trading signals (follow the biggest wallets before they move a market), whale-concentration anomaly detection, and prediction-market backtesting from the full price history.

#### What format is the output?

JSON, pushed to an Apify dataset you can export as JSON / CSV / Excel or pull through the Apify API.

***

### License

Apache 2.0

# Actor input Schema

## `action` (type: `string`):

Which data to fetch. Start with list_markets to discover market IDs and whale_list to discover wallet addresses.

## `marketId` (type: `string`):

Numeric market ID (e.g. '553861'). Required for market_detail, market_history, and market_whales. Run list_markets first to find IDs.

## `walletAddress` (type: `string`):

Polymarket proxy wallet address (0x…). Required for whale_positions and whale_history. Run whale_list first to find addresses.

## `isActive` (type: `boolean`):

For list_markets: when enabled, only returns markets that are currently open and unresolved.

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

For list_markets: exclude markets with total traded volume below this threshold.

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

For list_markets: filter results to one macro category.

## `subCategory` (type: `string`):

For list_markets: partial-match filter on sub-category (e.g. 'bitcoin', 'NBA'). Case-insensitive.

## `from` (type: `string`):

For market_history: return snapshots captured on or after this date.

## `to` (type: `string`):

For market_history: return snapshots captured on or before this date.

## `days` (type: `integer`):

For whale_history: number of days to look back from today.

## `limit` (type: `integer`):

Maximum number of records to return. Applies to list_markets (default 100) and whale_list (default 50).

## `apiKey` (type: `string`):

Optional. Provide an API key to access higher rate limits and priority data freshness.

## Actor input object example

```json
{
  "action": "list_markets",
  "marketId": "553861",
  "walletAddress": "0x204f72f35326db932158cba6adff0b9a1da95e14",
  "isActive": true,
  "minVolume": 50000,
  "subCategory": "bitcoin",
  "from": "2026-01-01",
  "to": "2026-03-01",
  "days": 30,
  "limit": 50
}
```

# Actor output Schema

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

Market data records pushed to the dataset.

## `summary` (type: `string`):

Run metadata (action, record count, timestamp) stored under the OUTPUT key.

# 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("apimie/polymarket-whales-tracker").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("apimie/polymarket-whales-tracker").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 '{}' |
apify call apimie/polymarket-whales-tracker --silent --output-dataset

```

## MCP server setup

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

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/N5u8wVgS1bKzibZdf/builds/CUYigLwZVAUduFFs2/openapi.json