Polymarket Engine — Документация

Тема

Environment Variables Reference ​

Canonical source of every supported env var with [REQUIRED] / [OPTIONAL] markers: env/.env.example.

This document groups variables by feature area and explains the interplay between groups. It does not list every variable individually — env/.env.example is the single source of truth and is enforced at startup by the BotConfig::from_env fail-fast policy (see CLAUDE.md "Environment").

Strategy scope (ADR-024): активная стратегия одна — directional/Harvester. Все strategy-knobs (включая directional) живут в SQLite config.db per ADR-015, не в env. Архивные стратегии (bucket-arb, maker, maker-rebate, merge-arb, single-token-mm) и их env-блоки удалены — см. docs/restoration-backlog/README.md.

Reading guide ​

  • [REQUIRED] — pm-engine panics at startup if missing or empty.
  • [OPTIONAL] — None / empty has explicit semantic (e.g. "no exit price", "no IP allowlist").

There are no silent runtime defaults. Every value the bot trades against must be declared explicitly in .env. Bootstrap a fresh .env via:

sh
cargo run -p pm-cli -- init --chain-id 137

Variable groups ​

Polymarket connectivity ​

  • POLY_API_KEY, POLY_SECRET, POLY_PASSPHRASE — CLOB L2 credentials. Generate via cargo run -p pm-cli -- init.
  • WALLET_PRIVATE_KEY — Polygon private key. Per feedback_encrypted_wallets, prefer the pm-sdk encrypted-keys feature (AES-256-GCM + Argon2id) over plaintext .env. With ADR-015 multi-wallet, prefer BOT_WALLET_LABEL → encrypted wallets.db.
  • CLOB_URL, POLYMARKET_GAMMA_URL, POLYMARKET_DATA_URL, POLYMARKET_CLOB_URL — REST endpoints. Production: clob.polymarket.com, gamma-api.polymarket.com, data-api.polymarket.com. Override only on staging.

Global thresholds ​

  • BOT_BUDGET_PER_MARKET, BOT_TOTAL_BUDGET — risk caps. TOTAL empty/unset = unlimited (use only with explicit operator authorisation).

Risk management (cross-strategy) ​

  • BOT_MAX_ORDERS, BOT_FALLBACK_SCAN_SECS. (BOT_MAX_ORDER_AGE_HOURS removed by openspec cleanup-sim-ttl-legacy — per-order TTL is now driven through DIRECTIONAL_BUY_ORDER_TTL_* knobs / config.db.)

Per ADR-024 (directional-first), automated stop-loss env knobs (BOT_RISK_MANAGEMENT, BOT_STOP_LOSS_* block) have been removed. Operator intervention via the dashboard emergency-stop button (POST /api/local/emergency-stop, ADR-005) is the canonical exit path.

Re-pricing ​

BOT_REPRICE_* block.

WebSocket freeze handling ​

BOT_WS_FREEZE_* — graceful order cancellation + emergency stop on prolonged WS disconnect.

External signal source — webhook (ADR-003) ​

WEBHOOK_* block. Every knob [REQUIRED] (operator declares intent even for the disable path). When enabled: HMAC-SHA256 on X-Webhook-Signature, LRU dedupe by signal_id, token-bucket rate limit. Loopback bind by default. See integrations/webhook.md.

Real-Time Data Stream (ADR-004) ​

Не env-настройка: подписка на wss://ws-live-data.polymarket.com включается потребителем в config.db (stop_loss.confirm_source = "rtds_actor_buffer" либо секция directional.toxic_flow), а не переменной окружения. ENGINE_RTDS_ENABLED снята и отклоняется на старте (решение оператора 2026-08-31, rtds-consumer-driven-activation). Toxic-flow cancel — за двумя гейтами в том же config.db (directional.toxic_flow: log_only → active_cancel_enabled, оба fail-safe) — env для strategy-config запрещён ADR-015 (legacy RTDS_TOXIC_FLOW_* движком не читаются). Пошаговая активация — rtds-cutover-runbook.md; модель — integrations/rtds.md.

State / cache / runtime tuning ​

  • BOT_STATE_DB_PATH — SQLite for position + history persistence.
  • BOT_CACHE_TTL_SECS, BOT_GTD_EXPIRE_SECS.
  • BOT_LOG_FILE — JSON daily-rolling log destination.
  • RUST_LOG — tracing filter (e.g. info, pm_engine=debug).
  • BOOTSTRAP_RECONCILE_TIMEOUT_SECONDS — [REQUIRED] положительное целое число секунд для единого срока bootstrap-сверки. Значения по умолчанию нет; отсутствие, пустая строка, ноль и неверный формат останавливают pm-engine до сборки сетевого контура. Политика повтора описана в target/engine.md §«Lifecycle + bootstrap». Для production-инстанса harvester-engine оператор утвердил 60 секунд; значение закреплено в его deploy/server/instances/harvester-engine/docker-compose.yml, а не в коде как default.

Multi-wallet + strategy config (ADR-015) ​

  • BOT_WALLET_LABEL — [OPTIONAL] selector → row in encrypted wallets.db. Requires non-empty WALLETS_MASTER_PASSPHRASE.
  • BOT_STRATEGY_LABEL — [OPTIONAL] selector → row in plaintext config.db. Unset ⇒ env-based path.
  • BOT_WALLETS_DB_PATH, BOT_CONFIG_DB_PATH — [OPTIONAL] overrides for default paths.

pm-engine-dashboard ​

DASHBOARD_* envs — see the top half of env/.env.example. Independent of the engine knobs. Local-Bot Mode toggle: BOT_LOCAL_API_ENABLED, BOT_LOCAL_API_BIND.

Cross-references ​