Skip to content

MCP Tools

github-actions[bot] edited this page Oct 12, 2026 · 11 revisions

MCP tools

Tools exposed by stonks mcp (server stonks). Setup and the safety model: docs/mcp.md.

Tool Kind Needs confirm
add_journal_note job no
backtest_draft job no
cancel_job job no
cancel_order guarded yes
change_order guarded yes
check_factor_expression read no
check_model_swap read no
compare_tickers read no
confirm_rebalance guarded yes
create_draft job no
create_price_alert job no
create_screen job no
create_universe guarded yes
create_watchlist job no
delete_draft guarded yes
delete_price_alert guarded yes
delete_screen guarded yes
delete_screen_alert guarded yes
delete_universe guarded yes
disable_draft guarded yes
draft_order job no
edit_journal_note job no
enable_draft guarded yes
engage_kill_switch guarded yes
ensure_universe_data guarded yes
get_api_health read no
get_bars read no
get_behaviour_report read no
get_broker read no
get_broker_gateways read no
get_calendar read no
get_catalog read no
get_chart read no
get_connection_accounts read no
get_coverage read no
get_draft read no
get_earnings_warnings read no
get_execution_algo_settings read no
get_factor read no
get_factor_values read no
get_fx_rate read no
get_golive_report read no
get_health_report read no
get_insights read no
get_insights_totals read no
get_job read no
get_journal_breakdown read no
get_leaderboard read no
get_ledger_run read no
get_live_allocation read no
get_live_gate_report read no
get_live_margin read no
get_live_risk read no
get_live_rules read no
get_live_stage read no
get_look_through read no
get_market_breadth read no
get_model_calibration read no
get_model_version_history read no
get_my_risk_limits read no
get_news read no
get_notification_preferences read no
get_option_chain read no
get_option_payoff read no
get_options_live read no
get_order_tca read no
get_pnl read no
get_pnl_calendar read no
get_portfolio read no
get_portfolio_totals read no
get_price_check read no
get_reconcile_report read no
get_research_session read no
get_risk_policy read no
get_round_trip read no
get_rule_schema read no
get_schedule read no
get_screen read no
get_shadow_pnl read no
get_strategy read no
get_strategy_agreement read no
get_strategy_history read no
get_stream_status read no
get_studio_capabilities read no
get_tax_settings read no
get_tax_year read no
get_tca_summary read no
get_tear_sheet read no
get_tick read no
get_ticket read no
get_universe read no
get_universe_history read no
get_universe_members read no
get_watchlist read no
health read no
import_index_history guarded yes
lab_run_draft guarded yes
list_alerts read no
list_algo_parents read no
list_cash_flows read no
list_connections read no
list_cost_models read no
list_drafts read no
list_event_alert_kinds read no
list_execution_algos read no
list_factors read no
list_fills read no
list_halts read no
list_ingest_runs read no
list_intraday_snapshots read no
list_jobs read no
list_lab_objectives read no
list_lab_tuners read no
list_ledger_runs read no
list_model_candidates read no
list_model_versions read no
list_notifications read no
list_option_strategies read no
list_option_structures read no
list_option_underlyings read no
list_order_drafts read no
list_orders read no
list_playbooks read no
list_portfolio_snapshots read no
list_portfolios read no
list_price_alert_events read no
list_price_alerts read no
list_reconcile_reports read no
list_research_sessions read no
list_risk_snapshots read no
list_round_trips read no
list_screen_alert_events read no
list_screen_alerts read no
list_screen_metrics read no
list_screens read no
list_shadow_decisions read no
list_shadow_pnl read no
list_sources read no
list_statement_flags read no
list_strategies read no
list_studio_templates read no
list_subscriptions read no
list_survival_presets read no
list_survival_tests read no
list_tax_lot_picks read no
list_tickets read no
list_ticks read no
list_trade_decisions read no
list_trade_journal read no
list_trading_modes read no
list_universe_exchanges read no
list_universes read no
list_watchlists read no
live_risk read no
mark_notifications_read job no
order_tca read no
place_order guarded yes
plan_rebalance read no
preview_trade_tax read no
promote_strategy guarded yes
refresh_universe guarded yes
register_draft guarded yes
reject_model_version guarded yes
retire_strategy guarded yes
retrain_models guarded yes
risk_snapshots read no
run_backtest job no
run_draft_backtest job no
run_draft_lab guarded yes
run_factor_tearsheet job no
run_ingest job no
run_lab guarded yes
run_options_backtest job no
run_screen read no
run_signal_ic job no
run_sweep job no
run_tick guarded yes
save_screen_as_universe guarded yes
search_instruments read no
set_event_alerts guarded yes
set_execution_algo guarded yes
set_screen_alert job no
shadow_strategy guarded yes
start_research job no
subscribe guarded yes
swap_model_version guarded yes
sync_connection guarded yes
tca_summary read no
trade_journal read no
update_draft job no
update_price_alert job no
update_screen job no
update_subscription guarded yes
update_universe guarded yes
update_watchlist job no
validate_draft job no
validate_rule_spec read no
verify_lab_results job no
wait_for_job read no
whoami read no

Read tools

Only issue GETs. Safe to call any time.

check_factor_expression

Check a formula in the factor expression language: whether it parses and is point in time (no future reads, no raw price levels that later splits would change), its canonical form and warm-up.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
expression string yes

check_model_swap

The swap check of a candidate against the live version: model book days, drawdown and return against the live model over the same days, each with value, limit and pass or fail. Read it before swap_model_version: an override skips exactly these checks.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes
version integer yes the model version number

compare_tickers

Several tickers on one scale: daily adjusted closes rebased to 100 on the first day they all have a price, each with its drawdown from the running peak, its rolling Sharpe, total return and worst drawdown. Tickers without prices come back in missing.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
tickers list[string] yes instrument ids, e.g. AAPL.US
start string | null no null YYYY-MM-DD
end string | null no null YYYY-MM-DD
limit integer no 750
window integer no 63 bars behind each rolling Sharpe point

get_api_health

Check that the Stonks API is up and report its version.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_bars

OHLCV bars for one instrument at one interval.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string yes instrument id, e.g. AAPL.US or BTC-USD.CC
interval string no "1d" bar interval, e.g. 1d, 1h, 5m
start date | null no null YYYY-MM-DD
end date | null no null YYYY-MM-DD
limit integer | null no null max bars

get_behaviour_report

How you trade by hand in one of your portfolios: manual and synced broker trades as round trips, with P&L by holding time and weekday, win rate, the disposition effect, overtrading, revenge trades after a loss, and what trading against the active strategies cost.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
since string | null no null

get_broker

The broker production ticks trade through: kind (simulated/alpaca), paper, allow_live and whether credentials are configured (keys are never shown). Read-only.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_broker_gateways

IB Gateway health: connected or not, the last good check, and the auto books of yours a gateway outage paused.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_calendar

Upcoming earnings (with the time of day and the EPS estimate), ex-dividend dates and economic releases from start (default today) to end (default two weeks on, at most 120 days). Economic releases are market wide.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
scope "holdings" | "watchlists" | "tickers" | "all" no "holdings" holdings (default), watchlists, tickers or all
tickers list[string] | null no null instrument ids (scope tickers)
watchlist_id string | null no null one of your watchlists (scope watchlists)
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
start date | null no null YYYY-MM-DD
end date | null no null YYYY-MM-DD
countries list[string] | null no null economic events of these ISO alpha-2 codes

get_catalog

Strategy classes that can be backtested or tuned, with their parameter specs, plus the valid bar intervals and asset classes.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_chart

A price chart's data for one ticker: OHLCV bars (the latest limit in the window), your fills of it (side, quantity, price) in one of your portfolios, and every strategy's signal events for it (entry, exit, increase, decrease) with the plain reason.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string yes instrument id, e.g. AAPL.US or BTC-USD.CC
interval string no "1d"
start string | null no null YYYY-MM-DD
end string | null no null YYYY-MM-DD
limit integer no 750
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
strategy_id string | null no null only this strategy's signals

get_connection_accounts

External accounts on one of your connections, each with the portfolio that mirrors it (null when not linked).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
connection_id string yes

get_coverage

