Skip to content

Configuration File Reference

The bot is configured via a JSON file (typically config/config.json). This page documents every available parameter.

Complete Example

{
  "exchange": {
    "name": "binance",
    "trading_fee": 0.001,
    "trading_mode": "backtest"
  },
  "pair": {
    "base_currency": "SOL",
    "quote_currency": "USDT"
  },
  "trading_settings": {
    "timeframe": "1m",
    "period": {
      "start_date": "2024-08-01T00:00:00Z",
      "end_date": "2024-10-20T00:00:00Z"
    },
    "initial_balance": 10000,
    "historical_data_file": "data/SOL_USDT/2024/1m.csv"
  },
  "grid_strategy": {
    "type": "simple_grid",
    "spacing": "geometric",
    "num_grids": 8,
    "range": {
      "top": 200,
      "bottom": 250
    },
    "buy_ratio": 1.0,
    "sell_ratio": 0.5
  },
  "risk_management": {
    "take_profit": {
      "enabled": false,
      "threshold": 300
    },
    "stop_loss": {
      "enabled": false,
      "threshold": 150
    }
  },
  "execution": {
    "max_retries": 3,
    "retry_delay": 1.0,
    "max_slippage": 0.01,
    "backtest_slippage": 0.001,
    "order_polling_interval": 15.0,
    "websocket_max_retries": 5,
    "websocket_retry_base_delay": 5,
    "health_check_interval": 60,
    "circuit_breaker_failure_threshold": 5,
    "circuit_breaker_recovery_timeout": 60.0,
    "circuit_breaker_half_open_max_calls": 1,
    "reconciliation_interval": 300.0,
    "reconciliation_balance_tolerance": 0.01
  },
  "logging": {
    "log_level": "INFO",
    "log_to_file": true
  },
  "persistence": {
    "enabled": true,
    "db_path": "data/SOL_USDT/state.db"
  }
}

Parameter Reference

exchange

Parameter Type Required Description
name string Yes Exchange name (e.g., binance, kraken). Must be supported by CCXT.
trading_fee float Yes Flat trading fee in decimal format (e.g., 0.001 for 0.1%). Used for both sides unless maker_fee / taker_fee are set.
maker_fee float No Fee charged on liquidity-adding fills — resting grid limit orders. Defaults to trading_fee.
taker_fee float No Fee charged on liquidity-taking fills — the initial purchase, take-profit, stop-loss and liquidation market orders. Defaults to trading_fee.
post_only bool No Post grid limit orders maker-only. Defaults to false.
trading_mode string Yes One of backtest, paper_trading, or live.

Maker and taker fees

Grid limit orders are meant to rest on the book and pay the maker fee, while the market orders the bot places on its own (initial purchase, take-profit, stop-loss, liquidation) cross the spread and pay the taker fee. On venues where the two rates differ — Kraken (0.16% / 0.26%) or Coinbase (0.60% / 1.20%) at low volume tiers, versus Binance spot which charges the same on both sides — declaring only trading_fee under-costs whichever side is cheaper in the config and distorts backtest results.

Both keys default to trading_fee, so an existing single-rate config keeps behaving exactly as before.

Post-only orders

post_only sends grid limit orders as maker-only: the exchange rejects an order that would cross the spread instead of filling it as a taker. It is never applied to market orders, which cross by definition.

A rejection is treated as an expected market condition, not a failure. The bot:

  • releases the funds it had reserved for the order;
  • leaves the grid level exactly as it was, so the next initialize_grid_orders — triggered by a regrid or a trailing-stop move — retries it;
  • logs at INFO and sends no failure notification;
  • does not count the rejection toward the circuit breaker's failure threshold.

The order is never re-priced away from its grid level: that would place it off-grid and silently distort the profit spacing the whole strategy is built on.

Recommended for live trading

config.live.example.json ships with post_only: true. The default is false so that upgrading never changes how an existing deployment places orders.

pair

Parameter Type Required Description
base_currency string Yes Base currency symbol (e.g., SOL, ETH, BTC).
quote_currency string Yes Quote currency symbol (e.g., USDT, USDC).

trading_settings

Parameter Type Required Description
timeframe string Yes OHLCV timeframe (e.g., 1m, 5m, 1h, 1d).
period.start_date string Yes Start date in ISO 8601 format.
period.end_date string Yes End date in ISO 8601 format.
initial_balance float Yes Starting balance in quote currency.
historical_data_file string No Path to local CSV file for offline backtesting. If omitted, data is fetched via CCXT.

grid_strategy

Parameter Type Required Description
type string Yes simple_grid (independent levels) or hedged_grid (paired levels).
spacing string Yes arithmetic (equal intervals) or geometric (proportional intervals).
num_grids int Yes Total number of grid levels.
range.top float Yes Upper price limit of the grid.
range.bottom float Yes Lower price limit of the grid.
buy_ratio float No Fraction of the base quantity to use for buy orders. Must be in (0, 1.0]. Default: 1.0.
sell_ratio float No Fraction of the base quantity to use for sell orders. Must be in (0, 1.0]. Default: 1.0.

risk_management

Parameter Type Required Description
take_profit.enabled bool Yes Whether take-profit is active.
take_profit.threshold float Yes Price at which to take profit.
stop_loss.enabled bool Yes Whether stop-loss is active.
stop_loss.threshold float Yes Price at which to stop loss.

execution (optional)

All fields are optional with sensible defaults. These fine-tune order execution behavior.

Parameter Type Default Range Description
max_retries int 3 1–20 Maximum retry attempts for failed orders (live/paper).
retry_delay float 1.0 0.1–60.0 Delay in seconds between retries.
max_slippage float 0.01 0.0001–0.1 Maximum acceptable slippage for live/paper execution (e.g., 0.01 = 1%).
backtest_slippage float 0.0 0.0–0.1 Fixed slippage applied to simulated fills (e.g., 0.001 = 0.1%). Buys fill higher, sells fill lower.
order_polling_interval float 15.0 1.0–300.0 Seconds between open order status polls (live/paper).
websocket_max_retries int 5 1–50 Maximum WebSocket reconnection attempts.
websocket_retry_base_delay int 5 1–120 Base delay (seconds) for WebSocket reconnection backoff.
health_check_interval int 60 10–3600 Seconds between health check pings.
circuit_breaker_failure_threshold int 5 1–50 Consecutive API failures before circuit breaker opens.
circuit_breaker_recovery_timeout float 60.0 1.0–600.0 Seconds to wait before recovery attempt after circuit breaker opens.
circuit_breaker_half_open_max_calls int 1 1–10 Maximum test calls allowed in half-open state.
reconciliation_interval float 300.0 60.0–3600.0 Seconds between reconciliation cycles that audit local state vs exchange (live mode only).
reconciliation_balance_tolerance float 0.01 0.0–100.0 Minimum absolute difference to report a balance drift. Avoids alerts for rounding noise.

logging

Parameter Type Required Description
log_level string Yes Logging level: DEBUG, INFO, WARNING, ERROR.
log_to_file bool Yes Enable logging to a file in the logs/ directory.

persistence (optional, live mode only)

SQLite state persistence for crash recovery. Only active in live trading mode — ignored in backtest and paper_trading.

Parameter Type Default Description
enabled bool true Whether to persist bot state to SQLite.
db_path string data/{BASE}_{QUOTE}/state_{hash}.db Path to the SQLite database file. The default path includes a short config hash so different grid configurations for the same pair use separate databases.