Polymarket Whale Tracker

See what the biggest traders on Polymarket are betting on right now — which markets, which side, how much — in one API call.

No wallet addresses needed. This Actor scans active markets, finds whale traders automatically, and maps out every position they hold across Polymarket.

What You Get

Run whale_discovery and you get:

1. Whale list — Top traders ranked by position size, with tier classification (Whale $1M+ / Shark $100K+ / Dolphin $10K+)
2. Position map — Every active bet each whale holds: market name, YES or NO, dollar amount
3. Hot markets — Markets where multiple whales overlap. 4 whales on the same market = strong signal.

Real output example (crypto category, March 2026):

Whale #1 — 0xde17… (Shark, $414K across 2 markets)

• "Will Bitcoin reach $80,000 in March?" → No — $268K
• "Will Bitcoin reach $85,000 in March?" → No — $118K

Whale #2 — 0x3eba… (Whale, $1.09M across 3 markets)

• Active in 83 markets, $1.19M total exposure, 85% on NO side

Hot Market — "Will Bitcoin reach $80,000 in March?" → 4 whales, $302K total

Quick Start

{
  "mode": "whale_discovery",
  "maxMarkets": 20,
  "category": "crypto",
  "maxWhales": 10
}

Scans top 20 crypto markets → finds all $50K+ holders → returns top 10 whales with full position maps + hot market overlay.

Why This Actor

	Typical Polymarket Tool	Whale Tracker
Main question	"What's the price?"	"What are whales betting on?"
Whale discovery	You need wallet addresses	Automatic
Position tracking	Single market only	Cross-market: every bet a whale holds
Hot market signals	None	Multi-whale convergence detection
Data source	Single API	3 APIs cross-referenced
ML analysis	None	Anomaly detection, clustering, NLG reports

---

Five Analysis Modes

1. Whale Discovery (whale_discovery) — Start Here

Automatically find whale traders and map their positions across all markets. No wallet addresses needed.

The Actor scans top markets, collects wallets with large positions, profiles each whale (win rate, P&L, tier), and fetches their complete active positions across all Polymarket markets. Returns a whale-centric view with a hot market overlay.

Required input: None — automatically scans top markets. Use maxMarkets to control scan scope.

Best for: Discovering which markets smart money is concentrated in, without knowing any wallet addresses upfront.

Cost: $1.50 per discovery scan (same as bulk_scan)

Example input:

{
  "mode": "whale_discovery",
  "maxMarkets": 30,
  "category": "crypto",
  "whaleThreshold": 50000,
  "minWinRate": 0.55,
  "minPnl": 1000,
  "maxWhales": 10
}

What you get:

• whales[] — Each whale's profile (tier, win rate, PnL, ROI) + full list of active positions (market, side, size, value)
• hotMarkets[] — Markets where 2+ whales hold positions simultaneously — the strongest convergence signals
• metadata — Scan statistics and applied filters

2. Market Analysis (market_analysis) — Deep Dive

After finding interesting markets through whale discovery, use this to get detailed metrics: whale breakdown, trade flow, sentiment, orderbook depth, and impact simulation.

Required input: eventSlugs — event slug from Polymarket URL (e.g., ["presidential-election-winner-2028"]).

Best for: Deep-diving into a specific market found via whale discovery.

Cost: $0.15 per market

3. Whale Profile (whale_profile) — Follow a Whale

Found an interesting whale in discovery results? Use their address to get a complete profile: all positions, P&L, win rate, ROI.

Required input: walletAddresses — whale address from discovery output (e.g., ["0xde17f7144fbd..."]).

Best for: Following up on specific whales found through whale discovery.

Cost: $0.25 per wallet

4. Bulk Scan (bulk_scan) — Market Overview

Lists top N markets by volume with health scores. Useful for data pipelines, but does not show whale positions. For whale intelligence, use whale_discovery instead.

Required input: None — scans top markets automatically.

Cost: $1.50 per scan

5. Alert Check (alert_check) — Monitor

Lightweight large trade detection for specific markets. Run on a schedule to catch whale movements after initial discovery.

Required input: marketConditionIds — condition IDs from whale discovery or market analysis output.

Best for: Ongoing monitoring of hot markets identified through whale discovery.

Cost: $0.05 per check

Typical Workflow

1. whale_discovery (category: "crypto")
   → Find 10 whales + their positions + hot markets

2. market_analysis (eventSlug from hot market)
   → Deep dive: orderbook, trade flow, sentiment

3. whale_profile (address from discovery)
   → Full history of an interesting whale

4. alert_check (conditionId from hot market, scheduled hourly)
   → Ongoing monitoring for new large trades

Whale discovery is the starting point. Other modes are follow-up tools.

---

Input Parameters

Parameter	Type	Default	Required	Description
mode	string	—	Yes	Analysis mode: whale_discovery, market_analysis, whale_profile, bulk_scan, alert_check
eventSlugs	string[]	[]	For market_analysis	Event slugs from Polymarket URL (e.g., presidential-election-winner-2028)
marketConditionIds	string[]	[]	For alert_check	Hex condition IDs for markets to monitor
walletAddresses	string[]	[]	For whale_profile	Wallet addresses to profile (e.g., 0xd04d93...)
category	string	all	No	Category filter: politics, crypto, sports, pop-culture, business, science. Used in whale_discovery and bulk_scan.
whaleThreshold	integer	50000	No	Minimum USD position to classify as whale ($1K–$10M)
tradeAlertThreshold	integer	10000	No	Minimum USD trade size to flag as "large trade" ($1K–$1M)
timeWindow	string	24h	No	Analysis lookback window: 1h, 6h, 24h, 7d, 30d. Used in market_analysis and alert_check.
includeOrderbook	boolean	true	No	Include CLOB orderbook depth and impact simulation
includeTradeFlow	boolean	true	No	Include individual trade-level flow analysis
topHoldersCount	integer	20	No	Number of top holders to analyze per market (5–100). Note: Polymarket Data API may cap results at ~20 holders regardless of this setting.
maxMarkets	integer	20	No	Number of markets to scan (1–50). Used in whale_discovery and bulk_scan.
minWinRate	number	0.5	No	Minimum win rate filter for whale_discovery (0–1). Only whales with this win rate or higher are included.
minPnl	number	0	No	Minimum cumulative P&L filter for whale_discovery (USD). Only profitable whales above this threshold are returned.
maxWhales	integer	10	No	Maximum number of whales to return in whale_discovery (1–50). Whales are ranked by P&L before truncation.
enableMlAnalysis	boolean	false	No	Enable ML-powered analysis (anomaly detection, clustering, reports)
mlFeatures	object	{}	No	Toggle individual ML features (see ML Analysis section)

How to Find Event Slugs

1. Go to polymarket.com
2. Click on any event (e.g., "Presidential Election Winner 2028")
3. The URL will be: https://polymarket.com/event/presidential-election-winner-2028
4. The slug is: presidential-election-winner-2028

How to Find Wallet Addresses

1. Go to any market page on Polymarket
2. Click on a trader's profile
3. The URL contains the wallet address: https://polymarket.com/profile/0xd04d93...

How to Find Condition IDs

Each Polymarket market has a unique hex identifier called a condition ID (e.g., 0xdeb615a5...). You can find it in the Actor's output from any mode, or in Polymarket's API responses. Use condition IDs with alert_check mode for targeted monitoring.

---

ML Analysis (Optional)

Set enableMlAnalysis: true to activate machine learning-powered analysis on top of the standard metrics. All ML processing runs locally inside the Actor — no external AI APIs are called, no data leaves Apify infrastructure.

When ML is disabled (the default), the Actor output is identical to the standard version. When enabled, an mlInsights field is added to the output with the following components:

ML Features

Feature	Description	Toggle
Anomaly Detection	Isolation Forest algorithm detects unusual trading patterns across 5 dimensions (volume, trade count, whale ratio, price change, spread change)	mlFeatures.anomalyDetection
Whale Clustering	K-means groups whale traders by behavioral strategy instead of just position size	mlFeatures.whaleClustering
Statistical Enhancement	Trend detection via linear regression, confidence intervals for sentiment, cross-market correlation	mlFeatures.statisticalEnhancement
Report Generation	Template-based natural language summary with signals, risks, and actionable recommendation	mlFeatures.reportGeneration

ML Features Input Example

{
  "mode": "market_analysis",
  "eventSlugs": ["presidential-election-winner-2028"],
  "enableMlAnalysis": true,
  "mlFeatures": {
    "anomalyDetection": true,
    "whaleClustering": true,
    "statisticalEnhancement": true,
    "reportGeneration": true
  }
}

All four ML features default to true when enableMlAnalysis is enabled. You can selectively disable any feature to save processing time.

Whale Strategy Clusters

Instead of classifying whales only by position size, ML clustering groups them by behavioral patterns:

Cluster Label	Behavior Pattern
patient_value	High win rate + few trades — waits for high-conviction setups
active_momentum	High trade count + moderate win rate — active trading style
high_conviction	High ROI + positive P&L — concentrated bets that pay off
contrarian_risk	Low win rate — takes the other side of consensus

Anomaly Score

The anomaly detector scores each market from 0 to 1. A score above 0.7 flags the market as anomalous, with specific factors identified:

• volume_spike — Trading volume significantly above historical average
• whale_ratio_shift — Sudden change in whale vs retail participation
• price_change — Unusual price movement
• spread_change — Abnormal spread widening or tightening
• trade_count — Unusual number of individual trades

Recommendation Engine

The report generator produces one of four actionable recommendations:

Recommendation	Meaning
Opportunity	Multiple bullish signals + low risk — worth investigating
Monitor	Neutral or mixed signals — no clear edge
Caution	Bearish signals or elevated risk — proceed carefully
Avoid	High risk count (3+) — significant red flags detected

ML Output Example (mlInsights)

{
  "mlInsights": {
    "anomaly": {
      "anomalyScore": 0.85,
      "isAnomaly": true,
      "anomalyFactors": ["volume_spike", "whale_ratio_shift"]
    },
    "whaleClusters": [
      {
        "id": 0,
        "label": "patient_value",
        "memberCount": 5,
        "avgWinRate": 0.72,
        "avgRoi": 0.34,
        "avgTrades": 12,
        "members": ["0xabc...", "0xdef..."]
      },
      {
        "id": 1,
        "label": "active_momentum",
        "memberCount": 8,
        "avgWinRate": 0.55,
        "avgRoi": 0.18,
        "avgTrades": 89,
        "members": ["0x123...", "0x456..."]
      }
    ],
    "statistics": {
      "volumeTrend": {
        "direction": "increasing",
        "slope": 1250.5,
        "r2": 0.82
      },
      "sentimentConfidence": {
        "lower": 55,
        "upper": 89,
        "level": 0.95
      }
    },
    "report": {
      "summary": "Strong bullish momentum with whale accumulation. Anomalous volume spike detected — 3x above 7-day average. Patient value whales are dominant buyers.",
      "signals": [
        "Bullish: Whale sentiment +72",
        "Bullish: 80% buy-side volume"
      ],
      "risks": [
        "Anomaly: Volume spike (score 0.85)",
        "Concentration: HHI 0.35"
      ],
      "recommendation": "Opportunity"
    }
  }
}

ML Feature Availability by Mode

Feature	whale_discovery	market_analysis	whale_profile	bulk_scan	alert_check
Anomaly Detection	—	Yes	—	—	Yes
Whale Clustering	—	Yes	—	—	—
Statistical Enhancement	—	Yes	—	Sector analysis only	—
Report Generation	—	Yes	Yes*	—	Yes (on alerts)

*whale_profile: Requires sufficient closed position data. mlInsights may be absent if data is insufficient.

ML Design Principles

• Zero external API calls — All ML runs locally using npm packages (isolation-forest, ml-kmeans, simple-statistics, jstat)
• Graceful fallback — If any ML feature fails or lacks data, it returns null and the standard output remains intact
• Timer-aware — ML processing is skipped if the Actor is approaching its timeout budget (< 15 seconds remaining)
• Negligible overhead — Total ML processing adds < 10ms per market (CPU-only, no network calls)
• Off by default — Setting enableMlAnalysis: false (default) produces identical output to the non-ML version

---

Sample Output

Whale Discovery Output

Based on actual output from whale_discovery with category: "crypto", maxMarkets: 30, maxWhales: 10:

{
  "whales": [
    {
      "profile": {
        "address": "0xde17f7144fbd0eddb2679132c10ff5e74b120988",
        "tier": "shark",
        "totalAmount": 414350.988046,
        "marketsCount": 2,
        "winRate": 0,
        "roi": 0,
        "totalPnl": 0,
        "resolvedTrades": 0
      },
      "positions": [
        {
          "conditionId": "0x337e5c84b83679d5557acafcf78b5c5d4d932b...",
          "marketSlug": "will-bitcoin-reach-80k-in-march-2026",
          "title": "Will Bitcoin reach $80,000 in March?",
          "size": 293297.58,
          "currentValue": 268367.29,
          "outcome": "No"
        },
        {
          "conditionId": "0x844c6215079483f67667b86e4111b6acc24d17...",
          "marketSlug": "will-bitcoin-reach-85k-in-march-2026",
          "title": "Will Bitcoin reach $85,000 in March?",
          "size": 121053.41,
          "currentValue": 118934.97,
          "outcome": "No"
        }
      ],
      "positionSummary": {
        "totalPositionValue": 1193960.67,
        "activeMarkets": 83,
        "yesExposure": 189143.53,
        "noExposure": 1004817.14
      }
    }
  ],
  "hotMarkets": [
    {
      "conditionId": "0x337e5c84b83679d5557acafcf78b5c5d4d932b...",
      "slug": "will-bitcoin-reach-80k-in-march-2026",
      "whaleCount": 4,
      "totalWhaleValue": 302837.71
    }
  ],
  "metadata": {
    "generatedAt": "2026-03-23T09:01:38.842Z",
    "mode": "whale_discovery",
    "marketsScanned": 30,
    "marketsSuccessful": 30,
    "marketsFailed": 0,
    "uniqueWhalesFound": 54,
    "profilesFailed": 0,
    "qualifiedWhales": 10,
    "phase4TimedOut": false,
    "filters": {
      "minWinRate": 0.55,
      "minPnl": 1000,
      "whaleThreshold": 50000,
      "category": "crypto"
    }
  }
}

