Repository navigation
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]
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.
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.
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.
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.
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.
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.
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