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’s deterministic engine is built around eight named stages — fetch, candles, analyze, signal, bankroll, validate, execute, and report. Each stage is independently runnable, reads its inputs from runtime/ JSON files, and writes its outputs back there. No stage skips a failed predecessor or continues from malformed or stale upstream state.

​
Entry points

There are two ways to invoke a stage. Package CLI (polyclaw-engine) — the installed console script from the polyclaw_engine package: 
polyclaw-engine <stage>
# or, without installation:
uv run python -m polyclaw_engine <stage>
Subprocess runner (scripts/run_pipeline.py) — launches each stage as a separate process so JSON files remain the only inter-process contract. This is the Windows-first recommended entry point for full pipeline and loop execution: 
uv run python scripts/run_pipeline.py <mode>
Both entry points respect .env.local for configuration. The subprocess runner additionally pins LIVE_TRADING=0 when you use the dry-run mode, regardless of what the environment says.

​
The 8 pipeline stages

1

fetch — Discover active BTC markets

Queries the Polymarket Gamma API with keyset pagination, joins YES/NO outcomes by label, validates question semantics, and fetches public YES-token price history. Results are saved to runtime/.
uv run python -m polyclaw_engine fetch

# Offline testing with a fixture file (skips all network calls):
uv run python -m polyclaw_engine fetch --fixture tests/fixtures/btc_market.json
The --fixture flag accepts a path to a JSON file. When provided, the stage reads market data from the file instead of contacting Polymarket. Fixtures are forbidden in live mode.
2

candles — Build pseudo-OHLC candles

Constructs UTC-aligned 5-minute and 15-minute pseudo-OHLC candles from the price history written by fetch. The resulting candle sets are saved to runtime/.
uv run python -m polyclaw_engine candles
The engine uses 5m candles for execution signals and 15m candles for confirmation. Both must meet minimum quality thresholds (MIN_CANDLES_5M, MIN_CANDLES_15M) before the pipeline continues.
3

analyze — Compute indicators and quality

Reads the candle data and computes all indicators needed for signal generation: candle quality score, EMA8/EMA21, RSI14, ATR14, sample-density Point of Control (POC), realized volatility (population std of the last 20 close-to-close returns), and deterministic pattern evidence. Results are saved to runtime/market_analysis.json.
uv run python -m polyclaw_engine analyze
Indicators use exact Wilder smoothing for RSI and ATR. EMA uses alpha = 2 / (period + 1) with first-observation seeding. Non-finite numbers, bad OHLC geometry, and non-monotonic timestamps all fail closed.
4

signal — Generate YES/NO/HOLD decisions

Applies deterministic scoring across trend, RSI zone, candle patterns, candle quality, market quality, POC context, and timeframe alignment to produce a YES, NO, or HOLD direction with a confidence score. Every decision is persisted to runtime/decisions.json.
uv run python -m polyclaw_engine signal
The confidence formula is:
raw_score =
    trend          * 0.25 +
    rsi            * 0.15 +
    patterns       * 0.25 +
    candle_quality * 0.15 +
    market_quality * 0.10 +
    poc_context    * 0.05 +
    timeframe      * 0.05

confidence = clamp(raw_score - sum(penalties), 0, 1)
Any signal with confidence below MIN_EXECUTION_CONFIDENCE (default 0.72) becomes HOLD and is written to runtime/manual_review.json instead of proceeding to execution.
5

bankroll — Refresh risk and capital state

Reads the runtime trade registry and recomputes the current reserve balance, drawdown mode status, daily risk limits, daily notional limits, and open-exposure totals. Output is saved to runtime/bankroll_state.json.
uv run python -m polyclaw_engine bankroll
Drawdown multipliers are 1.00 (normal), 0.50 (reduced), and 0.25 (critical). Critical mode activates at twice DRAWDOWN_TRIGGER_PCT; recovery to normal requires drawdown to fall to or below DRAWDOWN_RECOVERY_PCT.
6

validate — Size position and check all gates

Sizes the position against every active capital cap (per-trade risk, daily risk, daily notional, open exposure, free balance minus reserve) and then reruns a fresh set of semantic, quality, expiry, cooldown, duplicate, and risk checks. Only a decision that clears every gate proceeds to execute.
uv run python -m polyclaw_engine validate
Position sizing takes the minimum of: the confidence-interpolated maximum, the bankroll-risk cap, the position cap, remaining daily risk, remaining daily notional, remaining exposure, and free balance. A failed gate writes the reason to runtime/trade_gate_status.json and stops the cycle.
7

