repository·master·Indexed 24 days ago
https://github.com/enarjord/passivbotA cryptocurrency trading bot written in Python and Rust for perpetual futures markets. It operates as a contrarian market maker using grid-based and trailing orders, featuring a Martingale-inspired strategy, an unstucking mechanism, and a Forager for dynamic market selection. The project includes a Rust runtime (passivbot_rust v0.1.0) and provides tools for configuration migration from v7 to v8.
Passivbot is a trading bot written in Python and Rust designed for perpetual futures markets. To begin using the bot, follow these primary steps:
Passivbot provides production-ready live connectors for the following exchanges:
Important Notes:
Forager mode is Passivbot's dynamic coin-selection system. It determines which symbols should occupy the limited entry slots available at any given time.
The system follows a three-step sequence:
forager_volume_drop_pct).This allows you to control the tradeoff between liquidity, volatility, and entry readiness directly via configuration.
Passivbot configurations can be optimized using a multi-objective evolutionary algorithm. This process allows you to balance different performance metrics (scoring objectives) while ensuring the resulting configuration adheres to specific constraints.
Key resources for configuration:
src/config/schema.py.configs/examples/default_trailing_martingale_long.json is an exact mirror of the canonical defaults.TWEL auto-reduce orders are not an emergency bypass for risk management. They must pass through the existing max_realized_loss_pct gate.
max_realized_loss_pct, the order will be blocked.max_realized_loss_pct blocks TWEL repair while the current TWE remains above twel_repair_target, the bot will emit a loud risk warning containing the side, current TWE, repair target, policy, number of candidates, and number of blocked orders.ClosePanicLong and ClosePanicShort orders. These panic close orders bypass max_realized_loss_pct regardless of whether they were triggered by HSL panic-close handling or another explicit panic-mode path.The Live Execution Gatekeeper is a multi-layered system designed to ensure trading safety by separating strategy intent from exchange execution. The architecture consists of four primary components:
ActionPlan.ActionPlan against a 'freshness contract' (e.g., checking if market data or account balances are sufficiently recent) to decide if an action is safe to execute.This separation ensures that even if the strategy (Rust) suggests an order, the Gatekeeper can block it if the underlying data (like candles or balance) is stale or unreliable.
Passivbot supports opt-in structured debug enrichment via the logging.live_event_debug_profiles configuration or the PASSIVBOT_LIVE_EVENT_DEBUG_PROFILES environment variable. Enabling these profiles provides deeper insights into specific events without changing trading behavior or console output.
Available debug profiles include:
ema (or ema-readiness): Enriches ema.unavailable events with parsed EMA type, span, and inner reason summaries.remote_calls: Enriches candle remote-fetch and authoritative state-fetch events with key shape, timing/correlation fields, and status/surface/kind.candles: Enriches candle.tail_projected and candle.coverage_checked events with timeframe/window and missing-coverage counters.Even if the strategy setting live.hedge_mode=false is used (which disables simultaneous long/short strategy exposure), the KuCoin connector keeps the exchange account in hedge mode.
Key behaviors for KuCoin Hedge Mode:
info.positionSide or info.posSide from the exchange. Never infer a resting order's position side from the current position.reduceOnly field.The TWEL auto-reduce mechanism interacts differently with various bot operational modes. While auto-reduce measures exposure from all open exchange positions (including manual and panic), the selection of which positions to reduce is restricted by the mode:
normal, graceful_stop, and tp_only: The bot chooses repair candidates only from managed open positions.manual and panic: The bot will not emit TWEL auto-reduce orders for these positions, even if the total exposure exceeds the target. This prevents the enforcer from overriding manual or emergency exit logic.The CandlestickManager automatically selects the best data source based on the following priority:
The LiveEvent is a structured data object used for real-time observability. It is designed to be serialized into NDJSON for structured sinks. A LiveEvent includes a stable set of fields for tracking bot state, order waves, and exchange interactions.
Core Fields:
schema_version: Version of the event schema.event_id: Unique identifier for the event.event_type: The category of the event (e.g., bot.started, cycle.completed).ts_ms / monotonic_ms: Timestamps.level: Logging level.source / component: Origin of the event.tags: Metadata tags.exchange / user / bot_id / symbol: Contextual identifiers.pside / side: Order side information.order_id / client_order_id: Order identifiers.cycle_id / snapshot_id / plan_id / action_id / order_wave_id: IDs used to reconstruct the lifecycle of a single trading cycle or order wave.status / reason_code / message: Outcome information.data: The event payload.raw_ref / raw_hash: References to raw payloads (subject to redaction and policy).In Passivbot v8, trailing_martingale is the canonical strategy. To support users transitioning from v7, a deprecated compatibility strategy called trailing_grid_v7 is provided.
Key characteristics of trailing_grid_v7:
trailing_martingale or other native v8 strategies.trailing_grid_v7, but it does not convert them into trailing_martingale.