<div align="center">

🤖 Polymarket Trading Bot & Dashboard

The Most Advanced Open-Source Automated Trading Platform for Polymarket Prediction Markets

7 trading strategies · 🐋 whale tracker & copy-trade simulator · 📊 real-time dashboard · 🔒 paper trading by default

Features · Quick Start · Strategies · Whale Scanner · Dashboard · Configuration · API Reference · Custom Development

<br/> <img src="docs/screenshots/dashboard.png" alt="Polymarket Trading Bot Dashboard — Real-time P&L tracking, 10 wallets, 8 strategies, whale scanner" width="100%" />

Real-time dashboard showing 10 active wallets, $72,800 total capital, $39,240 total P&L, and 7 concurrent strategies running in paper trading mode.

</div>

---

📖 Overview

A production-grade, modular trading system for Polymarket prediction markets. Run 7 concurrent strategies — from cross-market arbitrage to AI-driven forecasting — each isolated in its own wallet with independent capital, risk limits, and execution modes (LIVE or PAPER).

The platform includes an enterprise-level whale tracking engine that auto-discovers profitable traders, scores them with regime-adaptive algorithms, detects coordinated whale clusters, and lets you simulate copy-trading their moves — all from a beautiful real-time dashboard.

Why This Bot?

| Problem | Solution | |---------|----------| | Manual trading is slow & emotional | 7 automated strategies scan 24/7, execute in milliseconds | | Can't find alpha in prediction markets | Whale scanner discovers profitable traders with proven track records | | Risk of ruin from a single bad trade | Per-wallet isolation, daily loss limits, global kill switch | | No visibility into what the bot is doing | Real-time SSE dashboard with live trades, P&L, positions | | Rate-limited by Polymarket APIs | Multi-API pool with rotation, 16x parallel scanning | | Fear of losing real money while testing | Paper trading mode by default — no real funds at risk |

---

✨ Features

🧠 8 Built-In Trading Strategies

| # | Strategy | Type | Description | Edge | |---|----------|------|-------------|------| | 1 | Cross-Market Arbitrage | Arbitrage | Exploits price differences between correlated Polymarket markets | 3%+ minimum edge | | 2 | Mispricing Arbitrage | Arbitrage | Detects when outcome probabilities don't sum to 100% | 2%+ dislocation | | 3 | Filtered High-Prob Convergence | Convergence | 7-filter pipeline targeting 65-96% probability outcomes | 200 bps take profit | | 4 | Market Making (Spread) | Market Making | Provides liquidity by quoting both sides of the book | 40 bps spread capture | | 5 | Momentum | Trend Following | Rides short-term price trends with 15-min lookback | Trend continuation | | 6 | AI Forecast | Research/AI | ML-driven predictions with web research pipeline | Data-driven alpha | | 7 | Copy Trading | Whale Mirroring | Mirrors whale trades in real-time with full risk management | Whale alpha extraction | | 8 | User-Defined | Custom | Your own strategy — extend the base class | Unlimited |

🐋 Whale Tracking & Copy Trading

• Auto-Discovery Scanner — Scans 50+ liquid markets per cycle to find profitable whales
• 16x Parallel Scanning — Semaphore-based concurrency with tunable batch sizes
• Multi-Dimensional Scoring — Profitability (30%), timing skill (20%), low slippage (15%), consistency (15%), market selection (10%), recency (10%)
• Regime-Adaptive Scoring — Automatically adjusts whale scores based on current market conditions
• Whale Cluster Detection — Identifies when multiple whales converge on the same market
• Network Graph Analysis — Visualizes relationships between whale wallets
• Copy-Trade Simulator — Backtest copy-trading strategies with configurable slippage & delay
• Big Trade Alerts — Real-time alerts for trades ≥ $3K
• Cross-Reference Engine — Deep-scans top whales across all markets
• Historical Backfill — 7-day lookback on first run for immediate insights
• On-Chain Balance Lookup — USDC balance verification via Polygon RPC
• Multi-Exchange Ready — Stubs for Kalshi and Manifold Markets

📊 Real-Time Dashboard

