Trading bot running on Bybit, OKX, Bitget, Bitunix, GateIO, Binance, Kucoin, Hyperliquid and WEEX

:warning: Used at one's own risk :warning:

Current stable major version: v8.0.0.

Upgrading from v7: v8 is a breaking config and strategy release. Do not start v8 live with an unreviewed v7 config. Read the v8.0.0 upgrade notes and use the explicit passivbot tool migrate-config-v7 helper when preserving v7 trailing-grid behavior.

Overview

Passivbot is a cryptocurrency trading bot written in Python and Rust, intended to require minimal user intervention.

It operates on perpetual futures derivatives markets, automatically creating and cancelling limit buy and sell orders on behalf of the user. It does not try to predict future price movements or follow trends. Rather, it is a contrarian market maker, using price bands, EMA-derived context, and risk controls to provide resistance to price changes in both directions, thereby "serving the market" as a price stabilizer.

Order planning is computed by a shared Rust orchestrator used by both live trading and backtesting for speed and consistency. Also included is an optimizer, which finds better configurations by iterating thousands of backtests with different candidates, converging on the optimal ones with an evolutionary algorithm.

Strategy

Inspired by the Martingale betting strategy, the robot will make a small initial entry and double down on its losing positions multiple times to bring the average entry price closer to current price action. The orders are placed in a grid, ready to absorb sudden price movements. After each re-entry, the robot quickly updates its closing orders at a set take-profit markup. This way, if there is even a minor market reversal, or "bounce", the position can be closed in profit, and it starts over.

Trailing Orders

In addition to grid-based entries and closes, Passivbot may be configured to utilize trailing entries and trailing closes.

For trailing entries, the bot waits for the price to move beyond a specified threshold and then retrace by a defined percentage before placing a re-entry order. Similarly, for trailing closes, the bot waits before placing its closing orders until after the price has moved favorably by a threshold percentage and then retraced by a specified percentage. This may result in the bot locking in profits more effectively by exiting positions when the market shows signs of reversing instead of at a fixed distance from average entry price.

Grid and trailing orders may be combined, such that the robot enters or closes a whole or a part of the position as grid orders and/or as trailing orders.

Forager

The Forager feature dynamically chooses which approved markets may open positions. It first prunes low relative-volume candidates, then ranks the remaining markets with configurable weights for quote volume, EMA readiness, and 1m log-range volatility.

Unstucking Mechanism

Passivbot manages underperforming, or "stuck", positions by realizing small losses over time. If multiple positions are stuck, the bot prioritizes positions with the smallest gap between the entry price and current market price for "unstucking". Losses are limited by ensuring that the account balance does not fall under a set percentage below the past peak balance.

Installation

To install Passivbot and its dependencies, follow the steps below.

Passivbot supports Python 3.12 and Python 3.14. Python 3.13 is not supported by the pinned dependency set.

Upgrading a v7 config

V8 does not silently reinterpret v7 strategy fields. To preserve v7 trailing-grid behavior while moving the config into canonical v8 shape, run:

passivbot tool migrate-config-v7 \
  path/to/config_v7.json \
  path/to/config_v8_trailing_grid_v7.json \
  --report path/to/v7_migration_report.json

The helper writes the deprecated compatibility strategy trailing_grid_v7; it does not translate the config into the new trailing_martingale strategy. If unsupported or ambiguous fields require manual review, the command returns nonzero and does not write the output config unless --allow-manual-review-output is explicitly supplied. Review the report and backtest the result before considering a live run. New configs and new optimization work should start from configs/examples/default_trailing_martingale_long.json.

Step 1: Clone the Repository

First, clone the Passivbot repository to the local machine:

git clone https://github.com/enarjord/passivbot.git
cd passivbot

Step 2: Install Rust

Passivbot uses Rust for some of its components. Install Rust by following these steps:

Visit https://www.rust-lang.org/tools/install Follow the instructions to install Rustup, the Rust installer and version management tool. After installation, restart the terminal or command prompt.

Step 3: Create and Activate a Virtual Environment

Create a virtual environment to manage dependencies:

Linux/macOS:

