Value at Risk (VaR)

Calculate Value at Risk metrics for loan and collateral assets across multiple time horizons.

POST /var

Overview

The Value at Risk (VaR) endpoint calculates risk metrics for loan and collateral assets, including standard VaR and Conditional VaR (CVaR) across multiple time horizons and confidence levels.

Input Parameters

Required Parameters

Parameter	Type	Description
type	string	The methodology to perform the VaR analysis.
params	object	The parameters to be used in the VaR methodology.

Type Values

Value	Description
GBM	Perform a VaR Monte Carlo simulation using Geometric Brownian Motion.
GBM_VIX	Perform a VaR Monte Carlo Simulation using GBM, but with volatility derived from VIX data.
HISTORICAL	Perform a VaR analysis using an empirical model based on historical data.

Standard Parameters (Common to All Methods)

Parameter	Type	Required	Description	Default	Example
collateral_weights	object	Yes	Dictionary of collateral asset symbols mapping to respective weights.		{'PEPE': 0.8, 'SOL': 0.2}
loan_weights	object	Yes	Dictionary of loan asset symbols mapping to respective weights.		{'BTC': 0.1, 'USDC': 0.9}
analysis_date	string	No	Final date to consider when collecting historical data (format: "MM-DD-YYYY").	Today's date	"01-30-2020"
model_lookback	number	Yes	Number of days to look back from the analysis date to collect data.		100
var_duration	array	Yes	Array of time horizons (in days) to compute the VaR.		[30, 60, 90]
quantile	array	Yes	Array of quantiles to calculate the VaR.		[0.95, 0.97, 0.99]
loan_value	number	Yes	The value in USD to be loaned.		100000
collateral_value	number	Yes	The value in USD of the collateral.		150000
mc_iter	number	Yes	Number of Monte Carlo iterations (except for historical method).		1000

GBM-Specific Parameters

Parameter	Type	Required	Description	Default	Example
volatility_shock	number	No	Percentage increase to apply to asset volatilities.	0.0	0.1

Response

The response includes three main sections:

• Arguments: The processed input parameters
• Risk engine version: The software version
• Output: The VaR assessment results

Output Structure

The output is organized by time horizons and quantiles:

Output
├── <time_horizon_1>
│   ├── <quantile_1>
│   │   ├── CollateralVar
│   │   ├── CollateralCVar
│   │   ├── LoanVar
│   │   ├── LoanCVar
│   │   ├── NetExposureVar
│   │   └── NetExposureCVar
│   ├── <quantile_2>
│   │   └── ...
│   └── ...
├── <time_horizon_2>
│   └── ...
└── ...

Output Fields for Each Quantile

Field	Type	Description
CollateralVar	number	Maximum value of the (1-q)% worst cases of the collateral value
CollateralCVar	number	Expected value among the (1-q)% worst cases of collateral value
LoanVar	number	Maximum value of the (1-q)% worst cases of the loan value
LoanCVar	number	Expected value among the (1-q)% worst cases of loan value
NetExposureVar	number	Maximum value of the (1-q)% worst cases of net exposure (collateral - loan)
NetExposureCVar	number	Expected value among the (1-q)% worst cases of net exposure

GBM/GBM_VIX Additional Output

Field	Type	Description
Collateral Volatility	number	Volatility of the collateral portfolio
Loan Volatility	number	Volatility of the loan portfolio
Collateral/Loan Correlation	number	Correlation between collateral and loan portfolios

Examples

GBM Example

Request

POST /var

{
  "type": "GBM",
  "params": {
    "analysis_date": "08-22-2024",
    "collateral_value": 150000,
    "collateral_weights": {
      "BTC": 1.0
    },
    "loan_value": 100000,
    "loan_weights": {
      "USD": 1.0
    },
    "mc_iter": 100,
    "model_lookback": 100.0,
    "quantile": [0.25, 0.5, 0.75, 0.9, 0.95, 0.97, 0.99],
    "var_duration": [30, 60, 90]
  }
}

Response (Partial)

{
  "Arguments": {
    "analysis_date": "08-22-2024",
    "collateral_value": 150000,
    "collateral_weights": {
      "BTC": 1
    },
    "loan_value": 100000,
    "loan_weights": {
      "USDC": 1
    },
    "lookback_factor": 1.0,
    "mc_iter": 100,
    "model_lookback": 100,
    "quantile": [0.25, 0.5, 0.75, 0.9, 0.95, 0.97, 0.99],
    "type": "GBM",
    "var_duration": [30, 60, 90],
    "volatility_shock": 0
  },
  "Output": {
    "30": {
      "0.95": {
        "CollateralCVar": 114812.33006492336,
        "CollateralVar": 121504.45078699649,
        "LoanCVar": 99266.43391193973,
        "LoanVar": 99480.77955642693,
        "NetExposureCVar": 15086.581654478607,
        "NetExposureVar": 21220.220723086553
      },
      "0.99": {
        "CollateralCVar": 106228.99287369274,
        "CollateralVar": 111349.36287735903,
        "LoanCVar": 98936.35122878745,
        "LoanVar": 99257.72788938666,
        "NetExposureCVar": 6030.263850574702,
        "NetExposureVar": 11819.889187362813
      }
      // Other quantiles omitted for brevity
    },
    "60": {
      "0.95": {
        "CollateralCVar": 106159.56422271048,
        "CollateralVar": 113850.56519958921,
        "LoanCVar": 99009.63219341931,
        "LoanVar": 99222.49314626156,
        "NetExposureCVar": 6419.976167886751,
        "NetExposureVar": 13658.844884719154
      }
      // Other quantiles and time horizons omitted for brevity
    },
    "Collateral Volatility": 0.025727285512051612,
    "Collateral/Loan Correlation": 0.15622722049362323,
    "Loan Volatility": 0.0005990808490146791
  },
  "Risk engine version": "1.5.0"
}

