Repository navigation
Accounts and Modes
Stonks is built for several traders. Market data and the strategy catalog are shared. Money, people and notifications belong to a user or a portfolio.
flowchart LR
subgraph G[Global]
LAKE[(Market data)]
CAT[Strategy catalog<br/>and registry]
end
subgraph U[Per user]
USER[User<br/>viewer, trader, admin]
PF[Portfolios<br/>simulated or broker]
SUB[Subscriptions<br/>strategy + mode]
CON[Broker connections]
NOTE[Notifications]
end
USER --> PF
USER --> SUB
SUB --> CAT
SUB --> PF
CON --> PF
USER --> NOTE
The data model and services exist (roadmap 15.2, 15.3, 15.6). Still missing: login, per-user API tokens and screens for users, subscriptions and connections, and the tick building one book per portfolio. Today the API uses one shared STONKS_API_TOKEN, and the tick runs the single default portfolio.
| Role | Can |
|---|---|
viewer |
Read |
trader |
Read and act on their own portfolios |
admin |
Everything, but sees only totals across traders, never their holdings |
An existing install is migrated to one admin, usr_owner, and one portfolio, pf_default, so nothing changes for a single user. Scheduled jobs act as the service account service:scheduler. Another user's row always reads as "not found", never "forbidden", so ids don't leak.
A portfolio is simulated (paper money inside Stonks) or broker (linked to a connected broker account). Each has its own cash, universe, risk overrides and construction settings. Overrides can only tighten the global risk policy, never loosen it.
A subscription says "follow this strategy, in this mode".
| Mode | What happens | Needs |
|---|---|---|
notify |
Signals only, no orders | nothing |
paper |
Trades a simulated portfolio | a portfolio you own |
auto |
Trades a connected broker account | a broker portfolio and the auto checklist |
The auto checklist: the strategy is active, the portfolio is an active broker portfolio, and the subscription finished 20 trading days in paper without a risk breach. A subscription is never created in auto. Shadow strategies allow notify and paper only; retired ones take no new subscriptions. Every mode change writes an audit_log row.
Read-only sync of positions, cash and activity from a broker, behind the BrokerConnection seam. Providers: SnapTrade (many brokers), Alpaca and a fake one for tests. None is enabled until an admin lists it. Credentials are encrypted with STONKS_SECRET_KEYS and never printed.
uv run python -m stonks.security keygen # a master key entry for STONKS_SECRET_KEYS
uv run python -m stonks.connections providers
uv run python -m stonks.connections connect snaptrade --redirect https://stonks.example.com/cb
uv run python -m stonks.connections list
uv run python -m stonks.connections link <connection> <account>
uv run python -m stonks.connections sync --due
uv run python -m stonks.connections rotate-keysA sync writes one snapshot per portfolio and day (source = 'sync'), holdings to broker_positions and activities to broker_activities. Nothing trades through a connection yet.
A router turns an event into per-user rows: an in-app alert, an outbox row and one delivery per channel. A worker sends them with retries, quiet hours in the user's time zone and digests.
| Channel | Setup |
|---|---|
| Web Push | VAPID keys: python -m stonks.notify vapid-keygen
|
| Email (optional) |
STONKS_SMTP_* variables |
| Webhook | The user's own URL |
uv run python -m stonks.notify test --user you@example.com
uv run python -m stonks.notify deliver # one delivery passNot wired yet: the tick does not queue signal notifications (its hook only logs), no scheduler job runs the delivery worker, and the API has no push subscription routes, so the console's push opt-in stops after the browser permission.
Design: docs/design/accounts-and-modes.md in the repo.
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