Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deniszidbaev-cmyk/polyclaw-trading/llms.txt

Use this file to discover all available pages before exploring further.

PolyClaw Trading is deliberately fail-closed: the system never places a real order unless you complete each step in this guide in order. The default configuration (LIVE_TRADING=0) records every decision in daily ledgers so behavior is fully auditable before a single real dollar is at risk. Work through every step below before touching LIVE_TRADING=1.
Prediction market trading is high-risk. Nothing in PolyClaw Trading guarantees profit. Keep balances small, rotate any compromised secrets immediately, and treat every live trade as your own sole responsibility. This is not financial advice.

​
Prerequisites checklist

1

Fund the wallet with only what you can afford to lose

Transfer only the amount you are genuinely prepared to lose entirely. PolyClaw micro-orders default to MIN_TRADE_USD=0.25 and MAX_TRADE_USD=1.00, but the bankroll engine can execute up to MAX_TRADES_PER_DAY=6 per day and MAX_OPEN_EXPOSURE_PCT=20 of the working bankroll at once.Set BANK_USD and BANKROLL_USD in .env.local to match your actual funded balance before enabling live mode.
2

Complete the manual PolyClaw wallet approval step

The PolyClaw CLI requires a one-time wallet approval on-chain before it can submit orders. Run the approval interactively (substitute your actual market ID and amount):
uv run python scripts/polyclaw.py buy <market_id> YES <amount>
This step is deliberately manual. The engine will not attempt to approve the wallet automatically. Until approval is confirmed, any live execution attempt will be rejected by the PolyClaw subprocess.
3

Verify the PolyClaw CLI is installed and configured

Confirm that the PolyClaw binary is installed and that POLYCLAW_PATH in .env.local points to it:
# .env.local
POLYCLAW_PATH=/path/to/polyclaw
The engine reads POLYCLAW_PATH (or the backward-compatible alias POCLAW_PATH) at execution time. If the path is unset or the binary is missing, every live execution attempt will fail closed.
4

Set rotated API keys in .env.local

Copy .env.example to .env.local (which is gitignored) and fill in the secrets required for live trading. Never commit these values to version control.
cp .env.example .env.local
Minimum required secrets for live trading:
# .env.local
POLYMARKET_WALLET_ADDRESS=0x...
POLYCLAW_PRIVATE_KEY=...
CHAINSTACK_NODE=https://...
POLYCLAW_PATH=/path/to/polyclaw
The secret-scanner test (tests/test_secret_scanner.py) fails the build if secret-like patterns appear in any tracked file. Keep all keys in .env.local only.
5

Run the full audit

Before any live pass, verify the engine and all safety contracts pass their tests:
uv run python scripts/run_pipeline.py audit
The audit runs the full unittest suite covering deterministic boundaries, risk rules, contract validation, and execution safety. A failing audit must be resolved before proceeding.
6

Run multiple dry-run passes and inspect the execution ledger

Run several complete dry-run cycles and inspect the daily execution ledger to confirm the engine is making sensible decisions on your markets and configuration:
# Single dry-run pass (forces LIVE_TRADING=0 even if .env.local says otherwise):
uv run python scripts/run_pipeline.py dry-run

# Offline dry-run with a fixture (no network calls):
uv run python scripts/run_pipeline.py dry-run --fixture tests/fixtures/btc_market.json

# Bounded dry-run loop (2 cycles):
uv run python scripts/run_pipeline.py loop --fixture tests/fixtures/btc_market.json --max-cycles 2
After each pass, inspect the daily execution ledger. The file is created whether trading is live or not:
cat runtime/executions/$(date +%Y%m%d).json
Dry-run executions are recorded with "dry_run": true so the ledger is fully auditable before going live.
7

Inspect decisions.json and bankroll_state.json

Verify that the engine is reading your bankroll correctly and that decisions look reasonable:
cat runtime/decisions.json
cat runtime/bankroll_state.json
Check that equity_usd, working_bank_usd, and free_balance_usd in bankroll_state.json match your actual funded balance. Check that decisions in decisions.json have realistic confidence scores and correctly-sized amount_usd values relative to your bankroll.
8

Set LIVE_TRADING=1 in .env.local

When you are satisfied with dry-run behavior, enable live trading by editing .env.local:
# .env.local
LIVE_TRADING=1
The exact string "1" is required. Values like "true", "yes", "on", or "live" will not enable live trading — the check is a strict equality match against "1". Any other value leaves the engine in dry-run mode.
The dry-run mode of scripts/run_pipeline.py forcibly resets LIVE_TRADING to 0 and ALLOW_REDEEM to 0, even if .env.local says otherwise. To run live, use scripts/run_pipeline.py live --confirm-live or uv run python -m polyclaw_engine loop (which inherits the environment you have set).
9

Optionally enable automatic redeem

If you want the engine to automatically redeem resolved markets, set:
# .env.local
ALLOW_REDEEM=1
Like LIVE_TRADING, this must be the exact string "1". Leave it at 0 if you prefer to redeem manually.
10

Restart the loop

Start the live loop. The recommended entry point on Windows explicitly requires --confirm-live:
uv run python scripts/run_pipeline.py live --confirm-live
On macOS/Linux you can also use the package CLI directly (it inherits LIVE_TRADING=1 from .env.local):
uv run python -m polyclaw_engine loop
Every execution is journaled under runtime/executions/YYYYMMDD.json.

​
What happens at live execution

Immediately before launching the PolyClaw subprocess, the execute stage rereads the following state fresh from disk — it does not rely on values cached earlier in the same cycle:
  • Bankroll state (runtime/bankroll_state.json)
  • Risk gate state (runtime/trade_gate_status.json)
  • Trade registry (open positions and daily counters)
  • Market expiry and semantic mapping
  • Pattern and quality scores
  • Per-market cooldown status
This ensures that a state change that occurred mid-cycle — such as another process updating the trade registry, or a cooldown expiring — is reflected in the final go/no-go decision.

​
Partial failure handling

The PolyClaw CLI performs two on-chain operations: a contract split and a CLOB sell. These can succeed and fail independently:
  • If the on-chain split succeeds but the CLOB sell fails, the engine records the outcome as partial_failure in the execution ledger.
  • The affected market is reserved and a cooldown is activated (FAILED_ORDER_COOLDOWN_SEC, default 1800 seconds).
  • The engine does not retry automatically. Inspect the ledger and resolve manually.

​
Offline fixtures are forbidden in live mode

The --fixture flag is accepted only by fetch, cycle, or loop and only when LIVE_TRADING=0. Attempting to use --fixture in live mode raises a ConfigError and blocks execution. This prevents accidentally trading against stale or fabricated market data.

​
Returning to dry-run

To stop live trading at any time: 
# .env.local
LIVE_TRADING=0
Then restart the loop. The dry-run mode of the subprocess runner also hard-forces dry-run mode without requiring a file edit: 
uv run python scripts/run_pipeline.py dry-run
All execution records remain under runtime/executions/ and are not deleted when you switch modes.

Build docs developers (and LLMs) love

Get started for freeTalk to us