Skip to content

API Reference

github-actions[bot] edited this page Sep 27, 2026 · 22 revisions

REST API

Stonks API 0.1.0. Research + trading system: portfolio, strategies, market data, lab runs and background jobs.

flowchart LR
  C["Clients<br/>web UI, stonks mcp, scripts"] -->|"HTTP /api"| A["FastAPI app"]
  A --> S["Services"]
  S --> L[("lake.duckdb<br/>market data")]
  S --> T[("state.sqlite<br/>strategies, orders, ticks")]
Loading

Auth: every route except health and sign-in needs a credential: the browser session cookie (plus X-CSRF-Token on writes) or Authorization: Bearer stk_.... The Auth column names the permission a route checks (see docs/security.md). "sign-in" means any signed-in user.

Tags: alerts · auth · backups · brokers · catalog · connections · halts · health · ingest · insights · jobs · lab · market · notifications · orders · pnl · portfolio · push · risk · schedule · shadow · sources · statements · strategies · studio · subscriptions · tca · ticks · universes

alerts endpoints

Method Path Summary Auth Request Response
GET /api/alerts List Alerts sign-in Page_AlertView_

auth endpoints

Method Path Summary Auth Request Response
GET /api/auth/check Check Auth sign-in AuthCheck
POST /api/auth/login Login none LoginRequest LoginView
POST /api/auth/logout Logout none
GET /api/auth/me Me sign-in MeView
POST /api/auth/mfa/enrol Start Enrolment none EnrolStartView
POST /api/auth/mfa/enrol/confirm Confirm Enrolment none MfaCodeRequest MfaView
POST /api/auth/mfa/verify Verify Mfa none MfaCodeRequest MfaView
POST /api/auth/password Change Password password.change PasswordChangeRequest
POST /api/auth/recovery-codes Regenerate Recovery Codes mfa.recovery_codes RecoveryCodesView
GET /api/auth/tokens List Tokens sign-in Page_TokenView_
POST /api/auth/tokens Create Token tokens.manage TokenCreateRequest TokenCreatedView
DELETE /api/auth/tokens/{token_id} Revoke Token tokens.revoke
GET /api/auth/users List Users users.read Page_UserView_
POST /api/auth/users Create User users.manage UserCreateRequest UserView
PATCH /api/auth/users/{user_id} Update User users.manage UserUpdateRequest UserView
DELETE /api/auth/users/{user_id}/mfa Reset User Mfa users.manage
POST /api/auth/users/{user_id}/password Reset User Password users.manage PasswordResetRequest

backups endpoints

Method Path Summary Auth Request Response
GET /api/backups List Backups operations.run Page_BackupView_
POST /api/backups Start Backup operations.run Job
GET /api/backups/jobs/{job_id}/result Get Backup Result operations.run BackupResultView
GET /api/backups/restores/{job_id}/result Get Restore Result operations.run RestoreResultView
POST /api/backups/{backup_id}/restore Restore Backup backups.restore RestoreRequest Job
POST /api/backups/{backup_id}/verify Verify Backup operations.run VerifyView

brokers endpoints

Method Path Summary Auth Request Response
GET /api/brokers Get Broker Info sign-in BrokerInfo
GET /api/brokers/alpaca/status Get Alpaca Status sign-in AlpacaStatus

catalog endpoints

Method Path Summary Auth Request Response
GET /api/catalog/asset-classes List Asset Classes sign-in list[string]
GET /api/catalog/intervals List Intervals sign-in list[IntervalInfo]
GET /api/catalog/strategies List Strategy Classes sign-in list[StrategyClassInfo]

connections endpoints

Method Path Summary Auth Request Response
GET /api/connections List Connections sign-in Page_ConnectionView_
GET /api/connections/callback Complete Portal sign-in ConnectionView
POST /api/connections/keys Connect With Keys connection.manage ConnectWithKeysRequest ConnectionView
POST /api/connections/portal Start Portal connection.manage StartPortalRequest PortalLinkView
GET /api/connections/providers List Providers sign-in list[ProviderView]
GET /api/connections/{connection_id} Get Connection sign-in ConnectionView
DELETE /api/connections/{connection_id} Delete Connection connection.manage DisconnectView
GET /api/connections/{connection_id}/accounts List Accounts sign-in Page_BrokerAccountView_
POST /api/connections/{connection_id}/link Link Account portfolio.manage LinkAccountRequest LinkResultView
POST /api/connections/{connection_id}/sync Sync Connection portfolio.manage SyncResultView

halts endpoints

Method Path Summary Auth Request Response
GET /api/halts List Halts sign-in Page_HaltView_
POST /api/halts/kill Engage Kill Switch killswitch.user KillSwitchRequest HaltView
GET /api/halts/{halt_id} Get Halt sign-in HaltView
POST /api/halts/{halt_id}/clear Clear Halt risk.reset ClearHaltRequest HaltView
POST /api/halts/{halt_id}/resume Resume Kill Switch killswitch.resume ResumeRequest HaltView

health endpoints

Method Path Summary Auth Request Response
GET /api/health Liveness probe none Health
GET /api/health/live Liveness probe (process and hosted scheduler) none ProbeView
GET /api/health/ready Readiness probe (state migrated, lake present) none ProbeView
GET /api/health/report Health Report sign-in HealthReportView
POST /api/health/run Run Health Checks operations.run HealthRunRequest HealthReportView

ingest endpoints

Method Path Summary Auth Request Response
GET /api/ingest/jobs/{job_id}/result Get Ingest Result sign-in IngestResultView
GET /api/ingest/runs List Runs sign-in Page_IngestRunView_
POST /api/ingest/runs Start Ingest operations.run IngestRequest Job

insights endpoints

Method Path Summary Auth Request Response
GET /api/insights Get Insights sign-in InsightsView
GET /api/insights/agreement Get Agreement sign-in AgreementView
GET /api/insights/totals Get Totals portfolio.totals InsightsTotalsView

jobs endpoints

Method Path Summary Auth Request Response
GET /api/jobs List Jobs sign-in Page_Job_
GET /api/jobs/{job_id} Get Job sign-in Job
POST /api/jobs/{job_id}/cancel Cancel Job lab.run Job
GET /api/jobs/{job_id}/events Stream Job Events sign-in SSE of JobEvent
POST /api/jobs/{job_id}/stream-token Create Stream Token data.read StreamToken

lab endpoints

Method Path Summary Auth Request Response
POST /api/lab/backtests Start Backtest lab.run BacktestRequest Job
GET /api/lab/backtests/{job_id}/result Get Backtest Result sign-in BacktestResult
GET /api/lab/cost-models List Cost Models sign-in list[CostModelPreset]
GET /api/lab/ensure/{job_id}/result Get Lab Ensure Result sign-in EnsureReport
POST /api/lab/runs Start Lab Run lab.run LabRunRequest Job
GET /api/lab/runs/{job_id}/result Get Lab Run Result sign-in LabRunView
POST /api/lab/signal-ic Start Signal Ic lab.run SignalICRequest Job
GET /api/lab/signal-ic/{job_id}/result Get Signal Ic Result sign-in SignalICView
GET /api/lab/survival-presets List Survival Presets sign-in list[SurvivalPresetInfo]
GET /api/lab/survival-tests List Survival Tests sign-in list[SurvivalTestInfo]
POST /api/lab/sweeps Start Sweep lab.run SweepRequest Job
GET /api/lab/sweeps/{job_id}/result Get Sweep Result sign-in SweepResultView

market endpoints

Method Path Summary Auth Request Response
GET /api/market/bars Get Bars sign-in BarSeries
GET /api/market/coverage List Coverage sign-in Page_CoverageRow_
GET /api/market/instruments List Instruments sign-in Page_InstrumentView_

notifications endpoints

Method Path Summary Auth Request Response
GET /api/notifications List Notifications sign-in FeedView
GET /api/notifications/preferences Get Preferences sign-in PreferencesView
PUT /api/notifications/preferences Update Preferences notifications.manage PreferencesUpdate PreferencesView
PUT /api/notifications/quiet-hours Set Quiet Hours notifications.manage QuietHoursUpdate PreferencesView
POST /api/notifications/read Mark Read data.read MarkReadRequest MarkReadView
PUT /api/notifications/webhook Set Webhook notifications.manage WebhookUpdate PreferencesView

orders endpoints

Method Path Summary Auth Request Response
GET /api/orders List Orders sign-in Page_OrderView_
GET /api/orders/fills List Fills sign-in Page_FillView_