Data coverage: first/last bar and bar count per instrument and interval.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string | null no null
interval string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

get_draft

One Studio draft: spec, kind, status and its registered strategy's status.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
draft_id string yes

get_earnings_warnings

Which of tickers report earnings before the next open of their market. An order placed now fills after the report.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
tickers list[string] yes

get_execution_algo_settings

How one of your portfolio's orders are worked: its own algo and each strategy's override. Empty: plain limit orders.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes

get_factor

One library factor: formula, family, direction, hypothesis and warm-up in bars.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
factor_id string yes

get_factor_values

Each universe name's factor value known at the close of as_of, ranked best first in the factor's direction.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
factor string yes a library factor id (e.g. mom_12_1, ROC20, piotroski_f) or a formula such as '$close / Ref($close, 20) - 1'
as_of date yes YYYY-MM-DD
universe list[string] | null no null instrument ids; or name a stored universe_id
universe_id string | null no null a stored universe id (or give universe)

get_fx_rate

The FX rate the system converts with: units of quote per one base, the latest stored on or before the day (inverse pair or a cross through USD when needed). Null when no stored rate gives it.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
base string yes ISO code, e.g. EUR
quote string yes ISO code, e.g. EUR
day date | null no null YYYY-MM-DD; default today

get_golive_report

The go-live gate for one strategy: every check of its paper period (days, trades, drawdown, Sharpe against the backtest, MinTRL, ...) with its value, limit and pass or fail, and the verdict. Read it before promote_strategy: an override skips exactly these checks.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes
since date | null no null first day of the paper period, default all

get_health_report

Operational health (every stonks health check): bar freshness, stuck ticks and ingest runs, recent ingest failures; see healthy.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
tickers list[string] | null no null bar-freshness tickers; default [production].universe

get_insights

Insights for one of your portfolios (a synced broker account too): allocation by asset class, sector, currency and ticker; exposure (gross, net, beta); P&L over 1d, 1w, 1m, 3m, ytd, 1y and since inception; risk (volatility, drawdown, VaR, concentration).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
benchmark string | null no null ticker beta is measured against; default SPY.US

get_insights_totals

Admins only: asset-class allocation and exposure summed over every active portfolio (no tickers, no per-person numbers).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_job

One background job: status, progress, and its result once finished.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
job_id string yes

get_journal_breakdown

Win rate, P&L, profit factor, average R and exit efficiency per group: by sleeve, tag, mistake, playbook, or followed versus broke plan.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
by "all" | "sleeve" | "origin" | "ticker" | "side" | "exit_trigger" | "tag" | "mistake" | "playbook" | "plan" no "all" how to group the trades
since string | null no null YYYY-MM-DD
until string | null no null YYYY-MM-DD
sleeve string | null no null
origin "strategy" | "manual" | null no null strategy or manual orders
portfolio_id string | null no null

get_leaderboard

Every strategy ranked by its risk-adjusted paper result (the model book the tick keeps for it): total return, CAGR, Sharpe, Sortino, worst drawdown, trades in the model book and in real books, survival tests passed and the go-live verdict.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
sort "sharpe" | "return" | "drawdown" | "trades" no "sharpe" rank by paper Sharpe, total return, drawdown or trades
include_retired boolean no false

get_ledger_run

One recorded lab run with every trial (parameters, score, status) and the trial count of its strategy class across all runs.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
run_id string yes

get_live_allocation

How much Stonks may trade in a live portfolio, set by hand by its owner (amount null: not set, so nothing opens).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes a portfolio id of yours (pf_...)

get_live_gate_report

What a promotion to the next stage needs, checked now. A check with passed = null has no data yet and does not block. Promoting is done in the web app with a fresh second factor, never here.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes a portfolio id of yours (pf_...)

get_live_margin

Buying power and margin use of a live portfolio, read from the broker now: equity, available funds, initial and maintenance margin, the margin cushion and its level (ok, warn, reduce, call), the safety buffer, and whether the pattern day trader rule binds. A margin account is chosen in the web app with a fresh second factor, never here.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes a portfolio id of yours (pf_...)

get_live_risk

One of your portfolios on its latest tick day: one-day 95% and 99% VaR and expected shortfall (fractions of value, loss positive), the rolling VaR violation ratio (1.0 is right, outside 0.5 to 1.5 means the risk model is off) with its Kupiec p-value, and per strategy sleeve the same plus the alpha-decay check against the backtest's IR.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null

get_live_rules

Which live safeguards and account rules act on a live portfolio, with their settings as its book follows them.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes a portfolio id of yours (pf_...)

get_live_stage

A portfolio's live stage (sim_paper, broker_paper, live_small, live_scale), its stage changes, and the last sessions' gate metrics: orders sent, rejected and stuck, fills with no commission, the TCA gap, the book's and the model book's returns, and drift.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes a portfolio id of yours (pf_...)
days integer no 30

get_look_through

Look-through exposure of one of your portfolios: each held fund (an ETF) split into what it holds, then summed by sector, country and single name. Your real Apple weight counts AAPL plus its share of SPY and QQQ. Funds without a holdings list stay whole.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
top integer no 20 single names to list

get_market_breadth

Market breadth from the lake, display only: advances and declines, the share of stocks above their 50 and 200 day averages, new one year highs and lows, and distribution days on the index (falls of 0.2% or more on higher volume), each with a plain sentence.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
as_of date | null no null YYYY-MM-DD

get_model_calibration

Live calibration of a classifier version's probability forecasts: Brier score against the base rate, skill, expected calibration error and the reliability table. Empty for a model with no forecasts.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes
version integer yes the model version number

get_model_version_history

A strategy's append-only version log (baseline, candidate, swap, reject, supersede, fail), with actor, reason and swap check result.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes

get_my_risk_limits

Your own risk limits next to the system policy, what your portfolios follow (the system tightened by yours) and any of yours that are looser than the system and so change nothing.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_news

The newest articles on the scope's tickers and their daily sentiment over the last 30 days. Scope all is refused.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
scope "holdings" | "watchlists" | "tickers" | "all" no "holdings" holdings (default), watchlists, tickers or all
tickers list[string] | null no null instrument ids (scope tickers)
watchlist_id string | null no null one of your watchlists (scope watchlists)
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
limit integer no 50

get_notification_preferences

Your notification settings: which categories (signals, orders, risk, system, price alerts, event alerts) go to which channel, the upcoming-event alert kinds you get, and your quiet hours. The webhook shows its host only.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_option_chain

One expiry of a stored option chain with our implied vol and Greeks, calls and puts by strike. Theta is money per share per day, vega money per share per vol point.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
underlying string yes instrument id, e.g. AAPL.US or BTC-USD.CC
as_of date | null no null the last stored day on or before it; default latest
expiry date | null no null default: the expiry nearest 30 days out

get_option_payoff

One unit of a structure picked from a stored chain, its legs and its profit at expiry over a range of underlying prices, with max loss, max gain (null: no bound) and breakevens.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
underlying string yes instrument id, e.g. AAPL.US or BTC-USD.CC
structure string yes a name from list_option_structures
as_of date | null no null YYYY-MM-DD
dte integer no 35 target days to expiry
delta number | null no null absolute target delta, e.g. 0.30
long_delta number | null no null absolute target delta, e.g. 0.30
short_delta number | null no null absolute target delta, e.g. 0.30
wing_delta number | null no null absolute target delta, e.g. 0.30

get_options_live

Whether an option order may open in a live portfolio (off by default), with every reason it may not: the admin's switch, the live stage and the options approval level (none, covered, spreads, naked). Setting the level needs a fresh second factor in the web app.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes a portfolio id of yours (pf_...)

get_order_tca

One of your orders in full: decision price and context, arrival and fill prices, the shortfall split and the notes.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
client_id string yes

get_pnl

Daily P&L of one of your portfolios (last snapshot per UTC day). Returns and drawdown are measured from inception even when since trims the rows.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
since date | null no null YYYY-MM-DD; first day to include
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

get_pnl_calendar

Realised P&L of closed trades by exit day, with weekly and monthly totals, in the portfolio's base currency.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
since string | null no null YYYY-MM-DD
until string | null no null YYYY-MM-DD
sleeve string | null no null
origin "strategy" | "manual" | null no null strategy or manual orders
portfolio_id string | null no null

