Repository navigation
Risk and Go Live
Two guards stand between a strategy and real orders: the risk rules on every tick, and the go-live check before a human promotes.
flowchart LR
LAB[lab run passes] --> SH[shadow<br/>virtual trading]
SH --> GL{golive check}
GL -->|PASS| H[Human runs<br/>registry promote]
GL -->|FAIL| SH
GL -.->|FAIL, with --override --reason| H
H --> AC[active]
AC --> RL[risk rules<br/>every tick]
RL --> BR[Broker]
Risk rules sit between the constructor and the broker. Each rule is a registered class in production/rules/; a new rule is one new file. Clipped or dropped orders are listed in the tick summary under risk_adjustments.
Configured under [production.risk] today:
| Setting | Default | Effect |
|---|---|---|
enabled |
true |
false passes orders through untouched |
max_open_positions |
unlimited | Drops a buy that would open one position too many |
max_weight_per_ticker |
1.0 |
Clips buys so one ticker stays under this share of portfolio value |
max_weight_per_asset_class |
none | For example crypto = 0.2; clips buys per class |
cash_buffer_fraction |
0.0 |
Keeps this share of value in cash, net of costs |
min_order_notional |
0.0 |
Drops buys smaller than this amount |
Always on: sells are clipped to what you hold (never a short), and buys need a current price.
Registered but not wired to config yet (off until [production.risk.rules.*] lands):
| Rule | Guards against |
|---|---|
risk_per_position |
One position carrying too much loss (ATR-based, 2% rule) |
portfolio_vol |
Book volatility above a target |
drawdown_scaling |
Full size while in a drawdown (buys shrink as it deepens) |
liquidity |
Buys too big against daily dollar volume |
sector_cap |
Too much in one sector |
max_holding |
Zombie positions held too long |
- Weights use portfolio value before the tick's orders.
- Sells go first; buys are re-checked against the post-sell book.
- Shadow strategies go through the same policy.
[production.risk]
max_open_positions = 10
max_weight_per_ticker = 0.25
cash_buffer_fraction = 0.05
[production.risk.max_weight_per_asset_class]
crypto = 0.2stonks golive check <id> judges a strategy's paper period: its shadow P&L while shadow, the real simulated or paper book once active. The console shows the same checks (GET /api/strategies/{id}/golive).
uv run stonks golive check <id>
uv run stonks golive check <id> --since 2026-08-01| Check | Default limit ([golive]) |
|---|---|
| status |
shadow or active
|
min_days |
63 days, or MinTRL of the OOS Sharpe if longer (capped at 252) |
max_drawdown |
no fall deeper than 15% |
max_drift |
paper return within 10 points of what the OOS backtest expected |
min_trades |
at least 20 filled trades |
| survival | every stored survival report passed |
within_mc_band |
paper drawdown and return inside the Monte Carlo band of mc_trades
|
quit_rule |
paper drawdown under 1.5x the backtest drawdown |
promotion_preset |
every test of the promotion preset has a stored report |
nonzero_costs |
the lab run used a non-zero cost model |
hypothesis_recorded |
a hypothesis of at least 20 characters |
backtest_min_trades |
at least 30 trades in the backtest |
The last six belong to the incubation grade (incubation = true, the default). Missing data fails a check. Exit code is 1 when any check fails.
- The lab only registers in
shadow. - The go-live check only reports; it never changes status.
-
stonks registry promote <id>needs a passing go-live check, or--override --reason "..."(at least 20 characters). - Every status change is written to
status_changes; see it withstonks registry history <id>. - MCP write tools need
confirm: trueand cannot turn on live trading.
uv run stonks registry list --status shadow
uv run stonks registry show <id>
uv run stonks registry promote <id>
uv run stonks registry shadow <id> --reason "drawdown beyond plan"
uv run stonks registry retire <id> --reason "edge gone"
uv run stonks registry history <id>Not built yet: a global kill switch and the circuit breaker (roadmap 12.6 and Phase 9 Wave 3).
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