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 is designed from the ground up so that secrets — API keys, private keys, proxy credentials, and RPC URLs with embedded tokens — can never inadvertently end up in tracked files, build artifacts, log output, or the runtime/ state directory. This page documents every layer of that protection and the steps to take when a secret is suspected to have been exposed.
High-risk trading automation disclaimer. This software automates real-money trades on Polymarket prediction markets. Nothing in this system guarantees profit. Keep funded balances small; treat every live trade as your own responsibility. Rotate any compromised secret immediately and treat the associated wallet as compromised until you have verified the damage. This is not financial advice.

​
Where secrets live

Secrets are permitted in exactly two places:
  1. .env.local — a file in the project root that is listed in .gitignore and is never committed to version control. Copy .env.example to .env.local and fill in only the values you need.
  2. Environment variables — injected directly into the process environment by your shell, CI system, Docker secrets, or a secrets manager.
Secrets must never appear in:
  • Any tracked source file (.py, .json, .md, .yml, and so on)
  • Log files or terminal output
  • runtime/ files (these are generated state only — see the Runtime Files reference)
  • ~/.openclaw/openclaw.json except through the designated patching script described below
  • HTTP request URLs (API keys must always be sent as headers)

​
Build-time secret scanner

tests/test_secret_scanner.py fails the CI build if any secret-like pattern is detected in workspace-tracked files. This is an unconditional gate: the test suite cannot pass while a secret is present in a tracked file. The scanner detects API keys, private keys in PEM format, Google API keys, Telegram bot tokens, and hardcoded credential variable assignments. Common placeholder values used in .env.example are excluded from flagging to prevent false positives.
The scanner runs as part of the standard test suite: 
uv run pytest tests/test_secret_scanner.py -v
# or as part of the full audit:
uv run python run_pipeline.py audit
CI (GitHub Actions) runs this scanner on every push and pull request against Python 3.11 and 3.12.

​
OpenClaw config patching

The file ~/.openclaw/openclaw.json is secret-bearing (it may contain API keys and gateway tokens). It must only ever be modified through openclaw_patch.py: 
python openclaw_patch.py --key OPENROUTER_API_KEY --value "sk-or-..."
openclaw_patch.py performs the following sequence before every write:
  1. Reads the current ~/.openclaw/openclaw.json.
  2. Creates a timestamped backup (e.g. ~/.openclaw/openclaw.json.20260101T120000.bak).
  3. Applies the patch atomically.
This ensures that a failed patch leaves the previous known-good configuration intact. Direct editing of ~/.openclaw/openclaw.json is unsupported and bypasses the backup mechanism.

​
HTTP client security

All outbound HTTP requests made by the pipeline enforce the following rules, regardless of the endpoint:
  • HTTPS only. Any URL that does not begin with https:// raises a ConfigError at startup. Hardcoded internal URLs (gamma-api.polymarket.com, clob.polymarket.com) are validated at EngineConfig instantiation time.
  • No redirects. The HTTP client is configured to refuse all redirects to prevent credential forwarding to unexpected hosts.
  • Official-host allowlist. Only Polymarket’s official API hostnames are permitted as targets for authenticated requests. Attempts to contact unlisted hosts are rejected.
  • Response-size cap. Responses larger than HTTP_MAX_BYTES (default 8 MB) are truncated and the request fails closed.
  • Credentials never in URLs. API keys and tokens are always sent as HTTP headers. The Gemini API key, for example, was moved from URL query strings to secure headers in release 0.2.0 (#46).
  • Proxy credentials redacted. If HTTPS_PROXY contains embedded credentials, they are masked before any log output is written.

​
Secret redaction

The redaction layer is synchronized between two modules — openclaw_bot.io.runtime and polyclaw_engine.execution — so that both the LLM orchestration loop and the deterministic execution path apply identical masking rules. Redaction masks the following patterns wherever they appear in log output, runtime artifacts, or subprocess output:
  • OpenRouter, OpenAI, Anthropic, and Gemini API keys
  • Polymarket private keys
  • HTTPS proxy credentials (username:password in proxy URLs)
  • Telegram bot tokens (standalone occurrences)
  • Generic key parameters in URLs (e.g. ?key=abc123)
  • Key-value pairs in JSON objects where the key name matches a known secret field
  • Key-value pairs in shell-style assignments where the key name matches a known secret field
Redaction was hardened in release 3.3.0 to also cover standalone Telegram bot tokens and to keep both redaction implementations in strict sync (#1261).

​
Dashboard safety

The Mission Control dashboard (bot/dashboard/app.py) is read-only by design:
  • Loopback by default. The Flask app binds to 127.0.0.1 unless DASHBOARD_HOST is explicitly overridden.
  • Auth token required for non-local binding. If DASHBOARD_HOST is set to a non-loopback address, DASHBOARD_AUTH_TOKEN must also be set. Requests without the correct Bearer token or X-Auth-Token header receive HTTP 401. If the token is absent and the host is non-loopback, the server falls back to 127.0.0.1.
  • Runtime filename whitelist. Files served from runtime/ are validated against a strict filename regex before the path is resolved. This prevents path traversal attacks and ensures only the known runtime JSON files can be read through the dashboard API (#1197).
  • No writes through the dashboard. The dashboard exposes only GET endpoints for viewing equity, P&L, decisions, execution ledger, source health, and drawdown state.

​
File permissions

Sensitive local files are enforced to owner-only permissions (0600):
  • .env.local
  • ~/.openclaw/openclaw.json
  • Daily log files
The test tests/test_file_permissions_sentinel.py verifies these permissions programmatically so they cannot silently regress.

​
Vulnerability reporting

Report security vulnerabilities privately via GitHub Security Advisories. Do not open a public issue for security problems. You can expect an initial response within a few days. Only the latest release (main) is supported with security fixes. Particularly relevant areas for this project:
  • Secret leakage into tracked files, logs, or runtime artifacts.
  • Bypasses of the trade gate (trade_gate.py): dry-run/live enforcement, daily caps, circuit breaker (PANIC_STOP / auto-panic).
  • Command injection in PolyClaw subprocess invocations.
  • Dashboard authentication and binding weaknesses (bot/dashboard/).

​
Secret rotation

If you suspect a secret has been exposed:
  1. Rotate it immediately. Generate a new API key or private key from the relevant provider.
  2. Treat the associated wallet as compromised until you have verified no unauthorized transactions have occurred.
  3. Update .env.local with the new value (or set the new environment variable in your deployment environment).
  4. Restart the pipeline. The engine will pick up the new credentials on the next cycle without requiring any code changes.
  5. If a private key was exposed, revoke it at the wallet level and transfer funds to a new wallet before resuming live trading.
The pipeline does not cache secrets in memory between cycles, so a clean restart with rotated credentials is sufficient.

Build docs developers (and LLMs) love

Get started for freeTalk to us