🐋 Polymarket Whale Tracker & Copy Trading Radar

Real-time whale orderflow monitor, prediction market insider trade detector, and smart money copy-trading tracker for Polymarket and Kalshi.
Powered by the high-frequency institutional trade tape of NaxosData.

---

📌 Overview

polymarket-whale-tracker is a production-ready, open-source Python engine designed to monitor institutional-grade trades, block orders, and smart-money conviction bets across decentralized and regulated prediction markets.

Whether you are building an automated Polymarket copy trading bot, tailing prediction market insider trades, tracking whale alerts in Discord/Telegram communities, or analyzing smart money wallet profit & loss, this tool gives you instant visibility into market-moving orders before the broader retail market catches on.

Key Capabilities

• ⚡ Real-Time Whale Filtering: Continuous poller and stream consumer for NaxosData /api/v1/trades, filtering by notional size (size_usd > threshold) or institutional block flags (is_block_trade == True).
• 🔔 Instant Discord & Telegram Webhooks: High-impact notification embeds featuring outcome tags (🟢 YES / 🔴 NO), contract prices, implied odds, dollar sizes, and direct PolygonScan address & tx hyperlinks.
• 🏆 Cumulative Whale Leaderboard: Aggregates multi-venue trade history to profile top active whale wallets, calculate directional conviction biases (YES vs NO), and export rankings to JSON/CSV.
• 🔗 Full PolygonScan Integration: Automatic short-address formatting (0x72a1...4b39) and on-chain verification links for Polygon-based transactions.
• 🛡️ Zero Missing Trade Guarantee & Deduplication: Bounded LRU deduplication cache prevents duplicate alerts across polling cycles.
• 🧪 100% Test Coverage: Comprehensive unit tests covering payload generation, threshold triggers, wallet parsing, and CLI commands.

---

🏛 Architecture Diagram

flowchart TD
    subgraph DataSource["Data Source"]
        A["NaxosData API Tape (/api/v1/trades)"] -->|REST / Poller| B["WhaleTracker Consumer"]
    end

    subgraph CorePipeline["Core Processing Pipeline"]
        B --> C{"Deduplication Cache (LRU Seen Trades)"}
        C -->|New Trade| D{"Whale Criteria Filter"}
        C -->|Duplicate| X["Drop"]
        D -->|size_usd >= threshold OR is_block_trade| E["Whale Alert Triggered"]
        D -->|Sub-threshold| F["Update Leaderboard Only"]
    end

    subgraph AggStorage["Aggregation & Storage"]
        E --> G["WhaleLeaderboard Aggregator"]
        F --> G
        G --> H["Export CSV / JSON / Markdown"]
    end

    subgraph Notifications["Notification Dispatchers"]
        E --> I["AlertDispatcher"]
        I -->|Discord Webhook| J["Discord Channel Embeds"]
        I -->|Telegram Bot API| K["Telegram Group / Channel"]
        I -->|Console / Dry-Run| L["Terminal Color Stream"]
    end

---

🚀 Quickstart

1. Installation

Install via pip or clone the repository:

git clone https://github.com/nexosdata/polymarket-whale-tracker.git
cd polymarket-whale-tracker
pip install -e .

2. Monitor Whales in Dry-Run Mode (Console Only)

Run the CLI tracker in test mode to watch live simulated or public trade flow in your terminal:

polymarket-whale-tracker --threshold-usd 2500 --venue POLYMARKET --dry-run

3. Send Live Alerts to Discord & Telegram

Run with your production webhook and bot tokens:

polymarket-whale-tracker \
  --venue POLYMARKET \
  --threshold-usd 5000 \
  --poll-sec 3.0 \
  --discord-webhook "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL" \
  --telegram-token "YOUR_TELEGRAM_BOT_TOKEN" \
  --telegram-chat-id "-100123456789"

---

📸 Sample Alerts Preview

Discord Webhook Embed Preview

┌────────────────────────────────────────────────────────────────────────┐
│ 🚨 Whale Alert: POLYMARKET | $25,400.00 YES                            │
│ A whale executed a high-conviction order in US Recession in 2026?     │
├────────────────────────────────────────────────────────────────────────┤
│ 🏛 Venue: POLYMARKET                  🎯 Outcome Action: BUY 🟢 YES    │
│ ⚡ Classification: Institutional Block 💰 Notional Size: $25,400.00    │
│ 📊 Implied Odds: $0.620 (62.0%)       👛 Whale: [0x72a1...4b39](link)  │
│ 📌 Market: US Recession in 2026?      🔗 Tx Hash: [0x9a8b...12cd](link)│
├────────────────────────────────────────────────────────────────────────┤
│ Polymarket Whale Tracker • Powered by NaxosData Tape                   │
└────────────────────────────────────────────────────────────────────────┘

