Loan Risk with Liquidity Constraints

Calculate loan risk metrics with market liquidity constraints for large positions.

POST /loan_risk_low_liquidity

Overview

The Loan Risk Low Liquidity endpoint performs risk assessment for loans while accounting for market liquidity constraints. This is particularly important for large positions that cannot be liquidated instantly without significant market impact. The endpoint supports multiple risk modeling approaches including Geometric Brownian Motion (GBM) and GARCH (Generalized Autoregressive Conditional Heteroskedasticity).

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.
`GARCH`	Perform a Monte Carlo simulation using GARCH model for volatility forecasting.

Standard Parameters (Common to All Methods)

Parameter	Type	Required	Description	Example
`collateral_weights`	object	Yes	Dictionary of collateral asset symbols mapping to respective weights.	`{'BTC': 1.0}`
`loan_weights`	object	Yes	Dictionary of loan asset symbols mapping to respective weights.	`{'USDC': 1.0}`
`N`	number	Yes	Initial collateral ratio threshold.	`1.7`
`M`	number	Yes	Margin call threshold.	`1.47`
`L`	number	Yes	Liquidation threshold (CCR).	`1.3`
`R`	number	Yes	Recovery threshold.	`1.7`
`model_lookback`	number	Yes	Days of historical data for model fitting.	`90`
`volume_lookback`	number	Yes	Days of volume data for liquidity analysis.	`5`
`markets`	array	Yes	Array of trading pairs for volume aggregation.	`[["BTC", "USDT", "binance"], ["BTC", "USD", "coinbase"]]`
`participation_ratio`	number	Yes	Max fraction of daily volume for liquidation (0 < value ≤ 1).	`0.1`
`loan_duration`	number	Yes	Loan duration in days.	`30`
`mc_top_up`	number	Yes	Margin call top-up frequency in hours.	`24`
`loan_value`	number	Yes	Loan value in USD.	`10000000`
`mc_iter`	number	Yes	Number of Monte Carlo iterations.	`1000`

Optional Parameters

Parameter	Type	Required	Description	Default	Example
`analysis_date`	string	No	End date for analysis (format: "MM-DD-YYYY").	Current date	`"01-30-2023"`
`volatility_shock`	number	No	Volatility multiplier for stress testing.	`0`	`1.5`

Markets Parameter Format

The markets parameter specifies which trading pairs to aggregate volume from:

markets: [[base, quote, exchange], ...]

Element	Description	Examples
base	Base asset symbol	"BTC", "ETH", "SOL"
quote	Quote asset symbol	"USDT", "USD", "USDC"
exchange	Exchange name (lowercase)	"binance", "coinbase", "kraken"

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

Field	Type	Description
`PrMarginCall`	number	Probability of at least one margin call
`PrLiquidation`	number	Probability of liquidation
`PrUnderwater`	number	Probability of underwater position
`PrCloseout`	number	Probability of closeout
`AvgMarginCall`	number	Average margin call amount
`AvgLiquidation`	number	Average liquidation amount
`WorstCaseCCR`	number	Worst case collateral coverage ratio
`Collateral Volatility`	number	Annualized volatility of collateral
`Loan Volatility`	number	Annualized volatility of loan
`Collateral/Loan Correlation`	number	Correlation between collateral and loan
`Volume Summary (per Million)`	object	Daily volume statistics
`Maximum Market Daily Liquidation`	number	Max liquidation capacity in USD

Volume Summary Object

The Volume Summary provides statistics on the aggregated daily trading volume across all specified markets over the volume_lookback period.

Field	Description
`Mean`	Average daily volume across the lookback period
`Minimum`	Lowest single-day volume observed
`25% Quantile`	25th percentile - 75% of days had higher volume
`Median`	50th percentile - typical daily volume
`75% Quantile`	75th percentile - 25% of days had higher volume
`Maximum`	Highest single-day volume observed

Examples

GBM Example

Request

POST /loan_risk_low_liquidity

