Repository navigation
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
-
No look-ahead (no peeking at future data): 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. Orders left after the last bar never fill.
-
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 (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_barscounts bars, not days.
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.
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.
| 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 |
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.
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.
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