How to read this output:

• whales[].profile — Who is this whale? Tier (Whale $1M+ / Shark $100K+ / Dolphin $10K+), total position amount, and how many markets they were discovered in.
• whales[].positions — Every active bet this whale holds, sorted by value. The example shows a shark betting heavily on NO for Bitcoin price targets — a bearish signal.
• whales[].positionSummary — Total exposure at a glance. yesExposure vs noExposure shows directional bias: this whale has 84% on NO = strongly bearish.
• hotMarkets — Markets where 2+ discovered whales overlap. "Will Bitcoin reach $80K?" has 4 whales with $302K total — the strongest convergence signal in this scan.
• metadata — 30 markets scanned, 54 unique whales found, 10 passed filters. phase4TimedOut: false confirms all position data was fetched completely.

Note on resolvedTrades: 0: The Polymarket Data API provides limited closed position history for most wallets. When resolvedTrades is 0, the whale was selected by active position size rather than historical win rate. See FAQ for details.

Market Analysis Output

{
  "market": {
    "conditionId": "0x2d3c4fc5cde6dfb43448402b912e41bd...",
    "question": "Will Eric Trump win the 2028 US Presidential Election?",
    "slug": "will-eric-trump-win-the-2028-us-presidential-election",
    "category": "World Elections",
    "currentPrice": 0.0085,
    "volume24hr": 23286.52,
    "liquidity": 24781354.13,
    "openInterest": 0,
    "spread": 0.001
  },
  "smartMoneyMetrics": {
    "whaleSentiment": 0,
    "sentimentLabel": "neutral",
    "marketHealthScore": 54,
    "smartMoneyConsensus": {
      "yes": 0.38,
      "no": 0.62,
      "label": "moderate_bearish"
    },
    "concentrationHHI": 0.39
  },
  "whaleBreakdown": {
    "totalWhales": 40,
    "holders": [
      {
        "address": "0x0c0e270cf879583d6a0142fc817e05b768d0434e",
        "tier": "shark",
        "totalPositionValue": 345780.25,
        "winRate": 0.65,
        "roi": 0.34,
        "totalPnl": 87450,
        "resolvedTrades": 42,
        "topCategory": "politics"
      }
    ]
  },
  "tradeFlow": {
    "largeTrades": [
      {
        "wallet": "0xd04d93be590ded67b99f053d4b6d29d3f8483312",
        "side": "SELL",
        "size": 26600,
        "price": 0.992,
        "value": 26387.2,
        "timestamp": 1771982326,
        "walletTier": "unknown",
        "initiatedBy": "buyer"
      }
    ],
    "buyerInitiated": 26387.2,
    "sellerInitiated": 0,
    "totalVolume": 26387.2,
    "whaleVolume": 0,
    "whaleVolumeRatio": 0,
    "timeAnalysis": {
      "peakHour": 14,
      "quietHour": 3,
      "hourlyDistribution": {}
    }
  },
  "orderbook": {
    "bidDepth": 13361.95,
    "askDepth": 6309732.97,
    "imbalanceRatio": 1.16,
    "imbalanceLabel": "mild_bid",
    "bidLevels": 8,
    "askLevels": 54,
    "topBidLevels": [
      { "price": 0.008, "size": 364488.89 },
      { "price": 0.007, "size": 333295.37 }
    ],
    "topAskLevels": [
      { "price": 0.009, "size": 345016.06 },
      { "price": 0.01, "size": 595689.43 }
    ],
    "spreadAnalysis": {
      "bestBid": 0.008,
      "bestAsk": 0.009,
      "spread": 0.001,
      "spreadBps": 1176
    },
    "impact": {
      "impact_10k": 0.991,
      "impact_50k": 0.991,
      "impact_100k": 0.991
    }
  },
  "metadata": {
    "generatedAt": "2026-03-08T03:29:19.192Z",
    "mode": "market_analysis",
    "eventSlug": "presidential-election-winner-2028"
  }
}

Bulk Scan Output