Telegram HTML Notification Preview

⚡ INSTITUTIONAL BLOCK TRADE ⚡

🏛 Venue: POLYMARKET
📌 Market: US Recession in 2026?
🎯 Action: BUY 🟢 YES @ $0.620 (62.0% odds)
💰 Trade Notional: $25,400.00 (40,967 shares)
👛 Whale Wallet: 0x72a1...4b39 (WhaleAlpha)
🔗 Transaction: 0x9a8b...12cd

Powered by NaxosData Prediction Market Tape
#Polymarket #WhaleAlert #SmartMoney #CopyTrading

---

📊 Whale Leaderboard & Copy Trading

To inspect top cumulative whale wallets without running a background daemon, use --leaderboard:

polymarket-whale-tracker --venue POLYMARKET --leaderboard --export-csv whales.csv

Sample Output Table

Rank	Whale Wallet	Venue	Total Volume (USD)	Trades	YES Bias (%)	Largest Fill (USD)	Markets
#1	0x72a1...4b39 (WhaleAlpha)	POLYMARKET	$1,420,500.00	48	85.4%	$250,000.00	12
#2	0x9bc2...11ef (MacroGiga)	POLYMARKET	$890,200.00	31	42.0%	$125,000.00	8
#3	0x140d...98ca	POLYMARKET	$620,000.00	19	100.0%	$95,000.00	5

Use this leaderboard to isolate wallets with high win rates and directional bias for automated copy trading strategies.

---

🛠️ CLI Options Reference

Flag	Default	Description
--threshold-usd	2500.0	Minimum notional trade size in USD (price * size) to trigger an alert.
--venue	POLYMARKET	Prediction market venue to monitor (POLYMARKET, KALSHI, or ALL).
--poll-sec	3.0	Interval in seconds between continuous trade tape polls.
--base-url	https://naxosdata.com	NaxosData institutional API gateway base URL.
--api-key	None	NaxosData API Key (optional, can also be provided via NAXOS_API_KEY).
--discord-webhook	None	Discord webhook endpoint for rich embed delivery.
--telegram-token	None	Telegram Bot Token for notification dispatch.
--telegram-chat-id	None	Telegram target chat or channel ID.
--dry-run	False	Log alerts to standard output without posting HTTP webhooks.
--leaderboard	False	Pull latest tape, calculate cumulative whale rankings, print table, and exit.
--export-csv	None	Path to save whale leaderboard stats as a CSV spreadsheet.
--export-json	None	Path to save whale leaderboard stats as a JSON document.
--limit	50	Maximum number of records fetched per polling request.
--verbose	False	Enable detailed debug logs in terminal.

---

🐍 Python SDK Programmatic Usage

You can embed the whale tracker directly into your own algorithmic trading scripts or bot infrastructure:

from whale_tracker import WhaleTracker, WhaleAlert

def on_whale_detected(alert: WhaleAlert):
    trade = alert.trade
    print(f"🚨 Custom Alert: {trade.side} {trade.taker_side} for ${trade.size_usd:,.2f} on {trade.venue}")
    print(f"   Wallet: {trade.trader_wallet}")
    print(f"   PolygonScan: {trade.polygonscan_wallet_url}")

tracker = WhaleTracker(
    base_url="https://naxosdata.com",
    venue="POLYMARKET",
    threshold_usd=5000.0,
    poll_interval_sec=2.0,
    discord_webhook="https://discord.com/api/webhooks/...",
    on_whale_trade=on_whale_detected,
    dry_run=False,
)

# Run continuous monitoring loop
tracker.run_continuous()

---

🌐 How NaxosData Powers the Trade Tape

High-frequency prediction market tracking requires a unified, low-latency, and normalized data feed:

1. Normalized L2 & Trade Tape: NaxosData continuously streams Level 2 orderbook state and matching engine executions across Polymarket, Kalshi, and other venues.
2. On-Chain Address Resolution: Polymarket executions are captured from Polygon RPCs and the CTF Exchange contracts, mapping raw 0x addresses and transaction hashes into canonical records.
3. Partitioned Parquet Tick Archives: Historical trades are compacted into standardized Apache Parquet tables for fast backtesting and wallet profiling.

Learn more and obtain an API key at naxosdata.com.

---

🧪 Running Automated Tests

Run the full unit test suite with 100% pass verification:

python3 -m unittest discover tests -v

All 23 test cases verify trade parsing, threshold triggers, block trade classification, notification embed structures, and leaderboard aggregation.

---

📄 License

Distributed under the MIT License. Copyright (c) 2026 NaxosData Contributors & William Gonda. See LICENSE for details.