Polymarket Research Bot

An AI-powered research toolkit for finding edge in Polymarket prediction markets.

Status: Paper trading — operational pipeline, no real trades yet. Contributions welcome.

---

What it does

Scans Polymarket for markets where the price diverges significantly from external evidence. When a discrepancy ≥ 8pp net is found, it researches the market using web search + Claude AI and generates a structured BUY/SKIP decision with full reasoning.

Example alert:

🔍 OPORTUNIDAD — PAPER

📋 Will X happen before March 31?

📊 Polymarket: 72% YES
🎯 Our probability (research): 48%
⚡ Net edge: +20pp | Confidence: 74/100
📈 Verdict: 🔴 BUY NO → $5.00

🧠 Recent news suggests the event is unlikely due to [reasoning...]
⚖️ Counter: The market may be pricing in [counter-argument...]
⚠️ Risk: Resolution criteria are ambiguous around [risk...]

---

Pipeline

Phase 1 — Market Scanner
  └─ Fetches active Polymarket markets (liquidity > $5K, < 30 days to resolution)
  └─ Scores and shortlists top 20 candidates

Phase 2 — External Anchors
  └─ Queries Manifold, Metaculus, Kalshi, The Odds API
  └─ Calculates discrepancy: abs(polymarket_price - anchor_prob) × 100
  └─ Net edge = discrepancy − 4pp friction (spread + fees)

Phase 3 — LLM Research (Brave + Claude)
  └─ Brave Search: recent news + base rate context
  └─ Claude CLI: structured analysis → probability, confidence, reasoning
  └─ Phase 2 hits validated by LLM before alerting (no blind anchor-only signals)

Phase 4 — Decision Engine
  └─ BUY if net edge ≥ 8pp AND confidence ≥ 50
  └─ Kelly-inspired sizing (max 5% bankroll, scaled by confidence)

Phase 5 — Persistence + Calibration
  └─ All decisions (BUY + SKIP) saved to SQLite for Brier score tracking
  └─ Outcome resolution when markets close

---

Installation

git clone https://github.com/sergiomarquezdev/polymarket-bot.git
cd polymarket-bot

pip install -r requirements.txt

cp config/.env.example config/.env
# Edit config/.env with your API keys

Required API keys

Key	Where to get it	Free tier
BRAVE_API_KEY	brave.com/search/api	2,000 req/month
ODDS_API_KEY	the-odds-api.com	500 req/month

Claude CLI must be installed and authenticated separately: claude.ai/code

---

Usage

# Daily scan (Phase 1 → 2 → 3 → decisions → alerts)
python run_research.py

# Analyze a specific market
python run_research.py --market will-trump-win-2026

# Resolve closed markets (updates outcomes in DB)
python run_research.py --resolve

# Show calibration metrics
python run_research.py --calibration

# System status
python run_research.py --status

Options

--bankroll FLOAT      Total bankroll in USD (default: 100)
--max-pages INT       Market pages to scan (default: 3, ~300 markets)
--max-llm-calls INT   Max Claude calls per run (default: 15, ~150s each on ARM)
--verbose             Log SKIP decisions too
--db PATH             Custom SQLite path

---

Project structure

polymarket-bot/
├── run_research.py          # Main runner — CLI entrypoint
├── src/
│   ├── data/
│   │   ├── market_scanner.py     # Polymarket Gamma API client + shortlisting
│   │   ├── prediction_markets.py # Manifold, Metaculus, Kalshi clients
│   │   ├── brave_search.py       # Brave Search API wrapper
│   │   └── price_feed.py         # CLOB API (best ask prices)
│   ├── signals/
│   │   ├── discrepancy.py        # Phase 2: anchor comparison + edge calc
│   │   ├── event_researcher.py   # Phase 3: Brave + Claude research
│   │   ├── event_analyzer.py     # Market categorization
│   │   └── llm_prompt.py         # Prompt templates
│   ├── execution/
│   │   ├── decision_engine.py    # BUY/SKIP logic + Kelly sizing
│   │   └── alerter.py            # Telegram message formatting
│   └── audit/
│       ├── trade_db.py           # SQLite persistence
│       ├── outcome_tracker.py    # Auto-resolution of closed markets
│       └── calibration.py        # Brier score + win rate metrics
├── tests/                   # 473 tests
├── config/
│   └── .env.example         # API key template
└── vps_executor/            # Optional: VPS execution bridge for py-clob-client

---

Limitations

• ARM64 only tested on Termux (Android). Linux x86 should work fine.
• Manual trade execution — the bot generates signals, you place orders on polymarket.com. py-clob-client is not integrated.
• Not validated yet — paper trading only. Win rate and calibration metrics are tracked but the model hasn't been proven profitable.
• Claude CLI dependency — LLM research requires Claude CLI installed and authenticated (not an API key).

---

Contributing

The codebase is well-tested (473 tests) and modular. Good areas to contribute:

• New anchor sources — add to src/data/prediction_markets.py
• Prompt improvements — src/signals/llm_prompt.py
• Alternative LLMs — replace Claude CLI in src/signals/event_researcher.py
• Trade execution — integrate py-clob-client for automated order placement

---

License

MIT