{
  "type": "GBM",
  "params": {
    "collateral_weights": {
      "BTC": 1.0
    },
    "loan_weights": {
      "USDC": 1.0
    },
    "N": 1.7,
    "M": 1.47,
    "L": 1.3,
    "R": 1.7,
    "model_lookback": 90,
    "volume_lookback": 5,
    "markets": [
      ["BTC", "USDT", "binance"],
      ["BTC", "USD", "coinbase"]
    ],
    "participation_ratio": 0.1,
    "loan_duration": 30,
    "mc_top_up": 24,
    "loan_value": 10000000,
    "mc_iter": 1000
  }
}

Response

{
  "Arguments": {
    "L": 1.3,
    "M": 1.47,
    "N": 1.7,
    "R": 1.7,
    "analysis_date": "12-22-2025",
    "collateral_weights": {
      "BTC": 1.0
    },
    "loan_duration": 30,
    "loan_value": 10000000,
    "loan_weights": {
      "USDC": 1.0
    },
    "markets": [
      ["BTC", "USDT", "binance"],
      ["BTC", "USD", "coinbase"]
    ],
    "mc_iter": 1000,
    "mc_top_up": 24,
    "model_lookback": 90,
    "participation_ratio": 0.1,
    "type": "GBM",
    "volume_lookback": 5,
    "volatility_shock": 0
  },
  "Output": {
    "AvgLiquidation": 1245678.32,
    "AvgMarginCall": 2345678.45,
    "Collateral Volatility": 0.0423,
    "Collateral/Loan Correlation": 0.0012,
    "Loan Volatility": 0.0002,
    "Maximum Market Daily Liquidation": 24001200,
    "PrCloseout": 0.002,
    "PrLiquidation": 0.125,
    "PrMarginCall": 0.345,
    "PrUnderwater": 0.001,
    "Volume Summary (per Million)": {
      "Mean": 245.123,
      "Minimum": 180.456,
      "25% Quantile": 210.789,
      "Median": 240.012,
      "75% Quantile": 275.345,
      "Maximum": 320.678
    },
    "WorstCaseCCR": 0.95
  },
  "Risk engine version": "1.6.0"
}

GARCH Example

Request

POST /loan_risk_low_liquidity

{
  "type": "GARCH",
  "params": {
    "collateral_weights": {
      "ETH": 1.0
    },
    "loan_weights": {
      "USDC": 1.0
    },
    "N": 1.7,
    "M": 1.47,
    "L": 1.3,
    "R": 1.7,
    "model_lookback": 100,
    "volume_lookback": 5,
    "markets": [
      ["ETH", "USDT", "binance"],
      ["ETH", "USD", "coinbase"]
    ],
    "participation_ratio": 0.1,
    "loan_duration": 30,
    "mc_top_up": 24,
    "loan_value": 5000000,
    "mc_iter": 1000
  }
}

Response

{
  "Arguments": {
    "L": 1.3,
    "M": 1.47,
    "N": 1.7,
    "R": 1.7,
    "analysis_date": "12-22-2025",
    "collateral_weights": {
      "ETH": 1.0
    },
    "loan_duration": 30,
    "loan_value": 5000000,
    "loan_weights": {
      "USDC": 1.0
    },
    "markets": [
      ["ETH", "USDT", "binance"],
      ["ETH", "USD", "coinbase"]
    ],
    "mc_iter": 1000,
    "mc_top_up": 24,
    "model_lookback": 100,
    "participation_ratio": 0.1,
    "type": "GARCH",
    "volume_lookback": 5,
    "volatility_shock": 0
  },
  "Output": {
    "AvgLiquidation": 845678.32,
    "AvgMarginCall": 1345678.45,
    "Collateral Volatility": 0.0523,
    "Collateral/Loan Correlation": 0.0015,
    "Loan Volatility": 0.0001,
    "Maximum Market Daily Liquidation": 18001200,
    "PrCloseout": 0.001,
    "PrLiquidation": 0.105,
    "PrMarginCall": 0.325,
    "PrUnderwater": 0.0005,
    "Volume Summary (per Million)": {
      "Mean": 185.123,
      "Minimum": 150.456,
      "25% Quantile": 170.789,
      "Median": 180.012,
      "75% Quantile": 195.345,
      "Maximum": 220.678
    },
    "WorstCaseCCR": 0.97
  },
  "Risk engine version": "1.6.0"
}

