Risk metrics

Use risk_metrics when calculation_type includes analytics and you want the API to calculate historical risk measures such as Value-at-Risk or Expected Shortfall.

This configuration controls the historical window, confidence interval, risk horizon, returns mode, and bond-pricing options used by the analytics engine.

Overview

The risk_metrics object is used on POST /portfolios alongside the submitted portfolio.

It is designed for historical analytics including:

Value-at-Risk
Expected Shortfall
configurable confidence intervals
configurable lookback windows
configurable margin period of risk
absolute or relative returns modes

How It Works

When calculation_type includes analytics, the API can calculate historical risk measures across the submitted portfolio using the configuration supplied in risk_metrics.

At a high level:

lookback controls how much historical data is used
ci controls the confidence level
method chooses between Value-at-Risk and Expected Shortfall
mpor controls the risk horizon or liquidity horizon in days
mode controls whether returns are treated as absolute or relative

For fixed income analytics, the object also exposes bond-specific pricing controls.

Fields

Name
lookback
Type
integer
Description
Historical lookback period in business days. Default is 250.
Name
ci
Type
number
Description
Confidence interval percentage, for example 99 for a 99% confidence level. Default is 99.
Name
method
Type
string
Description
Risk method. Supported values are value-at-risk and expected-shortfall. Default is value-at-risk.
Name
mpor
Type
integer
Description
Margin period of risk in days. Default is 1.
Name
mode
Type
string
Description
Returns mode. Supported values are absolute and relative. Default is absolute.
Name
bond_pricing_version
Type
integer
Description
Bond pricing model version. Default is 1.
Name
bond_use_continuous_compounding
Type
boolean
Description
Use continuous compounding when true, or annual compounding when false. Default is true.

Example request

This example uses historical Value-at-Risk with a 250-day lookback, 99% confidence interval, and 1-day MPOR:

{
  "calculation_type": "margins,analytics",
  "vendor_symbology": "clearing",
  "currency_code": "USD",
  "use_closest_match": true,
  "risk_metrics": {
    "lookback": 250,
    "ci": 99,
    "method": "value-at-risk",
    "mpor": 1,
    "mode": "absolute",
    "bond_pricing_version": 1,
    "bond_use_continuous_compounding": true
  },
  "portfolio": [
    {
      "account_code": "ETD_Account",
      "exchange_code": "NYMEX",
      "contract_code": "CL",
      "contract_type": "FUT",
      "contract_expiry": "202612",
      "net_position": "500",
      "account_type": "H"
    },
    {
      "account_code": "ETD_Account",
      "exchange_code": "NYMEX",
      "contract_code": "LO",
      "contract_type": "CALL",
      "contract_expiry": "202612",
      "contract_strike": "75",
      "net_position": "-200",
      "account_type": "H"
    }
  ]
}

To switch to Expected Shortfall, change:

{
  "method": "expected-shortfall"
}

Reading the results

The public multi-asset example prints account-level analytics including value_at_risk from the response.

That means risk_metrics is best documented as the control block for analytics configuration, while the resulting analytics values appear in the returned account results.

Typical uses include:

comparing VaR versus Expected Shortfall under the same portfolio
testing the effect of different confidence intervals
extending the historical lookback window
increasing MPOR for longer liquidation assumptions
choosing between absolute and relative return modes

Go to the Portfolios endpoint reference

Open the public multi-asset analytics example