pnl endpoints

Method Path Summary Auth Request Response
GET /api/pnl Get Pnl sign-in PnlSeries

portfolio endpoints

Method Path Summary Auth Request Response
GET /api/portfolio Get Portfolio sign-in PortfolioView
GET /api/portfolio/snapshots List Snapshots sign-in Page_SnapshotView_
GET /api/portfolio/totals Get Totals portfolio.totals PortfolioTotalsView
GET /api/portfolios List Portfolios data.read Page_PortfolioSummaryView_
GET /api/portfolios/trading-modes List Trading Modes data.read Page_TradingModeView_

push endpoints

Method Path Summary Auth Request Response
GET /api/push/subscriptions List Push Subscriptions sign-in Page_PushDeviceView_
POST /api/push/subscriptions Create Push Subscription notifications.manage PushSubscriptionRequest PushDeviceView
DELETE /api/push/subscriptions Delete Push Subscription notifications.manage PushUnsubscribeRequest
DELETE /api/push/subscriptions/{device_id} Delete Push Device notifications.manage
GET /api/push/vapid-key Vapid Key sign-in VapidKeyView

risk endpoints

Method Path Summary Auth Request Response
GET /api/risk/live Get Live Risk sign-in RiskSummaryView
GET /api/risk/policy Get Risk Policy sign-in RiskPolicy
GET /api/risk/snapshots List Risk Snapshots sign-in Page_RiskSnapshotView_

schedule endpoints

Method Path Summary Auth Request Response
GET /api/schedule Get Schedule sign-in ScheduleView
POST /api/schedule/{job}/run-now Run Now operations.run RunNowRequest RunNowView

shadow endpoints

Method Path Summary Auth Request Response
GET /api/shadow/decisions List Shadow Decisions sign-in Page_ShadowDecisionView_
GET /api/shadow/pnl List Shadow Pnl sign-in Page_ShadowPnlSummary_
GET /api/shadow/strategies/{strategy_id}/pnl Get Shadow Pnl sign-in PnlSeries

sources endpoints

Method Path Summary Auth Request Response
GET /api/sources List Sources sign-in list[DataSourceInfo]

statements endpoints

Method Path Summary Auth Request Response
GET /api/statements/flags List Statement Flags sign-in Page_StatementFlagView_

strategies endpoints

Method Path Summary Auth Request Response
GET /api/strategies List Strategies sign-in Page_StrategySummary_
GET /api/strategies/summary Strategy Summary sign-in StrategyStatusCounts
GET /api/strategies/{strategy_id} Get Strategy sign-in StrategyDetail
GET /api/strategies/{strategy_id}/golive Get Golive sign-in GoLiveReport
GET /api/strategies/{strategy_id}/history Get Strategy History sign-in Page_StatusChangeView_
POST /api/strategies/{strategy_id}/promote Promote strategy.promote StatusChangeRequest | null StrategyDetail
POST /api/strategies/{strategy_id}/retire Retire strategy.promote StatusChangeRequest | null StrategyDetail
POST /api/strategies/{strategy_id}/shadow Shadow strategy.promote StatusChangeRequest | null StrategyDetail

studio endpoints

Method Path Summary Auth Request Response
GET /api/studio/capabilities Capabilities sign-in StudioCapabilities
GET /api/studio/drafts List Drafts sign-in Page_Draft_
POST /api/studio/drafts Create Draft lab.run DraftCreate Draft
GET /api/studio/drafts/{draft_id} Get Draft sign-in Draft
PATCH /api/studio/drafts/{draft_id} Update Draft lab.run DraftUpdate Draft
DELETE /api/studio/drafts/{draft_id} Delete Draft lab.run Draft
POST /api/studio/drafts/{draft_id}/backtests Start Backtest lab.run DraftBacktestRequest Job
POST /api/studio/drafts/{draft_id}/disable Disable Draft strategy.promote StatusChangeRequest | null Draft
POST /api/studio/drafts/{draft_id}/enable Enable Draft strategy.promote StatusChangeRequest | null Draft
POST /api/studio/drafts/{draft_id}/lab-runs Start Lab Run lab.run DraftLabRunRequest Job
POST /api/studio/drafts/{draft_id}/register Register Draft strategy.promote Draft
POST /api/studio/drafts/{draft_id}/validate Validate Draft lab.run ValidateRequest | null DraftValidation
GET /api/studio/schema Schema sign-in object
POST /api/studio/spec/validate Validate Spec lab.run SpecValidateRequest DraftValidation
GET /api/studio/templates Templates sign-in list[RuleTemplateView]

subscriptions endpoints

Method Path Summary Auth Request Response
GET /api/subscriptions List Subscriptions data.read Page_SubscriptionView_
POST /api/subscriptions Subscribe portfolio.trade SubscribeRequest SubscriptionView
PATCH /api/subscriptions/{subscription_id} Update Subscription portfolio.trade SubscriptionUpdate SubscriptionView

tca endpoints

Method Path Summary Auth Request Response
GET /api/tca/journal List Journal sign-in Page_JournalEntryView_
PUT /api/tca/notes/{note_id} Update Journal Note portfolio.manage NoteRequest JournalNoteView
GET /api/tca/orders/{client_id} Get Order Tca sign-in JournalEntryView
POST /api/tca/orders/{client_id}/notes Add Journal Note portfolio.manage NoteRequest JournalNoteView
GET /api/tca/summary Tca Summary sign-in TcaSummaryView

ticks endpoints

Method Path Summary Auth Request Response
GET /api/ticks List Ticks sign-in Page_TickRun_
POST /api/ticks Start Tick operations.run TickRequest Job
GET /api/ticks/jobs/{job_id}/result Get Tick Result sign-in TickResultView
GET /api/ticks/{tick_id} Get Tick sign-in TickRunWithOrders

universes endpoints

Method Path Summary Auth Request Response
GET /api/universes List Universes sign-in Page_UniverseView_
POST /api/universes Create Universe lab.run UniverseCreate UniverseView
GET /api/universes/ensure/{job_id}/result Get Ensure Result sign-in EnsureReport
POST /api/universes/index-history Import Index History lab.run IndexHistoryImport IndexHistoryView
GET /api/universes/refresh/{job_id}/result Get Refresh Result sign-in UniverseRefreshView
GET /api/universes/{universe_id} Get Universe sign-in UniverseView
DELETE /api/universes/{universe_id} Delete Universe strategy.promote UniverseView
POST /api/universes/{universe_id}/ensure Ensure Data lab.run EnsureDataRequest Job
GET /api/universes/{universe_id}/members Get Members sign-in UniverseMembers
POST /api/universes/{universe_id}/refresh Refresh Universe lab.run Job

Schemas

AgreementView

Field Type Required Description
as_of date | null yes The price day the strategies scored.
holdings list[HoldingAgreement] yes
portfolio_id string yes
skipped list[string] yes Active strategies that could not be loaded.
strategies list[string] yes Active strategies asked, in registry order.

AlertView

Field Type Required Description
context object yes
created_at date-time yes
id integer yes
level "info" | "warning" | "error" yes
message string yes
title string yes

AllocationSlice

Field Type Required Description
holdings integer yes Holdings in the group (0 for cash).
key string yes The group: an asset class, sector, currency or ticker.
value number yes Market value of the group (shorts count negative).
weight number | null yes value / the book's total value; null when the total is zero or less.

AllocationView

Field Type Required Description
asset_class list[AllocationSlice] yes
currency list[AllocationSlice] yes
sector list[AllocationSlice] yes
ticker list[AllocationSlice] yes

AlpacaStatus

Field Type Required Description
account stonks__app__brokers__BrokerAccountView | null no
clock MarketClockView | null no
connected boolean yes
error string | null no
paper boolean yes

ApiScope

What a credential may do. A token never exceeds its user's role.

Type: "read" | "trade" | "lab" | "admin"

AssetClassCosts

Fee and spread for one asset class.

Field Type Required Description
fee_bps number no
fee_flat number no
half_spread_bps number no

AuthCheck

Field Type Required Description
authenticated true no

BacktestRequest

Field Type Required Description
benchmark string | null no
cost_model "zero" | "realistic" | CostModelSettings | null no
end date yes
fee_per_trade number no
initial_cash number no
interval string no
rebalance_every_bars integer no
slippage_bps number no
start date yes
strategy StrategyRef yes
threshold number no
universe list[string] yes

