Skip to content
TotalFinance

One registry, several front doors

Operation catalog

48 registered operations. The default profile exposes 23; selected packs and permissions decide what a given server actually offers. This is a curated serializable subset, not the whole SDK.

Machine-readable: operation-catalog.json with full input and output schemas.

artifact pack

backtest pack

Run a cross-sectional backtestOpt-intotalfinance_backtest_cross_sectional_runBacktest a point-in-time cross-sectional strategy: a returns dataset with declared features, a universe history with entries and exits, one declarative signal (a versioned factor recipe, a composite score, or a screen), a rebalance schedule, and a portfolio construction (quantile/count/fraction selection on each side; equal, score, inverse-volatility, or risk-budget weights; dollar/sector/beta/factor neutrality; position, weight, turnover, and participation caps — every trim a reported goal). Fills go through the execution policy into the portfolio ledger; the final value reconciles to the ledger NAV. Rebalances, holdings, fills, the ledger, the timeline, attribution, the benchmark block, and the performance summary — crossSectionalBacktest(...) verbatim. Opt-in (backtestPack): payloads and runtime are heavier than the default set; bulk row sets above the row cap travel by handle.Bench a baseline policy over one trading-environment episodeOpt-intotalfinance_backtest_environment_episodeRun one of the six maintained baseline policies through the deterministic trading environment over a catalogue episode (or a named declarative definition) at a seed, and return Agent Bench's report for that episode: operational conformance (look-ahead, replay equality, duplicate orders under the retry drive, external-order attempts, reconciliation; the mask and limit counts) apart from strategy quality (return, volatility, Sharpe, Sortino, drawdown, turnover, cost, exposure, violations) — no single score by design. With artifact: 'embed', the recorded episode travels as an `environment` run artifact that replays to its run hash. Declarative inputs only: a TypeScript policy or a reward goal callback is SDK-only. Opt-in (backtestPack).Run an options backtestOpt-intotalfinance_backtest_options_runBacktest a declarative options strategy over chain snapshots: structure selection by delta and DTE, exit and roll triggers, optional delta hedging, declarative commission and slippage, American assignment modelling, and the marking policy (current-quote or entry volatility; what a missing mark does). Several rules may hold several trades at once (book), pre-trade limits reject entries with rows, combo or legged fills, quote freshness, split lineage, dividend evidence, the surface summary, and the portfolio ledger the equity reconciles to. Equity points, trades with per-leg attribution and mark counts, settlements, and the standard performance summary. The result is optionsBacktest(...) verbatim. Opt-in (backtestPack): payloads and runtime are heavier than the default set.Run a portfolio backtestOpt-intotalfinance_backtest_portfolio_runBacktest a multi-asset portfolio through the ledger: instruments with built-in adapters (equity, etf, option, future, fx-forward, crypto-spot, crypto-perpetual, bond), market data by row set, a model or inline targets on a rebalance schedule, an execution policy with settlement lags, external flows, a calendar, and the margin check with forced liquidation. Every fill, flow, lifecycle fact, and liquidation is a portfolio event; the equity is the ledger's net asset value. The result is portfolioBacktest(...) verbatim. Opt-in (backtestPack): payloads and runtime are heavier than the default set; bulk row sets above the row cap travel by handle.Run a vectorized backtestOpt-intotalfinance_backtest_vectorized_runRun a single-asset vectorized backtest: signal-following fills at close, optional bps fees. Returns final value, turnover, and the performance summary; every hidden policy the run assumed (fill timing, costs, slippage, settlement, calendar, margin) is echoed in `assumptions`, and the implementation-risk warnings (look-ahead, data alignment) ride `diagnostics`. Deliberately opt-in (backtestPack) — payloads and runtime are heavier than the default tools. executionLag shifts signal lookup before rebalance sampling; a month-end target can miss the next monthly sample. Use the SDK researchProtocol and selection-hygiene workflow before comparing candidates; see docs/guides/dogfood-journeys.md.

calendar pack

crypto pack

fixed_income pack

options pack

performance pack

portfolio pack

