Repository navigation
Backtesting
The backtester replays history bar by bar and trades a SimulatedBroker. The lab uses it for every score and test. It shares the Broker protocol with production, so strategy code does not change. It can also run the tick's construction pipeline when BacktestConfig.construction is set, but the lab and API do not set it yet.
sequenceDiagram
participant E as Engine
participant S as Strategy
participant B as SimulatedBroker
loop every bar t
E->>B: apply splits and dividends with ex-date 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
-
No look-ahead: signals at bar
tsee data up tot's close. -
Fills at next bar open: orders decided at
tfill at the open of the next bar that ticker trades. - Replaced, not stacked: unfilled queued orders are replaced by the next decision.
-
Always decide:
decideruns even with no picks, so exits happen. - Marking: equity is valued at each bar's close. A ticker with no bar at that time keeps its last close.
-
Corporate actions: a split multiplies held shares (and queued orders); a cash dividend is credited, minus
[production] dividend_withholding_rate. Signals read adjusted prices; fills and marks use raw prices. - Long-only: sells are clipped to the held quantity.
-
Interval-aware: any interval (1m to 1w).
rebalance_every_barscounts bars, not days.
Costs are set under [backtest.costs] and are realistic by default. The simulated tick uses the same model.
| 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 by the square root of order size against bar volume, capped |
[backtest.costs.asset_classes.<class>] |
Override per asset class, e.g. crypto |
The fill model decides how much fills and at what price. The default fills every order in full at the open. A bar-range model (participation cap, partial fills, limit and stop orders from the bar's high and low, a gap guard) exists in code but is not wired to config yet.
Sharpe is annualized by the number of bars in a year for the universe's calendar: 252 sessions of 6.5 hours for equity, commodity and bond, 365 days of 24 hours for crypto. A mixed universe uses the densest calendar present. CAGR uses real elapsed time.
| Metric | Meaning |
|---|---|
final_return, cagr
|
Total return and compound annual growth |
sharpe, sortino, calmar
|
Return per unit of risk (see Glossary) |
max_drawdown, max_dd_duration_bars
|
Deepest fall from a peak and how long it lasted |
ulcer_index, upi
|
Depth and length of drawdowns, and CAGR per unit of it |
var_95, es_95
|
Typical bad day and the average of the worse days |
skew, kurtosis, lower_tail_ratio
|
Shape of the return distribution |
trades, trade_stats
|
FIFO round trips: win rate, profit factor, expectancy, holding time |
| turnover, costs paid | How much it trades and what that cost |
| benchmark stats | Beta, alpha, information ratio and tracking error against [lab].benchmark
|
From the CLI, backtests run inside stonks lab run. A tear sheet (strategy against benchmark, drawdowns, rolling Sharpe, monthly returns, trade stats):
uv run stonks report --backtest momentum --start 2023-01-01 --end 2026-09-01 \
--tickers AAPL.US,MSFT.US --out data/reports/momentum.htmlThe API has a direct job, POST /api/lab/backtests; MCP exposes it as run_backtest.
Source: sleousis/Stonks. Plans and status: docs/roadmap.md.
Start
Concepts
- Architecture
- Data and Storage
- Strategies
- Book Strategies
- Lab and Validation
- Backtesting
- Accounts and Modes
Using Stonks
- Strategy Studio
- Trading Tick
- Risk and Go-Live
- Operations
- Scheduling and Backups
- Deploy
- API and MCP
- Web Console
Reference