Repository navigation
API Reference
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")]
Auth: reads (GET) are open to loopback clients by default
([api].open_reads_on_loopback). Every other method needs
Authorization: Bearer $STONKS_API_TOKEN.
Tags: alerts · auth · brokers · catalog · health · ingest · jobs · lab · market · orders · pnl · portfolio · risk · shadow · sources · strategies · studio · ticks
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/alerts |
List Alerts | token, or open on loopback | Page_AlertView_ |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/auth/check |
Check Auth | token, or open on loopback | AuthCheck |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/brokers |
Get Broker Info | token, or open on loopback | BrokerInfo | |
| GET | /api/brokers/alpaca/status |
Get Alpaca Status | token, or open on loopback | AlpacaStatus |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/catalog/asset-classes |
List Asset Classes | token, or open on loopback | list[string] | |
| GET | /api/catalog/intervals |
List Intervals | token, or open on loopback | list[IntervalInfo] | |
| GET | /api/catalog/strategies |
List Strategy Classes | token, or open on loopback | list[StrategyClassInfo] |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/health |
Liveness probe | none | Health | |
| GET | /api/health/report |
Health Report | token, or open on loopback | HealthReportView |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/ingest/jobs/{job_id}/result |
Get Ingest Result | token, or open on loopback | IngestResultView | |
| GET | /api/ingest/runs |
List Runs | token, or open on loopback | Page_IngestRunView_ | |
| POST | /api/ingest/runs |
Start Ingest | bearer token | IngestRequest | Job |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/jobs |
List Jobs | token, or open on loopback | Page_Job_ | |
| GET | /api/jobs/{job_id} |
Get Job | token, or open on loopback | Job | |
| POST | /api/jobs/{job_id}/cancel |
Cancel Job | bearer token | Job | |
| GET | /api/jobs/{job_id}/events |
Stream Job Events | token, or open on loopback | SSE of JobEvent | |
| POST | /api/jobs/{job_id}/stream-token |
Create Stream Token | bearer token | StreamToken |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| POST | /api/lab/backtests |
Start Backtest | bearer token | BacktestRequest | Job |
| GET | /api/lab/backtests/{job_id}/result |
Get Backtest Result | token, or open on loopback | BacktestResult | |
| GET | /api/lab/cost-models |
List Cost Models | token, or open on loopback | list[CostModelPreset] | |
| POST | /api/lab/runs |
Start Lab Run | bearer token | LabRunRequest | Job |
| GET | /api/lab/runs/{job_id}/result |
Get Lab Run Result | token, or open on loopback | LabRunView |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/market/bars |
Get Bars | token, or open on loopback | BarSeries | |
| GET | /api/market/coverage |
List Coverage | token, or open on loopback | Page_CoverageRow_ | |
| GET | /api/market/instruments |
List Instruments | token, or open on loopback | Page_InstrumentView_ |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/orders |
List Orders | token, or open on loopback | Page_OrderView_ | |
| GET | /api/orders/fills |
List Fills | token, or open on loopback | Page_FillView_ |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/pnl |
Get Pnl | token, or open on loopback | PnlSeries |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/portfolio |
Get Portfolio | token, or open on loopback | PortfolioView | |
| GET | /api/portfolio/snapshots |
List Snapshots | token, or open on loopback | Page_SnapshotView_ |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/risk/policy |
Get Risk Policy | token, or open on loopback | RiskPolicy |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/shadow/decisions |
List Shadow Decisions | token, or open on loopback | Page_ShadowDecisionView_ | |
| GET | /api/shadow/pnl |
List Shadow Pnl | token, or open on loopback | Page_ShadowPnlSummary_ | |
| GET | /api/shadow/strategies/{strategy_id}/pnl |
Get Shadow Pnl | token, or open on loopback | PnlSeries |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/sources |
List Sources | token, or open on loopback | list[DataSourceInfo] |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/strategies |
List Strategies | token, or open on loopback | Page_StrategySummary_ | |
| GET | /api/strategies/summary |
Strategy Summary | token, or open on loopback | StrategyStatusCounts | |
| GET | /api/strategies/{strategy_id} |
Get Strategy | token, or open on loopback | StrategyDetail | |
| GET | /api/strategies/{strategy_id}/golive |
Get Golive | token, or open on loopback | GoLiveReport | |
| GET | /api/strategies/{strategy_id}/history |
Get Strategy History | token, or open on loopback | list[StatusChangeView] | |
| POST | /api/strategies/{strategy_id}/promote |
Promote | bearer token | StatusChangeRequest | null | StrategyDetail |
| POST | /api/strategies/{strategy_id}/retire |
Retire | bearer token | StatusChangeRequest | null | StrategyDetail |
| POST | /api/strategies/{strategy_id}/shadow |
Shadow | bearer token | StatusChangeRequest | null | StrategyDetail |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/studio/capabilities |
Capabilities | token, or open on loopback | StudioCapabilities | |
| GET | /api/studio/drafts |
List Drafts | token, or open on loopback | Page_Draft_ | |
| POST | /api/studio/drafts |
Create Draft | bearer token | DraftCreate | Draft |
| GET | /api/studio/drafts/{draft_id} |
Get Draft | token, or open on loopback | Draft | |
| PATCH | /api/studio/drafts/{draft_id} |
Update Draft | bearer token | DraftUpdate | Draft |
| DELETE | /api/studio/drafts/{draft_id} |
Delete Draft | bearer token | Draft | |
| POST | /api/studio/drafts/{draft_id}/backtests |
Start Backtest | bearer token | DraftBacktestRequest | Job |
| POST | /api/studio/drafts/{draft_id}/disable |
Disable Draft | bearer token | StatusChangeRequest | null | Draft |
| POST | /api/studio/drafts/{draft_id}/enable |
Enable Draft | bearer token | StatusChangeRequest | null | Draft |
| POST | /api/studio/drafts/{draft_id}/lab-runs |
Start Lab Run | bearer token | DraftLabRunRequest | Job |
| POST | /api/studio/drafts/{draft_id}/register |
Register Draft | bearer token | Draft | |
| POST | /api/studio/drafts/{draft_id}/validate |
Validate Draft | bearer token | ValidateRequest | null | DraftValidation |
| GET | /api/studio/schema |
Schema | token, or open on loopback | object | |
| POST | /api/studio/spec/validate |
Validate Spec | bearer token | SpecValidateRequest | DraftValidation |
| GET | /api/studio/templates |
Templates | token, or open on loopback | list[RuleTemplateView] |
| Method | Path | Summary | Auth | Request | Response |
|---|---|---|---|---|---|
| GET | /api/ticks |
List Ticks | token, or open on loopback | Page_TickRun_ | |
| POST | /api/ticks |
Start Tick | bearer token | TickRequest | Job |
| GET | /api/ticks/jobs/{job_id}/result |
Get Tick Result | token, or open on loopback | TickResultView | |
| GET | /api/ticks/{tick_id} |
Get Tick | token, or open on loopback | TickRunWithOrders |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
account |
BrokerAccountView | null | no | |
clock |
MarketClockView | null | no | |
connected |
boolean | yes | |
error |
string | null | no | |
paper |
boolean | yes |
Fee and spread for one asset class.
| Field | Type | Required | Description |
|---|---|---|---|
fee_bps |
number | no | |
fee_flat |
number | no | |
half_spread_bps |
number | no |
| Field | Type | Required | Description |
|---|---|---|---|
authenticated |
true | no |
| 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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
bars |
list[BarView] | yes | |
interval |
string | yes | |
ticker |
string | yes | |
truncated |
boolean | yes |
| 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 |
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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
allow_live |
boolean | yes | |
credentials_configured |
boolean | yes | |
kind |
"simulated" | "alpaca" | yes | |
paper |
boolean | yes |
| Field | Type | Required | Description |
|---|---|---|---|
description |
string | yes | |
name |
"zero" | "realistic" | yes | |
settings |
CostModelSettings | yes |
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 |
| Field | Type | Required | Description |
|---|---|---|---|
first_bar |
date-time | yes | |
interval |
string | yes | |
last_bar |
date-time | yes | |
rows |
integer | yes | |
ticker |
string | yes |
| Field | Type | Required | Description |
|---|---|---|---|
configured |
boolean | yes | |
default |
boolean | yes | |
detail |
string | null | no | |
id |
"eodhd" | "yahoo" | "defillama" | yes |
| Field | Type | Required | Description |
|---|---|---|---|
created_at |
string | yes | |
id |
string | yes | |
kind |
"rule" | "code" | yes | |
name |
string | yes | |
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 |
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 |
| Field | Type | Required | Description |
|---|---|---|---|
kind |
"rule" | "code" | no | |
name |
string | yes | |
source_code |
string | null | no | |
spec |
object | no |
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" | 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 | |
survival_tests |
list["benchmark_relative" | "cost_stress" | "cross_instrument" | "deflated_sharpe" | "drift" | "event_study" | "mc_trades" | "mcpt" | "oos" | "pbo" | "period_stability" | "permutation" | "perturbation" | "plateau" | "runs_test" | "signal_ic" | "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 |
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | null | no | |
source_code |
string | null | no | |
spec |
object | null | no |
| Field | Type | Required | Description |
|---|---|---|---|
issues |
list[ValidationIssue] | yes | |
smoke |
SmokeCheck | null | no | |
valid |
boolean | yes |
| Field | Type | Required | Description |
|---|---|---|---|
timestamp |
date-time | yes | |
value |
number | yes |
| 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 |
| 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 |
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 |
| Field | Type | Required | Description |
|---|---|---|---|
checklist |
PromotionChecklistView | no | |
checks |
list[GoLiveCheckView] | yes | |
passed |
boolean | yes | |
policy |
GoLivePolicy | yes | |
source |
"shadow" | "portfolio" | "none" | yes | |
status |
string | yes | |
strategy_id |
string | yes |
| Field | Type | Required | Description |
|---|---|---|---|
status |
string | yes | |
version |
string | yes |
| Field | Type | Required | Description |
|---|---|---|---|
detail |
string | yes | |
name |
string | yes | |
ok |
boolean | yes |
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 |
| Field | Type | Required | Description |
|---|---|---|---|
checked_at |
date-time | yes | |
checks |
list[HealthCheckView] | yes | |
healthy |
boolean | yes | |
thresholds |
HealthConfig | yes |
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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
kind |
string | yes | |
run_id |
integer | yes | |
status |
string | yes | |
tickers_failed |
integer | yes | |
tickers_ok |
integer | yes |
| 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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes | |
is_intraday |
boolean | yes | |
seconds |
integer | yes |
| 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 | |
params |
object | yes | |
progress |
number | yes | |
result |
any | no | |
started_at |
date-time | null | no | |
status |
"queued" | "running" | "succeeded" | "failed" | "cancelled" | yes |
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 |
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 | |
grid_size |
integer | no | |
hypothesis |
string | null | no | |
interval |
string | no | |
mcpt |
McptOptions | null | no | |
objective |
"sharpe" | "cagr" | "final_return" | 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 | |
survival_tests |
list["benchmark_relative" | "cost_stress" | "cross_instrument" | "deflated_sharpe" | "drift" | "event_study" | "mc_trades" | "mcpt" | "oos" | "pbo" | "period_stability" | "permutation" | "perturbation" | "plateau" | "runs_test" | "signal_ic" | "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 |
| Field | Type | Required | Description |
|---|---|---|---|
benchmark |
BenchmarkStatsView | null | no | |
best_params |
object | yes | |
best_score |
number | null | yes | |
class_path |
string | yes | |
n_trials_class |
integer | no | |
n_trials_run |
integer | no | |
registered_strategy_id |
string | null | yes | |
run_id |
string | no | |
survival_reports |
list[SurvivalReportView] | yes | |
verdict |
"pass" | "fail" | yes |
| Field | Type | Required | Description |
|---|---|---|---|
is_open |
boolean | yes | |
next_close |
date-time | yes | |
next_open |
date-time | yes | |
timestamp |
date-time | yes |
Monte-Carlo permutation test settings (survival test permutation).
| Field | Type | Required | Description |
|---|---|---|---|
max_p_value |
number | no | |
metric |
"profit_factor" | "sharpe" | "final_return" | "cagr" | no | |
n_permutations |
integer | no | |
retune |
boolean | "auto" | no | |
seed |
integer | null | no |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[AlertView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[CoverageRow] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[Draft] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[FillView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[IngestRunView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[InstrumentView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[Job] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[OrderView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[ShadowDecisionView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[ShadowPnlSummary] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[SnapshotView] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[StrategySummary] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
items |
list[TickRun] | yes | |
limit |
integer | yes | |
offset |
integer | yes | |
total |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
bounds |
list[any] | null | no | |
default |
any | no | |
description |
string | yes | |
kind |
string | yes | |
name |
string | yes | |
tunable |
boolean | yes |
| 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 |
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 |
| 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). |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
detail |
string | null | no | |
errors |
list[object] | null | no | |
instance |
string | null | no | |
status |
integer | yes | |
title |
string | yes | |
type |
string | no |
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 |
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 |
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 |
| Field | Type | Required | Description |
|---|---|---|---|
description |
string | yes | |
id |
string | yes | |
spec |
object | yes | |
title |
string | yes |
| 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 |
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 |
| 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 |
| 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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
spec |
object | yes |
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 |
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 |
| 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 |
| 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 |
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 |
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 |
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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
events_url |
string | yes | |
expires_at |
date-time | yes | |
token |
string | yes |
What this server lets the Studio do.
| Field | Type | Required | Description |
|---|---|---|---|
code_strategies |
boolean | yes |
| Field | Type | Required | Description |
|---|---|---|---|
metrics |
dict[str, number | null] | yes | |
notes |
string | yes | |
passed |
boolean | yes | |
test_id |
string | yes |
| Field | Type | Required | Description |
|---|---|---|---|
as_of |
date | null | no | |
asset_class |
"equity" | "crypto" | "commodity" | "bond" | null | no | |
dry_run |
boolean | no | |
tickers |
list[string] | null | no |
| 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 |
| 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 |
| 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 |
| Field | Type | Required | Description |
|---|---|---|---|
error |
string | null | no | |
error_type |
string | null | no | |
exit_strategy_id |
string | null | no | |
fills |
integer | null | no | |
orders_placed |
integer | 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 |
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 |
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 |
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 |
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes | |
path |
string | yes |
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 |
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