Skip to content

Trading Tick

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

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]
Loading

Steps

  1. Corporate actions: splits and cash dividends since the last snapshot are applied to the stored portfolio, once per event.
  2. Signal phase: every active strategy scores every universe ticker it applies to. Scores above threshold are its picks. The instance that scored is the one that decides.
  3. 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.
  4. Model books: shadow strategies run on their own virtual portfolios.
  5. 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.

Books and constructors

A book is one portfolio with its strategies, constructor, risk policy and broker.

  • Today stonks tick (CLI and API) runs one book: the default portfolio pf_default over every active strategy, with the single_winner constructor. The strategy with the best pick decides, using its own decide. 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 own decide.

Commands

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 universe

A real (non-dry-run) tick for a date before the latest snapshot is refused.

Idempotent order ids

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.

Shadow mode (model books)

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

[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].

Tick status

ok, partial (some order or book failed), error (the tick raised), or noop. Errors, partials and broker rejections send an alert. See Operations.

Clone this wiki locally