Loan Risk

Calculate the loan risk metrics using various risk assessment methodologies.

POST /loan_risk

Overview

The Loan Risk endpoint performs risk assessment for loans based on collateral and loan assets. It supports multiple risk modeling approaches including Geometric Brownian Motion (GBM), GBM with VIX data, and historical data analysis.

Input Parameters

Required Parameters

Parameter	Type	Description
type	string	The methodology to perform the loan risk assessment.
params	object	The parameters to be used in the loan risk methodology.

Type Values

Value	Description
GBM	Perform a Monte Carlo simulation using Geometric Brownian Motion.
GBM_VIX	Perform a Monte Carlo Simulation using GBM, but with volatility derived from VIX data. Currently only BTC and ETH volatilities are overridden.
HISTORICAL	Perform loan risk assessment 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.		30
loan_duration	number	Yes	Number of days that the loan will take place.		60
mc_top_up	number	Yes	Hours in the grace period between margin call and top-up requirement.		24
loan_value	number	Yes	The value in USD to be loaned.		5000.0
N	number	Yes	Nominal ratio.		1.5
M	number	Yes	Margin call ratio.		1.3
L	number	Yes	Liquidation ratio.		1.1
R	number	Yes	Recovery ratio.		1.7
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 risk assessment results

Standard Output (Common to All Models)

Field	Type	Description
AvgLossPct	number	Percentage loss from the lender's perspective
AvgSurvivalRate	number	Average survival rate across all simulations
PrCloseout	number	Probability of reaching the Closeout liquidation state
PrLiquidation	number	Probability of reaching the Liquidation state
PrMarginCall	number	Probability of reaching the Margin Call state
PrUnderwater	number	Probability of being underwater (CCR < 1)
WorstCaseCCR	number	Worst CCR across all simulations

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 /loan_risk

{
  "type": "GBM",
  "params": {
    "collateral_weights": {
      "PEPE": 0.2,
      "SOL": 0.8
    },
    "loan_weights": {
      "ADA": 0.3,
      "USDC": 0.7
    },
    "N": 1.7,
    "M": 1.5,
    "L": 1.4,
    "R": 1.7,
    "analysis_date": "11-28-2024",
    "model_lookback": 90.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 1000,
    "mc_iter": 2500
  }
}

Response

{
  "Arguments": {
    "L": 1.4,
    "M": 1.5,
    "N": 1.7,
    "R": 1.7,
    "analysis_date": "11-28-2024",
    "collateral_weights": {
      "PEPE": 0.2,
      "SOL": 0.8
    },
    "loan_duration": 30,
    "loan_value": 1000,
    "loan_weights": {
      "ADA": 0.3,
      "USDC": 0.7
    },
    "mc_iter": 2500,
    "mc_top_up": 24,
    "model_lookback": 90,
    "type": "GBM",
    "volatility_shock": 0
  },
  "Output": {
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 1.0,
    "Collateral Volatility": 0.03837350504388694,
    "Collateral/Loan Correlation": 0.4289787072331317,
    "Loan Volatility": 0.016597796754734623,
    "PrCloseout": 0.0,
    "PrLiquidation": 0.03604,
    "PrMarginCall": 0.30121,
    "PrUnderwater": 0.0,
    "WorstCaseCCR": 1.2478372708096614
  },
  "Risk engine version": "1.5.0"
}

GBM with Volatility Shock Example

Request

POST /loan_risk

{
  "type": "GBM",
  "params": {
    "collateral_weights": {
      "PEPE": 0.2,
      "SOL": 0.8
    },
    "loan_weights": {
      "ADA": 0.3,
      "USDC": 0.7
    },
    "N": 1.7,
    "M": 1.5,
    "L": 1.4,
    "R": 1.7,
    "volatility_shock": 2,
    "analysis_date": "11-28-2024",
    "model_lookback": 90.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 1000,
    "mc_iter": 1000
  }
}

Response

{
  "Arguments": {
    "L": 1.4,
    "M": 1.5,
    "N": 1.7,
    "R": 1.7,
    "analysis_date": "11-28-2024",
    "collateral_weights": {
      "PEPE": 0.2,
      "SOL": 0.8
    },
    "loan_duration": 30,
    "loan_value": 1000,
    "loan_weights": {
      "ADA": 0.3,
      "USDC": 0.7
    },
    "mc_iter": 1000,
    "mc_top_up": 24,
    "model_lookback": 90,
    "type": "GBM",
    "volatility_shock": 2
  },
  "Output": {
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 0.9998689655172414,
    "Collateral Volatility": 0.11512051513166081,
    "Collateral/Loan Correlation": 0.4289787072331316,
    "Loan Volatility": 0.04979339026420388,
    "PrCloseout": 0.00032,
    "PrLiquidation": 0.61285,
    "PrMarginCall": 0.73879,
    "PrUnderwater": 0.00032,
    "WorstCaseCCR": 0.8948748441558193
  },
  "Risk engine version": "1.5.0"
}