{
  "question": "Will the Fed decrease interest rates by 50+ bps after the March 2026 meeting?",
  "slug": "will-the-fed-decrease-interest-rates-by-50-bps-after-the-march-2026-meeting",
  "conditionId": "0xdeb615a52cd114e5aa27d8344ae506a72bea81f6...",
  "category": "Economics",
  "currentPrice": 0.0015,
  "volume24hr": 11503957.55,
  "healthScore": 65,
  "topHolderCount": 2,
  "metadata": {
    "generatedAt": "2026-03-08T03:42:17.227Z",
    "mode": "bulk_scan"
  }
}

Note: When ML is disabled (default), bulk_scan returns a flat array of market objects. When ML is enabled (enableMlAnalysis: true with statisticalEnhancement), the output is wrapped in { markets: [...], mlInsights: { sectorAnalysis: {...} } }.

Bulk Scan with ML Output:

{
  "markets": [
    { "question": "...", "slug": "...", "healthScore": 65, "..." : "..." }
  ],
  "mlInsights": {
    "sectorAnalysis": {
      "Sports": { "avgHealth": 50, "marketCount": 5 },
      "Economics": { "avgHealth": 72, "marketCount": 3 }
    }
  }
}

Whale Profile Output

{
  "wallet": "0xd04d93be590ded67b99f053d4b6d29d3f8483312",
  "summary": {
    "winRate": 0.65,
    "totalPnl": 12500.75,
    "roi": 0.34,
    "resolvedTrades": 42,
    "activePositionValue": 12450.75,
    "activePositionCount": 100
  },
  "activePositions": [
    {
      "conditionId": "0x098e2be3df8ab529940c567819f8ef007cf...",
      "size": 519292.67,
      "avgPrice": 0.4999,
      "initialValue": 259623.49,
      "currentValue": 778.94,
      "cashPnl": -258844.55,
      "percentPnl": -99.7,
      "curPrice": 0.0015,
      "title": "Will Australia win the 2026 FIFA World Cup?",
      "outcome": "Yes",
      "endDate": "2026-07-20"
    }
  ],
  "recentActivity": [],
  "metadata": {
    "generatedAt": "2026-03-08T03:38:18.355Z",
    "mode": "whale_profile"
  }
}

Alert Check Output

Note: newLargeTrades is the total count of trades above tradeAlertThreshold found in the current query window. It does not track state between runs — each run independently queries the timeWindow period.

{
  "conditionId": "0x2d3c4fc5cde6dfb43448402b912e41bd...",
  "newLargeTrades": 1,
  "totalVolume": 26387.2,
  "trades": [
    {
      "proxyWallet": "0xd04d93be590ded67b99f053d4b6d29d3f8483312",
      "side": "SELL",
      "size": 26600,
      "price": 0.992,
      "timestamp": 1771982326,
      "title": "Will Eric Trump win the 2028 US Presidential Election?"
    }
  ],
  "metadata": {
    "generatedAt": "2026-03-08T03:31:20.560Z",
    "mode": "alert_check"
  }
}

---

Computed Metrics Explained

Smart Money Consensus

Measures the directional bias of top holders. Returns the ratio of whale capital on YES vs NO:

• yes: 0.8, no: 0.2 = 80% of whale capital is on YES

YES Ratio	Label
> 70%	strong_bullish
55–70%	moderate_bullish
45–55%	neutral
30–45%	moderate_bearish
< 30%	strong_bearish

Whale Sentiment Score (-100 to +100)

Net directional signal from whale traders. Positive = bullish, negative = bearish. Derived from trade history and position sizing.

Score Range	Label
75 and above	extreme_bullish
25 to 74	moderately_bullish
-24 to 24	neutral
-74 to -25	moderately_bearish
-75 and below	extreme_bearish

Market Health Score (0–100)

Composite score combining:

• 24-hour volume (25% weight)
• Liquidity depth (25% weight)
• Open interest (20% weight)
• Bid-ask spread — tighter is better (15% weight)
• Competitive score (15% weight)

Markets scoring below 40 are thin and susceptible to manipulation. Markets above 75 are healthy for larger positions.

Concentration HHI (0–1)

Herfindahl-Hirschman Index measuring how concentrated holdings are among top holders. Values above 0.25 indicate high concentration — fewer dominant holders controlling more of the market.

Orderbook Impact Simulation

Simulates the price impact of executing $10K, $50K, and $100K market orders against the live CLOB orderbook. Answers: "If I wanted to buy $50K YES right now, what would my average fill price be?"

Trade Flow Analysis

Breaks down recent large trades by:

• Buyer-initiated vs seller-initiated volume
• Whale vs non-whale volume ratio
• Hourly distribution (peak/quiet trading hours)

---

Whale Classification Tiers

Position sizes are classified into tiers based on total USD value:

Tier	Position Size	Description
Whale	$1,000,000+	Institutional-level capital
Shark	$100,000 – $999,999	Sophisticated individual traders
Dolphin	$10,000 – $99,999	Active retail with significant capital
Fish	$1,000 – $9,999	Standard retail positions
Retail	Below $1,000	Small positions

