# Polymarket Copy Trader (Project B)

**Quantitative copy-trading bot for Polymarket** — follows the top 1% of profitable wallets using Bayesian credibility updates + Kelly position sizing + Favorite-Longshot bias correction.

## What's Different from Project A (Whale Watcher)

| Aspect | Project A (whale-watcher) | Project B (copy-trader) |
|---|---|---|
| Goal | Detect "insider" trades via LLM | Mirror statistically profitable wallets |
| LLM cost | $0.5-2 per signal | $0 (all math, no LLM) |
| Win rate evidence | 63.5% on 250 signals | Expected ≥55% from top-1% PnL data |
| Latency | Asynchronous | Real-time WebSocket |

## Phase Plan

- ✅ **Phase 0**: foundation, pool builder, Telegram notifier
- ✅ **Phase 1**: Trade stream (poll-based, 30s interval, restart-safe)
- ✅ **Phase 2**: Signal aggregator (Bayesian update + Kelly sizer + 5-layer filter)
- ✅ **Phase 3**: CLOB trader (optional, off by default — manual first)
- ✅ **Phase 4**: Dashboard (FastAPI for P&L tracking)
- ✅ **Phase 5**: Strategy analytics (signal outcome backfill + 6-dimension hit-rate dashboard for parameter tuning)

## Architecture (target)

```
Data API ──┐
           ├─→ Wallet Pool Builder ──→ SQLite (top 100 wallets)
           │
           └─→ Health score = f(PnL, trades, category diversity)
                    ↓
           User WebSocket (User channel) per wallet
                    ↓
           On each trade → check eligibility (size, price)
                    ↓
           Bayesian credibility update
                    ↓
           Softmax aggregation across wallets
                    ↓
           Kelly sizing + Favorite-Longshot correction
                    ↓
           Telegram notification + optional CLOB execution
```

## Running

```bash
# Main bot (6 asyncio loops: pool/stream/credibility/cleanup/health/outcome-resolve)
python -m src.main run

# Strategy analytics dashboard (http://localhost:8518/analytics)
python -m src.main dashboard

# CLI stats — hit rate / PnL
python -m src.main stats

# Manually backfill resolved-market outcomes onto historical signals
python -m src.main backfill --batch 500

# Docker (cloud)
docker compose build --no-cache && docker compose up -d
```

## Configuration

Copy `.env.example` to `.env` and fill in:
- Polymarket Gamma + Data API (no auth needed for reads)
- Telegram bot token + chat ID for notifications
- CLOB credentials (only if enabling live execution)
- Wallet pool criteria (PnL minimum, trade count, etc.)

## Why this will (probably) make money

- Polymarket data: **top 1% users capture 84% of all profits**
- Their edge = identifying mispriced contracts, NOT insider info
- Following their trades = systematic exposure to that edge
- Bayesian updating = self-correcting when a wallet's skill degrades
- Favorite-Longshot correction = avoid 70.8% user loss pattern

## Disclaimer

Backtesting not yet performed. Start with `ENABLE_EXECUTION=false` and observe signals via Telegram for 2-4 weeks before any live trading.