Developer documentation API v1

Portfolio risk and scenario analysis

Measure shared exposures, tail losses and the effect of adverse conditions.

The risk snapshot

risk.stress binds the account snapshot, risk-model revision, scenario-set revision and confidence level. Holdings, pending orders and unsettled movements retain separate components. Currency conversions and valuation observations share the declared cutoff. An incomplete material exposure blocks a complete portfolio risk result.

Factor decomposition

B contains instrument factor loadings, Ω factor covariance and D residual covariance under the selected model. Asset order, horizon, units and estimator window are pinned. A diagonal D assumes uncorrelated residuals; a model using that simplification records it explicitly. Factor labels describe statistical or economic exposures, not necessarily causal mechanisms.

r=Bf+\epsilon,\qquad\Sigma=B\Omega B^\top+D,\qquad\operatorname{Var}(R_p)=w^\top\Sigma w

Euler volatility contribution

For nonzero portfolio volatility and fixed covariance, the contributions sum to total volatility. Hedging positions can have negative contributions. This homogeneous decomposition is not a forecast of realized loss and does not capture nonlinear option repricing by itself.

\sigma_p=\sqrt{w^\top\Sigma w},\qquad RC_i=\frac{w_i(\Sigma w)_i}{\sigma_p},\qquad\sum_i RC_i=\sigma_p

Expected shortfall under weighted scenarios

Lₛ is loss in the reporting currency under scenario s; pₛ≥0 and sums to one; 0<α<1. The representation handles probability mass at the quantile. Return-based loss fractions and currency losses are never mixed. Scenarios, weights and horizon determine the estimate; unweighted hypothetical stress cases are reported separately, without invented occurrence probabilities.

\operatorname{ES}_\alpha(L)=\min_{\eta}\left[\eta+\frac{1}{1-\alpha}\sum_{s=1}^{m}p_s\max(L_s-\eta,0)\right]

Probability mass at the tail boundary

Five synthetic losses of minus 10, 0, 10, 20 and 40 dollars have probabilities 10, 30, 30, 20 and 10 percent. At alpha 80 percent, VaR is 20 dollars and ES is 30 dollars. — The worst 20% contains the entire 10% atom at $40 and half the 20% atom at $20. Averaging this tail mass gives $30. Including the whole VaR atom would average 30% of outcomes and would not compute ES at α = 80%. These are teaching scenarios, not assigned probabilities for an actual portfolio. View full size ↗

Request a stress analysis

POST /v1/tool-invocations. Confidence is an analysis parameter, not a guarantee that larger losses cannot occur.

json

{
  "agent_revision_id": "agr_example_3",
  "tool": "risk.stress",
  "input": {
    "account_snapshot_id": "acctsnap_example_1",
    "risk_model_revision": "risk-example-r1",
    "scenario_set_revision": "scenarios-example-r2",
    "confidence": 0.975
  }
}

Scenario dimensions

Shock	Required treatment
Market, sector and currency	Joint shocks, factor overlap and currency translation.
Liquidity contraction	Wider spread, reduced executable size and increased liquidation cost.
Token basis	Independent token/underlying prices and time-valid exposure multiplier.
Options or other nonlinear instruments	Full contract repricing or an explicitly bounded approximation, including volatility and expiry.
Funding and collateral	Borrow availability, funding changes, margin and liquidation conditions where the account supports them.

Interpreting a risk result

The report contains current account exposures, factor diagnostics, volatility contributions where defined, weighted tail metrics when scenario probabilities exist, named stress losses and model coverage. This endpoint analyzes the referenced account snapshot. Candidate allocation feasibility and binding constraints belong to the portfolio-proposal calculation.

Scenario P&L uses the declared repricing and cost model. It does not net away cash needed for settlement or assume that a hedge can be executed at a stale reference price. A risk-reducing sale is assessed against its risk objective rather than requiring a positive return forecast.

Methods

Rockafellar and Uryasev: CVaR optimizationScenario-based tail-loss representation.Boyd et al.: multi-period tradingPortfolio decisions with trading costs, holding costs and constraints.