Isolated Perpetual Futures Risk

Calculate risk metrics for isolated perpetual futures positions.

POST /isolated_perp_risk

Overview

The Isolated Perpetual Futures Risk endpoint performs risk assessment for isolated perpetual futures positions. It helps traders understand the risk profile of their positions, including liquidation probability, return on investment, and equity drawdown metrics.

Input Parameters

Required Parameters

Parameter	Type	Description
`model`	string	The methodology to perform the risk assessment.
`market`	string	Market to analyze (e.g., BTC, ETH).
`model_lookback`	integer	Days of historical data for model fitting (1-1000).
`trade_duration_hours`	integer	Duration to simulate in hours (minimum 3).
`contract_type`	string	Type of perpetual contract ('linear' or 'inverse').
`funding_method`	string	Funding calculation method ('flat' or 'debitflat').
`entry_price`	number	Entry price of position (minimum 0.000001).
`initial_margin`	number	Initial margin deposit (USD for linear, coins for inverse).
`position_size`	number	Position size (negative = short).
`funding_rate`	number	Funding rate per interval (-0.999999 to 0.999999).
`funding_interval_hour`	number	Hours between funding payments (minimum 0.000001).

Optional Parameters

Parameter	Type	Required	Description	Default	Example
`contract_size`	number	Required for linear	Asset amount per contract.		`1`
`contract_value_usd`	number	Required for inverse	USD value per contract.		`1`
`mc_iter`	integer	No	Monte Carlo iterations (GBM only, 1-100000).		`1000`
`analysis_date`	string	No	End date for analysis window (format mm-dd-yyyy).	Today's date	`"08-22-2024"`
`unrealized_pnl`	number	No	Initial unrealized PnL.	`0`	`100`
`volatility_shock`	number	No	Volatility shock factor (GBM only).	`0`	`0.5`

Model Values

Value	Description
`GBM`	Perform a Monte Carlo simulation using Geometric Brownian Motion.
`HISTORICAL`	Perform risk assessment using an empirical model based on historical data.

Response

The response includes two main sections:

Arguments: The processed input parameters
Results: The risk assessment results

Results Fields

Field	Type	Description
`PrMarginCall`	number	Probability of at least one margin call
`PrLiquidation`	number	Probability of liquidation
`Roi`	object	Return on investment quantiles
`AccFunding`	object	Accumulated funding payment quantiles
`MaxEquityDrawDown`	object	Maximum equity drawdown quantiles (negative values)
`Leverage`	object	Median leverage per simulation quantiles
`FinalEquity`	object	Final equity value quantiles

Quantile Objects

Each quantile object contains the following percentile values:

Field	Description
`q01`	1st percentile
`q05`	5th percentile
`q10`	10th percentile
`q25`	25th percentile
`q50`	50th percentile (median)
`q75`	75th percentile
`q90`	90th percentile
`q95`	95th percentile
`q99`	99th percentile

Examples

GBM Example

Request

POST /isolated_perp_risk

{
  "model": "GBM",
  "market": "BTC",
  "model_lookback": 90,
  "trade_duration_hours": 24,
  "contract_type": "linear",
  "funding_method": "flat",
  "entry_price": 65000,
  "initial_margin": 1000,
  "position_size": 0.5,
  "funding_rate": 0.0001,
  "funding_interval_hour": 8,
  "contract_size": 1,
  "mc_iter": 1000
}

Response

{
  "Arguments": {
    "analysis_date": "10-09-2025",
    "contract_size": 1,
    "contract_type": "linear",
    "entry_price": 65000,
    "funding_interval_hour": 8,
    "funding_method": "flat",
    "funding_rate": 0.0001,
    "initial_margin": 1000,
    "market": "BTC",
    "mc_iter": 1000,
    "model": "GBM",
    "model_lookback": 90,
    "position_size": 0.5,
    "trade_duration_hours": 24,
    "unrealized_pnl": 0
  },
  "Results": {
    "PrMarginCall": 0.021,
    "PrLiquidation": 0.002,
    "Roi": {
      "q01": -0.32451,
      "q05": -0.19876,
      "q10": -0.14532,
      "q25": -0.07621,
      "q50": 0.00124,
      "q75": 0.08342,
      "q90": 0.16521,
      "q95": 0.21987,
      "q99": 0.32145
    },
    "AccFunding": {
      "q01": 0.00003,
      "q05": 0.00003,
      "q10": 0.00003,
      "q25": 0.00003,
      "q50": 0.00003,
      "q75": 0.00003,
      "q90": 0.00003,
      "q95": 0.00003,
      "q99": 0.00003
    },
    "MaxEquityDrawDown": {
      "q01": -0.35421,
      "q05": -0.21345,
      "q10": -0.15678,
      "q25": -0.08765,
      "q50": -0.03421,
      "q75": -0.01234,
      "q90": -0.00432,
      "q95": -0.00123,
      "q99": -0.00021
    },
    "Leverage": {
      "q01": 3.12345,
      "q05": 3.23456,
      "q10": 3.34567,
      "q25": 3.45678,
      "q50": 3.56789,
      "q75": 3.67891,
      "q90": 3.78912,
      "q95": 3.89123,
      "q99": 4.01234
    },
    "FinalEquity": {
      "q01": 675.49,
      "q05": 801.24,
      "q10": 854.68,
      "q25": 923.79,
      "q50": 1001.24,
      "q75": 1083.42,
      "q90": 1165.21,
      "q95": 1219.87,
      "q99": 1321.45
    }
  },
  "Risk engine version": "1.5.0"
}

