Update README with complete system documentation
Rewrite README to reflect current architecture: 14 LLM tools, multi-dimensional anomaly detection, signal accuracy tracking, daily briefings, web dashboard, and all CLI commands. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
SII-leiyu
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
b1cf6c9d31
commit
9df88bcf89
@@ -1,138 +1,192 @@
|
|||||||
# Polymarket Whale Watcher
|
# Polymarket Whale Watcher
|
||||||
|
|
||||||
AI-powered whale trade detection and analysis bot for Polymarket prediction markets.
|
AI-powered whale trade surveillance and analysis system for Polymarket prediction markets. Combines real-time monitoring, multi-dimensional anomaly detection, LLM-driven investigation with 14 autonomous tools, and signal accuracy tracking.
|
||||||
|
|
||||||
## Overview
|
## Features
|
||||||
|
|
||||||
This bot combines the market monitoring approach from `polymarket-copy-trading-bot` with the AI analysis capabilities of `PolyMarket-trading-AI-model` to:
|
- **Real-Time Monitoring** — Parallel per-market polling of 50+ trending markets
|
||||||
|
- **Multi-Dimensional Anomaly Detection** — Scores trades on size, price uncertainty, time-of-day, trader deviation, and cluster signals
|
||||||
|
- **Trader Profiling** — Leaderboard ranking, trading history, recent behavior analysis
|
||||||
|
- **LLM Analysis with Tool-Use** — 14 autonomous tools (Twitter, web search, Telegram, crypto prices, stocks, economic data, Congress bills, DeFi metrics, on-chain analysis)
|
||||||
|
- **Signal Accuracy Tracking** — Automatic market resolution checking, win rate stats by confidence tier
|
||||||
|
- **Daily Intelligence Briefing** — Automated 10:00 AM daily summary with high-confidence signals
|
||||||
|
- **Email Alerts** — Real-time notifications for high-IAS signals (>= 60%)
|
||||||
|
- **Web Dashboard** — FastAPI-based signal performance dashboard
|
||||||
|
- **Leading Signal Research** — "Price leads news" dataset collection
|
||||||
|
|
||||||
1. **Fetch Trending Markets** - Gets the most active markets by 24-hour volume
|
## Quick Start
|
||||||
2. **Monitor for Whale Trades** - Watches for large trades ($10,000+ USD)
|
|
||||||
3. **Filter Anomalies** - Only triggers on trades with prices between 0.2-0.8 (uncertain markets)
|
|
||||||
4. **AI Analysis** - Uses LLM to analyze the whale trade and market context
|
|
||||||
5. **Trade Execution** - Optionally executes trades based on AI recommendations
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone or navigate to the project
|
|
||||||
cd polymarket-whale-watcher
|
|
||||||
|
|
||||||
# Create virtual environment
|
|
||||||
python -m venv venv
|
|
||||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
||||||
|
|
||||||
# Install dependencies
|
# Install dependencies
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
# Configure environment
|
||||||
|
|
||||||
Copy `.env.example` to `.env` and configure:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
```
|
# Edit .env with your API keys
|
||||||
|
|
||||||
Required settings:
|
# Start the whale watcher
|
||||||
- `OPENAI_API_KEY` - Your OpenAI API key for LLM analysis
|
|
||||||
- `POLYGON_WALLET_PRIVATE_KEY` - Your wallet private key (for trade execution)
|
|
||||||
|
|
||||||
Optional settings:
|
|
||||||
- `MIN_TRADE_SIZE_USD` - Minimum trade size to trigger (default: 10000)
|
|
||||||
- `MIN_PRICE` / `MAX_PRICE` - Price range filter (default: 0.2-0.8)
|
|
||||||
- `ENABLE_TRADE_EXECUTION` - Set to `true` to enable actual trading (default: false)
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Start the Whale Watcher
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run the bot
|
|
||||||
python -m src.main run
|
python -m src.main run
|
||||||
|
|
||||||
# With debug logging
|
# With debug logging
|
||||||
python -m src.main run --debug
|
python -m src.main run --debug
|
||||||
```
|
```
|
||||||
|
|
||||||
### Check Trending Markets
|
## Configuration
|
||||||
|
|
||||||
|
Copy `.env.example` to `.env` and configure:
|
||||||
|
|
||||||
|
**Required:**
|
||||||
|
- `GEMINI_API_KEY` — Gemini API key for LLM analysis
|
||||||
|
- `INTERNAL_API_URL` / `INTERNAL_API_KEY` — Internal trade data API
|
||||||
|
|
||||||
|
**Optional:**
|
||||||
|
- `TAVILY_API_KEY` — Web search (primary)
|
||||||
|
- `TWITTER_API_KEY` — Twitter sentiment search
|
||||||
|
- `POLYGON_API_KEY` — Stock/ETF data
|
||||||
|
- `FRED_API_KEY` — Economic indicators
|
||||||
|
- `ETHERSCAN_API_KEY` — On-chain data
|
||||||
|
- `EMAIL_*` — Email alert settings
|
||||||
|
- `MIN_TRADE_SIZE_USD` — Minimum trade size (default: 1000)
|
||||||
|
- `MIN_PRICE` / `MAX_PRICE` — Price range filter (default: 0.2-0.8)
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Start monitoring
|
||||||
|
python -m src.main run [--debug]
|
||||||
|
|
||||||
|
# Check trending markets
|
||||||
python -m src.main check-markets --limit 20
|
python -m src.main check-markets --limit 20
|
||||||
```
|
|
||||||
|
|
||||||
### Check Wallet Balance
|
# Test LLM analysis on a specific market
|
||||||
|
|
||||||
```bash
|
|
||||||
python -m src.main check-balance
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test LLM Analysis
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python -m src.main test-analyze <market_id>
|
python -m src.main test-analyze <market_id>
|
||||||
|
|
||||||
|
# Generate daily briefing
|
||||||
|
python -m src.main briefing --today
|
||||||
|
python -m src.main briefing --date 2026-04-17
|
||||||
|
|
||||||
|
# Migrate legacy JSON signals to SQLite
|
||||||
|
python -m src.main migrate
|
||||||
|
|
||||||
|
# Start web dashboard
|
||||||
|
python -m src.main dashboard --port 8000
|
||||||
```
|
```
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
Polymarket API Internal Trade API Gamma API
|
||||||
|
| | |
|
||||||
|
v v v
|
||||||
|
MarketFetcher TradeMonitor PriceMonitor
|
||||||
|
| | |
|
||||||
|
v v v
|
||||||
|
TrendingMarkets AnomalyDetector VolatilityAnalyzer
|
||||||
|
|
|
||||||
|
v
|
||||||
|
LLMAnalyzer (14 tools)
|
||||||
|
| |
|
||||||
|
v v
|
||||||
|
AnomalySignal Reports/Alerts
|
||||||
|
|
|
||||||
|
v
|
||||||
|
ResolutionTracker → StatsEngine → Dashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
src/
|
src/
|
||||||
├── config/
|
├── config/settings.py # Environment configuration
|
||||||
│ └── settings.py # Configuration management
|
|
||||||
├── models/
|
├── models/
|
||||||
│ ├── market.py # Market data models
|
│ ├── market.py # Market, TrendingMarket
|
||||||
│ ├── trade.py # Trade/whale trade models
|
│ ├── trade.py # TradeActivity, WhaleTrade, TraderRanking
|
||||||
│ └── decision.py # LLM decision models
|
│ ├── decision.py # TradeRecommendation, LLMDecision
|
||||||
|
│ ├── anomaly_signal.py # AnomalySignal (stored signal)
|
||||||
|
│ └── leading_signal.py # LeadingSignal (price leads news)
|
||||||
├── services/
|
├── services/
|
||||||
│ ├── market_fetcher.py # Fetches trending markets
|
│ ├── market_fetcher.py # Polymarket API, market filtering
|
||||||
│ ├── trade_monitor.py # Monitors markets for trades
|
│ ├── trade_monitor.py # Per-market parallel monitoring
|
||||||
│ ├── anomaly_detector.py # Detects whale trades
|
│ ├── price_monitor.py # Volatility detection
|
||||||
│ ├── llm_analyzer.py # AI analysis
|
│ ├── anomaly_detector.py # Multi-dimensional anomaly scoring
|
||||||
│ └── trade_executor.py # Trade execution
|
│ ├── llm_analyzer.py # LLM with tool-use (14 tools, 5 rounds max)
|
||||||
|
│ ├── volatility_analyzer.py # Leading signal detection
|
||||||
|
│ ├── trader_profiler.py # Trader profile generation
|
||||||
|
│ ├── tools.py # Tool registry
|
||||||
|
│ ├── daily_briefing.py # Daily summary generation
|
||||||
|
│ ├── resolution_tracker.py # Market resolution checking
|
||||||
|
│ ├── stats_engine.py # Performance statistics
|
||||||
|
│ ├── anomaly_history.py # Signal storage (SQLite)
|
||||||
|
│ ├── coingecko.py # Crypto prices
|
||||||
|
│ ├── fred.py # Economic indicators (FRED)
|
||||||
|
│ ├── polygon.py # Stock prices & news
|
||||||
|
│ ├── congress.py # US legislation
|
||||||
|
│ ├── defillama.py # DeFi TVL, revenue, token unlocks
|
||||||
|
│ ├── etherscan.py # On-chain wallet analysis
|
||||||
|
│ ├── twitter_search.py # Twitter API
|
||||||
|
│ ├── telegram_search.py # Telegram channels
|
||||||
|
│ └── web_search.py # Unified search (Tavily → Serper → DDG)
|
||||||
|
├── db/database.py # SQLite signal storage
|
||||||
├── prompts/
|
├── prompts/
|
||||||
│ └── whale_analyzer.py # LLM prompts
|
│ ├── whale_analyzer.py # LLM system prompt & tool schemas
|
||||||
├── utils/
|
│ └── volatility_analyzer.py # Volatility analysis prompt
|
||||||
│ └── logger.py # Logging utilities
|
├── dashboard.py # FastAPI web dashboard
|
||||||
└── main.py # Entry point
|
└── main.py # Entry point (WhaleWatcher orchestrator)
|
||||||
|
|
||||||
|
data/ # SQLite database + processed transactions
|
||||||
|
reports/ # Analysis reports (by date)
|
||||||
|
daily_briefings/ # Daily intelligence summaries
|
||||||
|
leading_signals/ # "Price leads news" research dataset
|
||||||
|
price_volatility/ # Volatility alert records
|
||||||
```
|
```
|
||||||
|
|
||||||
## How It Works
|
## How It Works
|
||||||
|
|
||||||
### 1. Market Selection
|
### 1. Market Selection
|
||||||
- Fetches top markets sorted by 24-hour trading volume
|
- Fetches top trending markets by 24h volume from Polymarket Gamma API
|
||||||
- Filters for active, CLOB-enabled markets
|
- Filters out sports, weather, and short-term price markets
|
||||||
- Refreshes market list every 5 minutes
|
- Refreshes market list every 15 minutes
|
||||||
|
|
||||||
### 2. Trade Monitoring
|
### 2. Trade Monitoring
|
||||||
- Polls Polymarket Data API for trade activity
|
- Runs parallel async tasks per monitored market
|
||||||
- Checks each monitored market every N seconds (configurable)
|
- Polls internal API incrementally (new trades since last check)
|
||||||
- Tracks processed transactions to avoid duplicates
|
- Rate-limited at 5 QPS to respect API limits
|
||||||
|
- Deduplicates by transaction hash
|
||||||
|
|
||||||
### 3. Anomaly Detection
|
### 3. Anomaly Detection
|
||||||
Triggers when:
|
Multi-dimensional scoring on 5 axes:
|
||||||
- Trade size >= $10,000 USD
|
- **Size** — Trade size relative to market 24h volume
|
||||||
- Trade price between 0.2 and 0.8 (uncertain outcome)
|
- **Price uncertainty** — Closer to 0.5 = more interesting
|
||||||
|
- **Time-of-day** — ET hour-based suspicion weights
|
||||||
|
- **Trader deviation** — Trade size vs trader's historical average
|
||||||
|
- **Cluster signal** — Same-direction trades within 5-minute window
|
||||||
|
|
||||||
### 4. LLM Analysis
|
### 4. LLM Investigation
|
||||||
When a whale trade is detected:
|
When a whale trade triggers:
|
||||||
- Formats trade context (amount, direction, price, market info)
|
1. Builds rich context: trade details + trader profile + market data + historical signals
|
||||||
- Sends to GPT-4 with superforecaster methodology
|
2. LLM autonomously uses tools to investigate (up to 5 rounds):
|
||||||
- Extracts structured recommendation (BUY/SELL/HOLD)
|
- Search Twitter/Telegram for insider chatter
|
||||||
|
- Check crypto prices, DeFi metrics, on-chain activity
|
||||||
|
- Look up stock movements, economic data, Congress bills
|
||||||
|
- Web search for breaking news
|
||||||
|
3. Produces structured recommendation: action, confidence, information asymmetry score (0-1)
|
||||||
|
4. Generates markdown report saved to `reports/`
|
||||||
|
|
||||||
### 5. Trade Execution (Optional)
|
### 5. Signal Tracking
|
||||||
If enabled and LLM recommends:
|
- Resolution tracker checks every 30 minutes for resolved markets
|
||||||
- Calculates position size (capped at 20% of balance)
|
- Validates signal correctness against actual outcomes
|
||||||
- Executes market order via Polymarket CLOB
|
- Computes theoretical ROI for each signal
|
||||||
- Logs execution result
|
- Stats engine aggregates win rates by confidence tier
|
||||||
|
|
||||||
## Safety Features
|
## Safety
|
||||||
|
|
||||||
- Trade execution disabled by default
|
- Trade execution disabled by default (`ENABLE_TRADE_EXECUTION=false`)
|
||||||
- Maximum position size capped at 20%
|
- Position size capped at 20% of balance if enabled
|
||||||
- Minimum confidence threshold (60%) for trade execution
|
- Minimum 60% confidence threshold for execution
|
||||||
- Price range filter to avoid obvious outcomes
|
- Price range filter avoids obvious outcomes (0.2-0.8)
|
||||||
- Comprehensive logging for audit trail
|
- All decisions logged for audit trail
|
||||||
|
- Rate limiting on all external APIs
|
||||||
|
|
||||||
## Disclaimer
|
## Disclaimer
|
||||||
|
|
||||||
This bot is for educational and research purposes. Trading on prediction markets involves significant risk. Never trade with funds you cannot afford to lose. Always verify the bot's recommendations independently.
|
This system is for research and educational purposes. Prediction market trading involves significant risk. Never trade with funds you cannot afford to lose. Always verify recommendations independently.
|
||||||
|
|||||||
Reference in New Issue
Block a user