GBM_VIX Example

Request

POST /loan_risk

{
  "type": "GBM_VIX",
  "params": {
    "collateral_weights": {
      "ETH": 1.0
    },
    "loan_weights": {
      "USDC": 1.0
    },
    "N": 1.7,
    "M": 1.5,
    "L": 1.4,
    "R": 1.7,
    "analysis_date": "08-22-2024",
    "model_lookback": 90.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 1000,
    "mc_iter": 1000
  }
}

Response

{
  "Arguments": {
    "L": 1.4,
    "M": 1.5,
    "N": 1.7,
    "R": 1.7,
    "analysis_date": "08-22-2024",
    "collateral_weights": {
      "ETH": 1
    },
    "loan_duration": 30,
    "loan_value": 1000,
    "loan_weights": {
      "USDC": 1
    },
    "mc_iter": 1000,
    "mc_top_up": 24,
    "model_lookback": 90,
    "type": "GBM_VIX",
    "vix_data": {
      "BTC": 58.36,
      "ETH": 72.97
    }
  },
  "Output": {
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 1.0,
    "Collateral Volatility": 0.030793387821771802,
    "Collateral/Loan Correlation": 0.2157945077612465,
    "Loan Volatility": 0.000593795683426351,
    "PrCloseout": 0.0,
    "PrLiquidation": 0.01738,
    "PrMarginCall": 0.22189,
    "PrUnderwater": 0.0,
    "WorstCaseCCR": 1.293690860648954
  },
  "Risk engine version": "1.5.0"
}

Historical Example

Request

POST /loan_risk

{
  "type": "HISTORICAL",
  "params": {
    "collateral_weights": {
      "ADA": 1.0
    },
    "loan_weights": {
      "BTC": 1.0
    },
    "N": 1.7,
    "M": 1.5,
    "L": 1.1,
    "R": 1.7,
    "analysis_date": "08-22-2024",
    "model_lookback": 100.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 10000
  }
}

Response

{
  "Arguments": {
    "L": 1.1,
    "M": 1.5,
    "N": 1.7,
    "R": 1.7,
    "analysis_date": "08-22-2024",
    "collateral_weights": {
      "ADA": 1
    },
    "loan_duration": 30,
    "loan_value": 10000,
    "loan_weights": {
      "BTC": 1
    },
    "mc_top_up": 24,
    "model_lookback": 100,
    "type": "HISTORICAL"
  },
  "Output": {
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 1.0,
    "PrCloseout": 0.0,
    "PrLiquidation": 0.0,
    "PrMarginCall": 0.5651397977394408,
    "PrUnderwater": 0.0,
    "WorstCaseCCR": 1.3638596095828477
  },
  "Risk engine version": "1.5.0"
}

POST/loan_risk

cURL

curl -X POST "https://api.bitpulse.io/loan_risk" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "GBM",
    "params": {
      "collateral_weights": {
        "PEPE": 0.2,
        "SOL": 0.8
      },
      "loan_weights": {
        "ADA": 0.3,
        "USDC": 0.7
      },
      "N": 1.7,
      "M": 1.5,
      "L": 1.4,
      "R": 1.7,
      "model_lookback": 90.0,
      "loan_duration": 30.0,
      "mc_top_up": 24.0,
      "loan_value": 1000,
      "mc_iter": 1000
    }
  }'

Python

import requests
import json

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

payload = {
    "type": "GBM",
    "params": {
        "collateral_weights": {
            "PEPE": 0.2,
            "SOL": 0.8
        },
        "loan_weights": {
            "ADA": 0.3,
            "USDC": 0.7
        },
        "N": 1.7,
        "M": 1.5,
        "L": 1.4,
        "R": 1.7,
        "model_lookback": 90.0,
        "loan_duration": 30.0,
        "mc_top_up": 24.0,
        "loan_value": 1000,
        "mc_iter": 1000
    }
}

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/loan_risk';

const payload = {
  type: 'GBM',
  params: {
    collateral_weights: {
      PEPE: 0.2,
      SOL: 0.8
    },
    loan_weights: {
      ADA: 0.3,
      USDC: 0.7
    },
    N: 1.7,
    M: 1.5,
    L: 1.4,
    R: 1.7,
    model_lookback: 90.0,
    loan_duration: 30.0,
    mc_top_up: 24.0,
    loan_value: 1000,
    mc_iter: 1000
  }
};

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);
  });