PolyClaw Trading is a dry-run-first automation workspace for Polymarket prediction markets. It combines a deterministic Bitcoin signal engine, strict multi-layer bankroll and risk gating, multi-role LLM orchestration (advisory only), and optional live micro-order execution through the PolyClaw CLI. The system is deliberately conservative: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.
LIVE_TRADING defaults to 0 in every code path, real orders are never placed unless the operator explicitly sets LIVE_TRADING=1 in .env.local and completes a manual wallet approval step, and the dry-run command forcibly resets that value even if the environment already contains it. This architecture means you can safely run the full 8-stage pipeline — including signal generation, risk sizing, and execution — without touching a live market, and the simulated executions are still journaled to runtime/executions/YYYYMMDD.json so the system’s behavior is fully auditable before going live.
Safety default:
LIVE_TRADING=0. The system never submits a real order unless you explicitly set LIVE_TRADING=1 in .env.local and complete the manual PolyClaw wallet approval step. The dry-run command always pins LIVE_TRADING=0 and ALLOW_REDEEM=0, ignoring any inherited environment. Treat every dry-run record as a rehearsal — not a commitment.Key Components
PolyClaw Trading is organized around four primary components that work together to produce auditable, risk-gated trading decisions.polyclaw_engine (src/polyclaw_engine/, engine version 0.7.1) is the deterministic core. It trades only semantically validated Bitcoin binary markets using 5m pseudo-OHLC candles for execution and 15m candles for confirmation. Every indicator — EMA(8)/EMA(21), RSI(14), ATR(14), candle-pattern evidence, quality scoring — is computed deterministically, and an unclear or unsafe setup always resolves to HOLD, which is then persisted to runtime/manual_review.json rather than silently discarded.
openclaw_bot (src/, package version 3.3.0) provides the broader bot infrastructure: bankroll runtime, trade history, copy-trading signals, Telegram delivery, and the Flask-based Mission Control dashboard.
Mission Control dashboard (bot/dashboard/) is a Flask application that surfaces equity, realized P&L, drawdown state, open exposure, daily capacity, trade signals, and execution ledger data in read-only form. It binds to loopback (127.0.0.1:8080) by default and supports optional Bearer/X-Auth-Token authentication.
LLM orchestration (prompts/, multi-role) provides advisory analysis only. LLM roles may read runtime artifacts, but the deterministic execution gate does not depend on an LLM response. No order is ever blocked or permitted solely because of LLM output.
The 8-Stage Pipeline
Each independently executable stage communicates only through versioned JSON files inruntime/. Atomic writes, freshness checks, strict schemas, and finite-number validation prevent malformed or stale state from crossing a stage boundary.
| Stage | What it does |
|---|---|
| fetch | Discovers active BTC markets via Gamma keyset pagination, validates question semantics, and fetches public YES-token price history |
| candles | Builds UTC-aligned 5m and 15m pseudo-OHLC candles from raw history |
| analyze | Calculates quality scores, EMA8/EMA21, RSI14, ATR14, sample-density POC, and deterministic pattern evidence |
| signal | Generates a deterministic YES, NO, or HOLD signal and persists it |
| bankroll | Refreshes reserve, drawdown mode, daily limits, and exposure from the runtime trade registry |
| validate | Sizes the decision against every active capital cap; repeats semantic, quality, expiry, cooldown, duplicate, and risk checks |
| execute | Runs a dry-run log entry or dispatches through the PolyClaw subprocess (live mode only) |
| report | Writes the terminal report and runtime snapshot |
analysis-cycle (stages 1–4), trade-cycle (stages 1–7), and loop (continuous repetition) as compound orchestration modes.
Supported Platforms
PolyClaw Trading ships with first-class support for four operating environments.Linux / macOS (Shell)
Native Python 3.12+ with
uv for dependency management. POSIX launchers (cron_run.sh, scripts/*.sh) handle cron/launchd scheduling and gateway/TUI/Kilo worker startup.Windows
Full automation through
scripts/bootstrap_polyclaw_kilo.bat, which installs dependencies, prompts for local secrets, and launches the Kilo interactive shell plus an isolated worker loop.Docker
Single-command startup with
docker compose up --build. The dry-run pipeline runs automatically and state persists in the ./runtime volume mount.macOS Native Swift
A dependency-free Swift Package (
Sources/PolyclawMacCore/) replaces shell-specific workspace discovery and process launching with a native CLI. Trading and risk logic remain in Python; JSON files under runtime/ are the language boundary.Safety Contract
PolyClaw Trading enforces a strict secret hygiene policy by design. All secrets — API keys, private keys, proxy credentials, RPC URLs with embedded tokens — must live only in.env.local, which is gitignored. The repository includes tests/test_secret_scanner.py, which fails the CI build if secret-like patterns appear in any tracked file. The PolyClaw home config (~/.openclaw/openclaw.json) is modified exclusively through openclaw_patch.py, which takes a timestamped backup before every patch. The current stable release is openclaw-bot 3.3.0 / polyclaw_engine 0.7.1.
Explore the Docs
Quickstart
Clone the repo, sync dependencies, and run your first dry-run pipeline pass in under five minutes.
Installation
Platform-specific setup for Linux/macOS, Windows, Docker, and the native macOS Swift runner.