# Replace python3.14 with the installed supported executable (python3.12 or python3.14).
PYTHON_BIN=python3.14
"$PYTHON_BIN" --version
"$PYTHON_BIN" -m venv venv

Windows (Command Prompt or PowerShell):

py -3.12 -m venv venv

Activate the virtual environment:

Linux/macOS:

source venv/bin/activate

Windows (Command Prompt):

venv\Scripts\activate

Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Step 4: Install Passivbot

Choose the install profile that matches your use case:

• Live-only VPS: python3 -m pip install -e .
• Backtesting / optimization / research workstation: python3 -m pip install -e ".[full]"
• Contributing / docs / lint tooling: python3 -m pip install -e ".[dev]"

All profiles build the Rust extension and register the passivbot command.

Typical live-only install:

python3 -m pip install -e .

Step 5 (optional): Build Rust Extensions

Passivbot will attempt to build the necessary Rust extensions automatically, but they can also be built manually by navigating to the passivbot-rust directory and using maturin:

cd passivbot-rust
maturin develop --release
cd ..

If changes in the Rust source are detected, recompilation is needed, which Passivbot will attempt to do automatically when starting. To manually recompile, use the commands given above.

Step 6: Add API keys

Make a copy of the api-keys template file:

cp api-keys.json.example api-keys.json

Add your keys to api-keys.json.

Step 7: Run Passivbot

Hint:
To ensure cache folder names are Windows-compatible (even outside Windows), set the environment variable WINDOWS_COMPATIBILITY=1.
This is only required in certain scenarios, e.g., running under Docker (Linux) while mounting the caches folder to a Windows host.

To start the bot with the default settings, run:

passivbot live -u {account_name_from_api-keys.json}

or make a new configuration file, using configs/examples/default_trailing_martingale_long.json as a starting point, and start the bot with:

passivbot live path/to/config.json

Legacy direct-script entrypoints such as python3 src/main.py ..., python3 src/backtest.py ..., and python3 src/optimize.py ... still work unchanged for backwards compatibility.

The canonical hardcoded defaults live in src/config/schema.py. The example config configs/examples/default_trailing_martingale_long.json mirrors that default profile exactly, so copying it is the recommended starting point for new configs.

Logging

Passivbot uses Python's logging module throughout the bot, backtester, and supporting tools.

• Use --log-level {warning|info|debug|trace} or --log-level {0-3} on passivbot live or passivbot backtest to adjust verbosity at runtime: 0 = warnings only, 1 = info, 2 = debug, 3 = trace.
• Use --verbose on passivbot live to force debug logging (--log-level debug).
• Persist a default by adding a top-level section to your config: "logging": {"level": 2}. The CLI flag always overrides the config value for that run.
• passivbot live now writes a timestamped logfile under logs/ by default and refreshes logs/{user}.log as a stable alias to the current run. Control this with config.logging.persist_to_file, config.logging.dir, and the optional rotation settings in config.logging.
• CandlestickManager and other subsystems inherit the chosen level so EMA warm-up, data fetching, and cache behaviour can be inspected consistently.

Running Multiple Bots

Running several Passivbot instances against the same exchange on one machine is supported. Each process shares the same on-disk OHLCV cache, and the candlestick manager now uses short-lived, self-healing locks with automatic stale cleanup so that one stalled process cannot block the rest. No manual deletion of lock files is required; the bot removes stale locks on startup and logs whenever a lock acquisition times out.

Jupyter Lab

Jupyter lab needs to be run in the same virtual environment as the bot. Activate venv (see installation instructions above, step 3), and launch Jupyter lab from the Passivbot root dir with:

python3 -m jupyter lab

Requirements

• Python >= 3.12
• python3 -m pip install -e . for live trading only
• python3 -m pip install -e ".[full]" for backtesting, optimization, downloader, and advanced tools
• python3 -m pip install -e ".[dev]" for contributor tooling on top of the full install

Pre-optimized configurations

Coming soon...

See also https://pbconfigdb.scud.dedyn.io/

Documentation

For more detailed information about Passivbot, see documentation files here: docs/

Useful entry points:

• Installation
• Troubleshooting
• [Backtesting](docs/backtestin