Loan Origination

Calculate the Nominal, Recovery, and Margin ratios to achieve a desired risk score for a specific target variable.

POST /loan_origination

Overview

The Loan Origination endpoint helps determine optimal loan parameters (N, M, R ratios) based on risk tolerance. It uses the same risk assessment methodologies as the Loan Risk endpoint but optimizes for a specific risk target.

Input Parameters

Required Parameters

Parameter	Type	Description
`type`	string	The methodology to perform the loan origination.
`params`	object	The parameters to be used in the loan origination 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.
`HISTORICAL`	Perform loan origination 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`
`L`	number	Yes	Liquidation ratio.		`1.1`
`mc_iter`	number	Yes	Number of Monte Carlo iterations (except for historical method).		`1000`
`opt_param`	object	Yes	Dictionary with optimization guidelines.		See below

Optimization Parameters

The opt_param object must include:

Parameter	Type	Description	Example
`score_variable`	string	The variable to optimize.	`"PrLiquidation"`
`score_target`	number	The target value for the score variable.	`0.1`
`variable_min`	number	Minimum value for N, R and M.	`1.2`
`variable_max`	number	Maximum value for N, R and M.	`2.0`
`error_tolerance`	number	Error tolerance for the optimization.	`0.01`

Supported Score Variables

Variable	Description
`PrCloseout`	Probability of reaching the Closeout liquidation state
`PrLiquidation`	Probability of reaching the Liquidation state
`PrMarginCall`	Probability of reaching the Margin Call state
`PrUnderwater`	Probability of being underwater (CCR < 1)
`WorstCaseCCR`	Worst CCR across all simulations

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, including the optimized N, M, and R values
Risk engine version: The software version
Output: The risk assessment results and optimized parameters

Output Fields

The output includes the same fields as the Loan Risk endpoint, plus:

Field	Type	Description
`N`	number	The optimized Nominal ratio
`M`	number	The optimized Margin Call ratio

Examples

GBM Example

Request

POST /loan_origination

{
  "type": "GBM",
  "params": {
    "collateral_weights": {
      "PEPE": 0.2,
      "SOL": 0.8
    },
    "loan_weights": {
      "ADA": 0.3,
      "USDC": 0.7
    },
    "L": 1.4,
    "analysis_date": "08-22-2024",
    "model_lookback": 90.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 1000,
    "mc_iter": 1000,
    "opt_param": {
      "variable_min": 1.35,
      "variable_max": 3.0,
      "error_tolerance": 0.007,
      "score_target": 0.1,
      "score_variable": "PrLiquidation"
    }
  }
}

Response

{
  "Arguments": {
    "L": 1.4,
    "M": 1.5232421874999997,
    "N": 1.6464843749999998,
    "R": 1.6464843749999998,
    "analysis_date": "08-22-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,
    "opt_param": {
      "error_tolerance": 0.007,
      "score_target": 0.1,
      "score_variable": "PrLiquidation",
      "variable_max": 3,
      "variable_min": 1.35
    },
    "type": "GBM",
    "volatility_shock": 0
  },
  "Output": {
    "M": 1.5232421874999997,
    "N": 1.6464843749999998,
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 1.0,
    "Collateral Volatility": 0.04250031219899017,
    "Collateral/Loan Correlation": 0.7306339410912476,
    "Loan Volatility": 0.010173980969891623,
    "PrCloseout": 0.0,
    "PrLiquidation": 0.105,
    "PrMarginCall": 0.666,
    "PrUnderwater": 0.0,
    "WorstCaseCCR": 1.2818092112776276
  },
  "Risk engine version": "1.5.0"
}

GBM_VIX Example

Request

POST /loan_origination

{
  "type": "GBM_VIX",
  "params": {
    "collateral_weights": {
      "ETH": 1.0
    },
    "loan_weights": {
      "USDC": 1.0
    },
    "L": 1.4,
    "analysis_date": "08-22-2024",
    "model_lookback": 90.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 1000,
    "mc_iter": 1000,
    "opt_param": {
      "variable_min": 1.35,
      "variable_max": 3.0,
      "error_tolerance": 0.006,
      "score_target": 0.1,
      "score_variable": "PrLiquidation"
    }
  }
}

Response

{
  "Arguments": {
    "L": 1.4,
    "M": 1.478125,
    "N": 1.55625,
    "R": 1.55625,
    "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,
    "opt_param": {
      "error_tolerance": 0.006,
      "score_target": 0.1,
      "score_variable": "PrLiquidation",
      "variable_max": 3,
      "variable_min": 1.35
    },
    "type": "GBM_VIX",
    "vix_data": {
      "BTC": 57.77,
      "ETH": 71.67
    }
  },
  "Output": {
    "M": 1.478125,
    "N": 1.55625,
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 1.0,
    "Collateral Volatility": 0.030793387821771802,
    "Collateral/Loan Correlation": 0.2157945077612465,
    "Loan Volatility": 0.000593795683426351,
    "PrCloseout": 0.0,
    "PrLiquidation": 0.101,
    "PrMarginCall": 0.5,
    "PrUnderwater": 0.0,
    "WorstCaseCCR": 1.3100897065884627
  },
  "Risk engine version": "1.5.0"
}

Historical Example

Request

POST /loan_origination

{
  "type": "HISTORICAL",
  "params": {
    "collateral_weights": {
      "ADA": 1.0
    },
    "loan_weights": {
      "BTC": 1.0
    },
    "L": 1.1,
    "analysis_date": "08-22-2024",
    "model_lookback": 100.0,
    "loan_duration": 30.0,
    "mc_top_up": 24.0,
    "loan_value": 10000,
    "opt_param": {
      "variable_min": 1.2,
      "variable_max": 2.0,
      "error_tolerance": 0.01,
      "score_target": 0.1,
      "score_variable": "PrLiquidation"
    }
  }
}

Response

{
  "Arguments": {
    "L": 1.1,
    "M": 1.190625,
    "N": 1.28125,
    "R": 1.28125,
    "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,
    "opt_param": {
      "error_tolerance": 0.01,
      "score_target": 0.1,
      "score_variable": "PrLiquidation",
      "variable_max": 2,
      "variable_min": 1.2
    },
    "type": "HISTORICAL"
  },
  "Output": {
    "M": 1.190625,
    "N": 1.28125,
    "AvgLossPct": 0.0,
    "AvgSurvivalRate": 1.0,
    "PrCloseout": 0.0,
    "PrLiquidation": 0.09934562760261749,
    "PrMarginCall": 0.8292682926829268,
    "PrUnderwater": 0.0,
    "WorstCaseCCR": 1.0822557008742846
  },
  "Risk engine version": "1.5.0"
}

POST/loan_origination

cURL
Python
JavaScript

curl -X POST "https://api.bitpulse.io/loan_origination" \
  -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
      },
      "L": 1.4,
      "model_lookback": 90.0,
      "loan_duration": 30.0,
      "mc_top_up": 24.0,
      "loan_value": 1000,
      "mc_iter": 1000,
      "opt_param": {
        "variable_min": 1.1,
        "variable_max": 2.0,
        "error_tolerance": 0.01,
        "score_target": 0.05,
        "score_variable": "PrLiquidation"
      }
    }
  }'

import requests
import json

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

payload = {
    "type": "GBM",
    "params": {
        "collateral_weights": {
            "PEPE": 0.2,
            "SOL": 0.8
        },
        "loan_weights": {
            "ADA": 0.3,
            "USDC": 0.7
        },
        "L": 1.4,
        "model_lookback": 90.0,
        "loan_duration": 30.0,
        "mc_top_up": 24.0,
        "loan_value": 1000,
        "mc_iter": 1000,
        "opt_param": {
            "variable_min": 1.1,
            "variable_max": 2.0,
            "error_tolerance": 0.01,
            "score_target": 0.05,
            "score_variable": "PrLiquidation"
        }
    }
}

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

const axios = require('axios');

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

const payload = {
  type: 'GBM',
  params: {
    collateral_weights: {
      PEPE: 0.2,
      SOL: 0.8
    },
    loan_weights: {
      ADA: 0.3,
      USDC: 0.7
    },
    L: 1.4,
    model_lookback: 90.0,
    loan_duration: 30.0,
    mc_top_up: 24.0,
    loan_value: 1000,
    mc_iter: 1000,
    opt_param: {
      variable_min: 1.1,
      variable_max: 2.0,
      error_tolerance: 0.01,
      score_target: 0.05,
      score_variable: "PrLiquidation"
    }
  }
};

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

Overview​

Input Parameters​

Required Parameters​

Type Values​

Standard Parameters (Common to All Methods)​

Optimization Parameters​

Supported Score Variables​

GBM-Specific Parameters​

Response​

Output Fields​

Examples​

GBM Example​

Request​

Response​

GBM_VIX Example​

Request​

Response​

Historical Example​

Request​

Response​

Overview

Input Parameters

Required Parameters

Type Values

Standard Parameters (Common to All Methods)

Optimization Parameters

Supported Score Variables

GBM-Specific Parameters

Response

Output Fields

Examples

GBM Example

Request

Response

GBM_VIX Example

Request

Response

Historical Example

Request

Response