Historical Example

Request

POST /isolated_perp_risk

{
  "model": "HISTORICAL",
  "market": "ETH",
  "model_lookback": 90,
  "trade_duration_hours": 48,
  "contract_type": "linear",
  "funding_method": "flat",
  "entry_price": 3500,
  "initial_margin": 1000,
  "position_size": -0.5,
  "funding_rate": -0.0001,
  "funding_interval_hour": 8,
  "contract_size": 1
}

Response

{
  "Arguments": {
    "analysis_date": "10-09-2025",
    "contract_size": 1,
    "contract_type": "linear",
    "entry_price": 3500,
    "funding_interval_hour": 8,
    "funding_method": "flat",
    "funding_rate": -0.0001,
    "initial_margin": 1000,
    "market": "ETH",
    "model": "HISTORICAL",
    "model_lookback": 90,
    "position_size": -0.5,
    "trade_duration_hours": 48,
    "unrealized_pnl": 0
  },
  "Results": {
    "PrMarginCall": 0.031,
    "PrLiquidation": 0.005,
    "Roi": {
      "q01": -0.29876,
      "q05": -0.17654,
      "q10": -0.12345,
      "q25": -0.05432,
      "q50": 0.00321,
      "q75": 0.07654,
      "q90": 0.14321,
      "q95": 0.19876,
      "q99": 0.29876
    },
    "AccFunding": {
      "q01": -0.00003,
      "q05": -0.00003,
      "q10": -0.00003,
      "q25": -0.00003,
      "q50": -0.00003,
      "q75": -0.00003,
      "q90": -0.00003,
      "q95": -0.00003,
      "q99": -0.00003
    },
    "MaxEquityDrawDown": {
      "q01": -0.32145,
      "q05": -0.19876,
      "q10": -0.14321,
      "q25": -0.07654,
      "q50": -0.02345,
      "q75": -0.00987,
      "q90": -0.00321,
      "q95": -0.00098,
      "q99": -0.00012
    },
    "Leverage": {
      "q01": 2.98765,
      "q05": 3.12345,
      "q10": 3.23456,
      "q25": 3.34567,
      "q50": 3.45678,
      "q75": 3.56789,
      "q90": 3.67891,
      "q95": 3.78912,
      "q99": 3.89123
    },
    "FinalEquity": {
      "q01": 701.24,
      "q05": 823.46,
      "q10": 876.55,
      "q25": 945.68,
      "q50": 1003.21,
      "q75": 1076.54,
      "q90": 1143.21,
      "q95": 1198.76,
      "q99": 1298.76
    }
  },
  "Risk engine version": "1.5.0"
}

Interpreting Results

PrMarginCall: The probability that your position will receive at least one margin call during the simulation period.
PrLiquidation: The probability that your position will be liquidated during the simulation period.
Roi: Return on investment distribution, showing potential profit/loss outcomes.
AccFunding: Accumulated funding payments distribution (positive values indicate receiving funding, negative values indicate paying funding).
MaxEquityDrawDown: Maximum equity drawdown distribution, showing the worst temporary loss of equity in each simulation.
Leverage: The distribution of median leverage observed across simulations.
FinalEquity: The distribution of final equity values at the end of the simulation period.

POST/isolated_perp_risk

cURL
Python
JavaScript

curl -X POST "https://api.bitpulse.io/isolated_perp_risk" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "GBM",
    "market": "BTC",
    "model_lookback": 90,
    "trade_duration_hours": 24,
    "contract_type": "linear",
    "funding_method": "flat",
    "entry_price": 65000,
    "initial_margin": 1000,
    "position_size": 0.5,
    "funding_rate": 0.0001,
    "funding_interval_hour": 8,
    "contract_size": 1,
    "mc_iter": 1000
  }'

import requests
import json

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

payload = {
    "model": "GBM",
    "market": "BTC",
    "model_lookback": 90,
    "trade_duration_hours": 24,
    "contract_type": "linear",
    "funding_method": "flat",
    "entry_price": 65000,
    "initial_margin": 1000,
    "position_size": 0.5,
    "funding_rate": 0.0001,
    "funding_interval_hour": 8,
    "contract_size": 1,
    "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/isolated_perp_risk';

const payload = {
  model: 'GBM',
  market: 'BTC',
  model_lookback: 90,
  trade_duration_hours: 24,
  contract_type: 'linear',
  funding_method: 'flat',
  entry_price: 65000,
  initial_margin: 1000,
  position_size: 0.5,
  funding_rate: 0.0001,
  funding_interval_hour: 8,
  contract_size: 1,
  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​

Optional Parameters​

Model Values​

Response​

Results Fields​

Quantile Objects​

Examples​

GBM Example​

Request​

Response​

Historical Example​

Request​

Response​

Interpreting Results​

Overview

Input Parameters

Required Parameters

Optional Parameters

Model Values

Response

Results Fields

Quantile Objects

Examples

GBM Example

Request

Response

Historical Example

Request

Response

Interpreting Results