The whaleThreshold input parameter controls the minimum position size for inclusion in whale analysis (default: $50,000).

---

Pricing

This Actor uses Apify's Pay Per Event (PPE) billing model. You pay only for the analysis events you consume — no subscription, no minimum spend, no monthly fees.

Mode	Price per Run	What You Get
Whale Discovery	$1.50 / scan	Auto-discover whales + cross-market position map + hot markets
Market Analysis	$0.15 / market	Full analysis: metrics + whales + trade flow + orderbook
Whale Profile	$0.25 / wallet	Complete wallet: positions + P&L + win rate + activity
Bulk Scan	$1.50 / scan	Batch scan of top N markets with health scores
Alert Check	$0.05 / check	Lightweight large trade detection

Note: Market Analysis charges $0.15 per market within an event. An event with 20 markets costs 20 x $0.15 = $3.00.

ML analysis adds no extra cost — it runs locally on the same compute.

Estimated Monthly Costs

Usage Pattern	What You Do	Estimated Cost
Smart money tracking	1 whale discovery/day	~$45/month
Casual monitoring	1 bulk scan/day	~$45/month
Active trading	5 market analyses/day + hourly alerts	~$60/month
Research pipeline	Daily whale discovery + targeted analysis	~$120/month
Hourly alerts only	24 alert checks/day on 5 markets	~$7.50/month

Free Trial

Apify provides free credits for new accounts. Start with whale_discovery to see what smart money is doing before committing to any spending.

---

API Integration

Whale Discovery (Python) — Recommended Starting Point

import requests

response = requests.post(
    "https://api.apify.com/v2/acts/jy-labs~polymarket-whale-tracker/run-sync-get-dataset-items",
    params={"token": "YOUR_API_TOKEN"},
    json={
        "mode": "whale_discovery",
        "maxMarkets": 20,
        "minWinRate": 0.55,
        "maxWhales": 10
    }
)
data = response.json()[0]

# Top whales and their positions
for whale in data["whales"]:
    p = whale["profile"]
    print(f"\n{p['tier'].upper()} — {p['address'][:10]}...")
    print(f"  Win Rate: {p['winRate']:.0%} | PnL: ${p['totalPnl']:,.0f} | Markets: {p['marketsCount']}")
    for pos in whale["positions"][:3]:
        print(f"  → {pos['title']} | {pos['outcome']} | ${pos['currentValue']:,.0f}")

# Hot markets — where whales converge
print("\n🔥 Hot Markets (2+ whales):")
for hm in data["hotMarkets"]:
    print(f"  {hm['slug']} — {hm['whaleCount']} whales, ${hm['totalWhaleValue']:,.0f}")

