🐋 Polymarket Whale Watcher

AI-Powered Whale Trade Intelligence for Polymarket Prediction Markets

Real-time monitoring of 700+ markets  ·  14 autonomous research tools  ·  Multi-step deep analysis  ·  Signal accuracy tracking

Quick Start   |   How It Works   |   Sample Report   |   Configuration   |   Dashboard

---

What It Does

Whale Watcher continuously monitors 700+ active Polymarket markets across three volume tiers, detects large trades with anomalous patterns, and deploys an LLM agent with 14 autonomous research tools to conduct multi-step deep investigations. Each whale trade undergoes a structured 7-step analysis pipeline — from trader profiling and cross-market position mapping to information gap assessment — producing an Information Asymmetry Score that quantifies the likelihood of non-public information advantage.

Live Demo

$ python -m src.main run

============================================================
WHALE WATCHER STARTED
============================================================
Monitoring: 765 markets
Interval: 10 seconds
Min Trade Size: $10,000 USD
Price Range: 0.1 - 0.9
============================================================

Tiered monitoring: Tier1=8 (>500K), Tier2=198 (>10K), Tier3=559 (>1K)

[23:41:12] WHALE TRADE DETECTED!
           Amount: $9,600.00 USDC
           Side: BUY Yes
           Price: 0.7142
           Market: US x Iran diplomatic meeting by June 30, 2026?

           Generating analysis report...
           Round 1: LLM requested 3 tool call(s)
           → search_web("US Iran diplomatic meeting June 2026")
           → search_twitter("US Iran meeting diplomacy")
           → get_wallet_transfers("0xceza...rn132")
           Round 2: LLM requested 2 tool call(s)
           → search_web("Islamabad Iran talks Witkoff April 2026")
           → search_twitter("POLYMARKET Iran meeting odds fading")
           Round 3: LLM requested 1 tool call(s)
           → search_web("Iran FM Araghchi 3 phase deal proposal")

           Analysis complete after 3 round(s)
           Information Asymmetry Score: 0.32 (LOW)
           Trader Credibility: MEDIUM (#1733, PnL: $84K)
           Verdict: Thesis continuation / loss recovery — HOLD/PASS
           Report saved: reports/20260504/...

Each whale trade generates a comprehensive markdown report with structured multi-step analysis:

Full example: docs/examples/sample_report.md

Report Structure

======================================================================
# Whale Trade Analysis Report
======================================================================

┌─ Trade Summary ─────────────────────────────────────────────────────┐
│  Market, trade size, direction, price, odds, time, trader rank     │
└─────────────────────────────────────────────────────────────────────┘

┌─ Step 2: Trade Signal Analysis ─────────────────────────────────────┐
│  Trader profile: rank, PnL, avg size, large trade ratio            │
│  Domain expertise detection, trade timing analysis                  │
└─────────────────────────────────────────────────────────────────────┘

┌─ Step 3: Event-Related Position Analysis ───────────────────────────┐
│  Cross-market positions, roll-forward detection                     │
│  Loss recovery patterns, hedge identification                       │
└─────────────────────────────────────────────────────────────────────┘

┌─ Step 4: Market Long/Short Analysis ────────────────────────────────┐
│  Top 5 bulls & bears with rankings and PnL                          │
│  Smart money consensus assessment                                   │
└─────────────────────────────────────────────────────────────────────┘

┌─ Step 5: Information Gap Analysis ──────────────────────────────────┐
│  Public information audit (web, Twitter, Telegram)                  │
│  Market pricing efficiency check                                    │
│  Non-public information evidence search                             │
└─────────────────────────────────────────────────────────────────────┘

┌─ Step 6: Historical Pattern ────────────────────────────────────────┐
│  Trader's past bets on related events                               │
│  Strategy pattern recognition (laddering, hedging, etc.)            │
└─────────────────────────────────────────────────────────────────────┘

┌─ Step 7: Information Asymmetry Assessment ──────────────────────────┐
│  Score (0–1), trader credibility, evidence, reasoning               │
│  Multi-factor summary table with signal strength                    │
│  Recommended action: BUY / HOLD / PASS                              │
└─────────────────────────────────────────────────────────────────────┘

Example Summary Table

Daily briefings are generated at 10:00 AM local time and emailed automatically.

Full example: docs/examples/sample_briefing.md

Includes:

• High-confidence signals (IAS >= 60%) with full analysis summaries
• Fallback: top 5 signals by score if none reach the threshold
• Abnormal price volatility alerts
• Historical signal performance — win rate and ROI by confidence tier

Quick Start

One-Click Setup

git clone https://github.com/chaoleiyv/polymarket-whale-watcher.git
cd polymarket-whale-watcher
chmod +x setup.sh && ./setup.sh

The setup script will:

1. Check Python 3.10+ is installed
2. Create a virtual environment
3. Install all dependencies
4. Create .env from template

Then add your API key and start:

# Add your Gemini API key (the only required key)
echo "GEMINI_API_KEY=your_key_here" >> .env

# Activate the environment and run
source .venv/bin/activate
python -m src.main run

Get a free Gemini API key: https://aistudio.google.com/apikey

Docker

docker build -t whale-watcher .
docker run --env-file .env -v ./data:/app/data -v ./reports:/app/reports whale-watcher

How It Works

flowchart LR
    A[Polymarket API] --> B[Market Fetcher]
    B --> C[700+ Tiered Markets]
    C --> D[Trade Monitor]
    D --> E{Whale\nTrade?}
    E -->|No| D
    E -->|Yes| F[Anomaly Detector]
    F --> G{Score >= 0.65?}
    G -->|No| D
    G -->|Yes| H[LLM Analyzer]
    H --> I[14 Research Tools]
    I --> J[Signal + Report]
    J --> K[Resolution Tracker]
    K --> L[Dashboard + Email]

Pipeline

Features

14 LLM Research Tools

The LLM agent autonomously selects and chains these tools during its multi-round investigation:

Sample Report

Every whale trade produces a structured multi-step report. Here's a condensed view:

======================================================================
# Whale Trade Analysis Report
======================================================================

Trade Summary
  Market: US x Iran diplomatic meeting by June 30, 2026?
  Size: $9,600 USDC  |  Direction: BUY Yes (71.4%)  |  Trader: #1733

Step 2: Trade Signal Analysis
  → Mid-tier trader, $84K PnL, Iran geopolitics specialist
  → Trade size ($9.6K) matches avg ($10K) — routine, not exceptional

Step 3: Event-Related Position Analysis            ← KEY FINDING
  → Losing -$6,508 on earlier "May 15 meeting" market (15.5% odds)
  → This trade is a thesis roll-forward, not a fresh insider bet

Step 4: Market Long/Short Analysis
  → Biggest Yes holder is a chronic loser (PnL: -$5.5M) — red flag
  → One elite trader (Rank #278) also long — modest support

Step 5: Information Gap Analysis
  → All supporting info widely reported in mainstream media
  → Market at 69.5% — already fairly priced

Step 6: Historical Pattern
  → "Timeline ladder" strategy across multiple Iran-related deadlines

Step 7: Information Asymmetry Assessment
  → Score: 0.32 (LOW)  |  Credibility: MEDIUM
  → Verdict: Thesis continuation / loss recovery — HOLD/PASS

======================================================================

Full report: docs/examples/sample_report.md

Configuration

Copy .env.example to .env and configure:

Required

Optional (enhances analysis quality)

Commands

# Core
python -m src.main run [--debug]              # Start monitoring
python -m src.main check-markets --limit 20   # View trending markets

# Analysis
python -m src.main test-analyze <market_id>   # Test LLM on a specific market

# Reports
python -m src.main briefing --today           # Generate today's briefing
python -m src.main briefing --date 2026-04-17 # Briefing for a specific date

# Dashboard
python -m src.main dashboard --port 8000      # Start web dashboard

# Maintenance
python -m src.main migrate                    # Migrate legacy JSON to SQLite

Dashboard

python -m src.main dashboard
# Open http://localhost:8000

The dashboard shows:

• Overall signal statistics (total signals, win rate, avg ROI)
• Performance breakdown by confidence tier
• Top best/worst signals by theoretical ROI
• Paginated signal history

Architecture

                    ┌──────────────────────────────┐
                    │     Polymarket Gamma API      │
                    │   (all active markets)        │
                    └──────────────┬───────────────┘
                                   │
                    ┌──────────────▼───────────────┐
                    │        Market Fetcher         │
                    │  Tier1: >$500K  (15s poll)    │
                    │  Tier2: >$10K   (60s poll)    │
                    │  Tier3: >$1K    (300s poll)   │
                    └──────────────┬───────────────┘
                                   │
              ┌────────────────────▼────────────────────┐
              │       Trade Monitor (async, 700+)       │
              │   Official Polymarket data-api           │
              │   Per-market parallel tasks              │
              │   Pool: 50 connections, 120s timeout     │
              └────────────────────┬────────────────────┘
                                   │
              ┌────────────────────▼────────────────────┐
              │          Pre-filter + Scoring            │
              │  $5K+ size, 0.10-0.90 price, conviction │
              │  5-factor anomaly score >= 0.65          │
              └────────────────────┬────────────────────┘
                                   │
              ┌────────────────────▼────────────────────┐
              │     LLM Analyzer — 7-Step Pipeline      │
              │   14 tools · up to 3 rounds             │
              ├──────────┬────────┬────────┬────────────┤
              │ Twitter  │  Web   │ DeFi   │  On-Chain  │
              │ Telegram │ Search │ Crypto │ Legislation│
              └──────────┴───┬────┴────────┴────────────┘
                             │
              ┌──────────────▼─────────────────────────┐
              │     Signal Storage (SQLite)             │
              │  → Resolution Tracker (every 30min)    │
              │  → Daily Briefing (10:00 AM + email)   │
              │  → Email Alerts (IAS >= 60%)           │
              │  → Dashboard (FastAPI)                 │
              └────────────────────────────────────────┘

Project Structure

src/
├── config/settings.py              # Environment configuration (Pydantic)
├── models/                         # Data models
│   ├── market.py                   # Market, TrendingMarket
│   ├── trade.py                    # TradeActivity, WhaleTrade, TraderRanking
│   ├── decision.py                 # TradeRecommendation, LLMDecision
│   └── anomaly_signal.py           # AnomalySignal (stored signal)
├── services/                       # Business logic
│   ├── market_fetcher.py           # Polymarket Gamma API (tiered market selection)
│   ├── trade_monitor.py            # Per-market parallel monitoring (official API)
│   ├── anomaly_detector.py         # 5-factor anomaly scoring
│   ├── llm_analyzer.py             # LLM with tool-use (14 tools, 3 rounds)
│   ├── tools.py                    # Tool registry
│   ├── resolution_tracker.py       # Market resolution checking
│   ├── stats_engine.py             # Performance statistics
│   ├── daily_briefing.py           # Daily summary generation + email
│   ├── twitter_search.py           # Twitter API search
│   ├── telegram_search.py          # Telegram channel monitoring
│   ├── web_search.py               # Tavily/Serper/DuckDuckGo search
│   ├── coingecko.py                # Crypto prices and market data
│   ├── defillama.py                # DeFi TVL, revenue, token unlocks
│   ├── fred.py                     # FRED macroeconomic data
│   ├── polygon.py                  # Stock/ETF prices and news
│   ├── etherscan.py                # On-chain data (Polygon, Etherscan V2)
│   └── congress.py                 # US legislation data
├── prompts/                        # LLM system prompts
│   ├── whale_analyzer.py           # Whale trade analysis prompt
│   └── volatility_analyzer.py      # Price volatility analysis prompt
├── db/database.py                  # SQLite signal storage
└── main.py                         # CLI entry point (Typer)

Disclaimer

This system is for research and educational purposes only. Prediction market trading involves significant risk. The information asymmetry scores and analyses are AI-generated estimates — not financial advice. Always conduct your own research and verify independently before making any trading decisions.