Analyze a portfolio (snapshot, timeline, monitor)Opt-intotalfinance_portfolio_analyzeOne report of up to three direct results: the valuation snapshot at `asOf` (always), the dated timeline with P&L since each prior mark and drawdown (when `marks` are supplied), and the policy monitor with its alerts and carried state (when `monitor` is supplied). Each result is the direct function verbatim; nothing is aggregated across them, and one `assumptions` says which parts ran and why the others did not.Explain portfolio P&L between two marksOpt-intotalfinance_portfolio_explain_pnlExplain the change in net asset value between two dated valuation marks: external flows, investment return, and the identity components (realized, unrealized, income, transaction costs, financing, foreign exchange) that reconcile to it with a published residual, by currency and by grouping. The result is portfolioPnl(...) verbatim.Open a portfolio ledger or handle and inspect a bounded pageOpt-intotalfinance_portfolio_inspectOpen a returned totalfinance://portfolios/... handle through the same configured store, or import an inline serialized ledger for read-only inspection. Revalidates and replays the ledger. Summary returns identity/counts; events, positions and cash return bounded previews (default 20, maximum 100 rows). This does not value the portfolio; use portfolio.snapshot with explicit marks. Opt-in (portfolioPack).Propose a rebalance (a proposal, never an order)Opt-intotalfinance_portfolio_rebalance_proposalFold the ledger snapshot to its state, mark it from the market snapshot, and propose the trades that take the portfolio to the policy targets (or only the drifted ones) under the policy limits, lot sizes, minimum notional, transaction-cost estimates, and an optional external flow. The result is proposePortfolioRebalance(...) verbatim: weights before and after, the cash summary, the trades with their estimates, the objective, and every target it could not resolve. Read-only by construction — it returns a proposal and places nothing. Opt-in (portfolioPack).Value a portfolio at an instantOpt-intotalfinance_portfolio_snapshotValue every cash balance and position of a portfolio at one instant from a Gate B market snapshot: net asset value in the base currency, per-account cash rows (settled and unsettled), per-position marks, cost basis and unrealized P&L. Supply the portfolio as its serialized ledger envelope (re-hydrated through readPortfolioLedgerSnapshot) or as a derived PortfolioState. The result is portfolioSnapshot(...) verbatim.

trade pack

Create and store an explicitly defined portfolio ledgerOpt-intotalfinance_portfolio_createStart here before portfolio.record_events: supply durable portfolioId, baseCurrency and explicit initial events (an empty array creates no cash). Uses the existing artifact store and ledger reducer. Requires portfolio:write and a writable store. Save the returned handle and open it with portfolio.inspect from portfolioPack (enable both trade and portfolio packs, or use --profile full); subsequent event writes return a new immutable handle. Opt-in (tradePack).Apply events to a ledger and store the new ledgerOpt-intotalfinance_portfolio_record_eventsFold validated portfolio events (fills from trade.submit, deposits, corporate actions) onto a ledger through the ledger's own reducer and put the new ledger into the artifact store as a content-addressed portfolio handle. The write is the put: an unchanged ledger is the same handle; identical replays fold once and applied counts only new events. Changed event bodies are refused. Requires a writable artifact store and the portfolio:write capability. Opt-in (tradePack).Mint an authorization grant for a preflighted planOpt-intotalfinance_trade_authorizeBind human authority to one plan and one preflight report: the plan hash, the portfolio and market hashes preflight judged, the market instant and an age allowance, the paper mode, the account, a variance envelope, an expiry, the approver, and a closed set of idempotency keys. Refuses a denied preflight, an unjudged plan, or a stale expiry. The grant is put into the authorization store under its content hash and returned with its handle. Requires the trade:approve capability. Opt-in (tradePack).Cancel an open paper orderOpt-intotalfinance_trade_cancelJournal cancel-requested then cancelled for an open order in the journal store under `<sourceId>:journal`; a terminal order is not cancelled twice (accepted: false, the state says why). Cancelling a combo leg cancels all remaining legs of that plan-local combo. Both the original journal and authorization stores are required to recover pending submissions before cancellation; no new grant is needed. A fill delivered after the cancellation is Decision 6's late-fill path. Paper only; requires trade:paper. Opt-in (tradePack).Preflight a trade plan against the ledger, the market, and the policyOpt-intotalfinance_trade_preflightNormalize an intent (or take an execution plan) and judge it: the portfolio before and after through the ledger's own fold of hypothetical fills, every policy check with its verdict, declared-rate cost estimates, the monitor's alerts on the after-state, and one decision — allow only when every check passes, deny on any failure, require-approval when evidence is missing; never an allow from missing information. No effect. Opt-in (tradePack).Reconcile an execution journal to the ledgerOpt-intotalfinance_trade_reconcileJoin the journal's order states (from the journal store by `journalId`, or inline events) to the ledger's fills under the execution source in both directions, compare delivered fill quantities per order within an explicit tolerance, list the unresolved orders, and — with an external snapshot — compose reconcilePortfolio verbatim. With planHash, exclude other plans’ journaled orders and fills from both joins; unattributed source fills remain discrepancies. External snapshots are judged over the whole portfolio. reconciled is true only when everything agrees and no order is unresolved. No effect; requires trade:paper. Opt-in (tradePack).Submit an authorized plan to the paper brokerOpt-intotalfinance_trade_submitVerify the grant against the plan, the portfolio and market hashes, the market instant, the account, and the idempotency key; journal submitted and acknowledged; return the content-addressed receipt — the SAME receipt for a retry with the same key and plan (no second order), trade.idempotency_conflict for the same key with another plan, trade.grant_expired for an expired grant. With `observations`, the open orders meet the market through the engines' own fill path. Top-level fills/events are only this call’s new deltas; the submission receipt is immutable. `currentOrders` is the authoritative journal-derived current state and cumulative filled/remaining quantities for this receipt. `recovery: { fills, events }` contains all persisted normalized fills and reproducible ledger envelopes for this receipt’s orders, including this call’s fills. Retry after a lost response and apply recovery.events with portfolio.record_events; identical events fold once. Recovery grows with later fills without replaying the fill engine. The journal continues transactionally from the required journal store under `<sourceId>:journal`; retries must retain that store and source. A grant atomically records its exact prepared submission before journal commit: a retry with the same key into the same store/journal recovers those events and reads the same receipt; any other submission of the grant is trade.grant_consumed. Every journal write recovers earlier pending submissions before allocating new identities. Inline history must match persisted history exactly. Inline grants must exist unchanged in the trusted authorization store. Paper only; requires trade:paper. Opt-in (tradePack).

