Skip to content

Getting Started

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

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

1. Install

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 sync

2. Add your data key

cp .env.example .env

Edit .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.

3. Create the databases

uv run stonks db init     # creates data/lake.duckdb and data/state.sqlite
uv run stonks db info     # lists tables and row counts

4. Collect some prices

uv run stonks ingest prices --tickers AAPL.US,MSFT.US,SPY.US --since 2025-01-01

5. Test a strategy in the lab

There 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).

6. Dry-run a tick

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.

7. Open the console (optional)

export STONKS_API_TOKEN=$(openssl rand -hex 32)
uv run stonks serve        # http://127.0.0.1:8000

See Web Console to build the UI.

Next

Clone this wiki locally