Read this before running with real money. No strategy in this repo is guaranteed to make money. The examples lose money on certain markets. Trading prediction markets is hard, the edges are small, and what worked last quarter may not work this quarter. This is a toolkit, not a turnkey bot. Read the code, understand what it does, and tune it for the markets you care about. The authors are not responsible for losses you incur using this software.

# 1. Clone and set up
git clone <your fork URL>
cd polymarket-trading-bot
python setup.py        # creates .venv, installs deps (incl. py-clob-client + web3)

# 2. Add your keys & wallet
cp env.template .env
# then open .env and fill in:
#   POLYMARKET_PRIVATE_KEY   — Polygon wallet that will sign orders
#   POLYMARKET_FUNDER        — proxy address (only if SIGNATURE_TYPE != 0)
#   POLYMARKET_SIGNATURE_TYPE — 0=EOA/MetaMask, 1=Magic Link, 2=Gnosis Safe
#   OPENROUTER_API_KEY       — for LLM-driven strategies

# 3. (One-time) approve USDC allowances for the Polymarket contracts
python scripts/set_allowances.py

# 4. Verify connectivity
python cli.py health

# 5. Run an example strategy in DRY-RUN mode (default)
python cli.py run --paper                  # AI directional (LLM-driven)
python cli.py run --safe-compounder        # Edge-based NO-side, no LLM

Open the dashboard in another terminal:

python cli.py dashboard

Need keys?

• Polygon wallet → export the private key from MetaMask (or use a Magic Link wallet from polymarket.com)
• You'll also need USDC.e on Polygon to actually trade — python cli.py status will print your balance
• OpenRouter key → openrouter.ai

This repo gives you the building blocks. The example strategies use them — your own strategies can too.

The repo also ships scaffolding for things that aren't fully wired — multi-agent debate runners in src/agents/, sentiment analyzer in src/data/, etc. Treat them as starting points if you want to extend them.

Three strategies ship with the repo. None of them is "the right answer." They exist so you can run something end-to-end and see how the pieces connect, then fork the one closest to what you want to build.

The default. For each candidate market, it calls a single LLM via OpenRouter (with a fallback chain on errors) to score directional confidence, then sizes positions with fractional Kelly and applies category/sector guardrails.

It is not a "5-model ensemble" despite earlier README claims. One model is called per decision. The fallback chain only triggers on errors. The agents/ directory contains scaffolding for real parallel multi-model voting, but it's not wired into the live trading path. If you want a real ensemble, fork src/jobs/decide.py and build it.

python cli.py run --paper          # paper trading
python cli.py run --live           # live trading (real money)

Defaults: 15% max drawdown, 45% min confidence, 3% max position size, 30% max sector concentration, quarter-Kelly. All configurable in src/config/settings.py.

Pure edge-based math, no LLM required. Scans every active Polymarket market for NO-side asks above a price threshold with a positive expected-value edge, then places resting maker orders one cent below the ask.

python cli.py run --safe-compounder              # dry-run preview
python cli.py run --safe-compounder --live       # live execution

# Run continuously instead of one cycle and exit:
python cli.py run --safe-compounder --live --loop --interval 300

Rules: NO side only, YES last ≤ 20¢, NO ask > 80¢, edge > 5¢, max 10%/position, skips sports/entertainment/"mention" markets.

Aggressive settings with no category guardrails. Available for comparison and experimentation — not recommended for live trading. Running this with real money historically led to significant losses on this repo.

Ctrl-C sends SIGINT and triggers graceful shutdown — the bot finishes the in-flight cycle, logs, and exits. Open positions remain on Polymarket until they resolve.

If you want to liquidate everything before stepping away:

# 1. Stop the bot
Ctrl-C

# 2. Place limit sells at the current best bid for every open position
python cli.py close-all              # dry-run preview
python cli.py close-all --live       # actually send orders

# 3. Verify
python cli.py status

close-all queries Polymarket directly (not the local DB), so it works even when local state is stale. Sells are limit-priced, so they may rest unfilled on thin books — check Polymarket or cli.py status after a minute.

• Python 3.12 or later
• A Polymarket account with API access (API docs)
• An OpenRouter API key (only needed for the AI directional strategy)

git clone https://github.com/zostaff/polymarket-ai-trading-bot.git
cd polymarket-ai-trading-bot
python setup.py

Creates a virtual env, installs dependencies, and prints next steps.

git clone https://github.com/zostaff/polymarket-ai-trading-bot.git
cd polymarket-ai-trading-bot

python -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate          # Windows

pip install -r requirements.txt

cp env.template .env
# then edit .env with your keys

The wallet's private key lives in .env only — never on disk. .env is git-ignored.

Verify everything is wired:

python cli.py health

All trading parameters live in src/config/settings.py. The most useful knobs:

# Position sizing
max_position_size_pct  = 3.0     # Max 3% of balance per position
max_positions          = 10      # Max concurrent positions
kelly_fraction         = 0.25    # Quarter-Kelly (conservative)

