Skip to content

Accounts and Modes

Savvas Leousis edited this page Sep 26, 2026 · 1 revision

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
Loading

Status

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.

Users and roles

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.

Portfolios

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.

Subscriptions and modes

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.

Broker connections

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-keys

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

Notifications

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 pass

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

Clone this wiki locally