Polymarket Whale Tracker & Public Market Intelligence

Research public Polymarket markets, wallets, holders, trades, and orderbooks without maintaining separate Gamma + Data + CLOB APIs. This Actor calls public APIs directly; it is not a browser scraper.

Use it for:

• market researchers comparing active markets and public wallet exposure;
• operators running scheduled large-trade checks;
• data teams feeding structured Dataset items into dashboards or warehouses;
• AI-agent builders using Apify API or MCP workflows.

Informational public-data research only. It does not provide financial advice, trading recommendations, guaranteed alpha, predictions, trade execution, streaming alerts, or push notifications.

Choose your workflow

Mode	Customer job	Required target	Dataset shape	PPE plan
bulk_scan	Scan a bounded set of active markets by category	None; use category and maxMarkets to narrow the scan	Non-ML: flat market rows; eligible statistical ML: one { markets, mlInsights } object	One $1.50 bulk_scan event only when eligible output exists
market_analysis	Deep-dive markets under one or more known event slugs	eventSlugs	One persisted Dataset item and one $0.15 charge per successfully analyzed market	$0.15 market_analysis per persisted market item
alert_check	Poll known condition IDs for trades above a threshold	marketConditionIds	One persisted condition summary per successfully checked unique condition ID, including zero-trade summaries	One $0.05 alert_check event per check, whatever the number of checked condition IDs
whale_profile	Profile known public wallet addresses	walletAddresses	One profile item per successfully processed wallet	$0.25 whale_profile per persisted wallet profile
whale_discovery	Discover candidate wallets across a bounded market set	None; use scan and qualification filters	One aggregate object containing whales, hotMarkets, and metadata	One $1.50 bulk_scan event only when eligible output exists

Target arrays are trimmed and de-duplicated before work starts. market_analysis, alert_check, and whale_profile reject an omitted required target field. Empty target arrays produce zero Dataset items and no mode-specific PPE charge. Malformed non-empty slugs, condition IDs, or wallet addresses are rejected before API work.

market_analysis resolves every supplied event slug to its current markets. One slug can therefore emit and charge for more than one selected market. Each metadata.eventSlug is copied from the Gamma response's event.slug, not inferred from market position or query order.

5-minute quickstart

This is the only copy-paste first run. It is intentionally bounded and does not request orderbook work because includeOrderbook affects market_analysis only.

{
  "mode": "bulk_scan",
  "category": "politics",
  "maxMarkets": 5,
  "whaleThreshold": 50000,
  "includeTradeFlow": true,
  "enableMlAnalysis": false
}

1. Open the Actor Input tab.
2. Paste the JSON and run it.
3. Read the Dataset items, then use an item’s eventSlug for market_analysis or conditionId for alert_check.

A normal item can include question, slug, eventSlug, conditionId, category, currentPrice, volume24hr, healthScore, topHolderCount, tradeFlow, and metadata. The Actor requests and analyzes at most topHoldersCount holders per market (5–20); topHolderCount reports holders that met whaleThreshold, not every returned holder.

A valid run can still return zero items when the current source has no matching category/market data or every candidate fails closed. whale_discovery may instead persist one aggregate object with empty whales/hotMarkets while planning no mode-specific PPE charge. Zero eligible output does not plan the mode-specific PPE charge.

Replace-before-run recipes

The following inputs are schema-valid templates, not live targets. Replace the marked slug, condition ID, or wallet before running.

Deep-dive an event

Replace replace-with-current-event-slug with a current slug from a Polymarket event URL or prior Actor output.

{
  "mode": "market_analysis",
  "eventSlugs": ["replace-with-current-event-slug"],
  "topHoldersCount": 20,
  "includeOrderbook": true,
  "includeTradeFlow": true,
  "enableMlAnalysis": false
}

Poll a condition ID

Replace the all-zero condition ID with a current 0x + 64-hex-character ID. This is scheduled polling, not streaming or push notifications.

{
  "mode": "alert_check",
  "marketConditionIds": ["0x0000000000000000000000000000000000000000000000000000000000000000"],
  "tradeAlertThreshold": 10000,
  "timeWindow": "24h"
}

Profile a wallet

Replace the all-zero wallet with a current 0x + 40-hex-character public wallet address.

{
  "mode": "whale_profile",
  "walletAddresses": ["0x0000000000000000000000000000000000000000"],
  "timeWindow": "30d",
  "enableMlAnalysis": false
}

Discover candidate wallets

{
  "mode": "whale_discovery",
  "category": "politics",
  "maxMarkets": 5,
  "whaleThreshold": 50000,
  "minWinRate": 0.5,
  "minPnl": 0,
  "maxWhales": 10,
  "enableMlAnalysis": false
}

