Developer runbook

From git-clone to first decision in fifteen minutes. Anything longer is a bug — file an issue against this page.

1. Local prerequisites

Node 20+ or Python 3.11+ (each bot declares which it ships in).
Docker + Docker Compose (for the local Polygon fork and the CLOB-V2 mock server).
A Polygon address with at least 100 pUSD on the testnet. (Bridge from https://bridge.polymarket.com testnet.)
Polytraders SDK installed: npm i @polytraders/sdk or pip install polytraders-sdk.

2. Clone and bootstrap

git clone https://github.com/polytraders/core.git
cd core
make bootstrap   # installs deps, runs migrations, starts local stack
make seed        # loads fixture markets, fills, and oracle proposals
make smoke       # runs a 30-second smoke test across all live bots

3. Run a single bot in shadow mode

POLYTRADERS_MODE=shadow_only \
POLYTRADERS_BOT=risk.liquidity_guard \
POLYTRADERS_LOG_LEVEL=debug \
make run-bot

# In another shell, replay fixture intents:
make replay FIXTURE=fixtures/intents/2026-05-01.jsonl

4. Author a new bot

Pick a layer + slug. Create bots/<layer>/<slug>.json and copy from templates/reference_bot_schema.md.
Set "is_reference": false until all 27 checklist fields are green.
Write the pseudocode under reference_implementation first. Do not start typing the implementation language until the pseudocode reviews clean.
Author the wire examples (wire_examples) using fixtures captured from staging — never invented.
List your reason codes. Reuse global codes where possible; add bot-specific codes only when none of the global ones fit.
Declare metrics, alerts, dependencies, security surfaces, V2 compatibility. Then implement.
Run make checklist BOT=<layer>.<slug> until 27/27 green.
Open the PR. CI gates on checklist completeness, schema validity, and reason-code stability (no rewords of existing codes).

5. Promotion

See Promotion gates for the criteria each readiness state must meet. Promotion is observable, not subjective: gates are derived from production metrics, never sign-off lists.

6. Common foot-guns

Hard-coding endpoints. Use the SDK constants. Endpoints have moved twice in twelve months.
Hand-rolling EIP-712. Don't. Use buildOrderTypedData. The Exchange domain version is "2" in V2; ClobAuth stays at "1". Conflating them produces silent rejects.
Embedding fees in the signed order. V2 fees are operator-set at match time. Do not put them on the order.
Building HMAC headers for builder attribution. That was V1. V2 uses the builderCode field on the order.
Reading USDC.e balances. Collateral is now pUSD. The migration completed Apr 28, 2026.
Treating WebSocket as best-effort. Two of the four channels (market and user) carry decisions. Reconnect with last-message-id resume; never trust an empty book on a fresh connection.