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 supports four distinct installation paths depending on your operating system and preference for containerization. All paths share the same Python core (polyclaw_engine, openclaw_bot) and the same runtime/ JSON contract — you can switch between them without losing state. Choose the tab that matches your environment, then review the requirements section below for what each path needs before enabling live trading.
Linux / macOS
Windows
Docker
macOS Swift
The native shell path uses Python 3.12+ and uv for dependency management. POSIX launchers under scripts/ and the root cron_run.sh handle scheduling and helper service startup.1. Install prerequisitesEnsure Python 3.12+ and uv are available on your PATH. The recommended way to install uv is via its official installer:curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/deniszidbaev-cmyk/polyclaw-trading.git
cd polyclaw-trading
uv sync
cp .env.example .env.local
# Edit .env.local — fill in only what you need.
# Confirm LIVE_TRADING=0 before running anything.
chmod +x cron_run.sh scripts/*.sh
uv run python scripts/run_pipeline.py audit
uv run python scripts/run_pipeline.py dry-run \
--fixture tests/fixtures/btc_market.json
cron_run.sh uses the checkout directory by default. If you run it from cron or launchd outside the project directory, set OPENCLAW_WORKSPACE to the absolute path of your checkout:# Example crontab entry (every 5 minutes)
*/5 * * * * OPENCLAW_WORKSPACE=/path/to/polyclaw-trading /path/to/polyclaw-trading/cron_run.sh dry-run
./scripts/launch_openclaw_gateway.sh # OpenClaw gateway
./scripts/launch_openclaw_tui.sh # OpenClaw TUI
./scripts/launch_kilo_worker.sh # Kilo worker loop
Windows uses the same Python 3.12+ and uv foundation, plus a batch installer that automates dependency setup, secret prompting, and service startup.1. Install prerequisites
- Python 3.12+ (ensure it is added to
PATH during installation)
- uv — install via PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
git clone https://github.com/deniszidbaev-cmyk/polyclaw-trading.git
cd polyclaw-trading
uv sync
Copy-Item .env.example .env.local
# Open .env.local in a text editor and fill in values.
# Confirm LIVE_TRADING=0 before proceeding.
uv run python scripts/run_pipeline.py audit
uv run python scripts/run_pipeline.py dry-run `
--fixture tests/fixtures/btc_market.json
scripts/bootstrap_polyclaw_kilo.bat automates the full Windows setup: installs dependencies, interactively prompts for local secrets, launches the Kilo interactive shell, starts an isolated Kilo worker for recurring LLM analysis, and starts the trading loop..\scripts\bootstrap_polyclaw_kilo.bat
scripts/README.md for all available launchers and docs/PORTABLE_VPS.md for the portable/VPS workflow.PowerShell execution policyIf you encounter execution policy errors, run the following before invoking any .ps1 scripts:Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Docker Compose provides an isolated, reproducible environment. The container runs the dry-run pipeline automatically on startup, and all runtime state persists in a local volume mount so it survives container restarts.Prerequisites: Docker Desktop (macOS/Windows) or Docker Engine + Compose plugin (Linux).1. Clone the repositorygit clone https://github.com/deniszidbaev-cmyk/polyclaw-trading.git
cd polyclaw-trading
cp .env.example .env.local
# Edit .env.local as needed.
# LIVE_TRADING=0 is the default — do not change it for initial testing.
docker compose up --build
./runtime on the host via a volume mount, so it persists across restarts and is accessible to host-side tools.4. Subsequent runsAfter the initial build, you can restart without rebuilding:Force a rebuild when you pull new code or change dependencies:docker compose up --build
.env.local are injected into the container at runtime. Do not bake secrets into the Docker image itself — the .env.local file must remain on the host and outside version control.Dashboard accessIf the Mission Control dashboard is enabled (DASHBOARD_HOST=0.0.0.0 in .env.local), it is accessible at http://localhost:8080. The default loopback binding (127.0.0.1) means the dashboard is not reachable from outside the container — set DASHBOARD_HOST=0.0.0.0 and DASHBOARD_AUTH_TOKEN when exposing it. The native macOS Swift runner (Sources/PolyclawMacCore/) replaces shell-specific workspace discovery, process launching, TUI retries, and the isolated Kilo worker loop with a single dependency-free native CLI binary. Trading and risk logic remain in Python; the Swift layer handles macOS process management only.The macOS Swift runner handles workspace discovery automatically from the current directory (or OPENCLAW_WORKSPACE), loads .env.local without echoing secret values, prefers .venv/uv for Python execution, and writes all pipeline output to runtime/macos-runner.log. Its dry-run command pins both LIVE_TRADING=0 and ALLOW_REDEEM=0 — even if inherited configuration says otherwise. JSON files under runtime/ remain the language boundary between Swift and Python, so trading modules can be migrated to Swift independently later.
uv are still required for the Python pipeline stages.1. Install Apple toolchain (if needed)2. Clone and sync Python dependenciesgit clone https://github.com/deniszidbaev-cmyk/polyclaw-trading.git
cd polyclaw-trading
uv sync
cp .env.example .env.local
swift run polyclaw-mac-selftest
.build/release/polyclaw-mac doctor
doctor checks that the Python environment, .env.local, and runtime/ directory are correctly configured.6. Run the audit.build/release/polyclaw-mac audit
.build/release/polyclaw-mac run
runtime/macos-runner.log.8. Run a single analysis pass.build/release/polyclaw-mac kilo-worker --once
LIVE_TRADING=1 in .env.local and the --confirm-live flag at the command line. Neither alone is sufficient:.build/release/polyclaw-mac run live --confirm-live
Requirements
Required for all modes
| Requirement | Notes |
|---|
| Python 3.12+ | Required by polyclaw_engine and openclaw_bot |
| uv | Dependency and virtual-environment manager (docs.astral.sh/uv) |
Required for live trading only
| Requirement | Notes |
|---|
| Funded wallet | Fund with only what you are prepared to lose; start with the minimum |
| PolyClaw CLI | From chainstacklabs/polyclaw; path configured via POLYCLAW_PATH in .env.local |
| Rotated API keys | POLYMARKET_WALLET_ADDRESS, POLYCLAW_PRIVATE_KEY, and any LLM/data keys you intend to use |
| Manual wallet approval | The PolyClaw wallet approval step must be completed before setting LIVE_TRADING=1 |
Optional
| Requirement | Notes |
|---|
| Docker | Required for the Docker Compose installation path |
| Xcode / Swift toolchain | Required for the native macOS Swift runner only |
| Telegram bot token | TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID for trade/report notifications |
| LLM API keys | OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY — required only if you enable multi-role LLM orchestration |
| OpenClaw gateway | OPENCLAW_GATEWAY_URL + OPENCLAW_GATEWAY_TOKEN for the gateway-backed TUI and Kilo worker |
