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

| Factor | Assessment | Signal | |--------|-----------|--------| | Trader Rank/PnL | Rank #1733, $84K PnL | Moderate | | Trade Size vs. Normal | ~$9.6K vs. avg $10K | Routine — neutral | | Related Position | Heavy loser on May 15 market (-$6.5K) | Suppresses signal | | Domain Expertise | Iran geopolitics specialist | Supportive | | Public Info Coverage | Extensive public news | Reduces asymmetry | | Smart Money Bulls | Rank #278 also long | Modest support | | Overall | Thesis continuation, not insider signal | Low-Medium |

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

| Stage | What Happens | |-------|-------------| | 1. Market Selection | Fetches all active markets from Polymarket Gamma API, classifies into 3 tiers by 24h volume, adds token launch markets. Refreshes every 15 minutes. | | 2. Trade Monitoring | Parallel async tasks per market (700+), polls official Polymarket data-api for new taker BUY trades, deduplicates by transaction hash. Connection pool: 50 connections, 120s timeout. | | 3. Whale Pre-filter | Price range 0.10–0.90, $5K hard floor, dynamic threshold scaled by volume ($5K–$100K), conviction check (must pay above mid), resolution window 6h–90d. | | 4. Anomaly Scoring | 5-factor model (max 1.0): base confidence (0.50) + premium ratio (0.20) + signal cleanliness (0.10) + depth ratio (0.10) + cluster tier (0.10). Threshold: >= 0.65. | | 5. LLM Investigation | Builds rich context (trade + trader profile + event positions + market top holders + historical signals). LLM autonomously selects tools for up to 3 rounds. Produces structured 7-step analysis with information asymmetry score (0–1). | | 6. Signal Tracking | Resolution tracker checks every 30 min, validates signal correctness, computes theoretical ROI. Daily briefings at 10:00 AM, emailed to recipients. |

Features

| Feature | Description | |---------|-------------| | Tiered Market Monitoring | 700+ markets across 3 tiers: Tier1 (>$500K, 15s), Tier2 (>$10K, 60s), Tier3 (>$1K, 300s) | | 5-Factor Anomaly Detection | Premium ratio, signal cleanliness, depth ratio, cluster signals, base confidence | | 7-Step Deep Analysis | Trade signal → Event positions