Quick Start
Upload historical market data, define your portfolio, and calculate portfolio risk using the Quant Risk API.
Overview
Quant Risk API is a quantitative risk analysis API designed to estimate potential losses for multi-asset portfolios.
You provide historical market data and define the portfolio you want to analyze. Quant Risk API then calculates portfolio risk over a selected confidence level and time horizon.
The API currently supports Monte Carlo simulation using a normal distribution, Monte Carlo simulation using a Student's t distribution, and historical simulation.
How it works
Quant Risk API uses a two-step workflow.
Step 1
Upload a dataset
Upload a CSV file containing historical market data. The API returns a dataset identifier that represents the uploaded dataset.
Step 2
Calculate portfolio risk
Use the dataset identifier together with your portfolio configuration to calculate risk metrics using one or more quantitative models.
Prerequisites
Before making requests, make sure you have the following:
- A Quant Risk API key.
- A CSV file containing historical market data.
- An HTTP client such as cURL, Postman, Python, or JavaScript.
Keep your API key secure
Every API request must include your API key using theX-API-Keyheader. Do not expose your API key in public repositories or client-side applications.
Step 1: Upload a dataset
Upload a CSV file containing the historical market data that will be used for portfolio risk calculations.
Send your API key using the X-API-Key header.
curl -X POST "https://quant-risk.scratio.com/api/v1/risk/datasets/upload" \
-H "X-API-Key: qr_live_xxxxxxx" \
-F "file=@market_data.csv"A successful upload returns a dataset_id that you will use when calculating portfolio risk.
{
"detail": {
"status": "success",
"dataset_id": "ds_xxxxxx"
}
}Step 2: Calculate portfolio risk
Use the dataset identifier returned from the upload request together with your portfolio configuration.
The method parameter determines which risk model is used.
curl -X POST "https://quant-risk.scratio.com/api/v1/risk/calculate" \
-H "X-API-Key: qr_live_xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "ds_xxxxxx",
"method": "all",
"portfolio_value": 10000,
"currency": "USD",
"portfolio": [
{
"symbol": "AAPL",
"weight": 0.6
},
{
"symbol": "BTC-USD",
"weight": 0.4
}
],
"portfolio_mode": "buy_and_hold",
"confidence_level": 0.95,
"time_horizon": 10,
"simulations": 1000
}'Understanding the response
A successful calculation returns metadata about the dataset and portfolio, followed by the results generated by the selected risk models.
The example below is abbreviated for readability.
{
"status": "success",
"meta": {
"data_source": {
"type": "custom"
},
"assets": [
"AAPL",
"BTC-USD"
],
"initial_values": [
6000,
4000
],
"simulation_counts": 10000,
"portfolio_value": 10000,
"confidence_level": 0.95,
"time_horizon_days": 10,
"observations_used": 30
},
"result": {
"monte_carlo_normal": {
"risk_metrics": {
"var": {
"value": 339.65,
"unit": "currency",
"meaning": "estimated_loss"
},
"cvar": {
"value": 468.74,
"unit": "currency",
"meaning": "average_tail_loss"
},
"pnl_quantile": {
"value": -339.65,
"unit": "currency"
}
},
"description": {
"summary": "At a 95% confidence level over a 10-day horizon, the estimated VaR is 339.65 and CVaR is 468.74."
},
"warnings": [],
"chart_data": {
"type": "pnl_distribution",
"bins": [
-993.93,
-941.14,
-888.36,
"...",
1645.20
],
"counts": [
2,
2,
2,
"...",
1
],
"var_threshold": -339.65,
"cvar_value": -468.74
}
},
"monte_carlo_student_t": {},
"historical_simulation": {}
}
}Risk metrics
Each selected risk model returns a set of metrics that describe potential portfolio losses.
| Field | Description |
|---|---|
| var | Estimated portfolio loss threshold at the selected confidence level and time horizon. |
| cvar | Estimated average loss among outcomes beyond the Value at Risk threshold. |
| pnl_quantile | The portfolio profit-and-loss value at the selected risk quantile. |
Why can VaR and pnl_quantile have opposite signs?
VaR is returned as the magnitude of an estimated loss, while pnl_quantile represents the corresponding value on the portfolio profit-and-loss distribution.
For example, a VaR of 339.65 may correspond to a P&L quantile of -339.65.
Chart data
Quant Risk API returns structured distribution data that can be used to visualize portfolio profit-and-loss outcomes without recalculating the distribution on the client.
| Field | Description |
|---|---|
| type | The type of chart data returned. Currently, the response provides a P&L distribution. |
| bins | Histogram bin boundaries representing ranges of simulated portfolio P&L values. |
| counts | The number of simulated outcomes that fall within each corresponding histogram bin. |
| var_threshold | The portfolio P&L threshold corresponding to the calculated Value at Risk. |
| cvar_value | The average tail-loss value associated with the calculated Conditional Value at Risk. |
Choose a risk model
Use the method parameter to select which risk model should be used.
| Method | Description |
|---|---|
monte_carlo_normal | Runs Monte Carlo simulation using a normal distribution. |
monte_carlo_student_t | Runs Monte Carlo simulation using a Student's t distribution, which can model heavier-tailed return distributions. |
historical_simulation | Estimates portfolio risk using historical return observations. |
all | Runs all available risk models and returns the results for each model. |
Next steps
You now have the basic workflow for using the Quant Risk API:
- Upload historical market data.
- Receive a dataset identifier.
- Define your portfolio.
- Calculate portfolio risk.
- Use the returned risk metrics and distribution data in your application.
Next, learn how to structure your CSV dataset and provide historical market data for risk calculations.