Polymarket Copy-Trading Bot

A four-phase pipeline that discovers alpha wallets on Polymarket, watches their on-chain trades in real time, and optionally copies them with configurable risk controls.

Architecture

discover_alpha.py  -->  alpha_wallets.json
                              |
                       watch_onchain.py  (Polygon logs, block time ~2s)
                              |
                        decision.py  (slippage, cooldown, risk gates)
                              |
                    executor_paper.py  OR  executor_live.py
                              |
                          ledger.jsonl
                              |
                     api_server.py + dashboard.html

Setup

pip install -r requirements.txt
cp .env.example .env   # fill in your RPC URL

Environment variables (.env)

POLYGON_RPC_URL=wss://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY
BANKROLL_USDC=500

# Live mode only:
PRIVATE_KEY=0x...
DEPOSIT_WALLET_ADDRESS=0x...
CLOB_API_KEY=...
CLOB_API_SECRET=...
CLOB_API_PASSPHRASE=...
I_UNDERSTAND_REAL_MONEY=yes

Phase 1 — Discover Alpha Wallets

python discover_alpha.py --pool 100 --top 20 --out alpha_wallets.json

This pulls the Polymarket leaderboard, profiles each wallet from their real closed positions, and scores them on a composite metric (realized PnL, win rate, breadth, concentration). Output: alpha_wallets.json.

Options:

• --category — OVERALL, POLITICS, SPORTS, CRYPTO, etc.
• --period — DAY, WEEK, MONTH, ALL
• --min-markets — minimum resolved markets to qualify (default 10)

Scoring metrics

Each wallet is profiled across 30+ metrics. Beyond raw performance (realized PnL, win rate, breadth, profit factor, drawdown, concentration), the score also weighs:

Risk-Adjusted (Tier 1) — reward consistent, capital-efficient edge:

• Brier score — mean (entry_price − outcome)²; probabilistic calibration. Lower is better (< 0.2 excellent).
• Sortino ratio — mean per-market ROI / downside deviation (only losses count as risk).
• Calmar ratio — annualized ROI / max drawdown (return per unit of worst-case loss).
• Capital turnover — total volume / cost basis (how hard capital is recycled).

Verification & Red Flags (Tier 2) — detect things that are dangerous to copy:

• On-chain wallet age / tx count / pre-Polymarket activity — via Polygonscan. Optional; requires POLYGONSCAN_API_KEY. Without a key these stay 0/false and discovery proceeds normally (graceful degradation).
• Sybil risk — pool-level Jaccard overlap of traded markets with other candidates; high overlap suggests coordinated / wash-trading farms. Heavily penalized in the score.
• Revenge trading — flags 2×+ position-size spikes immediately after a loss (count of events recorded).
• Slippage proxy — placeholder (0.0); see Roadmap below.

Set the optional key in .env:

POLYGONSCAN_API_KEY=your_free_polygonscan_key   # optional, enables on-chain verification

Roadmap / Not Implemented (Tier 3)

These were evaluated but deliberately left out — each requires an external/paid data feed we don't want to make a hard dependency:

• Slippage proxy (faithful) — needs per-trade OrderFilled on-chain history; aggregate /closed-positions only exposes one avgPrice per market, so a true fill-dispersion measure isn't derivable yet.
• News latency — requires a real-time news feed API to time entries against headline breaks.
• Social sentiment — requires Twitter/X or Reddit firehose access (paid).
• Cross-market arbitrage — requires synchronized full-book snapshots across correlated markets (paid streaming).
• Influence score — requires social-graph / follower data (paid social APIs).
• Closing-line value (CLV) — requires archived odds at resolution time across venues (paid odds history).

Phase 2 — Watch On-Chain

python watch_onchain.py --rpc $POLYGON_RPC_URL --watchlist alpha_wallets.json

Subscribes to OrderFilled logs from Polymarket's CTF Exchange contracts on Polygon. Prints signals as they arrive (block time ~2s). No money involved.

Phase 3 — Paper Trading

python bot.py --mode paper --bankroll 1000 --rpc $POLYGON_RPC_URL

Simulates trades against the real live order book (no real orders placed). Every decision and simulated fill is recorded in ledger.jsonl. A summary prints every 5 minutes.

Run the dashboard to watch in real time:

python api_server.py --ledger ledger.jsonl --port 8080
# open http://localhost:8080

Run at least 30 resolved paper trades before going live.

Check your paper results:

python -c "from ledger import Ledger; Ledger('ledger.jsonl').print_summary('paper')"

Phase 4 — Live Trading (Real Money)

The live gate requires ALL of the following:

1. I_UNDERSTAND_REAL_MONEY=yes in environment
2. At least 30 resolved paper trades in ledger.jsonl
3. BANKROLL_USDC > 0
4. Geoblock check passes (Polymarket is not available in all regions)
5. Interactive confirmation prompt

python bot.py --mode live --bankroll 500 --rpc $POLYGON_RPC_URL --really-send

Omit --really-send to run in dry-run mode (logs orders but does not post them).

Configuration

All tunables are in config.py and can be overridden via environment variables:

Env Var	Default	Description
BANKROLL_USDC	0	Your total USDC bankroll
POSITION_FRACTION	0.02	Fraction of bankroll per trade (2%)
MAX_POSITION_USDC	50	Hard cap per position
MAX_SLIPPAGE	0.02	Reject if fill price > alpha + this
MAX_OPEN_POSITIONS	5	Max concurrent positions
MAX_TOTAL_EXPOSURE_USDC	200	Max total open exposure
MAX_DAILY_LOSS_USDC	50	Daily loss circuit breaker
COOLDOWN_SECONDS	300	Per (wallet, market) cooldown
MIN_PAPER_TRADES	30	Paper trades required before live
POLYGONSCAN_API_KEY	""	Optional — enables on-chain wallet verification in discovery

Risk Warnings

• This bot copies other traders. Past performance does not guarantee future results.
• Prediction market prices are highly volatile and can go to 0 or 1 instantly on resolution.
• Copy-trading introduces additional latency vs. the alpha wallet. Slippage is real.
• Start with the smallest bankroll you are comfortable losing entirely.
• The paper-trading gate exists for a reason. Do not bypass it.
• Review ledger.jsonl and the dashboard before enabling live mode.
• Kill switch: the bot will cancel all open orders on SIGINT/SIGTERM in live mode.

Tests

python -m pytest tests/ -v

File Reference

File	Purpose
discover_alpha.py	Stage 1: wallet discovery & scoring
onchain_metrics.py	Polygonscan verification + sybil/slippage helpers
watch_onchain.py	Stage 2: real-time on-chain signal source
config.py	All configuration tunables
ledger.py	Append-only trade ledger (JSONL)
decision.py	Risk gates & trade sizing logic
executor_paper.py	Paper trade simulation
executor_live.py	Live CLOB order placement
bot.py	Main entrypoint / orchestrator
api_server.py	Flask API for the dashboard
dashboard.html	Web dashboard (dark theme, Chart.js)
requirements.txt	Python dependencies