Backtest VaR and expected shortfall forecasts
assay_var_esUse this when you have VaR or Expected-Shortfall forecasts and need to know whether reality breached them more often or deeper than your claimed tail level allows -- a risk-forecast audit, not buy/sell advice. Does your risk model's VaR/ES forecast survive contact with reality? Exceedance backtest over YOUR forecasts -- a new claim type: risk numbers, not return claims.
Submit realised per-period returns plus the VaR forecasts your model produced ex ante (positive loss thresholds at tail level alpha, e.g. 0.05 for a 95% VaR), optionally the matching expected-shortfall forecasts. The breach count is graded on the EXACT binomial Basel traffic-light zones (Basel Committee 1996: green below cumulative probability 0.95, yellow to 0.9999, red above) -- published boundaries, no house thresholds; red earns the named demote VAR_BREACH_RATE_EXCESS. Kupiec's proportion-of-failures LR (1995) and Christoffersen's independence LR (1998) ride along -- clustered breaches flag the advisory var_breaches_clustered (a model blind to volatility clustering). If ES forecasts are supplied, a joint (VaR, ES) mixture e-process (e-backtesting, Wang & Ziegel) grades breach DEPTH: crossing Ville's anytime-valid 1% line earns ES_TAIL_UNDERSTATED. Supply benchmark_var_forecasts (and optionally benchmark_es_forecasts, e.g. a rolling historical quantile) and the assay also tests EQUAL PREDICTIVE ABILITY: Diebold-Mariano (1995) on a strictly consistent loss (quantile tick, or the joint FZ0 loss of Fissler & Ziegel 2016 when both sides carry ES) -- a naive benchmark that beats your model past the one-sided 5% line earns RISK_FORECAST_DOMINATED_BY_BENCHMARK; the attention zone to 10% is the advisory risk_forecast_lags_benchmark. Demote-only: too many breaches can kill, too few is the mis-calibration advisory var_breach_rate_sparse -- conservative models pass with a flag, never a blessing. Code-computed end to end, fail-closed on malformed or undersized input (a series too short to reach the red zone answers insufficient_evidence instead of a hollow pass). Works for any asset class. NOT financial advice; no order path. Price: per check; see https://api.alphaassay.com/v1/meta/pricing (api_key required -- account setup at https://api.alphaassay.com/account).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| alpha | No | Tail level, e.g. 0.05 for a 95% VaR (0.001-0.25). Sets the Basel traffic-light expectation. | |
| api_key | No | API key for a paid MCP check. Hosted Streamable HTTP clients should send it in the Authorization: Bearer transport header so the model never sees the secret; local stdio callers may supply the raw key in this tool argument without a Bearer prefix. Create an account at https://api.alphaassay.com/account; the current free allowance and prices are published at https://api.alphaassay.com/v1/meta/pricing. Paid MCP calls use API-key credits; x402 buys only the separate REST POST /x402/v1/gauntlet and is not MCP billing. | |
| returns | Yes | Realised per-period returns (the outcomes your risk model was forecasting for). | |
| request_id | No | Optional idempotency key for this paid execution. Retry the same request_id with the same payload to replay one stored result without another charge; reuse with a different payload returns idempotency_conflict. | |
| es_forecasts | No | Optional matching expected-shortfall forecasts; enables the joint (VaR, ES) e-process tail test. | |
| var_forecasts | Yes | Your model's ex-ante VaR forecasts (positive loss thresholds at level alpha) to backtest for breaches. | |
| benchmark_es_forecasts | No | Optional benchmark ES forecasts; switches the EPA test to the joint FZ0 loss. | |
| benchmark_var_forecasts | No | Optional naive/benchmark VaR forecasts (e.g. a rolling historical quantile) for the Diebold-Mariano equal-predictive-ability test -- lose to it and the claim is demoted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |