### Example Configuration File Path

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v7.9.0.md

Instead of `configs/template.json`, use this example configuration file as a starting point for your setup.

```json
configs/examples/default_trailing_grid_long_npos10.json
```

--------------------------------

### Setup Virtual Environment and Install Dependencies

Source: https://github.com/enarjord/passivbot/blob/master/docs/ai/commands.md

Commands to create a virtual environment, activate it, and install the project dependencies. Use the full or dev extras for development.

```bash
python3 -m venv venv
source venv/bin/activate
python3 -m pip install -e .              # live-only
# or: python3 -m pip install -e ".[full]"
# or: python3 -m pip install -e ".[dev]"
```

--------------------------------

### Run Optimization with Starting Pool

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Example of running optimization using an existing configuration file as a starting point.

```bash
passivbot optimize configs/examples/default_trailing_grid_long_npos7.json --start configs/starting_pool/
```

--------------------------------

### Passivbot Project Setup and Execution

Source: https://github.com/enarjord/passivbot/blob/master/AGENTS.md

Provides the essential commands for setting up a Python virtual environment, installing dependencies, running tests, and launching the Passivbot live trading instance.

```bash
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest
passivbot live -u {account_name}
```

--------------------------------

### Example Config File Naming Convention

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/config_loader_redesign_handoff.md

This illustrates the recommended naming convention for user-facing example configuration files. Examples should be descriptive of their behavior and located in a dedicated examples directory.

```text
configs/examples/diversified_long_only_top20.json
configs/examples/hsl_single_coin_btc.json
configs/examples/optimize_many_objective_pymoo.json
```

--------------------------------

### Install Rust via rustup

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

Use this if 'rustup: command not found' error occurs. Follow the official installation guide.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Quick Start: HSL BTC Long Red Restart

Source: https://github.com/enarjord/passivbot/blob/master/docs/fake_live.md

Example command to run the fake live harness with HSL, BTC, and a specific scenario. Includes user and snapshot options.

```shell
PYTHONPATH=src python3 src/tools/run_fake_live.py \
  configs/fake_live_hsl_btc.hjson \
  scenarios/fake_live/hsl_long_red_restart.hjson \
  --user fake_hsl_restart_test \
  --snapshot-each-step
```

--------------------------------

### Example Initial Focus URL for Dashboard

Source: https://github.com/enarjord/passivbot/blob/master/docs/monitor.md

This example shows how to use query parameters to set the initial focus for the web dashboard. The dashboard consumes multiplexed relay feeds and supports filtering by exchange, user, and symbol.

```text
http://127.0.0.1:8765/dashboard?exchange=bitget&user=bitget_01&symbol=BTC/USDT:USDT
```

--------------------------------

### Install Full Profile

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Install the full profile for Passivbot optimization. This is a prerequisite for running optimization tasks.

```bash
pip install -e ".[full]"
```

--------------------------------

### Install Passivbot (Live-only VPS)

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Install Passivbot for live trading on a VPS. This installs the core package and its essential dependencies.

```sh
python3 -m pip install -e .
```

--------------------------------

### Install Passivbot (Development Profile)

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Install Passivbot with the 'dev' profile for contributing, building documentation, and linting. This includes development tools.

```sh
python3 -m pip install -e ".[dev]"
```

--------------------------------

### Install Passivbot (Full Profile)

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Install Passivbot with the 'full' profile for backtesting, optimization, and research. This includes all optional dependencies.

```sh
python3 -m pip install -e ".[full]"
```

--------------------------------

### Typical Live-Only Passivbot Installation

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

A common installation sequence for a live-only Passivbot setup, including upgrading pip and installing the package in editable mode.

```bash
python3 -m pip install -U pip
python3 -m pip install -e .
```

--------------------------------

### Quick Start: HSL BTC Long Terminal No Restart

Source: https://github.com/enarjord/passivbot/blob/master/docs/fake_live.md

Example command to run the fake live harness for a terminal HSL case without restart. Includes user and snapshot options.

```shell
PYTHONPATH=src python3 src/tools/run_fake_live.py \
  configs/fake_live_hsl_btc.hjson \
  scenarios/fake_live/hsl_long_terminal_no_restart.hjson \
  --user fake_hsl_terminal_test \
  --snapshot-each-step
```

--------------------------------

### Passivbot Pareto CLI Example with Reference Method

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/pareto_explorer_tool_draft.md

Shows how to use the 'reference' method with specific target values for objectives and assigns weights to them.

```bash
passivbot tool pareto <path> \
  --method reference \
  --target adg_strategy_pnl_rebased=0.001 \
  --target drawdown_worst_hsl=0.25 \
  --weight adg_strategy_pnl_rebased=2
```

--------------------------------

### Copy and Run Passivbot Commands

Source: https://github.com/enarjord/passivbot/blob/master/docs/config_workflow.md

Demonstrates the recommended workflow: copying an example config, then running backtest, optimize, and live commands.

```bash
cp configs/examples/default_trailing_grid_long_npos7.json configs/live/my_config.json
passivbot backtest configs/live/my_config.json -s BTC -sd 2025 --suite n
passivbot optimize configs/live/my_config.json -s BTC -sd 2025 -c 4 --suite n
passivbot live configs/live/my_config.json
```

--------------------------------

### Optimize from Canonical Defaults

Source: https://github.com/enarjord/passivbot/blob/master/docs/config_workflow.md

Starts an optimization process using the default configuration.

```bash
passivbot optimize -s BTC -sd 2025 -c 4 --suite n
```

--------------------------------

### Start the Web Monitor Dashboard

Source: https://github.com/enarjord/passivbot/blob/master/docs/monitor.md

This command starts the main browser monitor dashboard. It connects to the relay's aggregate feed and provides a dense overview of all visible bots.

```bash
passivbot tool monitor-web
```

--------------------------------

### Import Live Module

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/live_python_module_split_plan.md

Example of how to import modules from the new `live` package. Ensure existing root-level imports are maintained for compatibility.

```python
from live.freshness import ACCOUNT_SURFACES, LIVE_STATE_SURFACES, FreshnessLedger
```

--------------------------------

### Full Pymoo Configuration Example

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Detailed configuration for the pymoo optimizer backend, including shared parameters and specific algorithm settings for NSGA-II and NSGA-III.

```json
{
  "optimize": {
    "backend": "pymoo",
    "population_size": null,
    "pymoo": {
      "algorithm": "auto",
      "shared": {
        "crossover_eta": 20.0,
        "crossover_prob_var": 0.5,
        "mutation_eta": 20.0,
        "mutation_prob_var": "auto",
        "eliminate_duplicates": true
      },
      "algorithms": {
        "nsga2": {},
        "nsga3": {
          "ref_dirs": {
            "method": "das_dennis",
            "n_partitions": "auto"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Get Backtest CLI Help

Source: https://github.com/enarjord/passivbot/blob/master/docs/backtesting.md

Run this command to view all available command-line arguments for the backtest functionality.

```shell
passivbot backtest -h
```

--------------------------------

### Example Calculation of Effective WEL and TWEL

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/v8_twel_enforcer_policy_contract.md

Illustrates the calculation of effective WEL and TWEL based on provided parameters. This example shows how individual position sizing can differ from portfolio-level entry blocking.

```text
raw_twel = 1.0
n_positions = 10
risk_we_excess_allowance_pct = 0.25
twel_threshold = 0.9

effective_wel = 1.0 / 10 * 1.25 = 0.125
effective_twel = 1.0 * 0.9 = 0.9
```

--------------------------------

### Passivbot Pareto CLI Example with Limits

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/pareto_explorer_tool_draft.md

Demonstrates how to use the passivbot tool with the 'knee' method and apply multiple 'limit' constraints to filter candidates.

```bash
passivbot tool pareto <path> \
  --method knee \
  --limit 'drawdown_worst_hsl<=0.35' \
  --limit 'adg_strategy_pnl_rebased>0.0'
```

--------------------------------

### Explore Pareto Candidates with Reference Point Selection

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v7.9.0.md

Select a Pareto candidate using the reference point method. This example specifies a reference point for the ideal solution.

```bash
passivbot tool pareto --select-reference-point 0.8,0.2
```

--------------------------------

### Passivbot Pareto Default Output Example

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/pareto_explorer_tool_draft.md

Example of the default human-readable output format for the Pareto Explorer tool, including directory information, candidate counts, selection method, and objective values for the selected candidate.

```text
Pareto directory: optimize_results/.../pareto
Loaded candidates: 182
Retained after limits: 47
Method: knee
Selected: optimize_results/.../pareto/abc123.json
Score: 0.183241

