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 exposes two complementary CLI interfaces. The polyclaw-engine package entrypoint runs individual pipeline stages (or the full cycle) inside a single Python process, while scripts/run_pipeline.py is a Windows-first subprocess runner that launches each stage as a separate process so that JSON files remain the only inter-process contract. Both interfaces share the same exit-code convention and understand the same --fixture flag for offline dry-run verification.

​
polyclaw-engine

polyclaw-engine is installed as a package entrypoint backed by src/polyclaw_engine/orchestrator.py. It accepts one positional command and two optional flags.

​
Synopsis

polyclaw-engine <command> [--fixture <path>] [--max-cycles <N>]

​
Flags

​
--fixture
path
Path to an offline market fixture JSON file. Accepted only by fetch, cycle, and loop. Passing --fixture to any other stage raises ConfigError and exits with code 2.
​
--max-cycles
integer
default:"0"
Maximum number of loop iterations. 0 means unlimited. Only meaningful with the loop command.

​
Exit codes

CodeMeaning
0Success
2ConfigError, ContractError, HttpClientError, or OSError — printed to stderr as [blocked] ExceptionType: message
130KeyboardInterrupt — loop was interrupted cleanly

​
Commands

The full pipeline is fetch → candles → analyze → signal → bankroll → validate → execute → report. Each stage can be run in isolation:
CommandDescription
fetchDiscover active BTC binary markets via Gamma keyset pagination, validate semantics, fetch YES-token price history, and write runtime/market_snapshot.json.
candlesBuild UTC-aligned 5m and 15m pseudo-OHLC candle arrays from raw price samples and write runtime/candles.json.
analyzeCompute EMA8/EMA21, RSI14, ATR14, sample-density POC, realized volatility, candle patterns, and market/candle quality scores. Writes runtime/market_analysis.json.
signalGenerate deterministic YES, NO, or HOLD decisions with confidence breakdown from analysis state. Writes runtime/decisions.json and runtime/manual_review.json.
bankrollRefresh equity, reserve, drawdown mode, and daily limits from the trade registry. Writes runtime/bankroll_state.json and runtime/risk_state.json.
validateSize approved decisions against every active capital cap and repeat semantic, quality, expiry, and cooldown checks. Writes updated runtime/decisions.json (stage: validate) and runtime/manual_review.json.
executeSubmit to PolyClaw (live) or log a dry-run record. Appends to runtime/executions/YYYY-MM-DD.json.
reportPrint a terminal summary and write runtime/runtime_snapshot.json. Reads decisions.json, bankroll_state.json, risk_state.json, and execution_status.json; raises ContractError (exit 2) if any required file is missing or stale.
cycleRun all eight stages once in order. Equivalent to running each stage individually. Accepts --fixture.
loopRepeat the full cycle indefinitely (or up to --max-cycles), sleeping LOOP_INTERVAL_SEC seconds between cycles. Accepts --fixture and --max-cycles.
auditRun python -m unittest discover -s tests -v from the project root and return the subprocess exit code.

​
Example invocations

# Single stage — fetch live market data
polyclaw-engine fetch

# Full one-shot cycle
polyclaw-engine cycle

# Offline dry-run using a fixture (never contacts Polymarket)
polyclaw-engine fetch --fixture tests/fixtures/btc_market.json

# Recurring loop, stop after 5 cycles
polyclaw-engine loop --max-cycles 5

# Recurring offline loop with a fixture
polyclaw-engine loop --fixture tests/fixtures/btc_market.json --max-cycles 2

# Run audit suite
polyclaw-engine audit
--fixture is silently forwarded only to the fetch stage when running cycle or loop. The remaining stages always read from the standard runtime file locations.

​
run_pipeline.py

scripts/run_pipeline.py is the Windows-first subprocess runner. It launches each polyclaw_engine stage as a separate python -m polyclaw_engine <stage> process, keeping JSON files as the only inter-process contract. Its safety guarantee is that dry-run forcibly pins LIVE_TRADING=0, ALLOW_REDEEM=0, PIPELINE_FORCE_LIVE_TRADING=0, and PIPELINE_FORCE_ALLOW_REDEEM=0 before any subprocess starts.

​
Synopsis

python scripts/run_pipeline.py <mode> [--fixture <path>] [--max-cycles <N>] [--confirm-live]

​
All modes

ModeDescription
dry-runRuns the full pipeline (fetch → report) with LIVE_TRADING forcibly set to 0. Safe to call at any time.
liveRuns the full pipeline with LIVE_TRADING=1. Requires --confirm-live; blocked otherwise (exits 1).
pipeline / cycle / full-cycleRuns the full pipeline with the current environment. Warns if LIVE_TRADING=1 is already set.
trade-cycleRuns stages fetch through execute (skips report).
analysis-cycleRuns stages fetch through signal (skips bankroll, validate, execute, report).
loopDelegates to polyclaw-engine loop, forwarding --fixture and --max-cycles.
audit / testRuns python -m unittest discover -s tests -v.
fetch / candles / analyze / signal / bankroll / validate / execute / reportRuns the named stage as a subprocess, forwarding --fixture to fetch if provided.

​
Flags

​
--fixture
path
Forwarded to the fetch stage subprocess as --fixture <path>. Enables fully offline operation.
​
--max-cycles
integer
default:"0"
Forwarded to polyclaw-engine loop. 0 means unlimited.
​
--confirm-live
boolean
Required for live mode. Without it, the runner prints [blocked] live mode requires --confirm-live and exits 1.

​
Example invocations

Standard offline dry-run (from the README and btc_strategy_engine.md): 
# Windows — offline dry-run verification, never contacts Polymarket or PolyClaw
$env:LIVE_TRADING = "0"
uv run python .\run_pipeline.py dry-run --fixture .\tests\fixtures\btc_market.json

# macOS/Linux — equivalent
uv run python scripts/run_pipeline.py dry-run --fixture tests/fixtures/btc_market.json
Audit suite: 
uv run python scripts/run_pipeline.py audit
Recurring loop (dry-run, bounded): 
# Long-running dry-run loop; omit --max-cycles for continuous operation
uv run python scripts/run_pipeline.py loop --fixture tests/fixtures/btc_market.json --max-cycles 2
Live submission (deliberately manual): 
uv run python scripts/run_pipeline.py live --confirm-live
Individual stage: 
uv run python scripts/run_pipeline.py fetch
uv run python scripts/run_pipeline.py analyze
dry-run mode actively overwrites LIVE_TRADING, ALLOW_REDEEM, PIPELINE_FORCE_LIVE_TRADING, and PIPELINE_FORCE_ALLOW_REDEEM in the child environment to 0. It does not modify your shell environment or .env.local. live mode requires the exact string --confirm-live at the command line; no environment variable substitutes for this flag.
Use uv run python scripts/run_pipeline.py dry-run --fixture tests/fixtures/btc_market.json for a fully reproducible offline smoke-test that exercises every stage without any network calls.

Build docs developers (and LLMs) love

Get started for freeTalk to us