Skip to content

backtest#

Run, optimize, and walk-forward a strategy file against cached candles and funding.

Subcommands#

Command What it does
run <strategy.py> One backtest on one asset.
optimize <strategy.py> Grid or random search over --param sweeps.
walk-forward <strategy.py> Rolling-window analysis.

See Writing a strategy for the strategy file format.

hlr backtest run#

hlr backtest run my_strategy.py --asset BTC --interval 1h \
    --since 2024-01-01 --initial-cash 100000 \
    --out backtest.html

Default initial cash is $100,000. Without --out, prints a summary panel and ASCII equity sparkline. With --out PATH, writes a standalone HTML report with the plotly equity and drawdown curves, full metrics table, and top closed trades.

Output panel:

╭─ backtest ──────────────────────────────────────────────────────────────╮
│                                                                         │
│  STRATEGY           MovingAverage                                       │
│  ASSET              BTC                                                 │
│  PERIOD             2024-01-01 → 2026-05-01                             │
│                                                                         │
│  TOTAL RETURN       +24.81%                                             │
│  ANNUALIZED         +10.92%                                             │
│  SHARPE             1.18                                                │
│  SORTINO            1.63                                                │
│  MAX DRAWDOWN       -8.42%                                              │
│  HIT RATE           +51.20%                                             │
│  PROFIT FACTOR      1.31                                                │
│  TRADES             127                                                 │
│  NET FUNDING        -$842.14                                            │
│                                                                         │
╰─────────────────────────────────────────────────────────────────────────╯

hlr backtest optimize#

hlr backtest optimize my_strategy.py --asset BTC \
    --param "lookback:5..50:5" \
    --param "threshold:0.01..0.10:0.01" \
    --metric sharpe

Param syntax:

  • name:start..end:step — numeric grid (ints when whole, floats otherwise)
  • name:a,b,c — categorical choices

Multiple --param flags compose. Grid search is single-process in v0.

For random search:

hlr backtest optimize my_strategy.py --param "lookback:5..50:5" --random 200 --seed 42

--metric options: sharpe (default), sortino, calmar, total_return, profit_factor, hit_rate.

hlr backtest walk-forward#

hlr backtest walk-forward my_strategy.py --asset BTC \
    --window 90d --step 30d

Walks a rolling window across the cached candle range. Duration units: s, m, h, d, w. Output is a per-window metrics table.

JSON mode#

All three commands emit JSON with --json. The run payload includes the equity curve and closed trades. optimize lists every trial. walk-forward lists every window.