Understanding Volume-Constrained Results

The low liquidity model penalizes large positions relative to available market liquidity:

Median daily volume: Calculated from the markets parameter across the volume_lookback period
Max daily liquidation: Calculated as Median volume × participation_ratio
Liquidity constraint: Daily liquidations are capped at the max daily liquidation value
Higher liquidation risk: Large positions that require multiple days to liquidate face increased risk during adverse price movements

Comparing Standard vs Low Liquidity Models

Scenario	Standard Model	Low Liquidity Model
$10M loan, liquid market	PrLiq: 0.05	PrLiq: 0.05
$100M loan, liquid market	PrLiq: 0.05	PrLiq: 0.15
$100M loan, illiquid market	PrLiq: 0.05	PrLiq: 0.35

POST/loan_risk_low_liquidity

cURL
Python
JavaScript

curl -X POST "https://api.bitpulse.io/loan_risk_low_liquidity" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "GBM",
    "params": {
      "collateral_weights": {
        "BTC": 1.0
      },
      "loan_weights": {
        "USDC": 1.0
      },
      "N": 1.7,
      "M": 1.47,
      "L": 1.3,
      "R": 1.7,
      "model_lookback": 90.0,
      "volume_lookback": 5,
      "markets": [
        ["BTC", "USDT", "binance"],
        ["BTC", "USD", "coinbase"]
      ],
      "participation_ratio": 0.1,
      "loan_duration": 30.0,
      "mc_top_up": 24.0,
      "loan_value": 10000000,
      "mc_iter": 1000
    }
  }'

import requests
import json

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

payload = {
    "type": "GBM",
    "params": {
        "collateral_weights": {
            "BTC": 1.0
        },
        "loan_weights": {
            "USDC": 1.0
        },
        "N": 1.7,
        "M": 1.47,
        "L": 1.3,
        "R": 1.7,
        "model_lookback": 90.0,
        "volume_lookback": 5,
        "markets": [
            ["BTC", "USDT", "binance"],
            ["BTC", "USD", "coinbase"]
        ],
        "participation_ratio": 0.1,
        "loan_duration": 30.0,
        "mc_top_up": 24.0,
        "loan_value": 10000000,
        "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))

const axios = require('axios');

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

const payload = {
  type: 'GBM',
  params: {
    collateral_weights: {
      BTC: 1.0
    },
    loan_weights: {
      USDC: 1.0
    },
    N: 1.7,
    M: 1.47,
    L: 1.3,
    R: 1.7,
    model_lookback: 90.0,
    volume_lookback: 5,
    markets: [
      ["BTC", "USDT", "binance"],
      ["BTC", "USD", "coinbase"]
    ],
    participation_ratio: 0.1,
    loan_duration: 30.0,
    mc_top_up: 24.0,
    loan_value: 10000000,
    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);
  });

Overview​

Input Parameters​

Required Parameters​

Type Values​

Standard Parameters (Common to All Methods)​

Optional Parameters​

Markets Parameter Format​

Response​

Standard Output​

Volume Summary Object​

Examples​

GBM Example​

Request​

Response​

GARCH Example​

Request​

Response​

Understanding Volume-Constrained Results​

Comparing Standard vs Low Liquidity Models​

Overview

Input Parameters

Required Parameters

Type Values

Standard Parameters (Common to All Methods)

Optional Parameters

Markets Parameter Format

Response

Standard Output

Volume Summary Object

Examples

GBM Example

Request

Response

GARCH Example

Request

Response

Understanding Volume-Constrained Results

Comparing Standard vs Low Liquidity Models