Datasets & Portfolios

Portfolio Input

Define the portfolio, dataset, and simulation parameters used by the Quant Risk API to calculate portfolio risk.

Define Your Risk Request

A risk calculation request combines a dataset, portfolio definition, and simulation parameters. The API uses the selected assets and their portfolio weights together with the requested confidence level, time horizon, and simulation settings.

{
  "dataset_id": "ds_sample_001_970079",
  "portfolio_value": 100000,
  "currency": "USD",
  "portfolio": [
    {
      "symbol": "AAPL",
      "weight": 0.6
    },
    {
      "symbol": "BTC-USD",
      "weight": 0.4
    }
  ],
  "degrees_of_freedom": 5,
  "portfolio_mode": "buy_and_hold",
  "confidence_level": 0.95,
  "time_horizon": 1,
  "simulations": 1000,
  "method": "all",
  "method_options": {
    "monte_carlo_normal": {
      "include_chart_data": true
    }
  }
}

Request Fields

Field	Type	Description
`dataset_id`	`string`	Identifier of the dataset containing the historical price data used for the risk calculation.
`portfolio_value`	`number`	Initial total monetary value of the portfolio. This value is used as the starting portfolio value for the simulation. Must be greater than 0 and no greater than 1,000,000,000 USD.
`currency`	`string`	Currency of the portfolio value and resulting monetary risk metrics. Currently, only USD is supported.
`portfolio`	`array`	List of assets included in the portfolio and the weight assigned to each asset.
`symbol`	`string`	Asset symbol that must match an asset available in the selected dataset.
`weight`	`number`	Portfolio weight assigned to the asset. For a standard long-only portfolio, weights must be greater than zero and must sum to `1.0`.
`degrees_of_freedom`	`integer`	Degrees of freedom used by the Monte Carlo Student-t model. The default value is `3`. This field is only relevant when Student-t simulation is requested.
`portfolio_mode`	`string`	Defines how the portfolio positions are handled during the simulation. The current v1 mode is `buy_and_hold`.
`confidence_level`	`number`	Confidence level used to calculate VaR and CVaR. The v1 allowed range is `0.90–0.999`.
`time_horizon`	`integer`	Number of simulated time steps. The v1 allowed range is `1–252`.
`simulations`	`integer`	Number of Monte Carlo simulation scenarios. The v1 minimum is `1,000`. The maximum is determined by the active tier's `max_simulations` limit.
`method`	`string`	Risk model or models to run. For example, `monte_carlo_normal`, `monte_carlo_student_t`, or `all`.
`method_options`	`object`	Optional configuration for individual risk models. Options are applied only to the corresponding model.

Portfolio Rules

Portfolio definitions must satisfy the following rules:

The number of assets must be between 1 and 50.
Each symbol must exist in the selected dataset.
Each portfolio weight must be greater than zero.
Portfolio weights must sum to 1.0.
The initial portfolio_value must be greater than zero.

AAPL 0.60

BTC-USD 0.40

Total 1.00

Simulation Rules

The simulation parameters are shared across Monte Carlo models, with Student-t introducing one additional model-specific parameter.

Parameter	Allowed Range	Notes
`confidence_level`	`0.90–0.999`	Recommended values include `0.95` and `0.99`.
`simulations`	`1,000–tier.max_simulations`	The active subscription tier determines the maximum.
`time_horizon`	`1–252`	For daily return data, 252 represents approximately one trading year.
`n_assets`	`1–50`	Determined by the number of assets in the portfolio.
`degrees_of_freedom`	`3–100`	Student-t only. Default: `3`.

Historical Data Requirement

At least 30 historical observations are required to estimate the mean return and covariance matrix used by the simulation. More observations generally provide more stable parameter estimates.

Tail Sample Warning

Tail-risk estimates depend on the number of simulated observations available in the lower tail. The API evaluates the approximate tail sample size using:

tail_samples = simulations × (1 - confidence_level)

When the resulting tail sample is small, the API may return a warning that the selected simulation count may be insufficient for a stable tail-risk estimate.

Example Request

The following example defines a USD 100,000 portfolio consisting of AAPL and BTC-USD and requests all available risk methods.

{
  "dataset_id": "ds_sample_001_970079",
  "portfolio_value": 100000,
  "currency": "USD",

  "portfolio": [
    {
      "symbol": "AAPL",
      "weight": 0.6
    },
    {
      "symbol": "BTC-USD",
      "weight": 0.4
    }
  ],

  "degrees_of_freedom": 5,
  "portfolio_mode": "buy_and_hold",
  "confidence_level": 0.95,
  "time_horizon": 1,
  "simulations": 1000,

  "method": "all",

  "method_options": {
    "monte_carlo_normal": {
      "include_chart_data": true
    }
  }
}

dataset_id selects the historical price dataset used by the calculation.

portfolio_value defines the initial total portfolio value.

portfolio contains the assets and their portfolio weights. In this example, AAPL = 0.60 and BTC-USD = 0.40, giving a total weight of 1.00.

portfolio_mode is set to buy_and_hold, meaning positions are allowed to evolve according to simulated returns without rebalancing during the simulated horizon.

confidence_level is set to 0.95, so VaR is calculated from the lower 5% tail of the simulated P&L distribution.

simulations is set to 1000, which is the v1 minimum.

degrees_of_freedom is set to 5. This parameter is used by the Student-t Monte Carlo model and does not change the Normal model.

Weight Validation Example

{
  "portfolio": [
    {
      "symbol": "AAPL",
      "weight": 0.7
    },
    {
      "symbol": "BTC-USD",
      "weight": 0.5
    }
  ]
}

This portfolio is invalid because the weights sum to 1.2 instead of 1.0.

Confidence Level Validation Example

{
  "confidence_level": 0.80
}

This value is invalid for v1 because the allowed confidence level range is 0.90–0.999.

Student-t Validation Example

{
  "degrees_of_freedom": 2
}

This value is invalid because the standardized Student-t model requires degrees of freedom between 3 and 100.