BacktestResult

Field Type Required Description
benchmark BenchmarkStatsView | null no
benchmark_equity list[EquityPoint] no
cagr number | null yes
calmar number | null no
drawdown list[EquityPoint] no
end date yes
equity list[EquityPoint] yes
es_95 number | null no
final_return number | null yes
fitness number | null no
interval string yes
kurtosis number | null no
max_dd_duration_bars integer no
max_drawdown number | null yes
profit_factor number | null yes
sharpe number | null yes
skew number | null no
sortino number | null no
start date yes
strategy_id string yes
trade_count integer no
trade_stats TradeStatsView | null no
trades list[TradeView] no
ulcer_index number | null no
var_95 number | null no

BackupResultView

Field Type Required Description
backup_id string yes
pruned list[string] yes

BackupView

Field Type Required Description
created_at date-time yes
id string yes
size_bytes integer yes

BarSeries

Field Type Required Description
bars list[BarView] yes
interval string yes
ticker string yes
truncated boolean yes

BarView

Field Type Required Description
adj_close number | null yes
close number | null yes
high number | null yes
low number | null yes
open number | null yes
timestamp date-time yes
volume number | null yes

BenchmarkStatsView

A backtest against its benchmark (backtest.benchmark.BenchmarkStats). Ratios are None when not finite.

Field Type Required Description
alpha_annual number | null yes
alpha_tstat number | null yes
benchmark_cagr number | null yes
benchmark_max_dd number | null yes
benchmark_sharpe number | null yes
beta number | null yes
correlation number | null yes
down_capture number | null yes
excess_cagr number | null yes
excluded list[string] no
information_ratio number | null yes
members list[string] no
n_obs integer yes
name string yes
r2 number | null yes
residual_sharpe number | null yes
spec string yes
tracking_error number | null yes
up_capture number | null yes

BorrowCheckSettings

Field Type Required Description
borrow BorrowSettings | null no
enabled boolean no
max_borrow_fee number | null no

BorrowSettings

FlatBorrow knobs: the general-collateral fee per asset class and the tickers that are hard to borrow or not borrowable at all.

Field Type Required Description
fee_rate_annual dict[str, number] no
hard list[string] no
hard_fee_rate_annual number no
none list[string] no

BrokerInfo

Field Type Required Description
allow_live boolean yes
credentials_configured boolean yes
kind "simulated" | "alpaca" yes
paper boolean yes

ChannelDefaultView

Field Type Required Description
channel string yes
default_enabled boolean yes
fallback boolean yes

CircuitBreakerSettings

Field Type Required Description
cooldown "rest_of_month" | "none" no
max_drawdown_halt number | null no
max_month_loss number | null no
max_week_loss number | null no
week_sessions integer no

ClearHaltRequest

Field Type Required Description
reason string yes

Concentration

Field Type Required Description
effective_holdings number | null yes 1 / hhi.
hhi number | null yes Herfindahl index of the holding weights (0 to 1).
holdings integer yes Priced holdings.
largest string | null yes
top5_weight number | null yes
top_weight number | null yes Largest holding's share of gross holdings.

ConnectWithKeysRequest

API-key connect. fields are the provider's credential_fields (plus paper for brokers with a paper endpoint). They are write-only: never logged, stored only sealed, never returned.

Field Type Required Description
fields dict[str, password] yes
label string | null no
provider string yes

ConnectionView

Field Type Required Description
accounts_count integer no
consecutive_failures integer yes
created_at date-time yes
id string yes
label string | null yes
last_error string | null yes
last_sync_at date-time | null yes
last_sync_status "ok" | "partial" | "error" | null yes
next_sync_at date-time | null yes
provider string yes
status "pending" | "active" | "error" yes
updated_at date-time yes

CostComparisonView

Live shortfall of the strategy's real orders against the cost model's estimate (BL-32, P22), in bps.

Field Type Required Description
live_is_bps number | null no
model_gap_bps number | null no
modelled_bps number | null no
orders integer no

CostModelPreset

Field Type Required Description
description string yes
name "zero" | "realistic" yes
settings CostModelSettings yes

CostModelSettings

Settings for AssetClassCostModel. Zero costs by default; CostModelSettings.realistic() is a sensible starting point.

Field Type Required Description
adv_window integer no
asset_classes dict[str, AssetClassCosts] no
default AssetClassCosts no
half_spread_model "class" | "corwin_schultz" | "abdi_ranaldo" no
impact_bps number no
impact_gamma number no
impact_model "sqrt" | "sqrt_vol" | "istar" no
istar IStarSettings no
max_half_spread_bps number no
max_impact_bps number no
spread_window integer no
vol_window integer no

CoverageRow

Field Type Required Description
first_bar date-time yes
interval string yes
last_bar date-time yes
rows integer yes
ticker string yes

DataSourceInfo

Field Type Required Description
configured boolean yes
default boolean yes
detail string | null no
id "eodhd" | "yahoo" | "defillama" yes

DisconnectView

Field Type Required Description
archived_portfolios list[string] yes
connection_id string yes
remote_error string | null yes
remote_removed boolean | null yes

Draft

Field Type Required Description
created_at string yes
id string yes
kind "rule" | "code" yes
name string yes
owner_id string | null no
registered_strategy_id string | null yes
source_code string | null yes
spec object yes
status "draft" | "registered" yes
strategy_status "active" | "shadow" | "retired" | null yes
updated_at string yes

DraftBacktestRequest

A :class:~stonks.app.lab.BacktestRequest without the strategy (the draft is the strategy).

Field Type Required Description
benchmark string | null no
cost_model "zero" | "realistic" | CostModelSettings | null no
end date yes
fee_per_trade number no
initial_cash number no
interval string no
rebalance_every_bars integer no
slippage_bps number no
start date yes
threshold number no
universe list[string] yes

DraftCreate

Field Type Required Description
kind "rule" | "code" no
name string yes
source_code string | null no
spec object no

DraftLabRunRequest

A :class:~stonks.app.lab.LabRunRequest without the strategy. A rule draft's spec is fixed (it has no tunable parameters); a code draft's class is tuned over its parameter space. Registering (register_strategy always, register_if_passes only on a pass) links the new strategy to the draft.

Field Type Required Description
benchmark string | null no
budget integer no
cost_model "zero" | "realistic" | CostModelSettings | null no
embargo_bars integer | null no
end date yes
grid_size integer no
hypothesis string | null no
interval string no
mcpt McptOptions | null no
objective "sharpe" | "cagr" | "final_return" | "cv_sharpe" | "cv_cagr" | "cv_final_return" no
preflight boolean | null no
premortem string | null no
preset "promotion" | "quick" | "standard" | null no
register_if_passes boolean no
register_strategy boolean no
seed integer no
start date yes
strict_preflight boolean | null no
survival_tests list["benchmark_relative" | "cost_stress" | "cpcv" | "crisis" | "cross_instrument" | "deflated_sharpe" | "drift" | "event_study" | "mc_trades" | "mcpt" | "oos" | "pbo" | "period_stability" | "permutation" | "perturbation" | "plateau" | "pool_correlation" | "runs_test" | "signal_ic" | "stress" | "vs_random" | "walk_forward" | "walk_forward_mcpt"] | null no
test_options dict[str, object] | null no
train_ratio number no
tuner "grid" | "random" no
universe list[string] yes
walk_forward WalkForwardConfig | null no

DraftUpdate

Field Type Required Description
name string | null no
source_code string | null no
spec object | null no

DraftValidation

Field Type Required Description
issues list[ValidationIssue] yes
smoke SmokeCheck | null no
valid boolean yes

DrawdownScalingSettings

Field Type Required Description
schedule list[list[any]] | null no

EnrolStartView

Field Type Required Description
otpauth_uri string yes
secret string yes

EnsureDataRequest

Fetch the missing bars of the universe's members over a window (every name that was a member on any day of it, delisted ones too).

Field Type Required Description
end date yes
interval string no
source "eodhd" | "yahoo" | "defillama" | null no
start date yes

EnsureReport

What an ensure did. run_id is the ingest_runs row (None when nothing was missing).

Field Type Required Description
bulk_days integer no
clipped_start date | null no
end date yes
failed list[string] no
gaps integer no
interval string yes
readjusted list[string] no
run_id integer | null no
source string yes
start date yes
status string no
tickers_failed integer no
tickers_fetched integer no
tickers_requested integer no
tickers_up_to_date integer no
warnings list[string] no

