SII-leiyuandClaude
0254e2c01a
- Add trade monitoring and whale detection system - Add LLM-powered trade analysis - Add market data fetching from Polymarket API - Include example environment configuration - Add automated report generation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# Polymarket Whale Watcher
|
|
|
|
AI-powered whale trade detection and analysis bot for Polymarket prediction markets.
|
|
|
|
## Overview
|
|
|
|
This bot combines the market monitoring approach from `polymarket-copy-trading-bot` with the AI analysis capabilities of `PolyMarket-trading-AI-model` to:
|
|
|
|
1. **Fetch Trending Markets** - Gets the most active markets by 24-hour volume
|
|
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
|
|
# 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
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Copy `.env.example` to `.env` and configure:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Required settings:
|
|
- `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
|
|
|
|
# With debug logging
|
|
python -m src.main run --debug
|
|
```
|
|
|
|
### Check Trending Markets
|
|
|
|
```bash
|
|
python -m src.main check-markets --limit 20
|
|
```
|
|
|
|
### Check Wallet Balance
|
|
|
|
```bash
|
|
python -m src.main check-balance
|
|
```
|
|
|
|
### Test LLM Analysis
|
|
|
|
```bash
|
|
python -m src.main test-analyze <market_id>
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
├── config/
|
|
│ └── settings.py # Configuration management
|
|
├── models/
|
|
│ ├── market.py # Market data models
|
|
│ ├── trade.py # Trade/whale trade models
|
|
│ └── decision.py # LLM decision models
|
|
├── services/
|
|
│ ├── market_fetcher.py # Fetches trending markets
|
|
│ ├── trade_monitor.py # Monitors markets for trades
|
|
│ ├── anomaly_detector.py # Detects whale trades
|
|
│ ├── llm_analyzer.py # AI analysis
|
|
│ └── trade_executor.py # Trade execution
|
|
├── prompts/
|
|
│ └── whale_analyzer.py # LLM prompts
|
|
├── utils/
|
|
│ └── logger.py # Logging utilities
|
|
└── main.py # Entry point
|
|
```
|
|
|
|
## How It Works
|
|
|
|
### 1. Market Selection
|
|
- Fetches top markets sorted by 24-hour trading volume
|
|
- Filters for active, CLOB-enabled markets
|
|
- Refreshes market list every 5 minutes
|
|
|
|
### 2. Trade Monitoring
|
|
- Polls Polymarket Data API for trade activity
|
|
- Checks each monitored market every N seconds (configurable)
|
|
- Tracks processed transactions to avoid duplicates
|
|
|
|
### 3. Anomaly Detection
|
|
Triggers when:
|
|
- Trade size >= $10,000 USD
|
|
- Trade price between 0.2 and 0.8 (uncertain outcome)
|
|
|
|
### 4. LLM Analysis
|
|
When a whale trade is detected:
|
|
- Formats trade context (amount, direction, price, market info)
|
|
- Sends to GPT-4 with superforecaster methodology
|
|
- Extracts structured recommendation (BUY/SELL/HOLD)
|
|
|
|
### 5. Trade Execution (Optional)
|
|
If enabled and LLM recommends:
|
|
- Calculates position size (capped at 20% of balance)
|
|
- Executes market order via Polymarket CLOB
|
|
- Logs execution result
|
|
|
|
## Safety Features
|
|
|
|
- Trade execution disabled by default
|
|
- Maximum position size capped at 20%
|
|
- Minimum confidence threshold (60%) for trade execution
|
|
- Price range filter to avoid obvious outcomes
|
|
- Comprehensive logging for audit trail
|
|
|
|
## 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.
|