• Server-Sent Events (SSE) — Live updates, no polling
• Dark Theme UI — Professional trading terminal aesthetic
• 10 Wallet Cards — Each showing strategy, P&L, open positions, trade history
• Strategy Library — Browse all strategies, create wallets with one click
• Live Trade Feed — Every BUY/SELL across all wallets in real-time
• Market Scanner View — See which markets the bot is analyzing
• Console Logs — Live log stream from the engine
• Whale Tracking Panel with 6 sub-tabs:
  • 🔍 Scanner — Live scan results with whale profiles
  • 📊 Clusters — Coordinated whale activity detection
  • 🕸️ Network — Wallet relationship graph
  • 📈 Copy Sim — Copy-trade performance simulation
  • 🌊 Regime — Market regime analysis & adaptive scoring
  • 🔄 API Pool — Endpoint health & rate limit monitoring
• Performance Metrics — Markets/sec, trades/sec, fetch latency, cache hit rate

🔒 Risk Management

• Wallet Isolation — Each strategy runs in its own wallet with separate capital
• Per-Wallet Limits — Max position size, exposure per market, daily loss, max drawdown
• Global Kill Switch — Emergency stop across all strategies
• Paper Trading Default — LIVE mode requires explicit ENABLE_LIVE_TRADING=true
• Daily/Weekly Loss Halts — Auto-pause at configurable thresholds (3% daily, 8% weekly)
• MLE Caps — Maximum loss exposure capped at 5% per market, 15% total
• Order Rate Limiting — Prevents runaway order submission
• No Secrets in Code — All API keys via environment variables only

⚡ Performance & Scalability

• 50 TypeScript source files — Clean, modular architecture
• 106 unit tests — Full coverage with Vitest
• 16x parallel market scanning — Configurable concurrency
• Smart caching — 5-minute TTL market metadata cache
• API pool rotation — Distribute requests across multiple endpoints
• Docker-ready — Single docker build & docker run
• SQLite storage — Zero-config whale database

---

🚀 Quick Start

Prerequisites

• Node.js 18+ (download)
• npm (comes with Node.js)
• Git (download)

Installation

# Clone the repository
git clone https://github.com/dylanpersonguy/Polymarket-Trading-Bot.git
cd Polymarket-Trading-Bot

# Install dependencies
npm install

# Build the project
npm run build

Launch (Paper Trading — Safe by Default)

# Start the bot with default config (all wallets in PAPER mode)
npm start

# Or use the CLI directly
node dist/cli.js start --config config.yaml

The bot will start all 10 wallets (8 strategies), launch the whale scanner, and serve the dashboard at:

🌐 Dashboard: http://localhost:3000/dashboard

Verify It's Working

# Check the dashboard
open http://localhost:3000/dashboard

# View engine status via API
curl http://localhost:3000/api/data | jq

# List all wallets
curl http://localhost:3000/api/wallets | jq

# View live trades
curl http://localhost:3000/api/trades/all | jq

---

🧠 Strategies

1. Cross-Market Arbitrage

Identifies price discrepancies between correlated Polymarket markets and captures the spread.

strategy_config:
  cross_market_arbitrage:
    min_edge: 0.03  # Minimum 3% edge to trade

Example: Market A prices "Trump wins" at 52¢ while Market B prices "Trump nominee" at 48¢. If logically linked, the bot captures the 4% spread.

2. Mispricing Arbitrage

Detects when a market's outcome probabilities don't sum to 100% (minus the vig), indicating mispricing.

strategy_config:
  mispricing_arbitrage:
    min_dislocation: 0.02  # 2% minimum dislocation

Example: A binary market shows YES at 55¢ and NO at 42¢ (total = 97¢). The bot buys the underpriced side.

3. Filtered High-Probability Convergence

The flagship strategy. A rule-based, no-AI approach that targets markets where the leading outcome has a 65-96% probability AND passes 7 strict filters:

| Filter | What It Checks | |--------|---------------| | Liquidity | ≥ $10K market liquidity + depth within 1% of mid | | Probability Band | Leading outcome between 65% and 96% | | Spread | Bid-ask spread ≤ 200 bps | | Time-to-Resolution | Market resolves within 14 days | | Anti-Chasing | No recent 8%+ price spikes | | Flow/Pressure | Orderbook imbalance or net buy flow ≥ $500 | | Cluster Exposure | ≤ 25% capital in correlated markets |

Sizing: position = capital × 0.5% × setup_score where setup_score is a composite of spread tightness (30%), depth (25%), order flow (25%), and time-to-resolution (20%).

Example: Market "Will inflation drop below 3%?" — probability at 78%, spread at 120 bps, $50K liquidity, resolves in 9 days, strong buy flow. Setup score = 0.82. On $10K capital: position = $10,000 × 0.005 × 0.82 = $41 entry, targeti