# Market filtering
min_volume             = 500     # Minimum contract volume
max_time_to_expiry_days = 14     # How far out to trade
min_confidence_to_trade = 0.45   # Minimum AI confidence to enter

# LLM (OpenRouter)
primary_model          = "anthropic/claude-sonnet-4.5"
ai_temperature         = 0       # Deterministic
ai_max_tokens          = 8000

# Risk management
max_daily_loss_pct     = 10.0    # Daily loss circuit breaker
max_drawdown           = 0.15    # Portfolio drawdown halt
daily_ai_cost_limit    = 10.0    # Max daily LLM spend in USD

Swapping models: change primary_model to any slug from openrouter.ai/models. The fallback chain in src/clients/openrouter_client.py controls what happens when the primary errors.

Controlling LLM spend: the bot checks the daily limit before every API call and skips trading until the next calendar day once exhausted. Set DAILY_AI_COST_LIMIT in .env to override.

polymarket-ai-trading-bot/
├── beast_mode_bot.py          # Example AI directional bot — main loop orchestration
├── cli.py                     # Unified CLI: run, dashboard, status, health, close-all, scores, history
├── paper_trader.py            # Paper-trading signal logger + static dashboard
├── setup.py                   # Bootstrap script
├── env.template               # Environment variable template
│
├── src/
│   ├── agents/                # UNWIRED scaffolding for multi-agent debate (fork to use)
│   ├── clients/               # Polymarket, OpenRouter, WebSocket clients
│   ├── config/                # Settings and trading parameters
│   ├── data/                  # News + sentiment helpers (optional)
│   ├── events/                # Async event bus
│   ├── jobs/                  # ingest, decide, execute, track, evaluate
│   ├── strategies/            # Safe compounder, category scorer, portfolio enforcer
│   └── utils/                 # Database, logging, prompts, risk helpers
│
├── scripts/                   # Diagnostic and utility scripts
├── docs/                      # Additional docs + paper-trading dashboard HTML
└── tests/                     # Pytest suite

Simulate trades without sending real orders. Every signal is logged to SQLite and a static HTML dashboard renders cumulative P&L after markets settle.

python paper_trader.py                            # one scan
python paper_trader.py --loop --interval 900      # continuous, every 15m
python paper_trader.py --settle                   # update outcomes for resolved markets
python paper_trader.py --dashboard                # regenerate HTML
python paper_trader.py --stats                    # print stats

Output goes to docs/paper_dashboard.html.

The category scorer evaluates each Polymarket market category on a 0-100 scale based on historical ROI, win rate, recent trend, and sample size. Allocation per category is gated by score.

python cli.py scores

This is one heuristic for category-level risk control. If it doesn't fit your strategy, ignore it — it's only used by the AI directional path.

Every trade, AI decision, and cost metric is recorded to trading_system.db (local SQLite). Inspect via the dashboard or:

python cli.py history                # Last 50 trades
python cli.py history --limit 100    # Last 100
python cli.py status                 # Live balance + open positions from Polymarket

pytest tests/          # full suite
pytest tests/ -v       # verbose
pytest --cov=src       # with coverage

black src/ tests/ cli.py beast_mode_bot.py
isort src/ tests/ cli.py beast_mode_bot.py
mypy src/

1. Create a module under src/strategies/
2. Wire it into a CLI flag in cli.py (or invoke it directly)
3. Use the PolymarketClient for orders/positions and DatabaseManager for state
4. Add tests under tests/

python -m src.utils.database

grep -i "live trading\|paper trading\|LIVE ORDER" logs/trading_system.log | tail -20

export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
pip install -r requirements.txt

pyenv install 3.13.1 && pyenv local 3.13.1
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

These are observations from running the example strategies with real money on Polymarket. They informed the defaults shipped here. They are not universal trading wisdom — they're notes from one set of experiments.

1. Category discipline mattered more than AI confidence. The LLM could be 80% confident on a CPI trade and still be wrong. Market-implied probabilities on highly-watched economic releases are already efficient.

2. Kelly fraction matters enormously. Three-quarter Kelly compounds losses catastrophically on a 45% win-rate strategy. Quarter-Kelly is what the example strategies use.

3. A 50% drawdown limit isn't a limit. The default is 15% with the circuit breaker actually halting trades, not just logging.

4. Sector concentration creates correlated losses. When 90% of capital is in economic categories on a Fed day, everything moves together. The default cap is 30% per category.

5. More trades without edge is faster path to zero. The default scan interval is 60 seconds, not 30, and trades are gated by both confidence and category score.

Your edge is probably somewhere else. Use the toolkit to find it.

Contributions welcome. See CONTRIBUTING.md for full guidelines.

# 1. Fork
# 2. Create a feature branch
git checkout -b feature/your-feature
# 3. Make changes, add tests, run pytest and black
# 4. Commit using conventional commits (feat:, fix:, refactor:)
# 5. Open a PR

• Polymarket Trading API
• Polymarket CLOB Authentication
• Polymarket Markets
• OpenRouter Model Catalog

MIT. See LICENSE.