EquityPoint

Field Type Required Description
timestamp date-time yes
value number yes

Exposure

Field Type Required Description
benchmark string | null yes
beta number | null yes Sum of each holding's weight times its beta to the benchmark, over the holdings with a beta. Null when none has one.
beta_coverage number yes Share of the gross holdings (by value) that have a beta.
gross number | null yes (long - short) / total value; null without value.
long_value number yes
net number | null yes (long + short) / total value; null without value.
short_value number yes Market value of short holdings (zero or negative).

FailingCheck

One go-live check that failed (GoLiveCheck without passed).

Field Type Required Description
detail string no
limit number | null no
name string yes
value number | null no

FeedItemView

Field Type Required Description
category string | null yes
created_at date-time yes
deep_link string | null yes
id integer yes
level string yes
message string yes
read_at date-time | null yes
title string yes

FeedView

Field Type Required Description
items list[FeedItemView] yes
unread_count integer yes

FillView

Field Type Required Description
fee number yes
filled_at string yes
id integer yes
order_client_id string yes
price number yes
quantity number yes
tick_id string | null yes
ticker string yes

GoLiveCheckView

Field Type Required Description
detail string yes
limit number | null yes
name "status" | "min_days" | "max_drawdown" | "max_drift" | "min_trades" | "survival" | "within_mc_band" | "quit_rule" | "promotion_preset" | "nonzero_costs" | "hypothesis_recorded" | "backtest_min_trades" yes
passed boolean yes
value number | null yes

GoLivePolicy

Limits a paper-trading period must meet before stonks golive check passes ([golive]). The gate only reports; promotion stays a human action. Every limit is strict about missing data: a period with no snapshots, no fills or no backtest expectation fails.

Field Type Required Description
incubation boolean no
max_drawdown number no
max_drift number no
min_backtest_trades integer no
min_days integer no
min_hypothesis_chars integer no
min_trades integer no
min_trl_alpha number no
min_trl_cap_days integer no
periods_per_year number no
promotion_preset string no
quit_drawdown_multiple number no
require_all_survival_passed boolean no
use_min_trl boolean no

GoLiveReport

Field Type Required Description
checklist PromotionChecklistView no
checks list[GoLiveCheckView] yes
costs CostComparisonView | null no
passed boolean yes
policy GoLivePolicy yes
source "shadow" | "portfolio" | "none" yes
status string yes
strategy_id string yes

GrossExposureSettings

Field Type Required Description
max_gross number | null no

HaltView

Field Type Required Description
active boolean yes
clear_reason string | null yes
cleared_at string | null yes
cleared_by string | null yes
expires_on date | null yes
halt "buys" | "all" yes
id integer yes
kind "month_loss" | "week_loss" | "drawdown" | "operational" | "kill" yes
portfolio_id string | null yes
reason string yes
scope "global" | "user" | "portfolio" yes
tripped_at string yes
tripped_by string yes
user_id string | null yes

Health

Field Type Required Description
status string yes
version string yes

HealthCheckView

Field Type Required Description
detail string yes
name string yes
ok boolean yes

HealthConfig

Thresholds for stonks health ([production.health]).

Field Type Required Description
ingest_failure_lookback_hours integer no
max_bar_age_days integer no
stuck_ingest_minutes integer no
stuck_tick_minutes integer no

HealthReportView

Field Type Required Description
checked_at date-time yes
checks list[HealthCheckView] yes
healthy boolean yes
thresholds HealthConfig yes

HealthRunRequest

Field Type Required Description
tickers list[string] | null no

HoldingAgreement

Field Type Required Description
agree integer yes
disagree integer yes
opinions list[Opinion] yes
side "long" | "short" yes
symbol string yes
ticker string | null yes

HorizonICView

Field Type Required Description
hac_lags integer yes
hit_rate number | null yes
horizon integer yes
ic_std number | null yes
icir number | null yes
mean_ic number | null yes
n_dates integer yes
quantile_means list[number | null] yes
se_hac number | null yes
se_iid number | null yes
spread_mean number | null yes
spread_t_hac number | null yes
t_stat_hac number | null yes

IStarSettings

Kissell's I-Star parameters: I = a1 (Q/ADV)^a2 sigma^a3 bps, with a temporary part b1 I pov^a4 and a permanent part (1 - b1) I. The defaults are Kissell's published US-equity estimates, not calibrated for this system; treat them as a starting point.

Field Type Required Description
a1 number no
a2 number no
a3 number no
a4 number no
b1 number no
periods_per_year number no
pov number no

IndexHistoryImport

An index constituent history as CSV (date,ticker,action with add, remove or member) or JSON (as_of, constituents, changes).

Field Type Required Description
content string yes
format "csv" | "json" no
index_id string yes

IndexHistoryView

Field Type Required Description
as_of date | null yes
changes integer yes
constituents integer yes
index_id string yes

IngestRequest

Field Type Required Description
exchange string | null no
interval string | null no
kind "prices" | "intraday" | "fundamentals" | "metadata" yes
since date | null no
source "eodhd" | "yahoo" | "defillama" no
tickers list[string] no
until date | null no

IngestResultView

Field Type Required Description
kind string yes
run_id integer yes
status string yes
tickers_failed integer yes
tickers_ok integer yes

IngestRunView

Field Type Required Description
error string | null yes
finished_at date-time | null yes
id integer yes
kind string yes
source string yes
started_at date-time yes
status string | null yes
tickers_failed integer | null yes
tickers_ok integer | null yes

InsightsTotalsView

Sums over every active portfolio's latest snapshot, for admins. No tickers, sectors or per-person numbers (decision 2026-09-26).

Field Type Required Description
asset_class list[AllocationSlice] yes
cash number yes
exposure Exposure yes
owners integer yes
portfolios integer yes
total_value number yes

InsightsView

Field Type Required Description
allocation AllocationView yes
cash number yes
currency string yes Reporting currency. Amounts are not FX-converted.
exposure Exposure yes
notes list[string] yes
pnl list[PeriodPnl] yes
portfolio_id string yes
risk RiskView yes
source "tick" | "sync" | null yes tick (the Stonks ledger) or sync (a broker).
taken_at date-time | null yes When the snapshot read was taken.
total_value number yes
uncovered list[string] yes Broker symbols no ticker maps to.
unpriced list[string] yes Holdings without a price, left out of the numbers.

InstrumentView

Field Type Required Description
asset_class string | null yes
currency string | null yes
exchange string | null yes
id string yes
industry string | null yes
is_delisted boolean | null yes
name string | null yes
sector string | null yes

IntervalInfo

Field Type Required Description
code string yes
is_intraday boolean yes
seconds integer yes

Job

Field Type Required Description
created_at date-time yes
error string | null no
finished_at date-time | null no
id string yes
kind string yes
message string | null no
owner_id string | null no
params object yes
progress number yes
result any no
started_at date-time | null no
status "queued" | "running" | "succeeded" | "failed" | "cancelled" yes

JobEvent

One data: payload of the job event stream.

Field Type Required Description
error string | null no
job_id string yes
message string | null no
progress number yes
reason "timeout" | "untracked" | null no
status "queued" | "running" | "succeeded" | "failed" | "cancelled" yes

JournalEntryView

One order: why it was placed, the signal context, the outcome and the notes people added.

Field Type Required Description
client_id string yes
context object | null yes
created_at string yes
decided_at string | null yes
decision_price number | null yes
next_session_move_bps number | null yes
notes list[JournalNoteView] yes
portfolio_id string | null yes
quantity number yes
shortfall ShortfallView | null yes
side string yes
status string yes
status_reason string | null yes
strategy_id string | null yes
ticker string yes
trigger string | null yes

JournalNoteView

Field Type Required Description
author string yes
created_at string yes
id integer yes
note string yes
order_client_id string yes
updated_at string yes

KillSwitchRequest

Field Type Required Description
flatten boolean no
portfolio_id string | null no
reason string yes
scope "global" | "user" | "portfolio" yes

LabRunRequest

