gavindiaz/polymarket-whale-watcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Upgrade README to product-grade with 7-step analysis showcase and real report format

Browse Source 
- Redesign README with polished badges, structured report preview, collapsible config sections
- Update sample report to match actual 7-step deep analysis output (trade signal, event positions, long/short, info gap, historical pattern, asymmetry score)
- Add new whale trade report (US x Iran diplomatic meeting)
- Update signals database with latest data

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
SII-leiyu
2026-05-05 00:11:10 +08:00
parent 9eab3485a1
commit 3de7cd3373
7 changed files with 526 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+265 -149
View File
@@ -1,36 +1,42 @@
<div align="center">
# Polymarket Whale Watcher
# 🐋 Polymarket Whale Watcher
**AI-powered whale trade surveillance for Polymarket prediction markets**
**AI-Powered Whale Trade Intelligence for Polymarket Prediction Markets**
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Polymarket](https://img.shields.io/badge/Polymarket-Official_API-purple.svg)](https://docs.polymarket.com/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg?style=for-the-badge)](LICENSE)
[![Polymarket](https://img.shields.io/badge/Polymarket-API-8B5CF6.svg?style=for-the-badge)](https://docs.polymarket.com/)
[![Gemini](https://img.shields.io/badge/Gemini-LLM-4285F4.svg?style=for-the-badge&logo=google&logoColor=white)](https://aistudio.google.com/)
Real-time monitoring | Tiered market coverage | LLM investigation with 14 autonomous tools | Signal accuracy tracking
<br/>
[Quick Start](#-quick-start) | [How It Works](#-how-it-works) | [Features](#-features) | [Configuration](#-configuration) | [Dashboard](#-dashboard)
**Real-time monitoring** of 700+ markets &nbsp;·&nbsp; **14 autonomous research tools** &nbsp;·&nbsp; **Multi-step deep analysis** &nbsp;·&nbsp; **Signal accuracy tracking**
<br/>
[Quick Start](#-quick-start) &nbsp;&nbsp;|&nbsp;&nbsp; [How It Works](#-how-it-works) &nbsp;&nbsp;|&nbsp;&nbsp; [Sample Report](#-sample-report) &nbsp;&nbsp;|&nbsp;&nbsp; [Configuration](#%EF%B8%8F-configuration) &nbsp;&nbsp;|&nbsp;&nbsp; [Dashboard](#-dashboard)
---
<img width="720" alt="pipeline" src="https://img.shields.io/badge/Tiered_Markets_(700+)→Whale_Detection→Anomaly_Scoring→LLM_Investigation→Signal_Tracking-000?style=flat-square&labelColor=000"/>
</div>
---
<br/>
## What It Does
Whale Watcher continuously monitors **700+ active Polymarket markets** across three volume tiers, detects large trades with anomalous patterns, and uses an LLM agent with **14 autonomous research tools** to investigate whether the trader may possess an information advantage. It tracks signal accuracy over time, generates daily briefings, and sends real-time email alerts for high-confidence signals.
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.
```
Tiered Markets → Whale Detection → Anomaly Scoring → LLM Investigation → Signal Tracking
(700+) ($5k-$100k+) (5 dimensions) (14 tools, 3 rounds) (win rate, ROI)
```
<br/>
---
## Demo
## Live Demo
<details open>
<summary><b>Terminal Output</b> — Real-time whale detection and analysis</summary>
<summary><strong>Terminal Output</strong> — Real-time whale detection and analysis</summary>
<br/>
```
$ python -m src.main run
@@ -46,58 +52,122 @@ Price Range: 0.1 - 0.9
Tiered monitoring: Tier1=8 (>500K), Tier2=198 (>10K), Tier3=559 (>1K)
[22:05:14] WHALE TRADE DETECTED!
Amount: $5,000.00 USDC
[23:41:12] WHALE TRADE DETECTED!
Amount: $9,600.00 USDC
Side: BUY Yes
Price: 0.7962
Market: Over $20M committed to the Printr public sale?
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("Printr public sale Sonar raise commitments")
→ search_twitter("Printr PRINT token sale commitments")
→ search_telegram("Printr public sale Sonar raise")
→ 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("Printr PRINT token sale total raised April 28")
→ search_twitter("Printr sale oversubscribed April 28")
→ 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.22 (LOW)
Trader Credibility: LOW (#2650076, PnL: -$207K)
Report saved: reports/20260428/...
Information Asymmetry Score: 0.32 (LOW)
Trader Credibility: MEDIUM (#1733, PnL: $84K)
Verdict: Thesis continuation / loss recovery — HOLD/PASS
Report saved: reports/20260504/...
```
</details>
<br/>
<details>
<summary><b>Analysis Report</b> — LLM investigation with autonomous tool-use</summary>
<summary><strong>Sample Report</strong> — 7-Step Deep Analysis (click to expand)</summary>
Each whale trade generates a detailed markdown report:
<br/>
- **Trade details** — amount, direction, price, trader wallet
- **Trader profile** — leaderboard rank, PnL, history, recent trades
- **Event positions** — whale's positions across related markets (hedge detection)
- **Market top holders** — Top 5 buyers/sellers with rankings
- **LLM investigation** — autonomous tool calls (web, Twitter, Telegram, on-chain, DeFi)
- **Information asymmetry assessment** — score, evidence, reasoning
Each whale trade generates a comprehensive markdown report with structured multi-step analysis:
See full example: [docs/examples/sample_report.md](docs/examples/sample_report.md)
> **Full example**: [docs/examples/sample_report.md](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** |
</details>
<br/>
<details>
<summary><b>Daily Briefing</b> — Automated intelligence summary</summary>
<summary><strong>Daily Briefing</strong> — Automated intelligence summary</summary>
Daily briefings are generated at 10:00 AM local time and emailed automatically. They include:
- High-confidence signals (IAS >= 60%) with full analysis
- Fallback: top 5 signals by score if none reach 60%
- Price volatility alerts
- Historical signal performance (win rate, ROI by confidence tier)
<br/>
See full example: [docs/examples/sample_briefing.md](docs/examples/sample_briefing.md)
Daily briefings are generated at **10:00 AM local time** and emailed automatically.
> **Full example**: [docs/examples/sample_briefing.md](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
</details>
<br/>
---
## Quick Start
@@ -138,33 +208,6 @@ docker run --env-file .env -v ./data:/app/data -v ./reports:/app/reports whale-w
---
## Features
| Feature | Description |
|---------|-------------|
| **Tiered Market Monitoring** | 700+ markets across 3 tiers: Tier1 (>$500K, 15s), Tier2 (>$10K, 60s), Tier3 (>$1K, 300s) |
| **Anomaly Detection** | 5-factor scoring: premium ratio, signal cleanliness, depth ratio, cluster signals, base confidence |
| **Trader Profiling** | Leaderboard ranking, PnL, trading history, event positions, market top holders |
| **LLM Analysis** | 14 autonomous tools across up to 3 rounds of investigation |
| **Signal Tracking** | Automatic market resolution checking every 30 min, win rate stats by confidence tier |
| **Daily Briefing** | Automated 10:00 AM summary with high-confidence signals, emailed to configured recipients |
| **Email Alerts** | Real-time notifications for high information-asymmetry signals (>= 60%) |
| **Web Dashboard** | FastAPI-based signal performance dashboard |
### 14 LLM Research Tools
The LLM agent autonomously selects and uses these tools during investigation:
| Category | Tools |
|----------|-------|
| **Social Sentiment** | `search_twitter`, `search_telegram`, `search_web` |
| **Crypto Data** | `get_crypto_price`, `get_crypto_market_overview`, `get_protocol_tvl`, `get_token_unlocks`, `get_protocol_revenue` |
| **Financial Data** | `get_stock_price`, `get_stock_news`, `get_economic_data` |
| **On-Chain** | `get_wallet_transfers`, `get_contract_info` |
| **Legislation** | `get_bill_status`, `get_recent_legislation` |
---
## How It Works
```mermaid
@@ -172,7 +215,7 @@ flowchart LR
A[Polymarket API] --> B[Market Fetcher]
B --> C[700+ Tiered Markets]
C --> D[Trade Monitor]
D --> E{Whale Trade?}
D --> E{Whale\nTrade?}
E -->|No| D
E -->|Yes| F[Anomaly Detector]
F --> G{Score >= 0.65?}
@@ -181,33 +224,90 @@ flowchart LR
H --> I[14 Research Tools]
I --> J[Signal + Report]
J --> K[Resolution Tracker]
K --> L[Stats Dashboard]
K --> L[Dashboard + Email]
```
### Pipeline
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.
| 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. |
2. **Trade Monitoring** — Runs parallel async tasks per market (one task per market), polls official Polymarket data-api for new taker BUY trades, deduplicates by transaction hash. Connection pool tuned for 700+ concurrent markets.
---
3. **Whale Pre-filter** — Multi-layer filter chain:
- Price range: 0.10 - 0.90
- Minimum size: $5,000 hard floor
- Dynamic threshold: $10K base, scaled by market volume (floor $5K, cap $100K)
- Conviction check: must pay above market mid price
- Resolution window: 6 hours to 90 days
## Features
4. **Anomaly Scoring** — 5-factor model (max 1.0):
- Base confidence: 0.50
- Premium-to-threshold ratio: +0.20
- Signal cleanliness (conviction): +0.10
- Depth ratio (size vs liquidity): +0.10
- Cluster tier (repeated same-direction): +0.10
- Threshold: >= 0.65 to trigger LLM analysis
| 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 → Long/short mapping → Info gap → Historical pattern → Asymmetry score |
| **14 Autonomous Research Tools** | Web, Twitter, Telegram, crypto, DeFi, stocks, on-chain, legislation |
| **Cross-Market Position Analysis** | Detects roll-forwards, hedges, and loss recovery patterns across related markets |
| **Signal Accuracy Tracking** | Auto resolution checking every 30 min, win rate stats by confidence tier |
| **Daily Briefings** | 10:00 AM automated summary with high-confidence signals, emailed to recipients |
| **Real-time Email Alerts** | Instant notifications for high information-asymmetry signals (>= 60%) |
| **Web Dashboard** | FastAPI-based signal performance dashboard with ROI breakdowns |
5. **LLM Investigation** — Builds rich context (trade + trader profile + event positions + market top holders + historical signals), LLM autonomously uses tools for up to 3 rounds, produces structured assessment with information asymmetry score (0-1).
### 14 LLM Research Tools
6. **Signal Tracking** — Resolution tracker checks every 30 minutes for resolved markets, validates signal correctness, computes theoretical ROI. Daily briefings generated at 10:00 AM and emailed.
The LLM agent autonomously selects and chains these tools during its multi-round investigation:
| Category | Tools | Use Case |
|----------|-------|----------|
| **Social & Sentiment** | `search_twitter` · `search_telegram` · `search_web` | Public sentiment, insider chatter, news coverage |
| **Crypto & DeFi** | `get_crypto_price` · `get_crypto_market_overview` · `get_protocol_tvl` · `get_token_unlocks` · `get_protocol_revenue` | Token prices, TVL, unlocks, protocol health |
| **Financial Data** | `get_stock_price` · `get_stock_news` · `get_economic_data` | Equities, ETFs, macro indicators |
| **On-Chain** | `get_wallet_transfers` · `get_contract_info` | Wallet activity, contract deployments |
| **Legislation** | `get_bill_status` · `get_recent_legislation` | US bills, regulatory actions |
---
## 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](docs/examples/sample_report.md)
---
@@ -221,7 +321,10 @@ Copy `.env.example` to `.env` and configure:
|----------|-------------|--------|
| `GEMINI_API_KEY` | LLM API key for analysis | [Google AI Studio](https://aistudio.google.com/apikey) |
### Optional (enhances analysis)
### Optional (enhances analysis quality)
<details open>
<summary><strong>Data Source API Keys</strong></summary>
| Variable | Description | Get It |
|----------|-------------|--------|
@@ -234,7 +337,10 @@ Copy `.env.example` to `.env` and configure:
| `CONGRESS_API_KEY` | US legislation data | [congress.gov](https://api.congress.gov/) |
| `TELEGRAM_API_ID` / `TELEGRAM_API_HASH` | Telegram channel monitoring | [my.telegram.org](https://my.telegram.org) |
### LLM Settings
</details>
<details>
<summary><strong>LLM Settings</strong></summary>
| Variable | Default | Description |
|----------|---------|-------------|
@@ -242,7 +348,10 @@ Copy `.env.example` to `.env` and configure:
| `LLM_BASE_URL` | Google AI endpoint | OpenAI-compatible API base URL |
| `LLM_TEMPERATURE` | `0` | LLM temperature |
### Whale Detection Tuning
</details>
<details>
<summary><strong>Whale Detection Tuning</strong></summary>
| Variable | Default | Description |
|----------|---------|-------------|
@@ -250,7 +359,10 @@ Copy `.env.example` to `.env` and configure:
| `MIN_PRICE` / `MAX_PRICE` | `0.10` / `0.90` | Price range filter |
| `FETCH_INTERVAL_SECONDS` | `10` | Default polling interval |
### Tiered Market Monitoring
</details>
<details>
<summary><strong>Tiered Market Monitoring</strong></summary>
| Variable | Default | Description |
|----------|---------|-------------|
@@ -262,7 +374,10 @@ Copy `.env.example` to `.env` and configure:
| `TIER2_POLL_INTERVAL` | `60` | Tier 2 polling interval (seconds) |
| `TIER3_POLL_INTERVAL` | `300` | Tier 3 polling interval (seconds) |
### Email Alerts
</details>
<details>
<summary><strong>Email Alerts</strong></summary>
| Variable | Default | Description |
|----------|---------|-------------|
@@ -271,6 +386,8 @@ Copy `.env.example` to `.env` and configure:
| `EMAIL_PASSWORD` | — | Sender email password (app password) |
| `EMAIL_RECIPIENT` | — | Comma-separated recipient emails |
</details>
---
## Commands
@@ -298,8 +415,6 @@ python -m src.main migrate # Migrate legacy JSON to SQLite
## Dashboard
Start the web dashboard to view signal performance:
```bash
python -m src.main dashboard
# Open http://localhost:8000
@@ -313,6 +428,53 @@ The dashboard shows:
---
## 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
```
@@ -350,60 +512,14 @@ src/
---
## 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 (14 tools) │
│ Up to 3 rounds of investigation │
│ max_tokens: 4096 │
├─────────┬────────┬────────┬─────────────┤
│ 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) │
└────────────────────────────────────────┘
```
---
## Disclaimer
This system is for research and educational purposes. Prediction market trading involves significant risk. The information asymmetry scores and analyses are AI-generated estimates, not financial advice. Always verify independently.
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.
---
## License
<div align="center">
MIT
**MIT License** &nbsp;·&nbsp; Built with Polymarket API + Gemini
</div>
data/signals.db
BIN
View File
Binary file not shown.
data/signals.db-shm
BIN
View File
Binary file not shown.
data/signals.db-wal
View File
docs/examples/sample_report.md
+117 -68
View File
@@ -1,90 +1,139 @@
======================================================================
# Whale Trade Analysis Report
======================================================================
**Market**: Will MegaETH launch a token by June 30, 2026?
**Generated at**: 2026-05-04 16:00:00 UTC
**Generated**: 2026-04-15 14:23:07 UTC
## Trade Summary
| Field | Details |
|-------|---------|
| **Market** | US x Iran diplomatic meeting by June 30, 2026? |
| **Trade Size** | $9,600.00 USDC |
| **Direction** | BUY Yes Token (Bullish) |
| **Trade Price** | 0.7142 (71.4%) |
| **Current Odds** | Yes: 69.5% | No: 30.5% |
| **Trade Time** | 2026-05-04 23:41:12 |
| **Trader Rank** | #1733 (PnL: $84,695.33) |
======================================================================
## Full Analysis Report
### Step 2: Trade Signal Analysis
**Trader Profile Assessment:**
- **Rank #1733** — mid-tier experienced trader, not top-tier elite
- **PnL: $84,695** — solid positive track record across ~$4M lifetime volume
- **Avg trade size: $10,018** — this $9,600 trade is perfectly in-line with his normal size, not an unusual outlier
- **Large trade ratio: 66%** — consistent whale behavior, large trades are routine for this trader
- **Domain expertise: Strong Iran/geopolitics focus** — recent trades include Iranian regime fall (April/June), US-Iran meetings (April/June), Russia-Ukraine ceasefire, Ukraine Donbas. This is clearly a geopolitics specialist with deep focus on Iran specifically.
**Trade Timing:** The trade was made at 23:41 UTC on May 4, 2026. Given the active diplomatic situation, this is a routine positioning trade, not an oddly-timed pre-announcement bet.
---
## Whale Trade Anomaly Detection Report
### Step 3: Event-Related Position Analysis
### Trade Details
- **Trade amount**: $92,336.00 USDC
- **Trade direction**: BUY Yes Token (Bullish)
- **Buy price**: 0.4200 (~2.4x odds)
- **Trade time**: 2026-04-15 14:22:41 UTC
- **Trader wallet**: 0x7a3b...f91e
The whale has a **losing position** in the earlier "US x Iran diplomatic meeting by May 15, 2026?" market:
- Holding Yes tokens @ avg 65.29%, now priced at **15.50%**
- Cost basis: $8,534 | Current value: $2,026 | **PnL: -$6,508 (LOSS)**
### Anomaly Score
- **Overall score**: 0.78/1.00
- **Score breakdown**:
Absolute size: 0.85 | Relative to market: 0.72 | Price uncertainty: 0.68 | Time of day: 0.45 | Trader deviation: 0.91 | Cluster signal: 0.30
### Trade Interpretation
- **Direction**: Trader bought Yes Token @ 0.4200 — Bullish (believes event will occur)
### Trader Ranking (PnL Leaderboard)
- **Rank**: #47 (Period: all-time)
- **Cumulative PnL**: $284,521.00
- **Volume**: $1,892,340.00
- **Username**: Anonymous
- **Verification**: Unverified
### Trader History
- **Recent Trades**: 156
- **Recent Volume**: $743,210.00 USDC
- **Avg Trade Size**: $4,764.17 USDC
- **Large Trades** (>=$5000): 42
- **Active Markets**: MegaETH token launch, EdgeX FDV, Billions FDV, US forces enter Iran, Hungary PM
**Recent Large Trade Details**:
1. BUY $23,015.00 @ 0.3800 - MegaETH market cap FDV 1B one day...
2. BUY $15,000.00 @ 0.4100 - MegaETH market cap FDV 600M one d...
3. BUY $8,200.00 @ 0.5500 - EdgeX FDV above 500M one day after...
This is critical context:
1. The trader **bet heavily on a May 15 meeting** and that bet is **nearly dead** (15.5% odds)
2. The June 30 buy ($9,600) appears to be a **portfolio roll-forward** — doubling down on the same thesis with a later deadline to recoup losses
3. This is NOT a fresh, confident insider bet — it's a **loss recovery / thesis extension trade**
4. The pattern suggests the trader is sticking to a bullish Iran-diplomacy thesis despite being wrong on the nearer-term deadline
---
## LLM Investigation
### Step 4: Market Long/Short Analysis
### Tools Used
1. **search_web** — "MegaETH token launch date 2026"
2. **search_twitter** — "MegaETH $METH token TGE"
3. **get_protocol_tvl** — "megaeth"
4. **get_contract_info** — "0x4f9b...2a1c" (MegaETH deployer)
5. **search_telegram** — "MegaETH launch"
**Bulls (Yes side):**
- **anoin123** (Rank #2,682,942, PnL **-$5.54M**) — massive loser, leads the Yes side with $39K. This is a **red flag** — the biggest Yes holder is a chronic loser
- **ArmageddonRewardsBilly** (Rank #278, PnL $525K) — elite trader, $11K on Yes. This is the strongest bull signal
- **cezarn132** (the whale) — Rank #1733, $9.3K Yes
### Key Findings
**Bears (No side):**
- **aaron107** (Rank #48,390) — low-ranked, leads No
- **yungstalin** (Rank #1,969, PnL $73,759) — solid mid-tier trader on No side
**Web Search**: No official token launch announcement found. MegaETH blog (April 12) mentions "testnet phase 3 completion" but no TGE timeline.
**Twitter**: Multiple crypto KOLs discussing potential token launch. @cryptoinsider (42K followers) posted 3 hours ago: "Hearing MegaETH team is finalizing tokenomics. Could be sooner than people think." — This post preceded the whale trade.
**On-Chain**: MegaETH deployer wallet (0x4f9b...2a1c) deployed a new ERC-20 contract 6 hours ago. Contract is verified but not yet publicly linked to any token.
**Telegram**: WuBlockchain channel shared a rumor about "major L2 token launch in Q2" without naming the project. Multiple replies speculating it's MegaETH.
**TVL**: MegaETH TVL = $847M (+12% 7d), indicating growing ecosystem activity.
**Smart Money Consensus:** Mixed. One elite trader (Rank #278) is bullish, but the biggest Yes position belongs to a massive loser. The No side lacks elite concentration too. No clear smart money consensus signal in either direction.
---
### Step 5: Information Gap Analysis
**Public Information Summary:**
- There was already an indirect round of talks in Islamabad, Pakistan in late April 2026 (confirmed by Wikipedia)
- US envoy Steve Witkoff stated Washington is "in conversation" with Iran
- Iran's FM Araghchi has made public proposals for a 3-phase deal
- Market odds for June 30 meeting are ~69.5% — already well-priced for the optimistic scenario
- However, the **May 15 market is at just 15.5%**, showing markets believe a near-term meeting is unlikely
- Twitter data shows @faststocknewss noting "POLYMARKET ODDS OF A US-IRAN DIPLOMATIC MEETING ARE FADING" — the June 30 market was previously at 80%+ and has dropped to 66-69%
**Key Information Assessment:**
- All available information about Iran-US diplomacy is extensively covered in public media
- The market at 69.5% appears to **reasonably price** the known information
- No evidence of non-public information advantage — this appears to be public-information-based analysis
- The trade is consistent with this trader's established Iran geopolitics thesis
---
### Step 6: Historical Pattern
This trader has a **clear and consistent pattern**:
- Bought "Iranian regime fall by April 30" at 0.86 → **SOLD at 0.98** (big win)
- Bought "Iranian regime fall by June 30" at 0.76 and 0.74 → Still holding
- Bet on "US x Iran diplomatic meeting by April 25/May 15" → **LOSING** at 15.5%
The pattern suggests this trader uses a "timeline ladder" approach — betting on Iran-related events across multiple deadlines. When early deadlines miss, they roll to later ones. This reduces the information asymmetry signal significantly.
---
## Step 7: Information Asymmetry Assessment
```json
{
"information_asymmetry_score": 0.32,
"trader_credibility": "MEDIUM",
"reasoning": "Trader cezarn132 (Rank #1733, PnL $84K) is a confirmed geopolitics specialist with deep Iran-focused trading history. However, several factors suppress the information asymmetry score: (1) The $9,600 trade is exactly in-line with this trader's average trade size ($10K), making it routine rather than an exceptional conviction bet. (2) The trader currently holds a heavily losing position in the nearer 'May 15' meeting market (down $6,508), and this June 30 buy appears to be a thesis roll-forward/loss recovery strategy rather than a fresh insider signal. (3) All supporting information (Islamabad talks, Witkoff statements, Iranian proposals) is extensively public and already priced into the ~69.5% market odds.",
"insider_evidence": "No insider evidence found. All information supporting the bullish Iran diplomacy view is widely reported in mainstream media. The trade is most consistent with a thesis-continuation/loss-recovery strategy following a losing May 15 position."
}
```
---
### Summary Table
| Factor | Assessment | Signal Strength |
|--------|-----------|-----------------|
| 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 meeting (-$6.5K) | Suppresses signal |
| Domain Expertise | Iran geopolitics specialist | Supportive |
| Public Info Coverage | Extensive public news on US-Iran talks | Reduces asymmetry |
| Market Pricing | Already at 69.5% — well-priced | Reduces asymmetry |
| Smart Money Bulls | Rank #278 also long | Modest support |
| Biggest Yes Holder | Rank #2.6M, -$5.5M PnL | Negative signal |
| **Overall** | **Likely thesis continuation, not insider signal** | **Low-Medium** |
**Recommended Action: HOLD/PASS** — This trade reflects a geopolitics analyst rolling forward a losing thesis rather than a trader acting on non-public information.
======================================================================
## Information Asymmetry Assessment
======================================================================
| Metric | Value |
|--------|-------|
| **Information Asymmetry Score** | **0.72** |
| **Trader Credibility** | HIGH |
| **Confidence** | 0.75 |
| **Recommended Action** | BUY Yes |
| Field | Assessment |
|-------|------------|
| **Information Asymmetry** | Low Information Asymmetry (32%) |
| **Trader Credibility** | Medium Credibility (#1733) |
### Evidence
- High-ranked trader (#47) with strong PnL ($284K) making concentrated bets on MegaETH-related markets
- New smart contract deployed by MegaETH team 6 hours before trade — not yet public knowledge
- KOL tweets about insider knowledge preceded the trade by ~3 hours
- Trader's recent history shows 3 consecutive large buys on MegaETH markets at increasing prices (0.38 → 0.41 → 0.42)
**Key Evidence**: No insider evidence found. All information supporting the bullish Iran diplomacy view is widely reported in mainstream media. The trade is most consistent with a thesis-continuation/loss-recovery strategy following a losing May 15 position.
### Reasoning
The combination of a newly deployed (unannounced) smart contract, insider KOL chatter, and a high-ranked trader's aggressive accumulation pattern strongly suggests the trader has information about an imminent token launch. The information asymmetry score of 0.72 reflects multiple converging signals, though we cannot confirm the contract is the actual token contract.
**Reasoning**: Trader cezarn132 (Rank #1733, PnL $84K) is a confirmed geopolitics specialist with deep Iran-focused trading history. However, several factors suppress the information asymmetry score: (1) routine trade size, (2) losing position on nearer deadline, (3) extensive public information coverage, (4) declining market odds, (5) mixed smart money picture, (6) large geopolitical market with many participants.
---
*Disclaimer: This analysis is for research purposes only and does not constitute investment advice.*
======================================================================
Disclaimer: This report is AI-generated for informational purposes only and does not constitute investment advice.
======================================================================
reports/20260505/20260505_000000_BUY_9599USD_US_x_Iran_diplomatic_meeting_by_June_30_2026.md
+143
View File
@@ -0,0 +1,143 @@
======================================================================
# Whale Trade Analysis Report
======================================================================
**Generated at**: 2026-05-04 16:00:00 UTC
## Trade Summary
| Field | Details |
|-------|---------|
| **Market** | US x Iran diplomatic meeting by June 30, 2026? |
| **Trade Size** | $9,600.00 USDC |
| **Direction** | BUY Yes Token (Bullish) |
| **Trade Price** | 0.7142 (71.4%) |
| **Current Odds** | Yes: 69.5% | No: 30.5% |
| **Trade Time** | 2026-05-04 23:41:12 |
| **Trader Rank** | #1733 (PnL: $84,695.33) |
======================================================================
I have comprehensive data. Let me now conduct a thorough analysis.
---
## Full Analysis Report
### Step 2: Trade Signal Analysis
**Trader Profile Assessment:**
- **Rank #1733** — mid-tier experienced trader, not top-tier elite
- **PnL: $84,695** — solid positive track record across ~$4M lifetime volume
- **Avg trade size: $10,018** — this $9,600 trade is perfectly in-line with his normal size, not an unusual outlier
- **Large trade ratio: 66%** — consistent whale behavior, large trades are routine for this trader
- **Domain expertise: Strong Iran/geopolitics focus** — recent trades include Iranian regime fall (April/June), US-Iran meetings (April/June), Russia-Ukraine ceasefire, Ukraine Donbas. This is clearly a geopolitics specialist with deep focus on Iran specifically.
**Trade Timing:** The trade was made at 23:41 UTC on May 4, 2026. Given the active diplomatic situation, this is a routine positioning trade, not an oddly-timed pre-announcement bet.
---
### Step 3: Event-Related Position Analysis — 🚨 KEY FINDING
The whale has a **losing position** in the earlier "US x Iran diplomatic meeting by May 15, 2026?" market:
- Holding Yes tokens @ avg 65.29%, now priced at **15.50%**
- Cost basis: $8,534 | Current value: $2,026 | **PnL: -$6,508 (LOSS)**
This is critical context:
1. The trader **bet heavily on a May 15 meeting** and that bet is **nearly dead** (15.5% odds)
2. The June 30 buy ($9,600) appears to be a **portfolio roll-forward** — doubling down on the same thesis with a later deadline to recoup losses
3. This is NOT a fresh, confident insider bet — it's a **loss recovery / thesis extension trade**
4. The pattern suggests the trader is sticking to a bullish Iran-diplomacy thesis despite being wrong on the nearer-term deadline
---
### Step 4: Market Long/Short Analysis
**Bulls (Yes side):**
- **anoin123** (Rank #2,682,942, PnL **-$5.54M**) — massive loser, leads the Yes side with $39K. This is a **red flag** — the biggest Yes holder is a chronic loser
- **ArmageddonRewardsBilly** (Rank #278, PnL $525K) — elite trader, $11K on Yes. This is the strongest bull signal
- **cezarn132** (the whale) — Rank #1733, $9.3K Yes
**Bears (No side):**
- **aaron107** (Rank #48,390) — low-ranked, leads No
- **yungstalin** (Rank #1,969, PnL $73,759) — solid mid-tier trader on No side
**Smart Money Consensus:** Mixed. One elite trader (Rank #278) is bullish, but the biggest Yes position belongs to a massive loser. The No side lacks elite concentration too. No clear smart money consensus signal in either direction.
---
### Step 5: Information Gap Analysis
**Public Information Summary:**
- There was already an indirect round of talks in Islamabad, Pakistan in late April 2026 (confirmed by Wikipedia)
- US envoy Steve Witkoff stated Washington is "in conversation" with Iran
- Iran's FM Araghchi has made public proposals for a 3-phase deal
- Market odds for June 30 meeting are ~69.5% — already well-priced for the optimistic scenario
- However, the **May 15 market is at just 15.5%**, showing markets believe a near-term meeting is unlikely
- Twitter data shows @faststocknewss noting "POLYMARKET ODDS OF A US-IRAN DIPLOMATIC MEETING ARE FADING" — the June 30 market was previously at 80%+ and has dropped to 66-69%
**Key Information Assessment:**
- All available information about Iran-US diplomacy is extensively covered in public media
- The market at 69.5% appears to **reasonably price** the known information
- No evidence of non-public information advantage — this appears to be public-information-based analysis
- The trade is consistent with this trader's established Iran geopolitics thesis
---
### Step 6: Historical Pattern
This trader has a **clear and consistent pattern**:
- Bought "Iranian regime fall by April 30" at 0.86 → **SOLD at 0.98** (big win ✅)
- Bought "Iranian regime fall by June 30" at 0.76 and 0.74 → Still holding
- Bet on "US x Iran diplomatic meeting by April 25/May 15" → **LOSING** at 15.5%
The pattern suggests this trader uses a "timeline ladder" approach — betting on Iran-related events across multiple deadlines. When early deadlines miss, they roll to later ones. This reduces the information asymmetry signal significantly.
---
## Step 7: Information Asymmetry Assessment
```json
{
"information_asymmetry_score": 0.32,
"trader_credibility": "MEDIUM",
"reasoning": "Trader cezarn132 (Rank #1733, PnL $84K) is a confirmed geopolitics specialist with deep Iran-focused trading history. However, several factors suppress the information asymmetry score: (1) The $9,600 trade is exactly in-line with this trader's average trade size ($10K), making it routine rather than an exceptional conviction bet. (2) The trader currently holds a heavily losing position in the nearer 'May 15' meeting market (down $6,508), and this June 30 buy appears to be a thesis roll-forward/loss recovery strategy rather than a fresh insider signal. (3) All supporting information (Islamabad talks, Witkoff statements, Iranian proposals) is extensively public and already priced into the ~69.5% market odds. (4) The market was previously at 80%+ and has been declining — this is a contrarian hold, not a momentum play. (5) The smart money picture is mixed — the largest Yes holder is a chronic losing trader. (6) This is a large geopolitical market with many participants, where public analysis rather than non-public information drives most trades. The trader demonstrates domain expertise and pattern consistency, but no evidence of non-public information access.",
"insider_evidence": "No insider evidence found. All information supporting the bullish Iran diplomacy view (Islamabad round 1 talks, Witkoff statements, Iranian FM proposals, Oman mediation) is widely reported in mainstream media. The trade is most consistent with a thesis-continuation/loss-recovery strategy following a losing May 15 position, rather than a fresh signal based on non-public information."
}
```
---
### Summary Table
| Factor | Assessment | Signal Strength |
|--------|-----------|-----------------|
| 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 meeting (-$6.5K) | Suppresses signal ❌ |
| Domain Expertise | Iran geopolitics specialist | Supportive ✅ |
| Public Info Coverage | Extensive public news on US-Iran talks | Reduces asymmetry ❌ |
| Market Pricing | Already at 69.5% — well-priced | Reduces asymmetry ❌ |
| Smart Money Bulls | Rank #278 also long | Modest support ✅ |
| Biggest Yes Holder | Rank #2.6M, -$5.5M PnL | Negative signal ❌ |
| **Overall** | **Likely thesis continuation, not insider signal** | **Low-Medium** |
**Recommended Action: HOLD/PASS** — This trade reflects a geopolitics analyst rolling forward a losing thesis rather than a trader acting on non-public information. The market is already fairly priced at ~69.5% based on extensive public information about ongoing US-Iran diplomatic channels.
======================================================================
## Information Asymmetry Assessment
======================================================================
| Field | Assessment |
|-------|------------|
| **Information Asymmetry** | Low Information Asymmetry (32%) |
| **Trader Credibility** | Medium Credibility (#1733) |
**Key Evidence**: No insider evidence found. All information supporting the bullish Iran diplomacy view (Islamabad round 1 talks, Witkoff statements, Iranian FM proposals, Oman mediation) is widely reported in mainstream media. The trade is most consistent with a thesis-continuation/loss-recovery strategy following a losing May 15 position, rather than a fresh signal based on non-public information.
**Reasoning**: Trader cezarn132 (Rank #1733, PnL $84K) is a confirmed geopolitics specialist with deep Iran-focused trading history. However, several factors suppress the information asymmetry score: (1) The $9,600 trade is exactly in-line with this trader's average trade size ($10K), making it routine rather than an exceptional conviction bet. (2) The trader currently holds a heavily losing position in the nearer 'May 15' meeting market (down $6,508), and this June 30 buy appears to be a thesis roll-forward/loss recovery strategy rather than a fresh insider signal. (3) All supporting information (Islamabad talks, Witkoff statements, Iranian proposals) is extensively public and already priced into the ~69.5% market odds. (4) The market was previously at 80%+ and has been declining — this is a contrarian hold, not a momentum play. (5) The smart money picture is mixed — the largest Yes holder is a chronic losing trader. (6) This is a large geopolitical market with many participants, where public analysis rather than non-public information drives most trades. The trader demonstrates domain expertise and pattern consistency, but no evidence of non-public information access.
======================================================================
Disclaimer: This report is AI-generated for informational purposes only and does not constitute investment advice.
======================================================================
src/services/llm_analyzer.py
+1 -1
View File
@@ -275,7 +275,7 @@ class LLMAnalyzer:
call_kwargs = {
"model": self.settings.llm_model,
"messages": messages,
"max_tokens": 4096,
"max_tokens": 8192,
}
if tool_schemas and not is_last_round:
call_kwargs["tools"] = tool_schemas