Repository navigation
Trading Tick
A tick is one run of the trading loop, normally once a day after the close. Each tick is a fresh run; all state is in the databases.
flowchart TD
CA[Apply splits and dividends<br/>since the last snapshot] --> SIG
SIG[1. Signal phase<br/>each active strategy scores the universe once] --> BK
subgraph BK[2. Portfolio phase, per book]
C[Constructor<br/>signals to target book] --> R[Risk rules<br/>clip or drop]
R --> B[Broker<br/>sells, then buys]
B --> L[Orders, fills, snapshot,<br/>position attribution]
end
BK --> MB[3. Model books<br/>shadow strategies on virtual portfolios]
MB --> H[Tick hooks]
- Corporate actions: splits and cash dividends since the last snapshot are applied to the stored portfolio, once per event.
-
Signal phase: every active strategy scores every universe ticker it applies to. Scores above
thresholdare its picks. The instance that scored is the one that decides. -
Portfolio phase: each book runs the construction pipeline: keep the book's strategies, normalise signals, run the constructor, turn targets into orders, drop buys with stale prices (older than
max_price_staleness_days), apply the risk rules. Then the broker fills them and the ledger, snapshot and position attribution are written in one transaction. - Model books: shadow strategies run on their own virtual portfolios.
- Hooks: registered tick hooks run, and their output joins the tick summary. The notification hook only logs for now; the tick does not queue user notifications yet.
A book is one portfolio with its strategies, constructor, risk policy and broker.
- Today
stonks tick(CLI and API) runs one book: the default portfoliopf_defaultover every active strategy, with thesingle_winnerconstructor. The strategy with the best pick decides, using its owndecide. If nothing ranks but positions are held, their owner still decides with no picks, so exits happen. - One book per user portfolio, built from subscriptions (see Accounts and Modes), exists in the tick code but is not wired to the CLI or API yet.
- Other constructors (
equal_weight_top_n,inverse_vol,vol_target,atr_parity) diff target weights against the book with a no-trade buffer. The pipeline and a backtest config (BacktestConfig.construction, which the lab and API do not set yet) can use them; choosing one for the live tick ([production.construction]or a portfolio row) is not wired yet. The book strategies already size themselves this way inside their owndecide.
uv run stonks tick # trade today (UTC)
uv run stonks tick --dry-run # score and log, no orders, no snapshots
uv run stonks tick --as-of 2026-09-25 --dry-run # inspect a past day
uv run stonks tick --tickers AAPL.US,MSFT.US # override [production].universe
uv run stonks tick --asset-class crypto # only crypto tickers of the universeA real (non-dry-run) tick for a date before the latest snapshot is refused.
The default portfolio's order ids read <as_of>:<strategy_id>:<ticker>:<side>; other portfolios add the portfolio id. Rerunning a crashed tick for the same day produces the same ids, and orders already recorded are skipped. Safe to rerun.
Strategies in shadow are scored each tick but never traded. Each gets a virtual portfolio seeded with initial_cash, always on a simulated broker, through the same risk policy. Results go to shadow_decisions and shadow_portfolio_snapshots. Compare with stonks pnl --strategy <id>. Turn off with [production] shadow_enabled = false.
[brokers] kind |
What happens |
|---|---|
simulated (default) |
Fills in memory at the latest close, using [backtest.costs]. No keys needed. |
alpaca (opt-in) |
The default portfolio trades at Alpaca. Paper account by default. Keys from ALPACA_API_KEY and ALPACA_SECRET_KEY in env only. |
With Alpaca the tick reconciles open orders first, reads the portfolio from the account, saves each order as pending before sending it, and books fills only through reconciliation. Real money needs both paper = false and allow_live = true under [brokers.alpaca].
ok, partial (some order or book failed), error (the tick raised), or noop. Errors, partials and broker rejections send an alert. See Operations.
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