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.

This guide walks you through cloning PolyClaw Trading, installing its dependencies, and running your first complete dry-run pipeline pass — all without touching a live market. The entire sequence uses an offline BTC market fixture bundled in the repository, so no API keys or funded wallet are required for these first steps. When you’re ready to move beyond the fixture, see the Installation guide for platform-specific setup and the .env.example reference for the full configuration surface.
Never set LIVE_TRADING=1 until you are fully prepared. That means a funded wallet, a completed PolyClaw wallet approval step, rotated API keys, and a thorough review of your .env.local risk parameters. The dry-run command always pins LIVE_TRADING=0 regardless of your environment — but pipeline, cycle, and loop modes do not override it, so an accidental LIVE_TRADING=1 in your shell can reach real markets in those modes.

​
Prerequisites

Before you begin, make sure the following are available on your system:
  • Python 3.12+ — required by the polyclaw_engine package
  • uv — the project’s dependency and virtual-environment manager
  • git — to clone the repository
No other tools are required for dry-run operation.

​
Setup Steps

1

Clone the repository

Clone the PolyClaw Trading repository and move into the project directory.
git clone https://github.com/deniszidbaev-cmyk/polyclaw-trading.git
cd polyclaw-trading
2

Install dependencies with uv

Run uv sync to create a virtual environment and install all project dependencies declared in pyproject.toml. This includes python-dotenv, requests, py-clob-client, web3, and flask.
uv sync
3

Configure your environment file

Copy the exhaustive environment template to .env.local. The .env.local file is gitignored — it is the only place secrets should ever live. For this quickstart you do not need to fill in any secret values; the defaults are safe for offline dry-run operation.
cp .env.example .env.local
Open .env.local and confirm that LIVE_TRADING=0 is set (it is the default). Do not change it yet.
4

Run the audit

The audit command runs the full unittest discovery suite — covering deterministic boundaries, contracts, risk rules, secret scanner, and execution safety — without making any network requests. A clean audit output means the local environment and codebase are consistent.
uv run python scripts/run_pipeline.py audit
All tests should pass before proceeding. If the secret scanner test fails, check that .env.local has not been accidentally staged or that no API key has been hardcoded into a tracked file.
5

Run your first dry-run pass

Execute a complete single-pass dry-run of the 8-stage pipeline (fetch → candles → analyze → signal → bankroll → validate → execute → report) using the bundled BTC market fixture. The --fixture flag routes the fetch stage to load a local JSON file instead of calling the Polymarket API.
uv run python scripts/run_pipeline.py dry-run \
  --fixture tests/fixtures/btc_market.json
The runner pins LIVE_TRADING=0, ALLOW_REDEEM=0, PIPELINE_FORCE_LIVE_TRADING=0, and PIPELINE_FORCE_ALLOW_REDEEM=0 for the entire process tree, regardless of what .env.local or the shell environment says. Each stage runs as a separate subprocess and writes its output as a versioned JSON file under runtime/:
runtime/
├── markets.json          # fetch stage output
├── candles.json          # candles stage output
├── analysis.json         # analyze stage output
├── decisions.json        # signal stage output
├── bankroll_state.json   # bankroll stage output
├── executions/
│   └── YYYYMMDD.json     # execute stage ledger (dry-run entries)
└── report.json           # report stage output
A HOLD decision (common on first run with a static fixture) is expected and correct — it means the deterministic engine did not find sufficient confidence to size a position, and the result is persisted to runtime/manual_review.json for operator review.
6

Run a bounded dry-run loop

The loop mode repeats the full pipeline on a configurable interval. Use --max-cycles to bound it for testing so it stops automatically after the specified number of passes.
uv run python scripts/run_pipeline.py loop \
  --fixture tests/fixtures/btc_market.json \
  --max-cycles 2
Omit --max-cycles for continuous operation. The loop interval is controlled by LOOP_INTERVAL_SEC in .env.local (default: 300 seconds).

​
Docker One-Liner

If you prefer a containerized environment, Docker Compose provides a single-command alternative that mounts ./runtime for state persistence. 
cp .env.example .env.local
docker compose up --build
The container runs the dry-run pipeline automatically. See Installation → Docker for details on volume management and environment variable injection.

​
Next Steps

  • Installation — platform-specific setup for Linux/macOS shell, Windows batch launcher, Docker Compose, and the native macOS Swift runner.
  • .env.example — the exhaustive configuration reference, covering all risk parameters, indicator tuning, LLM role routing, and dashboard options.
  • docs/verified_dependencies.md — primary-source API and CLI preflight, including the verified PolyClaw buy syntax and known partial-failure behavior, required reading before enabling live trading.

Build docs developers (and LLMs) love

Get started for freeTalk to us