research pack

risk pack

scenario pack

strategy pack

structure pack

technical_analysis pack

Calculate a technical indicatorDefaulttotalfinance_technical_analysis_calculateCompute any of TotalFinance’s ~300 registered technical indicators over a price series. Pass canonical core Bar records directly under bars; symbol, timestampMs, vwap and adjusted are declared fields. Source records require open, one symbol and strictly increasing unique timestamps; no stripping or SDK preprocessing is needed. Identity/time are validated before OHLCV projection; retain the original source/provenance alongside the result. Close-based (`series`) indicators take `closes`; bar-based indicators take `bars` (OHLCV objects) or parallel column arrays under `series`; pair indicators (e.g. beta, correl) take `x` and `y`. Use `totalfinance.technical_analysis.list` to discover indicator names, input kinds, and parameters. Output is aligned to input length with null during warmup; `assumptions.parameters` echoes the parameters actually used (declared defaults merged with yours), and `diagnostics.warmup` is the first real index.Describe one technical indicatorDefaulttotalfinance_technical_analysis_describeReturn the full card for a single indicator (alias-aware): category, input kind, parameters, defaults, which parameters are required, its warmup (leading bars before the first real value), and its cross-library aliases. The token-lean way to learn one indicator without listing all ~335. Discover names with `totalfinance.technical_analysis.list`; compute with `totalfinance.technical_analysis.calculate`.List technical indicatorsDefaulttotalfinance_technical_analysis_listDiscover the technical indicators available to `totalfinance.technical_analysis.calculate`. Returns each indicator’s name, category, input kind (series | bars | pair), parameters, defaults, and which parameters are required. Narrow the ~335-indicator catalog with `search` (matches a name or a TA-Lib/pandas/TradingView alias) and/or `category`, and page it with `limit` (default 50) / `offset` (`total` is the full match count). For one indicator’s full card (including its warmup), use `totalfinance.technical_analysis.describe`. To browse momentum, use { category: "momentum" }, rather than searching the name momentum. Then pass a name to `totalfinance.technical_analysis.calculate`.

valuation pack

volatility pack

Event-volatility decomposition (earnings)Defaulttotalfinance_volatility_eventDecompose pre-event implied volatility into base + event variance and the implied one-day event move (the earnings-move read): eventMove = √max(0, atmVolatility²·timeToExpiryYears − baseVolatility²·timeToExpiryYears). Optionally reports the variance risk premium when `realizedVolatility` is supplied.Expected move (1σ)Defaulttotalfinance_volatility_expected_moveCompute the expected 1-sigma move of the underlying by expiry — the lognormal ±1σ band and the expected absolute move. Provide `impliedVolatility` + `timeToExpiryYears` to imply it from volatility, or `straddlePrice` to imply it from the ATM straddle. Risk-neutral, not a directional forecast.IV rank / percentile / statsDefaulttotalfinance_volatility_metricsWhere does the current implied volatility sit against its history? Returns IV rank (min–max position, 0–100), IV percentile (share of history below current, 0–100), and summary statistics — the standard "is IV high?" read before selling or buying premium.Probability of finishing in-the-moneyDefaulttotalfinance_volatility_probability_in_the_moneyRisk-neutral probability that an option finishes in the money at expiry — N(d2) for a call, N(−d2) for a put. This is the model probability P(S_t ⋛ K), not a real-world forecast.Probability of touching a levelDefaulttotalfinance_volatility_probability_of_touchRisk-neutral probability that the underlying TOUCHES `barrier` at any time before expiry (first-passage probability for geometric Brownian motion). Useful for stop/target and one-touch reasoning.Fit an implied-vol surfaceDefaulttotalfinance_volatility_surfaceFit an implied-volatility surface from chain quotes (IV given directly, or implied from price) and return the surface rows, per-expiry ATM term structure, and the static-arbitrage report (calendar/butterfly violations). The surface never fabricates: non-convergence and extrapolation are reported in diagnostics/warnings.