Repository navigation
Getting Started
From a fresh clone to a dry-run trade in a few minutes.
flowchart LR
I[Install] --> K[Set API key] --> D[db init] --> G[Ingest] --> L[Lab run] --> T[Dry-run tick]
You need Python 3.12+ and uv (a fast Python package manager).
pipx install uv
git clone https://github.com/sleousis/Stonks.git
cd Stonks
uv synccp .env.example .envEdit .env and set EODHD_API_KEY=... (get one at eodhd.com).
The free tier gives daily prices for about one year. No key? Use --source yahoo on ingest commands.
uv run stonks db init # creates data/lake.duckdb and data/state.sqlite
uv run stonks db info # lists tables and row countsuv run stonks ingest prices --tickers AAPL.US,MSFT.US,SPY.US --since 2025-01-01There is no separate backtest command. stonks lab run tunes, backtests and validates in one go.
uv run stonks lab run momentum \
--tickers AAPL.US,MSFT.US,SPY.US \
--start 2025-01-01 --end 2026-09-01 \
--hypothesis "winners keep winning for a few months"You get the best parameters, a table of survival tests (the quick preset by default) and a pass or fail verdict.
Add --register to save the strategy in shadow only if every test passes (that run uses the stricter promotion preset unless you pick one).
uv run stonks registry list
uv run stonks tick --dry-run --tickers AAPL.US,MSFT.US,SPY.US--dry-run scores and logs but places no orders and writes no snapshots. Shadow strategies trade on virtual books; promote one only after stonks golive check <id> passes.
export STONKS_API_TOKEN=$(openssl rand -hex 32)
uv run stonks serve # http://127.0.0.1:8000See Web Console to build the UI.
- How It Works for the big picture.
-
Strategies for the full list you can pass to
lab run. - Scheduling and Backups to run the daily loop unattended.
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