Objectives:
  adg_strategy_pnl_rebased (max): 0.00121
  drawdown_worst_hsl (min): 0.274
  peak_recovery_hours_hsl (min): 188.0
  ...
```

--------------------------------

### Passivbot Pareto CLI Example with Lexicographic Method

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/pareto_explorer_tool_draft.md

Illustrates the use of the 'lexicographic' method, specifying a prioritized list of objectives.

```bash
passivbot tool pareto <path> \
  --method lexicographic \
  --priority adg_strategy_pnl_rebased,drawdown_worst_hsl,peak_recovery_hours_hsl
```

--------------------------------

### Set ENTRYPOINT for Container

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/container_deployment_design.md

Define the default command to execute when a container starts. This entrypoint script handles the application's startup logic within the containerized environment.

```dockerfile
ENTRYPOINT ["/app/container/entrypoint.sh"]
```

--------------------------------

### Explore Pareto Candidates with Weighted Utility Selection

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v7.9.0.md

Select a Pareto candidate using the weighted utility method. This example assigns weights to objectives.

```bash
passivbot tool pareto --select-weighted-utility 0.6,0.4
```

--------------------------------

### Passivbot Balance Update Example

Source: https://github.com/enarjord/passivbot/blob/master/docs/stock_perps.md

Observe how Passivbot logs balance changes as margin is allocated or released when opening and closing positions.

```text
[balance] 105.21 -> 84.27   # Margin locked for new position
[balance] 84.27 -> 67.35    # More margin locked for second entry
```

--------------------------------

### Install Build Essentials and Python Dev Headers

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

Required for resolving linker errors like 'linker cc not found' or 'cannot find crt1.o'.

```bash
sudo apt-get update && sudo apt-get install build-essential python3-dev
```

--------------------------------

### Configure Pymoo Optimizer with NSGA-III Reference Directions

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v7.9.0.md

For NSGA-III optimization with `pymoo`, configure the reference directions. This example sets a single reference direction.

```json
optimize.pymoo.algorithm.ref_dirs = [[1.0, 0.0, 0.0]]
```

--------------------------------

### Select Pareto Candidate with Custom Objectives and Method

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Example of selecting a Pareto candidate using specific objectives and the 'ideal' selection method. Useful for scripting or precise selection.

```bash
passivbot tool pareto \
  -o sharpe_ratio_strategy_eq,adg_strategy_eq,strategy_eq_recovery_days_max \
  -m ideal
```

--------------------------------

### Activate Virtual Environment (Windows Command Prompt)

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Activate the virtual environment in Windows Command Prompt. This prepares the environment for package installation and running the bot.

```cmd
venv\Scripts\activate
```

--------------------------------

### Docker Run: Env-Generated Credentials and Schema Defaults

Source: https://github.com/enarjord/passivbot/blob/master/docs/container_deployment.md

Example of running the Passivbot container using environment variables for credentials and relying on schema defaults for configuration. Useful for quick setups or environments where file mounting is not preferred.

```bash
docker run --rm \
  -e PB_USER=bitget_01 \
  -e PB_EXCHANGE=bitget \
  -e PB_API_KEY=... \
  -e PB_API_SECRET=... \
  -e PB_APPROVED_COINS=BTC,ETH,SOL \
  passivbot-live:latest