Inputs and exact behavior

Parameter	Type	Default	Exact behavior
mode	string	bulk_scan	bulk_scan, market_analysis, alert_check, whale_profile, or whale_discovery
eventSlugs	string[]	[]	market_analysis only. The field must be present. After trimming, each value must match ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$; duplicates are removed in first-seen order. An explicit [] means zero output/no charge.
marketConditionIds	string[]	[]	alert_check only. The field must be present. Each trimmed value starts with lowercase 0x followed by exactly 64 hexadecimal characters; hex letters may be upper- or lowercase. De-duplication is case-insensitive. A successfully checked unique condition emits one persisted Dataset item, even when no trade crosses the threshold.
walletAddresses	string[]	[]	whale_profile only. The field must be present. Each trimmed value starts with lowercase 0x followed by exactly 40 hexadecimal characters; hex letters may be upper- or lowercase. De-duplication is case-insensitive. Emits one Dataset item and one charge per successfully processed and persisted wallet profile.
category	string	all	bulk_scan and whale_discovery. Values: all, politics, crypto, sports, pop-culture, business, science. Matching uses current Gamma event tags after case, whitespace, and hyphen normalization; no aliases are promised.
whaleThreshold	integer	50000	whaleThreshold is consumed only by bulk_scan and whale_discovery. It is the minimum estimated current USD holder position in the scanned market/outcome (shares × current outcome price), not total wallet portfolio value; range $1,000–$10,000,000.
tradeAlertThreshold	integer	10000	Minimum USD trade size used by alert_check and supported trade-flow paths; range $1,000–$1,000,000.
timeWindow	string	24h	1h, 6h, 24h, 7d, or 30d. timeWindow applies to market_analysis trade lookback, optional bulk_scan trade flow, alert_check polling, and whale_profile.recentActivity; whale_discovery ignores it. It does not limit active positions or all-time closed-history summaries. Future/invalid timestamps are skipped.
includeOrderbook	boolean	true	market_analysis only. Other modes ignore it.
includeTradeFlow	boolean	true	includeTradeFlow is consumed only by market_analysis and bulk_scan. It analyzes public trades over timeWindow/tradeAlertThreshold where valid trades exist; it does not add CLOB orderbooks.
topHoldersCount	integer	20	5–20. The Actor requests and analyzes at most this many holders per market.
maxMarkets	integer	5	1–50. Caps selected markets in bulk_scan and whale_discovery; it is a market cap, not an event cap.
minWinRate	number	0.5	whale_discovery qualification filter for wallets with resolved history; candidates without resolved history are exempt and assessed by active position size; range 0–1.
minPnl	number	0	whale_discovery historical P&L filter for wallets with resolved history; candidates without resolved history are exempt and assessed by active position size; range 0–10,000,000.
maxWhales	integer	10	whale_discovery output limit; range 1–50.
enableMlAnalysis	boolean	false	Enables best-effort local ML work supported by the selected mode. No external AI API key or AI-provider fee is required. Normal PPE charges and Apify platform usage still apply, local CPU work may affect platform usage, and enrichment can be absent when data/features are insufficient.
mlFeatures	object	all toggles true	ML support is mode-specific: market_analysis can use all toggles; bulk_scan uses statisticalEnhancement; alert_check uses anomalyDetection and optional report generation; whale_profile uses report generation; whale_discovery currently has no ML post-processing path. Enrichment is optional and data/time dependent.

Target formats are trust-boundary checks, not discovery shortcuts. Get slugs from Polymarket event URLs, condition IDs from current market/API data or prior Actor output, and wallets from public profile URLs or your own dataset.

Output and billing semantics

Results are written to the default Dataset. RUN_SUMMARY in the default key-value store records fetched/skipped counts, output cardinality, partial failures, zero-result reason, and planned/actual PPE counts.

• bulk_scan: non-ML output is a flat array of market rows. When enableMlAnalysis and statisticalEnhancement produce eligible enrichment, the runtime can emit one { markets, mlInsights } object instead. Neither shape emits whaleSentimentScore.
• market_analysis: flat market items. Output/PPE cardinality is the successfully analyzed and persisted market count, not the input slug count.
• alert_check: one item per successfully checked unique condition ID, including newLargeTrades: 0 when the check ran successfully but found none.
• whale_profile: one item per successfully processed wallet.
• whale_discovery: one aggregate object with whales, hotMarkets, and metadata.

Dataset persistence happens before PPE charging. If Dataset persistence fails, charging is not attempted. If summary persistence fails after Dataset output, the run suppresses charging rather than risking duplicate customer-visible output or duplicate charges.

Illustrative bulk_scan item

This is an output shape illustration, not a runnable input.

{
  "question": "Will Candidate X win the election?",
  "slug": "example-election-market",
  "eventSlug": "example-election-event",
  "conditionId": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "category": "Politics",
  "currentPrice": 0.52,
  "volume24hr": 11503957.55,
  "healthScore": 65,
  "topHolderCount": 7,
  "tradeFlow": null,
  "metadata": {
    "generatedAt": "2026-08-04T12:00:00.000Z",
    "mode": "bulk_scan"
  }
}

Cost control

This Actor uses Apify Pay Per Event pricing:

Mode	PPE event	Price
bulk_scan	bulk_scan	$1.50 per eligible scan
market_analysis	market_analysis	$0.15 per persisted market item
alert_check	alert_check	$0.05 per check, whatever the number of checked condition IDs
whale_profile	whale_profile	$0.25 per persisted wallet profile
whale_discovery	bulk_scan	$1.50 per eligible scan

Start with maxMarkets: 5, keep topHoldersCount at 20 or less, and enable orderbooks only for selected market_analysis runs. De-duplicate targets before repeated scheduled runs. Empty targets and zero eligible output do not plan the mode-specific PPE charge.

Data sources and freshness

• Gamma API: active events, markets, tags, prices, volume, liquidity, and market metadata.
• Data API: public holders, trades, positions, closed positions, and wallet activity.
• CLOB API: token orderbooks used only by market_analysis when includeOrderbook is enabled and token IDs are valid.

Each run is a snapshot of responses available during that run. metadata.generatedAt is Actor processing time, not an exchange settlement timestamp. Upstream API updates, event-tag taxonomy, late trades, and temporary source failures can change results between polls. Use Apify schedules for periodic snapshots; there is no streaming connection or push-notification channel in this Actor.

Troubleshooting

The Dataset is empty. Check that the selected mode includes its required target field, that every target has the exact format above, and that the current source still exposes matching data. Omitting a required target field fails validation; an explicit empty target array intentionally returns zero items/no charge. Category scans can also return zero when current Gamma tags do not match.

A scan returned fewer than maxMarkets. maxMarkets is a ceiling. Category filtering, invalid source records, per-market API failures, or the run deadline can reduce the eligible output count.

Trade flow is null. No valid recent trades may remain after timeWindow, or the selected mode/source path may not provide trade-flow data. timeWindow does not remove active positions or all-time closed-history summaries.

Orderbook data is missing. Confirm the mode is market_analysis, includeOrderbook is true, and the source market has valid string CLOB token IDs. Malformed token IDs fail closed instead of reaching CLOB.

A scheduled check found no large trades. A successful alert_check still emits one summary per selected condition ID with zero matching trades, and plans exactly one $0.05 check charge for the run. An empty target list emits nothing and plans no charge.

The run is partial. Inspect RUN_SUMMARY for partial failures, skipped records, time filtering, and planned/actual charge counts before retrying.

Scheduling, API, MCP, and downstream automation

• Schedules: run the same bounded alert_check input periodically. Downstream notifications must be configured through Apify integrations or your own automation.
• API: call jy-labs/polymarket-whale-tracker with the same validated JSON used in Console, then read the default Dataset.
• MCP/agents: expose the Actor through your existing Apify MCP setup and pass the same input contract; MCP does not change output or billing cardinality.
• Downstream: key market workflows by conditionId/eventSlug, wallet workflows by wallet address, and read RUN_SUMMARY before deciding whether to retry a partial run.

Python API example

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("jy-labs/polymarket-whale-tracker").call(run_input={
    "mode": "bulk_scan",
    "category": "politics",
    "maxMarkets": 5,
    "whaleThreshold": 50000,
    "enableMlAnalysis": False,
})
items = list(client.dataset(run["defaultDatasetId"]).iterate_items())
print(items)

Scheduled-check API example

Replace the condition ID before running.

curl "https://api.apify.com/v2/acts/jy-labs~polymarket-whale-tracker/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "alert_check",
    "marketConditionIds": ["0x0000000000000000000000000000000000000000000000000000000000000000"],
    "tradeAlertThreshold": 10000,
    "timeWindow": "24h"
  }'

Legal disclaimer

This Actor uses publicly available data for informational research. Computed metrics, classifications, and optional local ML output are not financial advice, trading recommendations, buy/sell signals, or guarantees. Prediction-market activity involves risk; independently verify source data and make your own decisions.