get_portfolio

Current portfolio: cash, positions valued at the latest stored closes, weights and total value, from the latest snapshot.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

get_portfolio_totals

Admins only: cash and value summed across every active portfolio (no holdings).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_price_check

The newest second-source price check: each held and signalled ticker's vendor close and adjusted return against a second source, and the tickers whose opening orders the tick holds (held). Null before the first check.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_reconcile_report

One reconcile report: every unexplained drift item, what the check explained itself, and the owner's own positions and orders it kept apart (never drift).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
report_id string yes

get_research_session

One research session with every proposal: its hypothesis, whether it ran or why not, and its lab run in the trial ledger.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
session_id string yes the rs_... id

get_risk_policy

The [production.risk] limits applied between a strategy's orders and the broker (max weights, order caps, ...).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_round_trip

One trade with every leg (each partial exit) and its review.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
trade_id integer yes the id of the opening fill
portfolio_id string | null no null

get_rule_schema

JSON Schema of a Studio rule spec (version 1): indicators, entry/exit conditions, ranking. Use it to write a draft's spec.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_schedule

The scheduler: each job with its next run and last outcome, the most recent runs (did last night's trading run go?), and the market session today and next (open, close, and whether it is open now).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
limit integer no 20 recent runs to show

get_screen

One of your saved screens with its spec.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
screen_id string yes

get_shadow_pnl

Daily P&L of one shadow strategy's virtual portfolio.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes
since date | null no null YYYY-MM-DD; first day to include

get_strategy

One registered strategy with its survival-test reports (pass/fail and metrics).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes

get_strategy_agreement

For each holding of one of your portfolios: whether each active strategy's latest signal agrees or disagrees with it, and why.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

get_strategy_history

A strategy's audited status changes (actor, reason, override, go-live result), oldest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes

get_stream_status

The live intraday engine: live or not, its market, the dead-man (silent after no bar close for deadman_minutes in market hours), the stream (connected, last event age, bars built, late ticks), dispatch lag and event to order latency. engines is empty until an engine runs.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_studio_capabilities

What the Studio allows on this server: whether code drafts are allowed (an operator setting MCP cannot change) and the draft kinds you can create.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

get_tax_settings

One of your portfolios' base currency and tax settings: the jurisdiction (us, eu or uk), the lot method (fifo or specific) and whether US wash sales are adjusted.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

get_tax_year

The gains one of your portfolios realised this year (or year) and the estimated tax owed on them, in its base currency.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
year integer | null no null
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

get_tca_summary

Implementation shortfall of your orders in bps of notional: delay (decision to arrival), impact (arrival to fill), fees and the opportunity cost of what did not fill, next to the cost model's estimate (model_gap_bps = realised minus modelled).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
by "all" | "strategy" | "ticker" | "portfolio" | "day" | "week" | "month" no "all" how to group the orders
since string | null no null YYYY-MM-DD
until string | null no null YYYY-MM-DD
strategy_id string | null no null
ticker string | null no null
portfolio_id string | null no null

get_tear_sheet

One strategy on one page: paper figures and value curve, monthly returns, recent model-book trades, survival verdicts, the go-live report and the status history.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes

get_tick

One production tick run with the orders it placed in your portfolios (or in portfolio_id only).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
tick_id string yes
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

get_ticket

One order ticket: the order, why the book wants it, the rules that touched it, and what became of it.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticket_id string yes

get_universe

One stored universe definition.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common

get_universe_history

Membership spans of a universe, latest change first: each ticker joined on start_date (null: from the start) and left on end_date (null: still a member).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
ticker string | null no null keep tickers containing this, e.g. AAPL
limit integer no 100
offset integer no 0

get_universe_members

Members of a universe on a date (default today), point in time: names that later died are members on the days they were listed.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
as_of date | null no null YYYY-MM-DD

get_watchlist

One of your watchlists with its tickers.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
watchlist_id string yes

health

Deprecated alias of get_api_health. Check that the Stonks API is up and report its version.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_alerts

System alerts for you, newest first (admins also see operational alerts with no single recipient): failed runs, halts, stale data.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
level "info" | "warning" | "error" | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_algo_parents

Parent orders Stonks works as child slices (TWAP, VWAP at a broker without them), with each slice's state.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes

list_cash_flows

Every deposit and withdrawal of one of your portfolios, oldest first: recorded ones and those a broker sync brought in. Returns take them out, so a deposit is never profit.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes
limit integer no 200 page size
offset integer no 0 rows to skip

list_connections

Your broker connections: provider, status, last sync and error. Never includes credentials.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_cost_models

Transaction-cost presets run_backtest accepts as cost_model, with their settings.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_drafts

Studio drafts (strategies being edited), with status and registered strategy.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
limit integer no 50 page size
offset integer no 0 rows to skip

list_event_alert_kinds

The upcoming-event alert kinds (earnings, ex-dividend) and how many days ahead each looks by default.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_execution_algos

Every execution algo (Adaptive, TWAP, VWAP): its parameters, defaults, whether Stonks can slice it at brokers without it, and the costs the backtest assumes for it.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_factors

The factor library: every factor with its family, direction, formula and hypothesis, plus the sets and families to filter by.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
family string | null no null e.g. momentum, value, kbar
set string | null no null alpha158, classic or fundamentals
kind "expression" | "fundamental" | null no null

list_fills

Fills (executions) of orders, with optional filters.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
tick_id string | null no null
ticker string | null no null
order_client_id string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_halts

Halts you can see, newest first: the kill switch, circuit-breaker trips (month loss, week loss, latched drawdown) and the operational halt. By default only those in force today.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
include_cleared boolean no false

list_ingest_runs

Market-data ingest runs (source, kind, tickers ok/failed, status).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
kind string | null no null
status string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_intraday_snapshots

Intraday P&L and risk snapshots of one of your portfolios for one day, newest first, one every few minutes of the session: realised and unrealised P&L from live marks, fees, the day's return, the drawdown from the day's high, gross and net exposure, and how many held names had a stale or missing mark.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null
day string | null no null YYYY-MM-DD; default the latest day with rows
strategy_id string | null no null one strategy's sleeve; default the whole portfolio
all_books boolean no false every book: the whole portfolio and each sleeve
limit integer no 50
offset integer no 0

list_jobs

Background jobs (backtests, lab runs, ingests, ticks), newest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
status "queued" | "running" | "succeeded" | "failed" | "cancelled" | null no null
kind string | null no null backtest, lab_run, ingest, tick, studio_backtest, studio_lab_run
limit integer no 50 page size
offset integer no 0 rows to skip

list_lab_objectives

Every objective a lab run can score trials with (the names objective takes), with a label and what it measures.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_lab_tuners

Every tuner a lab run can search with (the names tuner takes), with a label and the options schema of each.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_ledger_runs

The trial ledger: every recorded lab run, newest first, with its hypothesis, tuner, budget, trials run and failed, best score and verdict. Trials of a class add up across runs, which is what the deflated Sharpe and other multiple-testing checks count.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_class string | null no null only runs of this module:Class
limit integer no 50 page size
offset integer no 0 rows to skip

list_model_candidates

Every candidate model version running as a model book, across strategies.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
limit integer no 100 page size
offset integer no 0 rows to skip

list_model_versions

A strategy's model versions, oldest first: the live one, candidates running as model books beside it, and archived, rejected or failed fits.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string yes
limit integer no 100 page size
offset integer no 0 rows to skip

list_notifications

Your notification feed, newest first, with the unread count: what Stonks told you (signals, fills, halts, failed runs), each with a category, level, message and a link into the console.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
unread_only boolean no false
limit integer no 50
before_id integer | null no null page: only items with a lower id

list_option_strategies

The options strategy catalog: each strategy's hypothesis, the structures it opens and its parameters.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_option_structures

Structures a payoff can be drawn for, with the parameters each reads (dte, delta, long_delta, short_delta, wing_delta).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_option_underlyings

Underlyings with stored option chains: first and last day, days, contracts and sources. synthetic=true means generated chains, fine for trying the tools but never evidence.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_order_drafts

Your order drafts, newest first: proposed orders waiting for your approval in the web app, and what became of the others.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
status "pending" | "placed" | "rejected" | "expired" | "cancelled" | null no null

list_orders

Orders placed by production ticks, newest first, with optional filters.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
tick_id string | null no null
strategy_id string | null no null
ticker string | null no null
status string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_playbooks

Your playbooks: the setups you trade, with their rules.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
include_archived boolean no false

list_portfolio_snapshots

Portfolio history: one snapshot per production tick, newest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
limit integer no 50 page size
offset integer no 0 rows to skip

list_portfolios

Your portfolios, oldest first, each marked paper or live.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_price_alert_events

When your price alerts fired, newest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
rule_id string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_price_alerts

Your price alert rules, with the price each last saw per ticker.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
limit integer no 100 page size
offset integer no 0 rows to skip

list_reconcile_reports

The latest checks of your live portfolios against their brokers, newest first. Status clean, warn (an alert only), drift (opened the broker_drift halt and paused auto), outage (the day was skipped) or fault (auto paused).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null
limit integer no 20

list_research_sessions

Your AI research sessions, newest first: goal, budgets used, status.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
limit integer no 50 page size
offset integer no 0 rows to skip

list_risk_snapshots

Daily risk snapshots of one of your portfolios, newest first: VaR, ES, the day's hypothetical return, violations and decay.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null
strategy_id string | null no null one strategy's sleeve; default the whole portfolio
since string | null no null YYYY-MM-DD
limit integer no 50
offset integer no 0

list_round_trips

Your round trips built from fills, open first then newest exit first: entry and exit, holding days, P&L, adverse and favourable excursion, R multiple (when a stop is known), exit efficiency, and your tags, mistakes and playbook.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
status "all" | "open" | "closed" no "all" all, open or closed
sleeve string | null no null one strategy id, or manual
origin "strategy" | "manual" | null no null strategy or manual orders
ticker string | null no null
since string | null no null YYYY-MM-DD
until string | null no null YYYY-MM-DD
tag string | null no null
mistake string | null no null
plan "followed" | "broke" | "not_said" | null no null whether the plan was followed
portfolio_id string | null no null
limit integer no 50
offset integer no 0

list_screen_alert_events

When your screens found names that newly match, newest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
screen_id string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_screen_alerts

Your screen alerts: which saved screens alert, daily or weekly, the last day each ran and how many names it matched.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
limit integer no 100 page size
offset integer no 0 rows to skip

list_screen_metrics

Every metric a screen may filter or sort on: id, group (price or fundamental), unit and what it measures.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_screens

Your saved screens, oldest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_shadow_decisions

Virtual orders shadow strategies placed (never sent to a broker), newest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy_id string | null no null
ticker string | null no null
as_of date | null no null YYYY-MM-DD
limit integer no 50 page size
offset integer no 0 rows to skip

list_shadow_pnl

Latest value, return and worst drawdown of every shadow strategy's virtual portfolio.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
since date | null no null YYYY-MM-DD; first day to include
limit integer no 50 page size
offset integer no 0 rows to skip

list_sources

Market-data sources an ingest can name, which is the default, and whether each is configured.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_statement_flags

Statement periods the accounting audit flagged (BL-36): balance identity, net income and cash mismatches, quarters vs annual, filings dated before period end, negative shares. Error flags make lab preflight warn.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string | null no null instrument id, e.g. AAPL.US or BTC-USD.CC
severity "error" | "warning" | null no null only this severity
limit integer no 50 page size
offset integer no 0 rows to skip

list_strategies

Registered strategies (id, class, params, status), optionally by status or a search term.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
status "active" | "shadow" | "retired" | null no null
q string | null no null case-insensitive substring of the id or class path
limit integer no 50 page size
offset integer no 0 rows to skip

list_studio_templates

Starter rule specs (id, title, description, spec) for building a rule draft.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_subscriptions

Your subscriptions: strategy, portfolio, mode (notify, paper, auto), whether it is on, the paper-day count and what still blocks auto.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_survival_presets

The named survival suites (quick, standard, promotion) and the tests in each.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_survival_tests

Every survival test a lab run can name (the ids survival_tests takes), with what it checks and its options schema (the keys test_options takes).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_tax_lot_picks

The specific lots each sell closes (used with lot method specific).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
sell_fill_id integer | null no null

list_tickets

Your order tickets, newest first: the orders a live book decided after the close. Approve mode tickets wait for your approval in the web app (a fresh second factor, never through MCP). Approved ones are sent before the next open.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
status "awaiting_approval" | "approved" | "rejected" | "expired" | "submitted" | "filled" | "unfilled" | "cancelled" | "failed" | null no null
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

list_ticks

Production tick runs, newest first. Summaries show the global outcome and the parts about your own portfolios only.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
status string | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

list_trade_decisions

Why a ticker did or did not trade in one of your portfolios, newest first. Each row names the step that kept it out or trimmed it: universe, rank (another pick won), constructor (no weight), buffer (inside the no-trade band), stale_price, risk_rule (with the rule and the quantities), lots (rounded to tradable lots or skipped below one lot), scope, external, halt, held or traded. Ask with a ticker to answer "why didn't we buy X".

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string | null no null one ticker, e.g. AAPL.US
portfolio_id string | null no null
strategy_id string | null no null rows this strategy owned or scored
tick_id string | null no null one tick
since string | null no null YYYY-MM-DD
limit integer no 20
offset integer no 0

list_trade_journal

Your orders, newest first: why each was placed (trigger, signal score and rank), the outcome (shortfall, next-day move) and notes.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
since string | null no null YYYY-MM-DD
strategy_id string | null no null
ticker string | null no null
portfolio_id string | null no null
limit integer no 50
offset integer no 0

list_trading_modes

For each of your portfolios: paper or live money, and the broker (simulated ledger, the configured Alpaca account, or a linked connection).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_universe_exchanges

Exchanges our instruments name, with instrument counts, for an exchange universe's spec. The data source may list more.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_universes

Stored universes: id, kind, spec, last refresh and member count.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

list_watchlists

Your watchlists (named ticker lists), oldest first.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

live_risk

Deprecated alias of get_live_risk. One of your portfolios on its latest tick day: one-day 95% and 99% VaR and expected shortfall (fractions of value, loss positive), the rolling VaR violation ratio (1.0 is right, outside 0.5 to 1.5 means the risk model is off) with its Kupiec p-value, and per strategy sleeve the same plus the alpha-decay check against the backtest's IR.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null

order_tca

Deprecated alias of get_order_tca. One of your orders in full: decision price and context, arrival and fill prices, the shortfall split and the notes.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
client_id string yes

plan_rebalance

The trades that move one of your portfolios to a strategy's model weights (source=strategy) or your own targets (source=targets): whole shares, costs, turnover and a tax preview. Writes and sends nothing.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string yes
source "strategy" | "targets" yes
strategy_id string | null no null
targets object | null no null your own targets, ticker to weight, e.g. {"AAPL.US": 0.3}
min_trade_value number no 0.0
short_term_rate number | null no null tax rate as a fraction
long_term_rate number | null no null tax rate as a fraction

preview_trade_tax

Before a trade in one of your portfolios: the lots a sell closes under your lot method, the realised gain and holding period, the estimated tax at the configured rate, the after-tax proceeds and a US wash sale warning. An estimate, not tax advice. Places nothing.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string yes
side "buy" | "sell" yes
quantity number yes
price number | null no null Default: latest close
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book

risk_snapshots

Deprecated alias of list_risk_snapshots. Daily risk snapshots of one of your portfolios, newest first: VaR, ES, the day's hypothetical return, violations and decay.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
portfolio_id string | null no null
strategy_id string | null no null one strategy's sleeve; default the whole portfolio
since string | null no null YYYY-MM-DD
limit integer no 50
offset integer no 0

run_screen

Run a screen (or one of your saved ones) on the lake as it was on as_of (default today): the matching tickers with the value of each metric it uses. Only data known on that day counts.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
spec object | null no null the screen: rule filters (asset_classes, sectors, exclude_sectors, exchanges, min_price, min_adv), universe_id to start from a stored universe, filters [{"metric": "pe_ratio", "min": 0, "max": 15}], sort_by, descending, limit and columns. Metric ids come from list_screen_metrics
screen_id string | null no null one of your saved screens
as_of date | null no null YYYY-MM-DD

search_instruments

Search instruments in the lake by id/name and asset class.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
q string | null no null substring of id or name
asset_class "equity" | "crypto" | "commodity" | "bond" | null no null
limit integer no 50 page size
offset integer no 0 rows to skip

tca_summary

Deprecated alias of get_tca_summary. Implementation shortfall of your orders in bps of notional: delay (decision to arrival), impact (arrival to fill), fees and the opportunity cost of what did not fill, next to the cost model's estimate (model_gap_bps = realised minus modelled).

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
by "all" | "strategy" | "ticker" | "portfolio" | "day" | "week" | "month" no "all" how to group the orders
since string | null no null YYYY-MM-DD
until string | null no null YYYY-MM-DD
strategy_id string | null no null
ticker string | null no null
portfolio_id string | null no null

trade_journal

Deprecated alias of list_trade_journal. Your orders, newest first: why each was placed (trigger, signal score and rank), the outcome (shortfall, next-day move) and notes.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
since string | null no null YYYY-MM-DD
strategy_id string | null no null
ticker string | null no null
portfolio_id string | null no null
limit integer no 50
offset integer no 0

validate_rule_spec

Validate a rule spec without saving it (no smoke run): valid + issues.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
spec object yes rule spec (see get_rule_schema); constructor params for code drafts

wait_for_job

Poll a job until it finishes or the timeout passes. Returns {"timed_out": bool, "job": {...}, "result": {...} | null}: once the job succeeded, "result" is its typed result (BacktestResult, LabRunView, SignalICView, ingest or tick result); otherwise null and the job carries its error.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
job_id string yes
timeout_seconds number no 120.0 give up after this long (max 600)
poll_seconds number no 1.0

whoami

Who this MCP server acts as: the token's user, role and scopes. Every tool does only what that user may do.

Safety: read-only, non-destructive, idempotent, closed world. Needs confirm: no.

No inputs.

Job tools

Queue background work on the API. Research data only, never orders.

add_journal_note

Add a note to one of your orders in the trade journal (why you agree or disagree with it, what you learned). Needs a trading token. The note is yours and shows in the console.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
client_id string yes
note string yes the note text

backtest_draft

Deprecated alias of run_draft_backtest. Queue a backtest of a draft. Returns the job; wait_for_job gives the BacktestResult. Simulated only: never places real orders.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
draft_id string yes
universe list[string] yes instrument ids
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
interval string no "1d"
initial_cash number no 10000.0
threshold number no 0.0
rebalance_every_bars integer no 1
slippage_bps number no 0.0
fee_per_trade number no 0.0
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); default [backtest.costs]
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark

cancel_job

Stop one of your background jobs: a queued job never starts, and a running lab run stops at its next trial (it ends cancelled). Other running jobs cannot be interrupted (409). Ticks and ingests need an admin.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
job_id string yes

create_draft

Create a Studio draft (saved, not registered, never traded). Rule drafts take a spec; code drafts take source_code and are refused (403) unless the API allows code strategies.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
name string yes draft name
spec object | null no null rule spec (see get_rule_schema); constructor params for code drafts
kind "rule" | "code" no "rule"
source_code string | null no null Python source of a code draft (API must allow code strategies)

create_price_alert

Create a price alert on a ticker or one of your watchlists. It is checked after each data refresh and sent through your notification channels (push, email, Telegram) with your quiet hours.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
condition "crosses_above" | "crosses_below" | "moves_pct" yes crosses_above or crosses_below a level, or moves_pct
ticker string | null no null one instrument id, e.g. AAPL.US
watchlist_id string | null no null or every ticker of one of your watchlists
level number | null no null the price to watch (crossings)
pct number | null no null percent move, either way
window_days integer | null no null calendar days the move is measured over
name string | null no null

create_screen

Save a screen under a name, unique per person. Needs a trading token.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
name string yes the screen's name
spec object | null no null the screen: rule filters (asset_classes, sectors, exclude_sectors, exchanges, min_price, min_adv), universe_id to start from a stored universe, filters [{"metric": "pe_ratio", "min": 0, "max": 15}], sort_by, descending, limit and columns. Metric ids come from list_screen_metrics