GBM_VIX Example

Request

POST /var

{
  "type": "GBM_VIX",
  "params": {
    "analysis_date": "08-22-2024",
    "collateral_value": 150000,
    "collateral_weights": {
      "BTC": 1.0
    },
    "loan_value": 100000,
    "loan_weights": {
      "USD": 1.0
    },
    "mc_iter": 100,
    "model_lookback": 100.0,
    "quantile": [0.25, 0.5, 0.75, 0.9, 0.95, 0.97, 0.99],
    "var_duration": [30, 60, 90]
  }
}

Response (Partial)

{
  "Arguments": {
    "analysis_date": "08-22-2024",
    "collateral_value": 150000,
    "collateral_weights": {
      "BTC": 1
    },
    "loan_value": 100000,
    "loan_weights": {
      "USDC": 1
    },
    "lookback_factor": 1.0,
    "mc_iter": 100,
    "model_lookback": 100,
    "quantile": [0.25, 0.5, 0.75, 0.9, 0.95, 0.97, 0.99],
    "type": "GBM_VIX",
    "var_duration": [30, 60, 90],
    "vix_data": {
      "BTC": 57.68,
      "ETH": 71.65
    }
  },
  "Output": {
    "30": {
      "0.95": {
        "CollateralCVar": 109338.55908440318,
        "CollateralVar": 116463.8782684237,
        "LoanCVar": 99342.82199651105,
        "LoanVar": 99454.52111013529,
        "NetExposureCVar": 9490.31838955982,
        "NetExposureVar": 16639.557895217633
      }
      // Other quantiles omitted for brevity
    }
    // Other time horizons omitted for brevity
  },
  "Risk engine version": "1.5.0"
}

Historical Example

Request

POST /var

{
  "type": "HISTORICAL",
  "params": {
    "analysis_date": "08-22-2024",
    "collateral_value": 150000,
    "collateral_weights": {
      "BTC": 1.0
    },
    "loan_value": 100000,
    "loan_weights": {
      "USD": 1.0
    },
    "mc_iter": 100,
    "model_lookback": 100.0,
    "quantile": [0.25, 0.5, 0.75, 0.9, 0.95, 0.97, 0.99],
    "var_duration": [30, 60, 90]
  }
}

Response (Partial)

{
  "Arguments": {
    "analysis_date": "08-22-2024",
    "collateral_value": 150000,
    "collateral_weights": {
      "BTC": 1
    },
    "dt": 0.041666666666666664,
    "loan_value": 100000,
    "loan_weights": {
      "USDC": 1
    },
    "lookback_factor": 24.0,
    "mc_iter": 100,
    "model_lookback": 100,
    "quantile": [0.25, 0.5, 0.75, 0.9, 0.95, 0.97, 0.99],
    "type": "HISTORICAL",
    "var_duration": [30, 60, 90],
    "var_duration_max": 90
  },
  "Output": {
    "30": {
      "0.95": {
        "CollateralCVar": 136732.99458891468,
        "CollateralVar": 137397.709826899,
        "LoanCVar": 99780.02268747351,
        "LoanVar": 99851.84815184817,
        "NetExposureCVar": 36752.82800433917,
        "NetExposureVar": 37426.66011473037
      }
      // Other quantiles omitted for brevity
    }
    // Other time horizons omitted for brevity
  },
  "Risk engine version": "1.5.0"
}

Interpreting VaR Results

• CollateralVar/LoanVar: The worst-case value at the specified confidence level
• CollateralCVar/LoanCVar: The expected value in the worst cases beyond the VaR threshold
• NetExposureVar/NetExposureCVar: The worst-case and expected worst-case difference between collateral and loan values

A negative NetExposureVar indicates that in the worst-case scenario at the specified confidence level, the collateral value falls below the loan value, representing a potential loss.

POST/var

cURL

curl -X POST "https://api.bitpulse.io/var" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "GBM",
    "params": {
      "collateral_value": 10000,
      "collateral_weights": {
        "BTC": 0.4,
        "ETH": 0.6
      },
      "loan_value": 5000,
      "loan_weights": {
        "USDC": 1.0
      },
      "mc_iter": 1000,
      "model_lookback": 90,
      "quantile": [0.95, 0.99],
      "var_duration": [1, 7, 30]
    }
  }'

Python

import requests
import json

url = "https://api.bitpulse.io/var"

payload = {
    "type": "GBM",
    "params": {
        "collateral_value": 10000,
        "collateral_weights": {
            "BTC": 0.4,
            "ETH": 0.6
        },
        "loan_value": 5000,
        "loan_weights": {
            "USDC": 1.0
        },
        "mc_iter": 1000,
        "model_lookback": 90,
        "quantile": [0.95, 0.99],
        "var_duration": [1, 7, 30]
    }
}

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(json.dumps(response.json(), indent=2))

JavaScript

const axios = require('axios');

const url = 'https://api.bitpulse.io/var';

const payload = {
  type: 'GBM',
  params: {
    collateral_value: 10000,
    collateral_weights: {
      BTC: 0.4,
      ETH: 0.6
    },
    loan_value: 5000,
    loan_weights: {
      USDC: 1.0
    },
    mc_iter: 1000,
    model_lookback: 90,
    quantile: [0.95, 0.99],
    var_duration: [1, 7, 30]
  }
};

const headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error('Error:', error.response ? error.response.data : error.message);
  });