Skip to content

Backtesting

Savvas Leousis edited this page Sep 26, 2026 · 2 revisions

Backtesting

The backtester replays history bar by bar and trades a SimulatedBroker. The lab uses it for every score and test. The same Broker protocol is used live, so strategy code does not change.

sequenceDiagram
  participant E as Engine
  participant S as Strategy
  participant B as SimulatedBroker
  loop every bar t
    E->>B: fill queued orders at bar t open
    E->>B: set prices to bar t close
    alt rebalance bar
      E->>S: estimate_return for each ticker
      E->>S: decide(picks, portfolio, prices)
      S-->>E: orders (queued for bar t+1)
    end
    E->>E: mark equity at closes
  end
Loading

Rules

  • No look-ahead (no peeking at future data): signals at bar t see data up to t's close.
  • Fills at next bar open: orders decided at t fill at the open of the next bar that ticker trades.
  • Replaced, not stacked: unfilled queued orders are replaced by the next decision. Orders left after the last bar never fill.
  • Always decide: decide runs even with no picks, so exits happen.
  • Marking: equity is valued at each bar's close. A ticker with no bar at that time (for example a stock on a crypto weekend) keeps its last close.
  • Long-only: sells are clipped to the held quantity.
  • Interval-aware: any interval (1m to 1w). rebalance_every_bars counts bars, not days.

Costs

Set under [backtest.costs]. All zero means free trading.

Setting Effect
fee_flat, fee_bps Fee per fill: flat plus basis points of notional
half_spread_bps Half the bid-ask spread, paid on every fill
impact_bps, max_impact_bps Market impact, square-root of order size vs bar volume, capped
[backtest.costs.asset_classes.<class>] Override per asset class, e.g. crypto

A basis point (bps) is 0.01%. The simulated tick uses the same cost model.

Annualization

Sharpe is annualized by the number of bars in a year for the universe's calendar:

Asset class Calendar
equity, commodity, bond 252 sessions of 6.5 hours
crypto 365 days of 24 hours

A mixed universe uses the densest calendar present. CAGR uses real elapsed time, so it works intraday too.

Report metrics

Metric Meaning
final_return End value / start value - 1
sharpe Annualized mean return / volatility
max_drawdown Deepest fall from a peak (negative number)
cagr Compound annual growth rate
profit_factor Sum of up-bar returns / sum of down-bar losses
equity_curve Portfolio value per bar

Running one

From the CLI, backtests run inside stonks lab run. The API has a direct job: POST /api/lab/backtests. MCP exposes it as run_backtest.

Known gap

Splits and dividends are stored but not yet applied in backtests. Engine and strategies trade on raw close, so a split looks like a crash. This is roadmap item 8.6.

Clone this wiki locally