create_watchlist

Start a watchlist of yours. Names are unique per person. Needs a trading token.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
name string yes the list's name
tickers list[string] | null no null instrument ids, kept once and in order

draft_order

Propose an order without placing it. The server prices it at the latest close and checks it. The person approves it in the web app with a fresh second factor, and only then is it placed.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ticker string yes instrument id, e.g. AAPL.US or BTC-USD.CC
side "buy" | "sell" yes
quantity number yes
reason string yes why you trade (recorded and audited)
retry_key string yes the same key returns the draft already made (a safe retry)
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
order_type "market" | "limit" no "market"
limit_price number | null no null

edit_journal_note

Replace the text of one of your journal notes.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
note_id integer yes
note string yes the note text

mark_notifications_read

Mark notifications read (all of yours when ids is omitted). Only touches your own feed, and returns how many changed and the new unread count.

Safety: writes, non-destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
ids list[integer] | null no null notification ids, or omit to mark all of yours

run_backtest

Queue a backtest of one strategy over typed tickers (universe) or a stored universe (universe_id) and a date window. Returns the job. Use wait_for_job to get the metrics and equity curve. Simulated only: never places real orders.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
universe list[string] | null no null instrument ids, or give universe_id
universe_id string | null no null a stored universe (see list_universes): its point-in-time members, delisted names included, instead of typed tickers
strategy_id string | null no null registered strategy id (or use class_path)
class_path string | null no null catalog class path, e.g. pkg.mod:Class
params object | null no null strategy params (with class_path)
interval string no "1d"
initial_cash number no 10000.0
threshold number no 0.0
rebalance_every_bars integer no 1
slippage_bps number no 0.0
fee_per_trade number no 0.0
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); replaces slippage_bps/fee_per_trade. Neither: the configured [backtest.costs]
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark

run_draft_backtest

Queue a backtest of a draft. Returns the job; wait_for_job gives the BacktestResult. Simulated only: never places real orders.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
draft_id string yes
universe list[string] yes instrument ids
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
interval string no "1d"
initial_cash number no 10000.0
threshold number no 0.0
rebalance_every_bars integer no 1
slippage_bps number no 0.0
fee_per_trade number no 0.0
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); default [backtest.costs]
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark

run_factor_tearsheet

Queue a factor tear sheet: IC per horizon and by sector, asset class and size, returns per quantile, factor alpha and beta, a monthly IC heatmap and turnover. Needs at least 10 tickers (else n/a). Returns the job; use wait_for_job for the result. Research only: writes nothing.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
factor string yes a library factor id (e.g. mom_12_1, ROC20, piotroski_f) or a formula such as '$close / Ref($close, 20) - 1'
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
universe list[string] | null no null instrument ids; or name a stored universe_id
universe_id string | null no null a stored universe id (or give universe)
interval string no "1d"
horizons list[integer] | null no null forward-return horizons in bars; default [1, 5, 21]
every_bars integer no 5 sample every N bars
n_quantiles integer no 5

run_ingest

Queue a market-data ingest into the lake from the configured vendor, or from source. borrow pulls daily stock borrow rates. Returns the job; use wait_for_job for the outcome.

Safety: writes, non-destructive, not idempotent, open world. Needs confirm: no.

Input Type Required Default Description
kind "prices" | "intraday" | "fundamentals" | "metadata" | "borrow" yes
source "eodhd" | "yahoo" | "defillama" | null no null data source; the default one when left out (see list_sources)
tickers list[string] | null no null instrument ids; or use exchange
exchange string | null no null ingest a whole exchange
since date | null no null YYYY-MM-DD
until date | null no null YYYY-MM-DD
interval string | null no null for intraday, e.g. 5m
markets list[string] | null no null for borrow: IBKR short stock markets, e.g. usa

run_options_backtest

