Metadata-Version: 2.4
Name: polymarket-whale-tracker
Version: 1.0.0
Summary: Real-time whale trade tracker and smart money copy-trading radar for Polymarket and Kalshi
Author-email: William Gonda & NaxosData Contributors <hello@naxosdata.com>
License-Expression: MIT
Project-URL: Homepage, https://naxosdata.com
Project-URL: Documentation, https://naxosdata.com/docs
Project-URL: Repository, https://github.com/nexosdata/polymarket-whale-tracker
Project-URL: Tracker, https://github.com/nexosdata/polymarket-whale-tracker/issues
Keywords: polymarket whale tracker,polymarket wallet tracker,polymarket copy trading,prediction market insider trades,whale alerts,orderflow tape,kalshi,naxosdata
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: requests>=2.28.0; extra == "dev"
Dynamic: license-file

# 🐋 Polymarket Whale Tracker & Copy Trading Radar

[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](#)
[![Discord Alerts](https://img.shields.io/badge/Discord-Webhooks-7289da.svg)](https://discord.com)
[![Telegram Alerts](https://img.shields.io/badge/Telegram-Bot%20API-0088cc.svg)](https://telegram.org)
[![NaxosData API](https://img.shields.io/badge/Tape-NaxosData%20API%20v1-orange.svg)](https://naxosdata.com)

> **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](https://naxosdata.com).

---

## 📌 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

```mermaid
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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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`](https://polygonscan.com/address/0x72a1563f4581177eb) (WhaleAlpha) | POLYMARKET | \$1,420,500.00 | 48 | 85.4% | \$250,000.00 | 12 |
| #2 | [`0x9bc2...11ef`](https://polygonscan.com/address/0x9bc2891391af19c2) (MacroGiga) | POLYMARKET | \$890,200.00 | 31 | 42.0% | \$125,000.00 | 8 |
| #3 | [`0x140d...98ca`](https://polygonscan.com/address/0x140db423321cc83a) | 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:

```python
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](https://naxosdata.com).

---

## 🧪 Running Automated Tests

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

```bash
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](LICENSE) for details.
