by chaoleiyv
AI-powered whale trade surveillance for Polymarket — real-time monitoring of 700+ markets, 14 autonomous research tools, 7-step deep analysis with information asymmetry scoring.
# Add to your Claude Code skills
git clone https://github.com/chaoleiyv/polymarket-whale-watcherGuides for using ai agents skills like polymarket-whale-watcher.
Last scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T15:37:20.326Z",
"npmAuditRan": true,
"pipAuditRan": true
}polymarket-whale-watcher is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by chaoleiyv. AI-powered whale trade surveillance for Polymarket — real-time monitoring of 700+ markets, 14 autonomous research tools, 7-step deep analysis with information asymmetry scoring. It has 211 GitHub stars.
Yes. polymarket-whale-watcher passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/chaoleiyv/polymarket-whale-watcher" and add it to your Claude Code skills directory (see the Installation section above).
polymarket-whale-watcher is primarily written in Python. It is open-source under chaoleiyv on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh polymarket-whale-watcher against similar tools.
No comments yet. Be the first to share your thoughts!
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
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.
$ 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
======================================================================
# 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 │
└─────────────────────────────────────────────────────────────────────┘
| 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:
git clone https://github.com/chaoleiyv/polymarket-whale-watcher.git
cd polymarket-whale-watcher
chmod +x setup.sh && ./setup.sh
The setup script will:
.env from templateThen 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 build -t whale-watcher .
docker run --env-file .env -v ./data:/app/data -v ./reports:/app/reports whale-watcher
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]
| 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. |
| 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 |