```

--------------------------------

### Run Fake Live Harness

Source: https://github.com/enarjord/passivbot/blob/master/docs/fake_live.md

Entry point for running the fake live harness. Requires configuration and scenario files.

```shell
python3 src/tools/run_fake_live.py <config> <scenario>
```

--------------------------------

### Backtest CLI with Scenarios

Source: https://github.com/enarjord/passivbot/blob/master/docs/data_strategy_verification_tests.md

Demonstrates how to run a backtest using the CLI when scenarios are defined in the configuration file. It expects the suite mode to be detected and all scenarios to be executed.

```bash
passivbot backtest config_with_scenarios.json
```

--------------------------------

### Optimizer with Scenarios

Source: https://github.com/enarjord/passivbot/blob/master/docs/data_strategy_verification_tests.md

Illustrates running the optimizer with a configuration that includes scenarios. It verifies that the optimizer detects suite mode and evaluates candidates across all defined scenarios.

```bash
passivbot optimize config_with_scenarios.json
```

--------------------------------

### Start the Monitor Relay

Source: https://github.com/enarjord/passivbot/blob/master/docs/monitor.md

Use this command to start the monitor relay. It can be run directly or via a Python script. The default bind address is 127.0.0.1:8765.

```bash
passivbot tool monitor-relay --monitor-root monitor
```

```bash
python src/tools/monitor_relay.py --monitor-root monitor
```

--------------------------------

### Limit Filtering Examples

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/pareto_explorer_tool_draft.md

Examples of using the --limit and --limits flags to filter Pareto candidates based on metric conditions. These expressions act as keep-conditions.

```bash
--limit 'adg_strategy_pnl_rebased>0.0'
```

```bash
--limit 'drawdown_worst_hsl<=0.35'
```

```bash
--limit 'loss_profit_ratio outside_range [0.05,0.7]'
```

```bash
--limits '[{...}, {...}]'
```

--------------------------------

### Scenario with Custom Start Date

Source: https://github.com/enarjord/passivbot/blob/master/docs/data_strategy_verification_tests.md

Overrides the global 'start_date' for a specific scenario. This tests if scenario-specific date ranges are correctly applied, overriding the backtest's default start date.

```python
config = {
    "backtest": {
        "start_date": "2021-01-01",
        "end_date": "2024-01-01",
        "exchanges": ["binance"],
        "scenarios": [
            {"label": "recent", "start_date": "2023-01-01"}
        ]
    }
}
```

--------------------------------

### Verify Passivbot Installation

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

Run pytest to verify the core installation and use the command-line interface to check Passivbot's help output. Additional commands are provided for backtesting and optimization environments.

```bash
pytest -q
passivbot -h
```

```bash
passivbot backtest -h
passivbot optimize -h
```

--------------------------------

### Install Passivbot with Different Profiles

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

Install Passivbot using pip within the activated virtual environment. Choose the appropriate command based on your intended use case (live-only, backtesting, or development).

```bash
# Live-only VPS
 python3 -m pip install -e .
```

```bash
# Backtesting / optimization / research
 python3 -m pip install -e ".[full]"
```

```bash
# Contributing / docs / linting
 python3 -m pip install -e ".[dev]"
```

--------------------------------

### Run Passivbot Live (Default Settings)

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Start Passivbot in live trading mode using default settings. Replace '{account_name_from_api-keys.json}' with your actual account name from the api-keys.json file.

```sh
passivbot live -u {account_name_from_api-keys.json}
```

--------------------------------

### File-Based Override Configuration Example

Source: https://github.com/enarjord/passivbot/blob/master/docs/coin_overrides.md

Define specific bot parameters and live flags for a coin in a separate JSON file. Ensure that only allowed fields are modified, as disallowed keys are ignored.

```json
{
  "bot": {
    "long": {
      "entry_grid_spacing_pct": 0.021,
      "entry_initial_ema_dist": 0.001,
      "wallet_exposure_limit": 0.12
    },
    "short": {
      "entry_grid_spacing_pct": 0.019,
      "close_grid_markup_start": 0.004
    }
  },
  "live": {
    "forced_mode_short": "graceful_stop",
    "leverage": 4
  }
}
```

--------------------------------

### Clone Passivbot Repository

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Clone the Passivbot repository and navigate into the directory. This is the first step for installation.

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

--------------------------------

### Take Profit Order Sizing Example

Source: https://github.com/enarjord/passivbot/blob/master/docs/configuration.md

Demonstrates how quantities are allocated to Take Profit (TP) orders based on close_grid_qty_pct and the current position size. Excess size is added to the TP order closest to markup_start.

```text
full_pos_size = 100, long_pos_size = 55, prices built backwards
TP orders: [15@100.8, 20@100.9, 20@101.0]
```

```text
long_pos_size = 130, grid is forwards
TP orders: [50@100.5, 20@100.6, 20@100.7, 20@100.8, 20@100.9]
```

--------------------------------

### Load IPython Extensions and Autoreload

Source: https://github.com/enarjord/passivbot/blob/master/notebooks/notes_backtest.ipynb

Loads IPython extensions for autoreloading and running setup scripts.

```python
%load_ext autoreload
%autoreload 2
%run notebook_setup.py
```

--------------------------------

### CandlestickManager.warmup_since

Source: https://github.com/enarjord/passivbot/blob/master/src/prompt_for_candlestick_manager.txt

Backfills historical OHLCV data into memory and cache starting from a specified timestamp for multiple symbols.

```APIDOC
## warmup_since(symbols, since_ts)