execute — Dry-run or invoke PolyClaw

In dry-run mode (default, LIVE_TRADING=0), records the execution plan to runtime/executions/YYYYMMDD.json without sending any order. In live mode (LIVE_TRADING=1), rereads fresh bankroll, risk, registry, expiry, semantic, pattern, quality, and cooldown state immediately before launching the PolyClaw subprocess.
uv run python -m polyclaw_engine execute
Every execution — dry or live — is journaled under runtime/executions/. If PolyClaw succeeds on-chain but the CLOB sell fails, the engine records partial_failure, reserves the market, and activates cooldown. Offline fixtures are forbidden in live mode.
8

report — Write terminal report and runtime snapshot

Writes a human-readable terminal report summarizing the cycle outcome and saves a runtime snapshot to runtime/.
uv run python -m polyclaw_engine report
This is the final stage of every cycle. It does not affect state for subsequent cycles.

​
Orchestration commands

Beyond running individual stages, both entry points support higher-level orchestration:

​
cycle — Run all 8 stages once

Executes the complete pipeline from fetch through report in sequence: 
# Via package CLI:
uv run python -m polyclaw_engine cycle

# Via subprocess runner:
uv run python scripts/run_pipeline.py cycle
Use --fixture to supply an offline market file for the fetch stage: 
uv run python -m polyclaw_engine cycle --fixture tests/fixtures/btc_market.json

​
loop — Repeat cycle on interval

Runs cycle repeatedly, sleeping LOOP_INTERVAL_SEC seconds (default 300) between iterations: 
uv run python -m polyclaw_engine loop

# Bounded execution for supervision or testing:
uv run python -m polyclaw_engine loop --max-cycles 2

# With fixture for offline loop testing:
uv run python scripts/run_pipeline.py loop --fixture tests/fixtures/btc_market.json --max-cycles 2
--max-cycles 0 (the default) means unlimited. Set a positive integer to cap the number of cycles for supervision or automated test runs.

​
audit — Run the unittest test suite

Discovers and runs all tests under tests/ using Python’s built-in unittest: 
uv run python scripts/run_pipeline.py audit
# or:
uv run python -m polyclaw_engine audit
The audit covers deterministic boundaries, contracts, risk rules, and execution safety. It also runs the secret-scanner check that fails the build if secret-like patterns appear in tracked files.

​
analysis-cycle vs trade-cycle

The subprocess runner (scripts/run_pipeline.py) exposes two partial-pipeline shortcuts:
ModeStages runPurpose
analysis-cyclefetch, candles, analyze, signalSignal generation only — no bankroll, validation, or execution
trade-cyclefetch through execute (skips report)Full trading pass without the terminal report
dry-runAll 8 stages, LIVE_TRADING forced to 0Safe offline verification
# Analysis only:
uv run python scripts/run_pipeline.py analysis-cycle

# Trade cycle without report:
uv run python scripts/run_pipeline.py trade-cycle

# Forced dry-run (ignores any LIVE_TRADING=1 in the environment):
uv run python scripts/run_pipeline.py dry-run

​
Runtime JSON contract

Every stage reads and writes under runtime/. Key files:
FileWritten byContains
runtime/decisions.jsonsignalYES/NO/HOLD decisions with confidence scores
runtime/bankroll_state.jsonbankrollEquity, reserve, drawdown, exposure
runtime/market_analysis.jsonanalyzeIndicators, patterns, quality scores
runtime/trade_gate_status.jsonvalidateGate result, block reason, daily counters
runtime/executions/YYYYMMDD.jsonexecuteDaily execution ledger (dry and live)
runtime/manual_review.jsonsignalHOLD decisions that need operator review
All runtime files use an envelope schema with schema_version, stage, generated_at, and data fields. Atomic writes use a unique temporary sibling, flush with fsync, then os.replace. Malformed JSON, wrong schema version, stale timestamps, non-finite numbers, and invalid price bounds always fail closed.

Build docs developers (and LLMs) love

Get started for freeTalk to us