Tunes the class the strategy ref points at (its params are ignored: the tuner searches the class's parameter space).

Field Type Required Description
benchmark string | null no
budget integer no
cost_model "zero" | "realistic" | CostModelSettings | null no
embargo_bars integer | null no
end date yes
ensure_data boolean no
grid_size integer no
hypothesis string | null no
interval string no
mcpt McptOptions | null no
objective "sharpe" | "cagr" | "final_return" | "cv_sharpe" | "cv_cagr" | "cv_final_return" no
preflight boolean | null no
premortem string | null no
preset "promotion" | "quick" | "standard" | null no
register_if_passes boolean no
register_strategy boolean no
seed integer no
start date yes
strategy StrategyRef yes
strict_preflight boolean | null no
survival_tests list["benchmark_relative" | "cost_stress" | "cpcv" | "crisis" | "cross_instrument" | "deflated_sharpe" | "drift" | "event_study" | "mc_trades" | "mcpt" | "oos" | "pbo" | "period_stability" | "permutation" | "perturbation" | "plateau" | "pool_correlation" | "runs_test" | "signal_ic" | "stress" | "vs_random" | "walk_forward" | "walk_forward_mcpt"] | null no
test_options dict[str, object] | null no
train_ratio number no
tuner "grid" | "random" no
universe list[string] no
universe_id string | null no
walk_forward WalkForwardConfig | null no

LabRunView

Field Type Required Description
benchmark BenchmarkStatsView | null no
best_params object yes
best_score number | null yes
class_path string yes
ensure_job_id string | null no
n_trials_class integer no
n_trials_run integer no
preflight PreflightView | null no
registered_strategy_id string | null yes
run_id string no
survival_reports list[SurvivalReportView] yes
verdict "pass" | "fail" yes

LinkAccountRequest

Field Type Required Description
external_account_id string yes
name string | null no
portfolio_id string | null no

LinkResultView

Field Type Required Description
connection_id string yes
external_account_id string yes
portfolio_id string yes

LiquiditySettings

Field Type Required Description
max_amihud number | null no
max_pct_adv number | null no
min_median_dollar_volume number | null no

LoginRequest

Field Type Required Description
email string yes
password string yes

LoginView

Field Type Required Description
csrf_token string yes
display_name string yes
next_step "enrol" | "verify" yes
user_id string yes

MarginCallSettings

Field Type Required Description
buffer number no
enabled boolean no
margin MarginSettings no

MarginRates

Requirement rates, as fractions of a position's market value.

Field Type Required Description
initial_long number no
initial_short number no
maintenance_long number no
maintenance_short number no

MarginSettings

Which margin model a book uses, and its rates.

Field Type Required Description
debit_rate_annual number no
model "cash" | "reg_t" no
overrides dict[str, MarginRates] no
rates MarginRates no

MarkReadRequest

Field Type Required Description
ids list[integer] | null no

MarkReadView

Field Type Required Description
unread_count integer yes
updated integer yes

MarketClockView

Field Type Required Description
is_open boolean yes
next_close date-time yes
next_open date-time yes
timestamp date-time yes

MarketSessionsView

Field Type Required Description
calendar string yes
is_open boolean yes
next SessionTimesView yes
today SessionTimesView | null yes

MaxHoldingSettings

Field Type Required Description
max_holding_bars integer | null no

McptOptions

Monte-Carlo permutation test settings (survival test permutation).

Field Type Required Description
max_p_value number no
metric "profit_factor" | "bar_profit_factor" | "sharpe" | "final_return" | "cagr" no
n_permutations integer no
retune boolean | "auto" no
seed integer | null no

MeView

Field Type Required Description
display_name string yes
email string | null yes
mfa_enrolled boolean yes
mfa_fresh boolean yes
role Role yes
scopes list[ApiScope] yes
user_id string yes
via "session" | "token" | "legacy" | "cli" | "scheduler" yes

MfaCodeRequest

Field Type Required Description
code string | null no
recovery_code string | null no

MfaView

Field Type Required Description
csrf_token string | null no
method "totp" | "recovery_code" yes
recovery_codes list[string] | null no
recovery_codes_left integer yes

NetExposureSettings

Field Type Required Description
max_net number | null no
min_net number | null no

NoteRequest

Field Type Required Description
note string yes

OperationalHaltSettings

Field Type Required Description
max_bar_age_days integer | null no

Opinion

Field Type Required Description
expected_return number | null yes
reason string yes
stance "agree" | "disagree" | "no_view" | "not_applicable" | "error" yes
strategy_id string yes

OrderView

Field Type Required Description
broker_order_id string | null yes
client_id string yes
created_at string yes
limit_price number | null yes
order_type string yes
quantity number yes
side string yes
status string yes
status_reason string | null no
strategy_id string | null yes
tick_id string | null yes
ticker string yes
updated_at string yes

Page_AlertView_

Field Type Required Description
items list[AlertView] yes
limit integer yes
offset integer yes
total integer yes

Page_BackupView_

Field Type Required Description
items list[BackupView] yes
limit integer yes
offset integer yes
total integer yes

Page_BrokerAccountView_

Field Type Required Description
items list[stonks__app__connections__BrokerAccountView] yes
limit integer yes
offset integer yes
total integer yes

Page_ConnectionView_

Field Type Required Description
items list[ConnectionView] yes
limit integer yes
offset integer yes
total integer yes

Page_CoverageRow_

Field Type Required Description
items list[CoverageRow] yes
limit integer yes
offset integer yes
total integer yes

Page_Draft_

Field Type Required Description
items list[Draft] yes
limit integer yes
offset integer yes
total integer yes

Page_FillView_

Field Type Required Description
items list[FillView] yes
limit integer yes
offset integer yes
total integer yes

Page_HaltView_

Field Type Required Description
items list[HaltView] yes
limit integer yes
offset integer yes
total integer yes

Page_IngestRunView_

Field Type Required Description
items list[IngestRunView] yes
limit integer yes
offset integer yes
total integer yes

Page_InstrumentView_

Field Type Required Description
items list[InstrumentView] yes
limit integer yes
offset integer yes
total integer yes

Page_Job_

Field Type Required Description
items list[Job] yes
limit integer yes
offset integer yes
total integer yes

Page_JournalEntryView_

Field Type Required Description
items list[JournalEntryView] yes
limit integer yes
offset integer yes
total integer yes

Page_OrderView_

Field Type Required Description
items list[OrderView] yes
limit integer yes
offset integer yes
total integer yes

Page_PortfolioSummaryView_

Field Type Required Description
items list[PortfolioSummaryView] yes
limit integer yes
offset integer yes
total integer yes

Page_PushDeviceView_

Field Type Required Description
items list[PushDeviceView] yes
limit integer yes
offset integer yes
total integer yes

Page_RiskSnapshotView_

Field Type Required Description
items list[RiskSnapshotView] yes
limit integer yes
offset integer yes
total integer yes

Page_ShadowDecisionView_

Field Type Required Description
items list[ShadowDecisionView] yes
limit integer yes
offset integer yes
total integer yes

Page_ShadowPnlSummary_

Field Type Required Description
items list[ShadowPnlSummary] yes
limit integer yes
offset integer yes
total integer yes

Page_SnapshotView_

Field Type Required Description
items list[SnapshotView] yes
limit integer yes
offset integer yes
total integer yes

Page_StatementFlagView_

Field Type Required Description
items list[StatementFlagView] yes
limit integer yes
offset integer yes
total integer yes

Page_StatusChangeView_

Field Type Required Description
items list[StatusChangeView] yes
limit integer yes
offset integer yes
total integer yes

Page_StrategySummary_

Field Type Required Description
items list[StrategySummary] yes
limit integer yes
offset integer yes
total integer yes

Page_SubscriptionView_

Field Type Required Description
items list[SubscriptionView] yes
limit integer yes
offset integer yes
total integer yes

Page_TickRun_

Field Type Required Description
items list[TickRun] yes
limit integer yes
offset integer yes
total integer yes

Page_TokenView_

Field Type Required Description
items list[TokenView] yes
limit integer yes
offset integer yes
total integer yes

Page_TradingModeView_

Field Type Required Description
items list[TradingModeView] yes
limit integer yes
offset integer yes
total integer yes

Page_UniverseView_

Field Type Required Description
items list[UniverseView] yes
limit integer yes
offset integer yes
total integer yes

Page_UserView_

Field Type Required Description
items list[UserView] yes
limit integer yes
offset integer yes
total integer yes

ParameterInfo

Field Type Required Description
bounds list[any] | null no
default any no
description string yes
kind string yes
name string yes
tunable boolean yes

PasswordChangeRequest

Field Type Required Description
current_password string yes
new_password string yes

PasswordResetRequest

Field Type Required Description
new_password string yes

PeriodPnl

Field Type Required Description
change number | null yes Value change, deposits and withdrawals included.
change_pct number | null yes change / start_value (0.05 = +5%).
end_day date yes
end_value number yes
period "1d" | "1w" | "1m" | "3m" | "ytd" | "1y" | "inception" yes
start_day date | null yes Day of the start value; null without history.
start_value number | null yes

PnlRowView

Field Type Required Description
cumulative_return number | null yes
daily_change number | null yes
daily_return number | null yes
day date yes
days_elapsed integer | null no
drawdown number yes
total_value number yes

PnlSeries

One row per day. strategy_id is None for the real portfolio and a shadow strategy's id for its virtual portfolio.

Field Type Required Description
rows list[PnlRowView] yes
strategy_id string | null yes

PortalLinkView

Field Type Required Description
connection_id string yes
expires_at date-time yes
url string yes

PortfolioSummaryView

Field Type Required Description
base_currency string yes
broker_connection_id string | null yes
created_at date-time yes
id string yes
initial_cash number | null yes
is_default boolean no
kind "simulated" | "broker" yes
name string yes
status "active" | "paused" | "archived" yes
trading "paper" | "live" yes

PortfolioSyncView

Field Type Required Description
activities_new integer yes
activities_seen integer yes
error string | null yes
external_account_id string yes
portfolio_id string yes
positions integer yes
snapshot_id integer | null yes
unmapped list[string] yes

PortfolioTotalsView

Sums over every active portfolio's latest snapshot, for admins. No tickers and no per-person numbers (decision 2026-09-26).

Field Type Required Description
cash number yes
owners integer yes People who own those portfolios.
portfolios integer yes Active portfolios with at least one snapshot.
total_value number yes Sum of each book's value at its latest snapshot.

PortfolioView

Field Type Required Description
cash number yes
cost_basis number no Sum of the positions' cost_basis (positions with a known cost).
currency string no Reporting currency: the currency every held instrument shares, else 'USD' (also for an empty book or unknown currencies). Amounts are not FX-converted.
positions list[PositionView] yes
positions_value number yes
snapshot_total_value number | null yes
taken_at date-time | null yes
tick_id string | null yes
total_value number yes
unrealized_pnl number no Sum of the positions' unrealized_pnl (priced, known cost).

PortfolioVolSettings

Field Type Required Description
shock_cap number | null no
vol_cap number | null no

PositionView

Field Type Required Description
avg_cost number | null no Average cost per share from the fill history (weighted average, fees included); null when the ledger has no fills for the position.
cost_basis number | null no avg_cost * quantity.
currency string | null no The instrument's trading currency; null when unknown.
market_value number | null yes
price number | null yes
price_date date | null yes
quantity number yes
ticker string yes
unrealized_pnl number | null no (price - avg_cost) * quantity at the latest stored close.
unrealized_pnl_pct number | null no unrealized_pnl / |cost_basis| (0.05 = +5%).
weight number | null yes

PreferenceItem

Field Type Required Description
category "signal" | "order" | "risk" | "system" yes
channel string yes
enabled boolean yes
strategy_id string | null no

PreferencesUpdate

Field Type Required Description
preferences list[PreferenceItem] yes

PreferencesView

Field Type Required Description
channel_defaults list[ChannelDefaultView] no
channels list[string] yes
preferences list[PreferenceItem] yes
quiet_end string | null yes
quiet_start string | null yes
timezone string yes
webhook string | null yes

PreflightIssueView

Field Type Required Description
code string yes
details object no
message string yes
severity "error" | "warning" yes

PreflightView

The BL-37 data preflight of a lab run. A run only starts with no errors, so a result carries warnings (and ok true).

Field Type Required Description
issues list[PreflightIssueView] yes
ok boolean yes
skipped boolean yes

ProbeView

Field Type Required Description
checks dict[str, string] no
status string yes

ProblemDetails

Field Type Required Description
blockers list[string] | null no
code string | null no
detail string | null no
errors list[object] | null no
failing_checks list[FailingCheck] | null no
instance string | null no
next_step string | null no
status integer yes
title string yes
type string no

PromotionChecklistView

What a reviewer reads before promoting; it doesn't change the verdict. None for anything not recorded.

Field Type Required Description
dsr number | null no
excess_cagr number | null no
hypothesis string | null no
n_trials_class integer | null no
pbo number | null no
premortem string | null no

ProviderView

Field Type Required Description
auth_flow string yes
can_trade boolean yes
capabilities list[string] yes
credential_fields list[string] yes
display_name string yes
enabled boolean yes
has_paper boolean yes
name string yes

PushDeviceView

A registered browser or installed app: no endpoint, no keys.

Field Type Required Description
created_at date-time yes
endpoint_host string yes
failure_count integer yes
id string yes
last_success_at date-time | null yes
user_agent string | null yes

PushKeys

Field Type Required Description
auth string yes
p256dh string yes

PushSubscriptionRequest

The browser's PushSubscription.toJSON() plus its user agent.

Field Type Required Description
endpoint string yes
expirationTime number | null no
keys PushKeys yes
user_agent string | null no

PushUnsubscribeRequest

Field Type Required Description
endpoint string yes

QuietHoursUpdate

Field Type Required Description
end string | null no
start string | null no

RecoveryCodesView

Field Type Required Description
recovery_codes list[string] yes

RestoreRequest

Field Type Required Description
confirmation string yes

RestoreResultView

Field Type Required Description
backup_id string yes
data_dir string yes
lake_migrations_applied list[integer] yes
next_steps list[string] yes
state_migrations_applied list[integer] yes

ResumeRequest

Field Type Required Description
confirmation string yes
reason string yes

RiskAdjustmentView

One order the risk policy clipped or dropped.

Field Type Required Description
adjusted_quantity number yes
original_quantity number yes
reason string yes
rule string yes
side string yes
ticker string yes

RiskPerPositionSettings

Field Type Required Description
atr_multiple number no
max_risk number | null no
max_var number | null no

RiskPolicy

Portfolio construction limits applied between strategy.decide and the broker ([production.risk]). Defaults are permissive, so an unconfigured install trades exactly what the strategy asks for.

Field Type Required Description
cash_buffer_fraction number no
enabled boolean no
max_open_positions integer | null no
max_weight_per_asset_class dict[str, number] no
max_weight_per_ticker number no
min_order_notional number no
rules RuleSettings no

RiskSnapshotView

One book on one day. Figures are fractions of value; a loss is positive. strategy_id is null for the whole portfolio.

Field Type Required Description
as_of date yes
decay_days integer | null yes
decay_reason string | null yes
decayed boolean yes
es_95 number | null yes
es_99 number | null yes
expected_ir number | null yes
exposures dict[str, number] yes
ir_long number | null yes
ir_short number | null yes
kupiec_p_95 number | null yes
kupiec_p_99 number | null yes
observations integer yes
pnl number | null yes
portfolio_id string yes
ratio_out_of_band boolean yes
realized_return number | null yes
sigma number | null yes
strategy_id string | null yes
tick_id string | null yes
value number yes
var_95 number | null yes
var_99 number | null yes
violation_95 boolean | null yes
violation_99 boolean | null yes
violation_ratio_95 number | null yes
violation_ratio_99 number | null yes
violations_95 integer yes
violations_99 integer yes
window_days integer yes

RiskStats

Field Type Required Description
current_drawdown number yes Latest value against its peak, <= 0.
expected_shortfall_95 number yes Mean return at or below var_95.
max_drawdown number yes Worst fall from a peak, <= 0.
observations integer yes Daily returns the numbers use.
var_95 number yes One-day historical value at risk, a return (loss < 0).
volatility number | null yes Annualized (252 days) standard deviation.

RiskSummaryView

Field Type Required Description
as_of date | null yes
portfolio RiskSnapshotView | null yes
portfolio_id string yes
strategies list[RiskSnapshotView] yes

RiskView

Field Type Required Description
concentration Concentration yes
history RiskStats | null yes From the portfolio's own daily values; null with under three days.
holdings RiskStats | null yes Today's weights applied to the last year of price returns; null without enough prices.
returns_as_of date | null yes Last price day behind holdings risk and beta.

Role

Type: "viewer" | "trader" | "admin"

RuleSettings

Field Type Required Description
borrow_check BorrowCheckSettings no
circuit_breaker CircuitBreakerSettings no
drawdown_scaling DrawdownScalingSettings no
gross_exposure GrossExposureSettings no
liquidity LiquiditySettings no
margin_call MarginCallSettings no
max_holding MaxHoldingSettings no
net_exposure NetExposureSettings no
operational_halt OperationalHaltSettings no
portfolio_vol PortfolioVolSettings no
risk_per_position RiskPerPositionSettings no
sector_cap SectorCapSettings no
short_caps ShortCapsSettings no
squeeze_guard SqueezeGuardSettings no

RuleTemplateView

Field Type Required Description
description string yes
id string yes
spec object yes
title string yes

RunNowRequest

Field Type Required Description
as_of date | null no

RunNowView

Field Type Required Description
as_of date yes
job string yes
run_key string yes
status string no

ScheduleView

Field Type Required Description
backend string yes
hosted boolean yes
jobs list[ScheduledJobView] yes
market MarketSessionsView | null no
recent list[ScheduledRunView] yes

ScheduledJobView

Field Type Required Description
action string yes
name string yes
next_as_of date | null yes
next_run_at date-time | null yes
trigger string yes
trigger_text string no

ScheduledRunView

Field Type Required Description
action string yes
as_of string | null yes
catch_up boolean yes
detail object | null yes
error string | null yes
finished_at date-time | null yes
id string yes
job_name string yes
run_key string yes
scheduled_for date-time yes
started_at date-time yes
status string yes

SectorCapSettings

Field Type Required Description
max_weight_per_sector number | null no

SessionTimesView

Field Type Required Description
close date-time yes
date date yes
open date-time yes
pre_open date-time yes

ShadowDecisionView

Field Type Required Description
as_of date yes
created_at date-time yes
id integer yes
price number | null yes
quantity number yes
side string yes
status string yes
strategy_id string yes
tick_id string yes
ticker string yes

ShadowOutcomeView

How one shadow strategy was evaluated during the tick.

Field Type Required Description
decisions integer no
error string | null no
fills integer no
status string yes
strategy_id string yes
total_value number | null no

ShadowPnlSummary

Field Type Required Description
cumulative_return number | null yes
days integer yes
first_day date | null yes
latest_day date | null yes
max_drawdown number | null yes
status string | null yes
strategy_id string yes
total_value number | null yes

ShortCapsSettings

Field Type Required Description
max_short_total number | null no
max_short_weight number | null no

ShortfallView

Implementation shortfall of one order. Costs are positive, in bps of the filled quantity's value at the decision price; null while an input is not known yet.

Field Type Required Description
arrival_price number | null yes
benchmark_price number | null yes
convention_bps number | null yes
decision_price number yes
delay_bps number | null yes
expected_bps number | null yes
fee_bps number | null yes
fill_price number | null yes
filled_quantity number yes
impact_bps number | null yes
is_bps number | null yes
is_cost number | null yes
opportunity_bps number | null yes
opportunity_cost number | null yes
ordered_quantity number yes
post_close_price number | null yes
side string yes
total_bps number | null yes

SignalICRequest

Field Type Required Description
end date yes
every_bars integer no
horizons list[integer] no
interval string no
min_names integer no
n_quantiles integer no
start date yes
strategy StrategyRef yes
universe list[string] yes

SignalICView

:class:stonks.lab.signal_eval.SignalICResult; NaN is null.

Field Type Required Description
every_bars integer yes
horizons list[HorizonICView] no
ic_estimate number | null no
ic_horizon integer | null no
n_dates integer yes
n_quantiles integer yes
n_tickers integer yes
note string no
score_turnover number | null no
status string yes
strategy_id string yes
top_quantile_turnover number | null no
window list[any] yes

SmokeCheck

Field Type Required Description
data "lake" | "sample" yes
errors list[string] yes
evaluations integer yes
ok boolean yes
signals integer yes
tickers list[string] yes

SnapshotView

Field Type Required Description
cash number yes
id integer yes
positions dict[str, number] yes
taken_at date-time yes
tick_id string | null yes
total_value number yes

SpecValidateRequest

Field Type Required Description
spec object yes

SqueezeGuardSettings

Field Type Required Description
atr_multiple number | null no
borrow BorrowSettings | null no
max_adverse_pct number | null no
max_borrow_fee number | null no
spike_bars integer no
spike_pct number | null no

StartPortalRequest

Field Type Required Description
connection_id string | null no
label string | null no
provider string yes
redirect_uri string yes

StatementFlagView

Field Type Required Description
check_id string yes
detail string yes
flagged_at date-time yes
frequency string yes
period_end date yes
severity "error" | "warning" yes
ticker string yes

StatusChangeRequest

Body of a status-change route (promote / retire / shadow, Studio enable / disable). Demotions need reason; a promotion without a passing go-live check needs override plus a reason of at least 20 characters.

Field Type Required Description
actor string | null no
override boolean no
reason string | null no

StatusChangeView

One audited status change or intervention (BL-24).

Field Type Required Description
actor string yes
created_at string yes
from_status string | null yes
golive_passed boolean | null yes
golive_report object | null yes
id integer yes
kind string yes
override boolean yes
reason string yes
to_status string | null yes

StrategyClassInfo

Field Type Required Description
applicable_asset_classes list[string] yes
class_path string yes
description string yes
name string yes
parameters list[ParameterInfo] yes
source string yes

StrategyDetail

Field Type Required Description
applicable_asset_classes list[string] yes
class_path string yes
created_at string yes
id string yes
metadata StrategyMetadataView yes
params object yes
status "active" | "shadow" | "retired" yes
status_history list[StatusChangeView] yes
survival_reports list[SurvivalReportView] yes
updated_at string yes

StrategyMetadataView

The strategy's hypothesis card and capability hooks (BL-26).

Field Type Required Description
alpha_family "trend" | "reversion" | "carry" | "value" | "quality" | "growth" | "sentiment" | "data_driven" | "benchmark" | "other" yes
hypothesis string yes
label_horizon_bars integer yes
premise "trend" | "mean_reversion" | "none" yes
required_history_bars integer yes

StrategyRef

Which strategy to run: a registered id, or a catalog class + params.

Field Type Required Description
class_path string | null no
params object no
strategy_id string | null no

StrategyStatusCounts

How many registered strategies are in each lifecycle status.

Field Type Required Description
active integer yes
retired integer yes
shadow integer yes
total integer yes

StrategySummary

Field Type Required Description
applicable_asset_classes list[string] yes
class_path string yes
created_at string yes
id string yes
metadata StrategyMetadataView yes
params object yes
status "active" | "shadow" | "retired" yes
updated_at string yes

StreamToken

Field Type Required Description
events_url string yes
expires_at date-time yes
token string yes

StudioCapabilities

What this server lets the Studio do.

Field Type Required Description
code_strategies boolean yes

SubscribeRequest

Field Type Required Description
mode "notify" | "paper" | "auto" no
portfolio_id string | null no
strategy_id string yes
weight number no

SubscriptionUpdate

Field Type Required Description
enabled boolean | null no
mode "notify" | "paper" | "auto" | null no
reason string | null no

SubscriptionView

Field Type Required Description
auto_blockers list[string] yes
auto_enabled_at date-time | null yes
created_at date-time yes
enabled boolean yes
id string yes
mode "notify" | "paper" | "auto" yes
paper_days_completed integer yes
paper_days_required integer yes
paused_reason string | null yes
portfolio_id string | null yes
strategy_id string yes
strategy_status string | null yes
updated_at date-time yes
weight number yes

SurvivalPresetInfo

Field Type Required Description
name string yes
options dict[str, object] yes
tests list[string] yes

SurvivalReportView

Field Type Required Description
metrics dict[str, number | null] yes
notes string yes
passed boolean yes
test_id string yes

SurvivalTestInfo

A survival test and the options a request's test_options[id] may set, as JSON Schema from the backend's own options model.

Field Type Required Description
config_schema object | null no
description string yes
id string yes
options_schema object yes
presets list[string] yes

SweepRequest

A sweep over a basket: universe (tickers) or universe_id (every member during the window). strategies default to every catalogued non-wrapper strategy. The lab options apply to every run; sweeps never register strategies.

Field Type Required Description
benchmark string | null no
budget integer no
cost_model "zero" | "realistic" | CostModelSettings | null no
embargo_bars integer | null no
end date yes
exclude list[string] no
grid_size integer no
hypothesis string | null no
interval string no
mcpt McptOptions | null no
objective "sharpe" | "cagr" | "final_return" | "cv_sharpe" | "cv_cagr" | "cv_final_return" no
preflight boolean | null no
premortem string | null no
preset "promotion" | "quick" | "standard" | null no
register_if_passes boolean no
register_strategy boolean no
seed integer no
start date yes
strategies list[string] | null no
strict_preflight boolean | null no
survival_tests list["benchmark_relative" | "cost_stress" | "cpcv" | "crisis" | "cross_instrument" | "deflated_sharpe" | "drift" | "event_study" | "mc_trades" | "mcpt" | "oos" | "pbo" | "period_stability" | "permutation" | "perturbation" | "plateau" | "pool_correlation" | "runs_test" | "signal_ic" | "stress" | "vs_random" | "walk_forward" | "walk_forward_mcpt"] | null no
test_options dict[str, object] | null no
train_ratio number no
tuner "grid" | "random" no
universe list[string] no
universe_id string | null no
walk_forward WalkForwardConfig | null no

SweepResultView

Field Type Required Description
errors integer yes
failed integer yes
passed integer yes
rows list[SweepRowView] yes
universe list[string] yes
universe_id string | null no

SweepRowView

Field Type Required Description
best_params object no
best_score number | null no
error string | null no
n_trials integer no
run_id string no
strategy string yes
survival dict[str, object] no
ticker string | null yes
verdict "pass" | "fail" | "error" yes

SyncResultView

Field Type Required Description
accounts_seen integer yes
connection_id string yes
error string | null yes
next_sync_at date-time | null yes
portfolios list[PortfolioSyncView] yes
status "ok" | "partial" | "error" yes

TcaGroupView

Costs of a group of orders, weighted by notional, in bps.

Field Type Required Description
convention_bps number | null yes
delay_bps number | null yes
expected_bps number | null yes
fee_bps number | null yes
filled_notional number yes
filled_orders integer yes
impact_bps number | null yes
is_bps number | null yes
is_cost number yes
key string yes
model_gap_bps number | null yes
opportunity_bps number | null yes
opportunity_cost number yes
orders integer yes

TcaSummaryView

Field Type Required Description
by "all" | "strategy" | "ticker" | "portfolio" | "day" | "week" | "month" yes
groups list[TcaGroupView] yes
portfolio_id string yes
since date | null yes
until date | null yes

TickRequest

Field Type Required Description
as_of date | null no
asset_class "equity" | "crypto" | "commodity" | "bond" | null no
bars_due_at date-time | null no Buy only tickers whose latest session that closed by this time has its daily bar in the lake (scheduled ticks send their fire time). Tickers whose bar is missing are marked and sellable, not buyable.
dry_run boolean no
scoped boolean | null no Trade only the tick's tickers and leave other holdings alone, not even selling them. Default: true when tickers or asset_class narrow the universe.
tickers list[string] | null no

TickResultView

Field Type Required Description
dry_run boolean yes
fills integer yes
orders_placed integer yes
status string yes
tick_id string yes
winner_strategy_id string | null yes

TickRun

Field Type Required Description
as_of date | null no The trading date the tick ran for (null for rows that predate it).
finished_at date-time | null yes
id string yes
started_at date-time yes
status "running" | "ok" | "partial" | "error" yes
summary TickSummary | null yes

TickRunWithOrders

Field Type Required Description
as_of date | null no The trading date the tick ran for (null for rows that predate it).
finished_at date-time | null yes
id string yes
orders list[OrderView] yes
started_at date-time yes
status "running" | "ok" | "partial" | "error" yes
summary TickSummary | null yes

TickSummary

Field Type Required Description
deferred_corporate_actions list[object] no
error string | null no
error_type string | null no
exit_strategy_id string | null no
fills integer | null no
orders_placed integer | null no
outside_universe_skipped list[string] no
portfolio_id string | null no
reason string | null no
risk_adjustments list[RiskAdjustmentView] no
shadow list[ShadowOutcomeView] no
shadow_error string | null no
stale_buys_dropped list[string] no
winner_expected_return number | null no
winner_strategy_id string | null no

TokenCreateRequest

Field Type Required Description
expires_in_days integer | null no
name string yes
scopes list[ApiScope] yes

TokenCreatedView

Field Type Required Description
info TokenView yes
token string yes

TokenView

Field Type Required Description
created_at string yes
expires_at string | null yes
id string yes
last_used_at string | null yes
name string yes
revoked_at string | null yes
scopes list[ApiScope] yes

TradeStatsView

Trade-level statistics of a backtest (backtest.trades.TradeStats). Win/loss figures are over closed round trips; None marks an unbounded ratio (no losing trades).

Field Type Required Description
avg_bars_held number | null yes
avg_loss number | null yes
avg_win number | null yes
cost_drag_annual number | null yes
costs_paid number | null yes
expectancy number | null yes
exposure number | null yes
n_open integer yes
n_trades integer yes
payoff_ratio number | null yes
trade_profit_factor number | null yes
turnover_annual number | null yes
win_rate number | null yes

TradeView

One round trip (a lot, or part of one, from buy to sell or to the end).

Field Type Required Description
bars_held integer yes
entry_px number yes
entry_ts date-time yes
exit_px number yes
exit_ts date-time yes
fees number yes
is_open boolean yes
pnl number yes
qty number yes
return_pct number | null yes
ticker string yes

TradingModeView

Whether a portfolio trades paper or live money, and through what.

Field Type Required Description
broker "simulated" | "alpaca" | "connection" yes simulated (the Stonks ledger), alpaca (the configured account, default portfolio only) or connection (a linked broker account, synced read-only).
detail string yes
name string yes
portfolio_id string yes
trading "paper" | "live" yes paper: simulated fills or a paper broker account. live: real money.

UniverseCreate

Field Type Required Description
csv string | null no
description string | null no
id string yes
kind "list" | "exchange" | "rule" | "index" yes
name string | null no
spec object no

UniverseMembers

Field Type Required Description
as_of date yes
count integer yes
tickers list[string] yes
universe_id string yes

UniverseRefreshView

Field Type Required Description
current_members integer yes
kind string yes
members integer yes
refreshed_at date-time | null no
spans integer yes
universe_id string yes
warnings list[string] no

UniverseView

Field Type Required Description
created_at date-time | null no
description string | null no
id string yes
kind "list" | "exchange" | "rule" | "index" yes
member_count integer | null no
name string | null no
refreshed_at date-time | null no
spec object yes
updated_at date-time | null no

UserCreateRequest

Field Type Required Description
display_name string yes
email string yes
password string yes
role Role yes

UserUpdateRequest

Field Type Required Description
role Role | null no
status "active" | "disabled" | null no

UserView

Identity and status only. Admins never see holdings here.

Field Type Required Description
created_at string yes
display_name string yes
email string | null yes
id string yes
last_login_at string | null yes
mfa_enrolled boolean yes
role Role yes
status "active" | "disabled" yes

ValidateRequest

Smoke-run on these lake tickers (sample data when empty), over the last bars bars up to as_of (latest data when omitted).

Field Type Required Description
as_of date | null no
bars integer no
tickers list[string] no

ValidationIssue

Field Type Required Description
message string yes
path string yes

VapidKeyView

Field Type Required Description
public_key string | null yes

VerifyView

Field Type Required Description
backup_id string yes
ok boolean yes
problems list[string] yes

WalkForwardConfig

Walk-forward settings. test_days=None splits the dataset's validation window evenly over the folds; train_days=None means "everything before the first test window".

Field Type Required Description
anchored boolean no
matrix boolean no
matrix_min_pass_share number no
matrix_test_bars list[integer] no
matrix_train_bars list[integer] no
max_workers integer | null no
metric "sharpe" | "cagr" | "final_return" no
min_mean_score number no
min_positive_share number no
min_wfe number | null no
n_splits integer no
seed integer | null no
test_days integer | null no
train_days integer | null no

WebhookUpdate

Your own webhook (a public https URL). Write-only: responses show its scheme and host only. Null removes it.

Field Type Required Description
url password | null no

stonks__app__brokers__BrokerAccountView

Field Type Required Description
buying_power number yes
can_trade boolean yes
cash number yes
currency string yes
equity number yes
pattern_day_trader boolean yes
status string yes
trading_blocked boolean yes

stonks__app__connections__BrokerAccountView

Field Type Required Description
connection_id string yes
currency string yes
external_account_id string yes
institution string | null yes
name string yes
number_mask string | null yes
portfolio_id string | null yes

Clone this wiki locally