### Description
Backfills historical OHLCV data into the manager's memory and disk cache for a list of symbols, starting from a specified timestamp.

### Parameters
#### Path Parameters
- **symbols** (list[str]) - Required - A list of trading symbols (e.g., ['BTC/USDT', 'ETH/USDT']).
- **since_ts** (int) - Required - The starting timestamp in UTC milliseconds from which to backfill data.

### Returns
- None
```

--------------------------------

### Docker Compose Example for Live Deployment

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/container_deployment_design.md

A sample docker-compose.yml file for deploying the passivbot live container. It specifies the build context, environment variables for configuration, and volume mounts for persistent data and configuration files.

```yaml
services:
  passivbot-live:
    build:
      context: .
      dockerfile: Dockerfile_live
    environment:
      PB_USER: bitget_01
      PB_CONFIG_PATH: /data/configs/live.json
      PB_API_KEYS_PATH: /data/api-keys.json
    volumes:
      - ./configs:/data/configs:ro
      - ./api-keys.json:/data/api-keys.json:ro
      - ./logs:/data/logs
      - ./monitor:/data/monitor
```

--------------------------------

### CandlestickManager warmup_since Method

Source: https://github.com/enarjord/passivbot/blob/master/src/prompt_for_candlestick_manager.txt

Backfills historical OHLCV data into memory and cache starting from a specified timestamp.

```python
warmup_since(symbols, since_ts)
```

--------------------------------

### Copy API Keys Template

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Create a copy of the example API keys file to be used for storing your exchange API credentials. This ensures the correct file format is used.

```sh
cp api-keys.json.example api-keys.json
```

--------------------------------

### Get Candles for Coin

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v7.10.0.md

Helper function for notebook workflows to retrieve candles for a specific coin from a backtest artifact.

```python
candles_for_coin(...)

```

--------------------------------

### Trailing Grid Ratio Examples

Source: https://github.com/enarjord/passivbot/blob/master/docs/trailing_grid_ratio.md

Illustrates how different `*_trailing_grid_ratio` values influence the decision between trailing and grid orders based on `we_ratio`.

```text
- `*_trailing_grid_ratio = 0.1` (trailing first)
  - If `we_ratio < 0.1` → trailing order.
  - Else → grid order, leaving 10% of allowed exposure for trailing.
```

```text
- `*_trailing_grid_ratio = -0.1` (grid first)
  - If `we_ratio < 0.9` → grid order.
  - Else → trailing order, leaving 90% of allowed exposure for grid.
```

```text
- `*_trailing_grid_ratio = 0.9` (trailing first)
  - If `we_ratio < 0.9` → trailing order.
  - Else → grid order, leaving 90% of allowed exposure for trailing.
```

```text
- `*_trailing_grid_ratio = -0.9` (grid first)
  - If `we_ratio < 0.1` → grid order.
  - Else → trailing order, leaving 10% of allowed exposure for grid.
```

--------------------------------

### Enable and Configure Optimizer Suite Mode

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Enable suite mode using `backtest.suite_enabled` and define multiple scenarios with `backtest.scenarios`. Metrics are aggregated using `backtest.aggregate` rules.

```json
"suite_metrics": {
  "aggregate": {
    "aggregated": {"adg_btc_w": 0.0012, "...": "..."},
    "stats": {"adg_btc_w": {"mean": 0.0011, "min": 0.0008, "max": 0.0014, "std": 1.5e-4}}
  },
  "scenarios": {
    "scenario_a": {"stats": {"adg_btc_w": {"mean": 0.0012, "min": 0.0011, ...}}}
    "scenario_b": {"stats": {"adg_btc_w": {"mean": 0.0009, ...}}}
  }
}
```