Skip to content

How It Works

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

How It Works

Five stages. Each is a command, and the scheduler can run the daily ones for you. All state lives in local files (a DuckDB lake, a SQLite state DB, strategy artifacts), so any step can be rerun.

flowchart LR
  V[(Vendors<br/>EODHD, Yahoo, DefiLlama)] -->|ingest + quality checks| L[(Lake<br/>DuckDB)]
  L --> LAB[Lab<br/>tune, survival tests]
  LAB -->|pass| REG[(Registry<br/>shadow)]
  REG -->|go-live + human promotes| ACT[active]
  ACT --> TICK[Daily tick]
  L --> TICK
  TICK --> B[Broker<br/>simulated or Alpaca]
  TICK --> S[(State<br/>SQLite)]
  S --> W[health, pnl, report, alerts]
Loading

1. Collect

stonks ingest ... pulls prices, fundamentals, metadata, macro and DeFi TVL data and writes them into the lake. Bars are checked first: impossible rows are quarantined, odd ones raise warnings. Writes are upserts, so reruns are safe. One bad ticker is logged and skipped. See Data and Storage.

2. Research

stonks lab run <strategy> splits history into train and validation windows (with an optional embargo between them). It tunes on train, then runs survival tests on data the tuner never saw. The verdict is pass only if every gating test passes. Every trial is recorded. See Lab and Validation.

3. Approve

A passing strategy can be registered. It always lands in shadow: it trades a virtual portfolio every tick but never real money. stonks golive check <id> judges that paper record. stonks registry promote <id> makes it active, and needs a passing go-live check or --override --reason. See Risk and Go-Live.

4. Trade

stonks tick runs once a day. Every active strategy scores the universe once. Then each portfolio book turns those signals into target positions, the risk rules clip them, and the book's broker fills them. Snapshots, attribution and notifications follow. See Trading Tick.

5. Watch

stonks health checks data freshness and stuck runs. stonks pnl shows daily profit and loss. stonks report writes an HTML report or a backtest tear sheet. Alerts go to the log, the alerts table and a webhook. See Operations.

Other ways in

The same services are exposed as a REST API (stonks serve), an MCP server for Claude (stonks mcp) and the Angular web console. See API and MCP and Web Console.

Clone this wiki locally