Polymarket auto-trader (safe scaffold)

Open the hub locally (fewest steps)

1. One-time in the polymarket-bot folder: python -m venv .venv then .venv\Scripts\python.exe -m pip install -e .
2. Every time: double-click run-hub.bat in that folder, or in Cursor’s terminal:

cd C:\Users\you\Prediction_Agents\polymarket-bot
.\.venv\Scripts\python.exe -m pm_bot --hub

Keeps the window open on errors (run-hub.bat ends with pause). Remove pause from the .bat if you prefer it to exit immediately.

---

This is a minimal, dry-run by default scaffold for a Polymarket CLOB trading bot:

• Loads secrets from environment variables (never hardcode keys)
• Connects via py-clob-client
• Implements a simple “probability vs market price” decision rule
• Includes basic risk limits, optional polling loop, and persisted notional position
• Uses the real client API (OrderArgs, create_and_post_order, OrderBookSummary)

Polymarket guidelines (official docs)

This project follows the Polymarket CLOB overview and authentication model:

• L1: your private key derives L2 API credentials (create_or_derive_api_creds in py-clob-client).
• L2: signed orders are posted with HMAC headers; the SDK handles this after set_api_creds.
• Secrets: use env vars or a secrets manager; never commit keys (.env is git-ignored).
• Signature type + funder: If you use a Polymarket.com account (proxy wallet), set POLY_SIGNATURE_TYPE=2 (GNOSIS_SAFE) and POLY_FUNDER_ADDRESS to your profile wallet from settings. Omitting these defaults the SDK to EOA (0) — correct only for a standalone key that holds funds directly.
• Server / VPS: run the bot on the server only; do not put POLY_PRIVATE_KEY or API secrets in browser code.

Setup

Create and activate a virtualenv, then install the package (recommended) or dependencies only:

cd polymarket-bot
python -m venv .venv
.venv\Scripts\activate
python -m pip install -e .

Alternatively: python -m pip install -r requirements.txt (editable install is preferred so pm_bot is importable from any directory).

Environment file:

• pm_bot/env.prefill — full commented template (safe to commit). Copy it to pm_bot/.env (git-ignored) and fill in at least POLY_TOKEN_ID_YES and POLY_TOKEN_ID_NO.
• If you only use the repo root, copy .env.example to .env there instead.

Environment variables

• Live trading: POLY_PRIVATE_KEY or PRIVATE_KEY is required (orders are EIP-712 signed). Optionally set POLY_API_KEY / POLY_API_SECRET / POLY_API_PASSPHRASE if you already have L2 creds; otherwise the client derives them.
• Dry-run, quotes only: omit the private key, keep BOT_DRY_RUN=true. Read-only CLOB endpoints need no auth.

Variable	Purpose
POLY_TOKEN_ID_YES / POLY_TOKEN_ID_NO	Required — outcome token IDs for one market
POLY_PRIVATE_KEY or PRIVATE_KEY	Required when BOT_DRY_RUN=false
POLY_SIGNATURE_TYPE	Optional. 0 EOA, 1 POLY_PROXY, 2 GNOSIS_SAFE (typical for polymarket.com)
POLY_FUNDER_ADDRESS or FUNDER_ADDRESS	Optional. Proxy wallet that holds collateral (required with types 1–2 when applicable)
BOT_DRY_RUN	Default true — no orders posted
BOT_POLL_INTERVAL_SEC	0 = single run; >0 = loop (seconds between iterations)
PM_BOT_STATE_FILE	JSON file tracking estimated USD notional after live fills (default .pm_bot_state.json)

See pm_bot/env.prefill (or .env.example in the repo root) for the full template.

Run

From the polymarket-bot directory (so .env is found), either:

Unified hub (recommended) — one terminal: Agent tab (primary) and Trading bot tab (Polymarket, secondary). Trading polling runs only while the Trading tab is active.

python -m pm_bot --hub
# or: pm-hub
# or set BOT_UI=hub in .env

Extend the agent by editing pm_bot/agent.py (handle_message). Plug in an LLM, call another repo, etc.

Bot-only modes (no agent UI):

python -m pm_bot

or, after pip install -e .:

pm-bot

Terminal UI

• Trading-only Textual TUI: python -m pm_bot --tui — same keyboard tuning as the Trading tab in the hub.
• Rich dashboard (default in a real terminal): order book, signal, risk, and decision in panels. Use BOT_UI=rich or rely on the default.
• Plain logs: BOT_UI=plain or python -m pm_bot --ui plain
• JSON (for scripting / “pretty structure”): BOT_UI=json or python -m pm_bot --json

With BOT_POLL_INTERVAL_SEC greater than 0, the screen refreshes each tick; config is reloaded every iteration so you can edit .env and see changes on the next cycle (the API client is recreated only if host, keys, or token IDs change).

Running on a Hostinger VPS (or any Linux server)

• Install Python 3.10+, clone the repo, create a venv, pip install -e ..
• Upload pm_bot/.env (or /etc/polymarket-bot.env) with chmod 600; never commit it.
• Use BOT_UI=plain or BOT_UI=json under systemd so logs go to the journal. --tui needs an interactive terminal (SSH with TTY), not a typical service.
• Example systemd ExecStart: /srv/polymarket-bot/.venv/bin/python -m pm_bot with WorkingDirectory=/srv/polymarket-bot, EnvironmentFile=/srv/polymarket-bot/pm_bot/.env, and Restart=always.
• Open outbound HTTPS to clob.polymarket.com (no inbound port required for the bot).
• Check Polymarket docs for geographic and product restrictions that apply to you.

Next steps

• Replace pm_bot/strategy.py with your actual model (BTC 15m, ETH by 1pm, etc.)
• Point the bot at a specific market by setting POLY_TOKEN_ID_YES and POLY_TOKEN_ID_NO
• Flip BOT_DRY_RUN=false only after you’ve tested with tiny size