Queue an options backtest on the stored chains, with its validation checks and a verdict. Returns the job; use wait_for_job for the result. Research only: nothing trades options.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
strategy string yes an id from list_option_strategies
underlyings list[string] yes
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
cash number no 100000.0
params object | null no null strategy parameters; defaults otherwise
validation boolean no true also run out of sample, deflated Sharpe and stress checks
trials integer no 1 trials run so far, for the deflated Sharpe

run_signal_ic

Queue a signal IC analysis: does the strategy's estimate_return rank future returns across the universe? Reports mean IC, ICIR, HAC t-stat and quantile spread per horizon, plus turnover and the IC estimate. Needs at least 10 tickers (else n/a). Returns the job; use wait_for_job for the result. Research only: writes nothing.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
universe list[string] yes instrument ids
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
strategy_id string | null no null registered strategy id (or use class_path)
class_path string | null no null catalog class path, e.g. pkg.mod:Class
params object | null no null strategy params (with class_path)
interval string no "1d"
horizons list[integer] | null no null forward-return horizons in bars; default [1, 5, 21]
every_bars integer no 5 score every N bars
n_quantiles integer no 5

run_sweep

Queue a sweep: a lab run of every strategy (or the ones named) on the same tickers or stored universe and window, ranked best first. A strategy with a ticker parameter runs once per ticker. Returns the job, and wait_for_job gives the ranked rows. Every trial is counted in the trial ledger. A sweep never registers a strategy: register the one you like with run_lab.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
universe list[string] | null no null instrument ids, or give universe_id
universe_id string | null no null a stored universe (see list_universes): its point-in-time members, delisted names included, instead of typed tickers
strategies list[string] | null no null strategy ids (e.g. momentum), class names or module:Class. default every catalogued strategy
exclude list[string] | null no null strategies to leave out
preset "quick" | "standard" | "promotion" | null no null named survival suite when survival_tests is omitted (default: promotion when registering, else quick)
survival_tests list[string] | null no null survival suite for every strategy, the server default when omitted
tuner string no "random" a tuner: grid, random, optuna, prescreen or another from list_lab_tuners
objective string no "sharpe" an objective: sharpe, cagr, final_return, sortino, calmar, sharpe_dd, multi, a cv_ variant or another from list_lab_objectives
budget integer no 20 tuner trials each
train_ratio number no 0.7
interval string no "1d"
seed integer no 0
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); default [backtest.costs]
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark
embargo_bars integer | null no null trading bars skipped between the train and validation windows (a strategy's label horizon raises it); default [lab] embargo_bars
preflight boolean | null no null check the data before tuning (missing bars, gaps). Default [lab] preflight
strict_preflight boolean | null no null treat preflight warnings as errors. Default [lab] strict_preflight
hypothesis string | null no null the edge and who pays for it; recorded before tuning (trial ledger)
premortem string | null no null how the strategy is expected to fail; recorded

set_screen_alert

Turn on (or change) the alert of a saved screen. It runs after each data refresh and notifies you about names that newly match, through your notification channels. Notify only: nothing trades. The first run stores the matches and sends nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
screen_id string yes one of your saved screens
cadence "daily" | "weekly" no "daily" run on every trading day, or weekly
weekday integer | null no null weekly: the day it runs, 0 = Monday
enabled boolean no true

start_research

Start an AI research session: the assistant's model proposes lab trials for the goal and runs them under the session's budgets. Every proposal is recorded with its hypothesis first, every trial is counted in the trial ledger, and validation windows start after the model's training cutoff. It never registers or promotes a strategy. Returns the job; use wait_for_job, then get_research_session.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
goal string yes what to look for
universe list[string] | null no null instrument ids, or give universe_id
universe_id string | null no null a stored universe
max_trials integer | null no null tuning trials, at most the setting
max_proposals integer | null no null proposals, at most the setting
max_cpu_seconds number | null no null compute seconds, at most the setting

update_draft

Overwrite fields of a draft (only the ones given). A registered strategy keeps the version it was registered with.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
draft_id string yes
name string | null no null
spec object | null no null replaces the spec
source_code string | null no null Python source of a code draft (API must allow code strategies)

update_price_alert

Change a price alert's thresholds or name, or switch it on or off.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
alert_id string yes
level number | null no null the price to watch (crossings)
pct number | null no null percent move, either way
window_days integer | null no null calendar days the move is measured over
name string | null no null
enabled boolean | null no null

update_screen

Rename one of your saved screens, replace its spec, or both.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
screen_id string yes
name string | null no null
spec object | null no null the screen: rule filters (asset_classes, sectors, exclude_sectors, exchanges, min_price, min_adv), universe_id to start from a stored universe, filters [{"metric": "pe_ratio", "min": 0, "max": 15}], sort_by, descending, limit and columns. Metric ids come from list_screen_metrics

update_watchlist

Rename one of your watchlists, replace its tickers, or both.

Safety: writes, destructive, idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
watchlist_id string yes
name string | null no null
tickers list[string] | null no null instrument ids, kept once and in order

validate_draft

Validate a draft and smoke-run it (on lake tickers or synthetic data). Saves nothing, but a code draft's Python runs inside the API server.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
draft_id string yes
tickers list[string] | null no null lake tickers to smoke-run on; default sample data
as_of date | null no null YYYY-MM-DD
bars integer | null no null bars to evaluate

verify_lab_results

Queue a rerun of lab results from their stored manifests: per target the stored and rerun objective score, whether it moved beyond the tolerance, and the tickers whose bars or corporate actions changed since (vendor restatements). Returns the job; use wait_for_job for the result. Research only: writes nothing.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: no.

Input Type Required Default Description
targets list[string] | null no null lab run ids or strategy ids (default: every active strategy)
tolerance number | null no null allowed score drift (default [lab.verify] tolerance)

Guarded tools

Need confirm=true to act. Without it they return a preview and change nothing.

cancel_order

Cancel one working order of your portfolio (yours or a strategy's). Without confirm=true returns the order and cancels nothing.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
client_id string yes
reason string yes why you trade (recorded and audited)
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
confirm boolean no false must be true to apply; false (default) returns a preview only

change_order

Change the quantity or limit of one of your working manual orders. The order is cancelled at the broker and a new one replaces it, after every check again. Without confirm=true returns the order as it is now and changes nothing.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
client_id string yes
reason string yes why you trade (recorded and audited)
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
quantity number | null no null
limit_price number | null no null
allow_reduce boolean no false
confirm boolean no false must be true to apply; false (default) returns a preview only

confirm_rebalance

Write one order ticket per trade of the plan. Each waits for the person's approval with a fresh second factor in the web app, so nothing is sent from here. Without confirm=true returns the plan.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
portfolio_id string yes
source "strategy" | "targets" yes
reason string yes why (audited)
strategy_id string | null no null
targets object | null no null your own targets, ticker to weight, e.g. {"AAPL.US": 0.3}
min_trade_value number no 0.0
confirm boolean no false must be true to apply; false (default) returns a preview only

create_universe

Store a universe definition. It has no members until refreshed (refresh_universe). Without confirm=true returns a preview.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
kind "list" | "exchange" | "rule" | "index" yes
spec object | null no null kind settings. list: {tickers, spans}. exchange: {exchange, source, security_types, include_delisted}. rule: {start, end, rebalance, min_adv, min_price, asset_classes, sectors, exclude_sectors, exchanges}. index: {index_id, source, start_date}
name string | null no null
description string | null no null
csv string | null no null list only: CSV with a ticker column (replaces spec)
confirm boolean no false must be true to apply; false (default) returns a preview only

delete_draft

Delete one of your Studio drafts. A strategy already registered from it stays registered. Without confirm=true returns a preview (the draft's name, kind and status) and deletes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
draft_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only

delete_price_alert

Delete one of your price alerts. Without confirm=true returns the rule and deletes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
alert_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only

delete_screen

Delete one of your saved screens. Universes made from it stay. Without confirm=true returns a preview.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
screen_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only

delete_screen_alert

Remove the alert from one of your saved screens (the screen stays). Without confirm=true returns the alert and removes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
screen_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only

delete_universe

Delete a stored universe and its membership rows (admins only). Lab runs, ticks and scheduled jobs that name it stop resolving. Without confirm=true returns a preview.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
confirm boolean no false must be true to apply; false (default) returns a preview only

disable_draft

Move a registered draft's strategy back to shadow (stops trading it). Needs a reason. Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
draft_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides

enable_draft

Promote a registered draft's strategy to active so production ticks rank and trade it. Same go-live gate as promote_strategy (override=true needs a reason of at least 20 characters). Without confirm=true returns a preview (survival results, warnings) and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
draft_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides
override boolean no false promote without a passing go-live check; needs a reason of at least 20 characters

engage_kill_switch

Stop new orders at once and cancel the orders still working at the broker. Without confirm=true returns a preview and changes nothing. Resuming is done in the console or the CLI with a typed confirmation and a fresh 2FA code.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
scope "global" | "user" | "portfolio" yes global: every portfolio (admins only); user: all of yours; portfolio: one of yours (give portfolio_id)
reason string yes audited
portfolio_id string | null no null
buys_only boolean no false stop buys and cancel working buy orders only: sells and exits still go through, and no position is closed
confirm boolean no false must be true to apply; false (default) returns a preview only
flatten boolean no false deprecated name of buys_only (it never closed a position)

ensure_universe_data

Queue a job that fetches only the missing bars of every member over the window (delisted names included) from the data source. Follow up with wait_for_job. Without confirm=true returns a preview.

Safety: writes, destructive, idempotent, open world. Needs confirm: yes.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
interval string no "1d"
source "eodhd" | "yahoo" | "defillama" | null no null
confirm boolean no false must be true to apply; false (default) returns a preview only

import_index_history

Import an index's constituents and changes. CSV columns date,ticker,action with action add, remove or member. Without confirm=true returns a preview.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
index_id string yes lower_snake_case index code, e.g. sp500
content string yes the CSV or JSON text
format "csv" | "json" no "csv"
confirm boolean no false must be true to apply; false (default) returns a preview only

lab_run_draft

Deprecated alias of run_draft_lab. Queue tune -> fit -> survival suite for a draft (a rule draft's spec is fixed; a code draft is tuned). Returns the job; wait_for_job gives the verdict and survival reports. Registering (register_strategy, or register_if_passes for a passing run only) needs confirm=true (preview otherwise), like register_draft.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
draft_id string yes
universe list[string] yes instrument ids
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
survival_tests list[string] | null no null survival suite; server default when omitted
tuner string no "random" a tuner: grid, random, optuna, prescreen or another from list_lab_tuners
objective string no "sharpe" an objective: sharpe, cagr, final_return, sortino, calmar, sharpe_dd, multi, a cv_ variant or another from list_lab_objectives
budget integer no 20 tuner trials
train_ratio number no 0.7
interval string no "1d"
seed integer no 0
register_strategy boolean no false register the result in shadow status whatever the verdict (needs confirm=true)
register_if_passes boolean no false register the result in shadow only if every survival test passes (needs confirm=true)
confirm boolean no false must be true with register_strategy / register_if_passes; otherwise a preview
preset "quick" | "standard" | "promotion" | null no null named survival suite when survival_tests is omitted (default: promotion when registering, else quick)
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); default [backtest.costs]
hypothesis string | null no null the edge and who pays for it; recorded before tuning (trial ledger)
premortem string | null no null how the strategy is expected to fail; recorded
test_options object | null no null options per survival test id, validated by each test (422 on an unknown test or option), e.g. {"oos": {"mode": "sharpe", "min_trades": 0}, "deflated_sharpe": {"min_dsr": 0.9}, "pbo": {"max_pbo": 0.3}, "mc_trades": {"n_paths": 2000}, "cost_stress": {"stress_multiplier": 3}}; each test must be in the suite
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark
embargo_bars integer | null no null trading bars skipped between the train and validation windows (a strategy's label horizon raises it); default [lab] embargo_bars

place_order

Place a manual order on one of your portfolios. It goes through the kill switch, every halt and every risk rule, like a strategy's order. Without confirm=true returns the preview (what would be placed, the risk rules' adjustments) and places nothing. Real-money books are refused here: place those in the web app with a fresh second factor.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
ticker string yes instrument id, e.g. AAPL.US or BTC-USD.CC
side "buy" | "sell" yes
quantity number yes
reason string yes why you trade (recorded and audited)
portfolio_id string | null no null one of your portfolios (not found otherwise); default: your own book
order_type "market" | "limit" no "market"
limit_price number | null no null
client_id string | null no null your idempotency key: the same key places the order once
allow_reduce boolean no false accept a smaller order when a risk rule shrinks it
confirm boolean no false must be true to apply; false (default) returns a preview only

promote_strategy

Promote a strategy to active so production ticks rank and trade it. Needs a passing go-live check, or override=true with a reason of at least 20 characters; the change is audited. Without confirm=true returns a preview (current status, survival results, warnings) and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
strategy_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides
override boolean no false promote without a passing go-live check; needs a reason of at least 20 characters

refresh_universe

Queue a refresh that rebuilds the universe's membership (an exchange universe lists symbols at the data source). Follow up with wait_for_job. Without confirm=true returns a preview.

Safety: writes, destructive, idempotent, open world. Needs confirm: yes.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
confirm boolean no false must be true to apply; false (default) returns a preview only

register_draft

Register a draft's strategy in shadow (virtual portfolio, never traded until enabled). Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
draft_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only

reject_model_version

Drop a candidate version: its model book stops and it can never swap in. Needs a reason. Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
strategy_id string yes
version integer yes the model version number
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides

retire_strategy

Retire a strategy: it stops being ranked or evaluated. Needs a reason. Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
strategy_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides

retrain_models

Queue a retrain. Each fit becomes a candidate version that runs as a model book; nothing trades until a swap. Without confirm=true returns a preview and queues nothing.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
confirm boolean no false must be true to apply; false (default) returns a preview only
strategy_ids list[string] | null no null refit only these (default: every strategy that learns from data)
as_of date | null no null YYYY-MM-DD, last day of the training window
force boolean no false refit even when a recent fit exists
tickers list[string] | null no null tickers to fit on when a strategy records no lab universe

run_draft_lab

Queue tune -> fit -> survival suite for a draft (a rule draft's spec is fixed; a code draft is tuned). Returns the job; wait_for_job gives the verdict and survival reports. Registering (register_strategy, or register_if_passes for a passing run only) needs confirm=true (preview otherwise), like register_draft.

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
draft_id string yes
universe list[string] yes instrument ids
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
survival_tests list[string] | null no null survival suite; server default when omitted
tuner string no "random" a tuner: grid, random, optuna, prescreen or another from list_lab_tuners
objective string no "sharpe" an objective: sharpe, cagr, final_return, sortino, calmar, sharpe_dd, multi, a cv_ variant or another from list_lab_objectives
budget integer no 20 tuner trials
train_ratio number no 0.7
interval string no "1d"
seed integer no 0
register_strategy boolean no false register the result in shadow status whatever the verdict (needs confirm=true)
register_if_passes boolean no false register the result in shadow only if every survival test passes (needs confirm=true)
confirm boolean no false must be true with register_strategy / register_if_passes; otherwise a preview
preset "quick" | "standard" | "promotion" | null no null named survival suite when survival_tests is omitted (default: promotion when registering, else quick)
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); default [backtest.costs]
hypothesis string | null no null the edge and who pays for it; recorded before tuning (trial ledger)
premortem string | null no null how the strategy is expected to fail; recorded
test_options object | null no null options per survival test id, validated by each test (422 on an unknown test or option), e.g. {"oos": {"mode": "sharpe", "min_trades": 0}, "deflated_sharpe": {"min_dsr": 0.9}, "pbo": {"max_pbo": 0.3}, "mc_trades": {"n_paths": 2000}, "cost_stress": {"stress_multiplier": 3}}; each test must be in the suite
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark
embargo_bars integer | null no null trading bars skipped between the train and validation windows (a strategy's label horizon raises it); default [lab] embargo_bars

run_lab

Queue a lab run: tune a strategy class, fit, run the survival suite and give a pass/fail verdict. Returns the job; use wait_for_job for the result. Every run and trial is recorded in the trial ledger (with the hypothesis). Give typed tickers (universe) or a stored universe (universe_id), and ensure_data=true to fetch missing bars first. Registering (register_strategy, or register_if_passes to register only a passing run) needs confirm=true (preview otherwise).

Safety: writes, non-destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
class_path string yes catalog class path to tune
start date yes YYYY-MM-DD
end date yes YYYY-MM-DD
universe list[string] | null no null instrument ids, or give universe_id
universe_id string | null no null a stored universe (see list_universes): its point-in-time members, delisted names included, instead of typed tickers
ensure_data boolean no false fetch the bars the run needs that the lake lacks first (a lab_ensure job the run waits for, and its id is ensure_job_id in the result)
preflight boolean | null no null check the data before tuning (missing bars, gaps). Default [lab] preflight
strict_preflight boolean | null no null treat preflight warnings as errors. Default [lab] strict_preflight
survival_tests list[string] | null no null survival suite; server default when omitted
tuner string no "random" a tuner: grid, random, optuna, prescreen or another from list_lab_tuners
sampler "tpe" | "nsga2" | "random" no "tpe" optuna tuner: tpe, nsga2 (Pareto over multi) or random
prune boolean no false optuna tuner: stop trials whose fast score trails
objective string no "sharpe" an objective: sharpe, cagr, final_return, sortino, calmar, sharpe_dd, multi, a cv_ variant or another from list_lab_objectives
budget integer no 20 tuner trials
train_ratio number no 0.7
interval string no "1d"
seed integer no 0
register_strategy boolean no false register the result in shadow status whatever the verdict (needs confirm=true)
register_if_passes boolean no false register the result in shadow only if every survival test passes (needs confirm=true)
confirm boolean no false must be true with register_strategy / register_if_passes; otherwise a preview
preset "quick" | "standard" | "promotion" | null no null named survival suite when survival_tests is omitted (default: promotion when registering, else quick)
cost_model "zero" | "realistic" | "ibkr_tiered" | "ibkr_fixed" | null no null transaction-cost preset (see list_cost_models); default [backtest.costs]
hypothesis string | null no null the edge and who pays for it; recorded before tuning (trial ledger)
premortem string | null no null how the strategy is expected to fail; recorded
walk_forward any | null no null walk_forward test settings; add 'walk_forward' to survival_tests
mcpt any | null no null permutation (MCPT) settings; add 'permutation' to survival_tests
test_options object | null no null options per survival test id, validated by each test (422 on an unknown test or option), e.g. {"oos": {"mode": "sharpe", "min_trades": 0}, "deflated_sharpe": {"min_dsr": 0.9}, "pbo": {"max_pbo": 0.3}, "mc_trades": {"n_paths": 2000}, "cost_stress": {"stress_multiplier": 3}}; each test must be in the suite
benchmark string | null no null benchmark to compare against: auto (SPY.US when priced, else EW), EW (equal-weight universe), a ticker such as QQQ.US, or none; default [lab] benchmark
embargo_bars integer | null no null trading bars skipped between the train and validation windows (a strategy's label horizon raises it); default [lab] embargo_bars
heatmap any | null no null parameter heatmap around the tuned set (22.5)

run_tick

Queue one production tick (rank active strategies, then trade the winner). Dry run by default. Without confirm=true returns a preview and queues nothing. A real tick (dry_run=false) is refused unless GET /api/brokers reports a simulated or paper broker.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
confirm boolean no false must be true to apply; false (default) returns a preview only
dry_run boolean no true true (default): rank and log only, place no orders
as_of date | null no null YYYY-MM-DD; default today
tickers list[string] | null no null override [production].universe
asset_class "equity" | "crypto" | "commodity" | "bond" | null no null

save_screen_as_universe

Store a screen as a universe for the lab and queue its refresh (follow up with wait_for_job). Without confirm=true returns a preview.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
universe_id string yes new universe id, e.g. cheap_tech
spec object | null no null the screen: rule filters (asset_classes, sectors, exclude_sectors, exchanges, min_price, min_adv), universe_id to start from a stored universe, filters [{"metric": "pe_ratio", "min": 0, "max": 15}], sort_by, descending, limit and columns. Metric ids come from list_screen_metrics
screen_id string | null no null one of your saved screens
mode "rule" | "snapshot" no "rule" rule reruns the screen at each rebalance (point in time); snapshot stores today's matches
start date | null no null YYYY-MM-DD
end date | null no null YYYY-MM-DD
rebalance "weekly" | "monthly" | "quarterly" no "monthly"
name string | null no null
confirm boolean no false must be true to apply; false (default) returns a preview only

set_event_alerts

Turn kinds of upcoming-event alerts on or off for yourself: earnings coming up, ex-dividend dates coming up, economic releases coming up. Off means none of that kind, not even in the app. Also picks the countries and the importance threshold (low, medium, high) of economic release alerts. Without confirm=true returns your current choices and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
earnings boolean | null no null true: on, false: off, omit: leave as is
dividends boolean | null no null true: on, false: off, omit: leave as is
economic boolean | null no null true: on, false: off, omit: leave as is
economic_countries list[string] | null no null countries for economic release alerts, such as US, EU, DE
economic_default_countries boolean no false true: follow your portfolios' base currencies again
economic_importance "low" | "medium" | "high" | null no null the lowest importance of release that alerts you
confirm boolean no false must be true to apply; false (default) returns a preview only

set_execution_algo

Work a portfolio's orders (or one strategy's) with an algo from the next tickets on. Without confirm=true returns the current settings and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
portfolio_id string yes
algo "adaptive" | "twap" | "vwap" yes
params object | null no null the algo's parameters
strategy_id string | null no null only this strategy's orders
confirm boolean no false must be true to apply; false (default) returns a preview only

shadow_strategy

Move a strategy to shadow: evaluated on a virtual portfolio, never traded. Needs a reason. Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
strategy_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides

subscribe

Follow a strategy in notify or paper mode. Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
strategy_id string yes
mode "notify" | "paper" no "notify" notify: signals only; paper: simulated orders on one of your portfolios
portfolio_id string | null no null one of your portfolios (needed for paper)
confirm boolean no false must be true to apply; false (default) returns a preview only

swap_model_version

Make a candidate version live, so the next tick trades it. Needs a passing swap check, or override=true with a reason of at least 20 characters, and the change is audited. Without confirm=true returns the swap check as a preview and changes nothing.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
strategy_id string yes
version integer yes the model version number
confirm boolean no false must be true to apply; false (default) returns a preview only
reason string | null no null why (logged in the audit trail); required for demotions and overrides
override boolean no false swap without a passing swap check; needs a reason of at least 20 characters

sync_connection

Sync one of your connections now: read balances, positions and activity from the provider (read-only there) into the linked broker portfolios. Without confirm=true returns a preview and syncs nothing.

Safety: writes, destructive, idempotent, open world. Needs confirm: yes.

Input Type Required Default Description
connection_id string yes
confirm boolean no false must be true to apply; false (default) returns a preview only

update_subscription

Turn one of your subscriptions on or off, or move it between notify and paper. Auto is refused here (it needs the web app). Without confirm=true returns a preview and changes nothing.

Safety: writes, destructive, not idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
subscription_id string yes
enabled boolean | null no null
mode "notify" | "paper" | "auto" | null no null notify or paper; auto is switched on in the web app (second factor)
reason string | null no null audited
confirm boolean no false must be true to apply; false (default) returns a preview only

update_universe

Replace a universe's definition. The members stay as they are until the next refresh (refresh_universe). Without confirm=true returns a preview with the current definition.

Safety: writes, destructive, idempotent, closed world. Needs confirm: yes.

Input Type Required Default Description
universe_id string yes universe id, e.g. sp500 or us_common
kind "list" | "exchange" | "rule" | "index" yes
spec object | null no null kind settings. list: {tickers, spans}. exchange: {exchange, source, security_types, include_delisted}. rule: {start, end, rebalance, min_adv, min_price, asset_classes, sectors, exclude_sectors, exchanges}. index: {index_id, source, start_date}
name string | null no null
description string | null no null
csv string | null no null list only: CSV with a ticker column (replaces spec)
confirm boolean no false must be true to apply; false (default) returns a preview only

Resources

URI Name Type Description
stonks://portfolio/summary portfolio_summary application/json Cash, total value and positions of the current portfolio

Clone this wiki locally