Repository navigation
Configuration
Settings come from config/default.toml, then environment variables. Secrets come only from the environment (or .env).
flowchart LR
D[Code defaults] --> T[config/default.toml] --> E[Env vars and .env]
E --> S[Settings]
Later wins. Commands load .env from the working directory, so run them from the repo root.
| Section | Controls | Key settings (default) |
|---|---|---|
[lake] |
Market data file |
path (data/lake.duckdb) |
[lake.bars] |
Where bars live |
backend (duckdb or parquet) |
[state] |
Trading records file |
path (data/state.sqlite) |
[registry] |
Strategy artifacts |
artifacts_dir (data/artifacts) |
[logging] |
Log level |
level (INFO) |
[production] |
The tick |
universe ([]), threshold (0.0), initial_cash (10000), max_price_staleness_days (7), shadow_enabled (true), dividend_withholding_rate (0.0) |
[production.risk] |
Risk caps |
enabled, max_open_positions, max_weight_per_ticker (1.0), cash_buffer_fraction (0), min_order_notional (0) |
[production.risk.max_weight_per_asset_class] |
Caps per class | e.g. crypto = 0.2
|
[production.health] |
Health thresholds |
max_bar_age_days (4), stuck_tick_minutes (60), stuck_ingest_minutes (180), ingest_failure_lookback_hours (24) |
[backtest.costs] |
Trading costs (lab and simulated tick) |
impact_bps (100), max_impact_bps (500) |
[backtest.costs.default] |
Fallback costs |
fee_flat (0), half_spread_bps (2), fee_bps (0.5) |
[backtest.costs.asset_classes.<class>] |
Costs per asset class | same keys; crypto 5 bps spread and 10 bps fee |
[lab] |
Lab defaults |
benchmark (auto), embargo_bars (0) |
[lab.walk_forward] |
Walk-forward defaults |
n_splits (4), test_days, train_days, anchored (false), metric (sharpe), min_positive_share (0.5), min_mean_score (0), min_wfe (0.5), matrix (false) |
[lab.parallel] |
Worker processes |
max_workers (0 = every core, up to 32), blas_threads (1) |
[notify] |
Alerts |
backends (["log", "store"]), min_level (warning) |
[notify.webhook] |
Alert webhook |
timeout_seconds (5) |
[sources.eodhd] |
EODHD client |
base_url, timeout_seconds (30), max_retries (3) |
[sources.yahoo] |
Yahoo client |
timeout_seconds (30), max_retries (3), min_request_interval_seconds (0.5) |
[sources.defillama] |
DefiLlama client |
base_url, timeout_seconds (30), max_retries (3) |
[brokers] |
Broker of the tick |
kind (simulated or alpaca) |
[brokers.alpaca] |
Alpaca |
paper (true), allow_live (false), max_retries (3) |
[api] |
REST server |
host (127.0.0.1), port (8000), ui_origin, open_reads_on_loopback (true), allowed_hosts, max_concurrent_jobs (2), ui_dist, allow_code_strategies (false) |
[golive] |
Go-live limits |
min_days (63), max_drawdown (0.15), max_drift (0.10), min_trades (20), incubation (true), ... |
[mcp] |
MCP client |
api_url, timeout_seconds (30), max_wait_seconds (600) |
These are read straight from the TOML file by the block that owns them.
| Section | Read by | Notes |
|---|---|---|
[scheduler], [[scheduler.jobs]]
|
python -m stonks.scheduling |
See Scheduling and Backups. |
[connections] |
python -m stonks.connections |
enabled_providers (empty), portal_ttl_minutes, sync_workers. |
Not wired yet: [backup], [ingest.quality], [ingest.fallback], [production.construction] and [production.risk.rules.*] have settings models in the code, but Settings ignores them today. Backups and data quality run on their defaults, source fallback is off, the tick uses single_winner unless a portfolio row sets its own construction, and the six newer risk rules stay off.
| Variable | Purpose |
|---|---|
EODHD_API_KEY |
EODHD data key |
ALPACA_API_KEY, ALPACA_SECRET_KEY
|
Alpaca keys (rejected if put in TOML) |
STONKS_API_TOKEN |
Bearer token for the API, MCP and scheduler (rejected if put in TOML) |
STONKS_NOTIFY_WEBHOOK_URL |
Alert webhook URL |
STONKS_DATA_DIR |
Moves lake, state and artifacts under one folder |
STONKS_LOG_LEVEL |
Overrides [logging].level
|
STONKS_API_URL |
Makes the scheduler run jobs through the API |
STONKS_PING_* |
Dead-man ping URLs named by ping_url_env on scheduler jobs |
STONKS_SECRET_KEYS |
Master keys that encrypt broker credentials (python -m stonks.security keygen) |
STONKS_CONNECTIONS_ENABLED_PROVIDERS |
Overrides [connections].enabled_providers
|
STONKS_SNAPTRADE_CLIENT_ID, STONKS_SNAPTRADE_CONSUMER_KEY
|
SnapTrade partner credentials |
STONKS_VAPID_PUBLIC_KEY, STONKS_VAPID_PRIVATE_KEY, STONKS_VAPID_SUBJECT
|
Web Push keys (python -m stonks.notify vapid-keygen) |
STONKS_SMTP_HOST, _PORT, _USERNAME, _PASSWORD, _FROM, _SECURITY
|
Optional email channel |
STONKS_NOTIFY_* |
Notification outbox tuning (retries, backoff, dedupe window) |
STONKS_ALLOW_DESTRUCTIVE_MIGRATIONS |
1 lets db init run a migration that drops data |
STONKS_RUN_LIVE_TESTS |
1 enables live network tests |
Start from .env.example. .env is gitignored; never commit secrets.
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