Value at Risk (VaR)

Calculate the Value at Risk (VaR) of an investment portfolio or asset’s returns.

Value at Risk (VaR) is a risk management metric that quantifies the maximum potential loss an investment portfolio or asset may experience over a specified time horizon and confidence level. It provides insights into the downside risk associated with an investment and helps investors make informed decisions about risk tolerance.

The VaR is calculated as the quantile of the return distribution, representing the loss threshold that is only exceeded with tail probability alpha (e.g., in 5% of the periods for alpha=0.05, the 95% confidence level).

Value at Risk is a quantile: it says how bad a period gets at the chosen confidence level, not how bad the periods beyond it are, so two assets with the same VaR can have very different tails (see the Conditional Value at Risk for that). Historical VaR depends heavily on the window: one calm year gives a much smaller figure than a window that includes a crisis, so compare assets over the same period and confidence level. Scaling a daily VaR to a longer horizon with the square root of time assumes independent returns, which tends to understate risk when volatility clusters.

The formula is as follows (with the default distribution=”historic” and alpha=0.05):

\[\text{VaR} = \operatorname{Quantile}(\text{Returns},\; \alpha)\]

The quantile interpolates linearly between the two nearest returns and the VaR is reported as a return (negative for a loss). With rolling, the same quantile is taken over each trailing window of rolling returns. The other distributions replace the empirical quantile with:

\[\text{Gaussian VaR} = \text{Mean} + z \cdot \text{Std}\] \[\text{Cornish-Fisher VaR} = \text{Mean} + z_{cf} \cdot \text{Std}\] \[z_{cf} = z + (z ^{2} - 1) \cdot S / 6 + (z ^{3} - 3 \cdot z) \cdot K / 24 - (2 \cdot z ^{3} - 5 \cdot z) \cdot S ^{2} / 36\] \[\text{Student-T VaR} = \text{Location} + \text{Scale} \cdot t_{v} ^{-1} (\alpha)\] \[\text{EVT VaR} = - (u + (\text{Scale\_GPD} / \xi) \cdot ((\alpha / p) ^{- \xi} - 1))\]

Where z is the standard normal quantile at alpha, Std the sample standard deviation (ddof=1), S the sample skewness and K the sample excess kurtosis. The Student-T degrees of freedom v, Location and Scale are fitted by maximum likelihood. For “evt”, u is the loss at threshold_percentile, xi and Scale_GPD the shape and scale of the Generalized Pareto Distribution fitted to the losses above it and p the fraction of losses above it.

Also known as: VaR, maximum expected loss, portfolio loss risk.

Value at Risk (VaR) in Python or via the MCP

Install the Finance Toolkit with:

pip install financetoolkit -U

Then call get_value_at_risk as shown below.

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["BTCUSD", "ETHUSD", "^GSPC"],
    api_key="FINANCIAL_MODELING_PREP_KEY",
    start_date="2021-01-01",
    end_date="2025-12-31",
)

toolkit.risk.get_value_at_risk(period="yearly", within_period=True)

Or, after setting up the Finance Toolkit MCP, ask:

What was the daily 95% Value at Risk of Bitcoin, Ether and the S&P 500 in each year from 2021 to 2025?

Which returns:

	BTCUSD	ETHUSD	^GSPC	Benchmark
2021	-0.0626	-0.0838	-0.0087	-0.0089
2022	-0.0574	-0.0742	-0.02	-0.0203
2023	-0.0313	-0.0374	-0.0116	-0.0117
2024	-0.0407	-0.0533	-0.0094	-0.0096
2025	-0.0358	-0.0569	-0.0113	-0.0113

Parameters

get_value_at_risk accepts the following parameters.

Parameter	Type	Description	Example
`period`	`str`	The data frequency for returns (daily, weekly, monthly, quarterly, or yearly). Defaults to “daily”.	`"weekly"`
`alpha`	`float`	The tail probability for the VaR calculation (e.g., 0.05 for the 95% confidence level). Defaults to 0.05.	`0.01`
`within_period`	`bool`	Whether to calculate VaR within the specified period or for the entire period. Thus whether to look at the VaR within a specific year (if period = ‘yearly’) or look at the entirety of all years. Defaults to False. Note that this requires intraday data when period = ‘daily’, since a single day only nests observations when intraday data was fetched.	`True`
`rolling`	`int`	The rolling window size to use for the calculation. If set, VaR is calculated over a rolling window of this many periods across the full return history instead of per `period` (e.g. a rolling 60-day VaR). Only available for `distribution="historic"`; see `get_var_backtest` for a rolling, out-of-sample VaR path under the parametric distributions. Defaults to None.	`20`
`rounding`	`int \| None`	The number of decimals to round the results to. Defaults to None, which uses the rounding of the Toolkit (4 unless set otherwise).	`2`
`growth`	`bool`	Whether to calculate the growth of the VaR values over time. Defaults to False.	`True`
`lag`	`int \| list[int]`	The lag to use for the growth calculation. Defaults to 1.	`4`
`standardize`	`bool`	Whether to standardize (Z-Score) the result. When combined with growth=True, standardizes the growth values instead of the raw values. Defaults to False.	`True`
`distribution`	`str`	The distribution to use for the VaR calculations (historic, gaussian, cornish-fisher, studentt or evt). Defaults to “historic”. The parametric distributions use the sample standard deviation; “cornish-fisher” adjusts the gaussian quantile for the skewness and excess kurtosis of the returns (see `var_model.get_var_cornish_fisher`) and “studentt” uses the quantile of a Student-T distribution fitted by maximum likelihood.	`"studentt"`
`threshold_percentile`	`float`	Only used when `distribution` is “evt”. The percentile of losses above which the Generalized Pareto Distribution is fitted; `alpha` can be at most 1 - `threshold_percentile`, and a larger `alpha` gives an empty result (with a logged error). Defaults to 0.95.	`0.9`

Value at Risk (VaR) in Python or via the MCP

Parameters

Related Value at Risk and Tail Risk