Whale Discovery (JavaScript/Node.js)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const run = await client.actor('jy-labs/polymarket-whale-tracker').call({
    mode: 'whale_discovery',
    maxMarkets: 20,
    category: 'crypto',
    minWinRate: 0.5,
    maxWhales: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const { whales, hotMarkets } = items[0];

for (const whale of whales) {
    console.log(`${whale.profile.tier} — ${whale.profile.address}`);
    console.log(`  Positions: ${whale.positionSummary.activeMarkets} markets, $${whale.positionSummary.totalPositionValue}`);
}

console.log('\nHot Markets:', hotMarkets.map(m => `${m.slug} (${m.whaleCount} whales)`));

Run via Apify API (cURL)

curl -X POST \
  "https://api.apify.com/v2/acts/jy-labs~polymarket-whale-tracker/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "whale_discovery",
    "maxMarkets": 20,
    "minWinRate": 0.5,
    "maxWhales": 10
  }'

Market Analysis (Python)

import requests

response = requests.post(
    "https://api.apify.com/v2/acts/jy-labs~polymarket-whale-tracker/run-sync-get-dataset-items",
    params={"token": "YOUR_API_TOKEN"},
    json={
        "mode": "market_analysis",
        "eventSlugs": ["presidential-election-winner-2028"],
        "includeOrderbook": True,
        "includeTradeFlow": True
    }
)
markets = response.json()

for result in markets:
    print(f"{result['market']['question']}")
    print(f"  Health Score: {result['smartMoneyMetrics']['marketHealthScore']}")
    print(f"  Whale Sentiment: {result['smartMoneyMetrics']['sentimentLabel']}")
    print(f"  Consensus: {result['smartMoneyMetrics']['smartMoneyConsensus']['label']}")

Whale Profile (JavaScript/Node.js)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const run = await client.actor('jy-labs/polymarket-whale-tracker').call({
    mode: 'whale_profile',
    walletAddresses: ['0xd04d93be590ded67b99f053d4b6d29d3f8483312']
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].summary);
// { winRate: 0.65, totalPnl: 12500, roi: 0.34, activePositionCount: 42 }

Run with ML Analysis (Python)

import requests

response = requests.post(
    "https://api.apify.com/v2/acts/jy-labs~polymarket-whale-tracker/run-sync-get-dataset-items",
    params={"token": "YOUR_API_TOKEN"},
    json={
        "mode": "market_analysis",
        "eventSlugs": ["presidential-election-winner-2028"],
        "enableMlAnalysis": True
    }
)
markets = response.json()

for market in markets:
    ml = market.get("mlInsights")
    if ml:
        report = ml.get("report", {})
        print(f"Summary: {report.get('summary')}")
        print(f"Recommendation: {report.get('recommendation')}")

        clusters = ml.get("whaleClusters", [])
        for c in clusters:
            print(f"  Cluster '{c['label']}': {c['memberCount']} whales, "
                  f"avg win rate {c['avgWinRate']:.0%}")

Schedule Automated Monitoring

To run alert_check every hour:

1. Open this Actor in Apify Console
2. Click Schedule in the top navigation
3. Set interval to Every 1 hour
4. Configure input:

   {
     "mode": "alert_check",
     "marketConditionIds": ["0xdeb615a52cd114e5..."],
     "tradeAlertThreshold": 5000
   }
   

5. Optionally add a webhook to receive results via Slack, email, or your API

Cost: ~$0.05/hour = $1.20/day for continuous whale monitoring.

---

MCP and AI Agent Integration

This Actor is fully compatible with the Apify MCP server, enabling direct integration with Claude Desktop, ChatGPT, and custom AI agent workflows.

Because it uses Pay Per Event pricing, each AI agent invocation produces a predictable, bounded cost — safe for automated pipelines.

Example: Claude Desktop via Apify MCP

Once the Apify MCP server is configured, ask Claude:

"Find the top whales on Polymarket crypto markets and show me what they're betting on."

Claude will run whale_discovery with category: "crypto", then summarize: "4 whales are betting against Bitcoin hitting $80K in March, with $302K combined. The biggest position is a $268K NO bet by a shark-tier trader..."

"Deep dive into the Bitcoin $80K market — show me the orderbook and trade flow."

Claude will run market_analysis on the hot market discovered above, providing sentiment, whale breakdown, and impact simulation.

---

Performance Guide

Mode	Scope	Recommended Memory	Recommended Timeout
Whale Discovery	10–30 markets, 10 whales	256 MB	180s
Whale Discovery	30–50 markets, 50 whales	512 MB	240s
Market Analysis	1 event (~10-130 markets)	256 MB	120s
Whale Profile	1–5 wallets	256 MB	60s
Bulk Scan	5–20 markets	256 MB	60s
Bulk Scan	20–50 markets	256 MB	120s
Alert Check	1–10 condition IDs	256 MB	30s

Tip: Each event can contain many sub-markets (e.g., "Presidential Election Winner 2028" has 128 candidate markets). Start with maxMarkets: 5 and increase as needed.

Enabling ML analysis adds negligible overhead (< 10ms per market). Memory requirements remain the same.

---

Technical Details

• Runtime: Node.js 20 on Apify Cloud
• Memory: 256 MB minimum, up to 4 GB for large scans
• Dependencies: No browser, no Puppeteer, no Playwright — pure API calls
• APIs used: Three Polymarket public REST APIs (no auth required)
• Rate limiting: Built-in sliding window rate limiter respecting each API's limits
• Error handling: Graceful per-market fallback — one failed market doesn't crash the entire run
• Timeout management: Automatic early exit when approaching Actor timeout budget
• ML libraries: isolation-forest, ml-kmeans, simple-statistics, jstat (loaded only when ML is enabled)
• Typical performance: Bulk scan of 20 markets completes in ~15 seconds

---

Error Handling & Edge Cases

The Actor is designed to handle edge cases gracefully without crashing:

Scenario	Behavior
Empty eventSlugs / walletAddresses / marketConditionIds array	Returns empty result array with a WARN log. No crash.
Non-existent event slug	Skips the event, continues processing remaining slugs.
Invalid or unknown wallet address	Returns a profile with 0 positions and 0 closed trades (empty data, not an error).
Invalid condition ID	Returns empty trade/holder data for that market. Other markets continue normally.
API rate limit hit (HTTP 429)	Automatic retry with exponential backoff (built into rate limiter).
Single market API failure	Skipped with WARN log — other markets in the same run continue processing.
Actor approaching timeout	Stops processing new markets/wallets early and returns partial results collected so far.
ML analysis failure	Graceful fallback — mlInsights is omitted, standard output remains intact.
category filter matches no events	Returns empty result array (no error).
whale_discovery finds no whales above threshold	Returns { whales: [], hotMarkets: [], metadata: {...} } with scan stats.
Whale position fetch fails for one wallet	Skipped — other whales continue processing.

---

Frequently Asked Questions

How does Whale Discovery find whales automatically? It scans the top holders of active markets via the Data API. Any wallet holding a position above whaleThreshold (default $50K) is collected. Each wallet is then profiled and enriched with their full cross-market positions. No manual wallet input needed.

What are "Hot Markets"? Markets where 2 or more discovered whales hold active positions. The more whales converge on a single market, the stronger the smart money signal. In real tests, hot markets like "Will Bitcoin reach $80K?" showed 4 whales with $302K combined — that kind of convergence is hard to find manually.

Why do all whales show resolvedTrades: 0 and winRate: 0? The Polymarket Data API's /positions/closed endpoint returns limited or empty data for most wallets. This is a known API limitation, not a bug. When closed position history is unavailable, whales are ranked by active position size instead of historical win rate. The minWinRate and minPnl filters only apply to whales that have trade history — whales without history are included based on their current holdings.

Should I set minWinRate and minPnl filters? These filters are most useful when the Data API does return trade history (which varies by wallet and time period). If you're getting 0 qualified whales, lower the filters or set minWinRate: 0 to rank purely by position size. The whales with the largest active positions are often the most informative regardless of historical metrics.

Do I need a Polymarket account or API key? No. All three Polymarket APIs (Gamma, Data, CLOB) are public endpoints requiring no authentication. You only need an Apify account.

Does this Actor use a browser? No. It calls REST APIs directly — no browser automation, no DOM parsing. This makes it faster, more reliable, and less fragile than scraping.

How fresh is the data? Data reflects Polymarket's live state at runtime. CLOB orderbook data is real-time. Trade history is typically within minutes of live.

What if a Polymarket API is down? The Actor retries failed requests with exponential backoff for rate limits (429). If a specific market fails, it is skipped gracefully — other markets continue processing normally.

Why do some markets show 0 holders? The Data API's /holders endpoint may return limited data for newer or less active markets. The Actor handles this gracefully and still returns market metadata and orderbook data.

Does ML analysis call external AI APIs (OpenAI, Claude, etc.)? No. All ML processing uses local npm packages running inside the Actor container. No data is sent to any external AI service. This means no extra latency, no API keys needed, and no additional cost.

Why are all whale clusters labeled contrarian_risk? This happens when the Polymarket Data API returns empty closed position history for most wallets, resulting in 0% win rate across the board. The clustering algorithm correctly groups wallets with similar (low) win rates together. This is a data availability limitation, not a bug.

Can I use this for automated trading? This Actor provides information and analytics only. It does not execute trades. You can use the output to inform trading decisions or feed signals into your own trading system.

What is the difference between enableMlAnalysis: false and true? When false (default), the output contains standard computed metrics only. When true, an additional mlInsights field is added with anomaly detection, whale clustering, statistical analysis, and a natural language report. The standard fields remain identical in both cases.

---

Changelog

v1.2 (March 2026)

• New mode: whale_discovery — Auto-discover whale wallets from market data, no addresses needed
• Cross-market position mapping: see every position a whale holds across all Polymarket markets
• Hot Market detection: identifies markets where multiple whales converge
• Quality filtering: minWinRate, minPnl, maxWhales parameters for focusing on proven traders
• Category-aware scanning: filter whale discovery by market category (crypto, politics, etc.)

v1.1 (March 2026)

• Added optional ML analysis layer (enableMlAnalysis)
• Isolation Forest anomaly detection for unusual trading patterns
• K-means whale strategy clustering (4 behavioral labels)
• Statistical enhancement: trend detection, confidence intervals, correlation matrix
• Template-based NLG report with signals, risks, and recommendation
• All ML features are off by default and run locally (no external APIs)
• Granular ML feature toggles via mlFeatures object

v1.0 (March 2026)

• Initial release with 4 analysis modes
• Cross-API analytics (Gamma + Data + CLOB)
• Smart Money Consensus, Whale Sentiment, Market Health Score
• Orderbook depth analysis with impact simulation
• Trade flow analysis with hourly distribution
• Whale tier classification system
• Graceful error handling per market
• Built-in rate limiting for all 3 APIs

---

Legal Disclaimer

This Actor provides informational data only and does not constitute financial advice. The computed metrics, whale activity signals, ML-generated insights, and sentiment scores are derived from publicly available data and are intended for research and informational purposes only. Past patterns in whale trading behavior are not indicative of future market outcomes. Trading in prediction markets involves risk of financial loss. Users are solely responsible for any decisions made based on this data.