Cambrian Calculate Liquidation Risk API

By Cambrian Network risk

GET /api/v1/perp-risk-engine

Perpetual Risk Engine

Calculates liquidation risk probability for leveraged crypto positions using Monte Carlo simulations with historical price data. The engine supports both long and short positions with configurable risk horizons, providing comprehensive risk metrics including liquidation prices, volatility analysis, and probability distributions to help traders assess and manage their leveraged exposure.

Business Value

  • Risk Management: Quantify exact liquidation probabilities before entering leveraged positions to prevent unexpected losses
  • Position Sizing: Optimize leverage levels based on statistical risk assessments and personal risk tolerance
  • Market Intelligence: Understand volatility dynamics and price drift patterns for different tokens across various timeframes
  • Trading Strategy: Make data-driven decisions on entry points, stop losses, and position duration based on probabilistic outcomes
  • Capital Preservation: Avoid overleveraging by visualizing risk distributions and understanding sigma-based safety margins

Endpoint Details

URL: 

https://risk.cambrian.network/api/v1/perp-risk-engine

Method: GET
Authentication: Required via X-API-Key header

Query Parameters

Parameter Type Required Default Description
token_address string Yes - Solana token address for risk calculation
entry_price number Yes - Entry price in USD (must be greater than 0)
leverage number Yes - Leverage multiplier (1-1000)
direction string Yes - Position direction: "long" or "short"
risk_horizon string Yes - Risk time horizon: "1h", "1d", "1w", or "1mo"

Response Field Descriptions

Response Field Type Description
status string Status of the calculation ("success" or error message)
riskProbability number Probability of liquidation (0.0 to 1.0)
liquidationPrice number Price at which position will be liquidated
entryPrice number Entry price used for calculation
volatility number Historical volatility of the token
drift number Price drift/trend coefficient
priceChangeNeeded number Percentage price change needed for liquidation
sigmasAway number Number of standard deviations to liquidation
simulationDetails object Details about the Monte Carlo simulation
simulationDetails.totalSimulations integer Number of simulation paths run
simulationDetails.liquidatedPaths integer Number of paths that resulted in liquidation
simulationDetails.dataPointsUsed integer Historical data points used for calculation
simulationDetails.dataInterval string Time interval of historical data
simulationDetails.riskHorizon string Risk horizon used for simulation
visualizationData object Histogram data for probability visualization
visualizationData.histogram.bins array Price bin boundaries for distribution
visualizationData.histogram.counts array Frequency counts for each price bin

Examples

1. Low-Risk Conservative Position

This example calculates risk for a conservative USDC position with 10x leverage over a 1-day horizon, demonstrating extremely low liquidation probability due to stablecoin's minimal volatility.

curl -X GET "https://risk.cambrian.network/api/v1/perp-risk-engine?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&entry_price=2800&leverage=10&direction=long&risk_horizon=1d" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
    "status": "success",
    "riskProbability": 0.0,
    "liquidationPrice": 2519.8038627038927,
    "entryPrice": 2800.0,
    "volatility": 0.020297197762573476,
    "drift": -0.00999827935661967,
    "priceChangeNeeded": 0.10007004903432402,
    "sigmasAway": 94.1920961080266,
    "simulationDetails": {
        "totalSimulations": 10000,
        "liquidatedPaths": 0,
        "dataPointsUsed": 672,
        "dataInterval": "variable",
        "riskHorizon": "1d"
    },
    "visualizationData": {
        "histogram": {
            "bins": [2789.7353515625, 2790.1640625, 2790.5927734375, ...],
            "counts": [1, 4, 5, 10, 9, 19, 32, 34, 61, 67, ...]
        }
    }
}

The results show zero liquidation risk with the position being 94.19 standard deviations away from liquidation. The liquidation price of $2,519.80 requires a 10% drop from the $2,800 entry, which is extremely unlikely for USDC given its 0.02% daily volatility.

2. High-Risk Leveraged Position

This example demonstrates a high-risk BONK position with 20x leverage over a 1-week horizon, showing significant liquidation probability due to the token's high volatility.

curl -X GET "https://risk.cambrian.network/api/v1/perp-risk-engine?token_address=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263&entry_price=0.00005&leverage=20&direction=long&risk_horizon=1w" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
    "status": "success",
    "riskProbability": 0.7852,
    "liquidationPrice": 0.0000474982487741419,
    "entryPrice": 0.00005,
    "volatility": 0.9863634655060765,
    "drift": -3.154615032558206,
    "priceChangeNeeded": 0.050035024517161984,
    "sigmasAway": 0.36629800332352735,
    "simulationDetails": {
        "totalSimulations": 10000,
        "liquidatedPaths": 7852,
        "dataPointsUsed": 505,
        "dataInterval": "variable",
        "riskHorizon": "1w"
    },
    "visualizationData": {
        "histogram": {
            "bins": [0.000028527352696983144, 0.00002955128002213314, ...],
            "counts": [1, 5, 8, 19, 36, 49, 73, 146, ...]
        }
    }
}

The analysis reveals a 78.52% liquidation probability over one week, with the position only 0.37 standard deviations from liquidation. BONK's 98.64% weekly volatility combined with negative drift (-3.15%) creates extreme risk for this 20x leveraged position.

3. Short Position Risk Assessment

This example calculates risk for a SOL short position with 5x leverage over a 1-day horizon, useful for swing trading strategies.

  curl -X GET "https://risk.cambrian.network/api/v1/perp-risk-engine?token_address=So11111111111111111111111111111111111111112&entry_price=250&leverage=5&direction=short&risk_horizon=1d" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json"

Response:

  {
      "status": "success",
      "riskProbability": 0.0,
      "liquidationPrice": 300.035024517162,
      "entryPrice": 250.0,
      "volatility": 0.5233420309674812,
      "drift": 0.41767783160586225,
      "priceChangeNeeded": 0.20014009806864805,
      "sigmasAway": 7.306256670581608,
      "simulationDetails": {
          "totalSimulations": 10000,
          "liquidatedPaths": 0,
          "dataPointsUsed": 563,
          "dataInterval": "variable",
          "riskHorizon": "1d"
      },
      "visualizationData": {
          "histogram": {
              "bins": [227.99673461914062, 228.99478149414062, ...],
              "counts": [7, 3, 10, 13, 20, 13, 43, 58, ...]
          }
      }
  }

The short position shows zero liquidation risk over the 1-day timeframe, with liquidation occurring only if SOL rises 20% to $300. Being 7.3 standard deviations away from liquidation indicates very low risk for this swing trade despite SOL's 52% daily volatility.

4. Long-Term Investment Risk

This example evaluates a conservative Bitcoin (WBTC) position with 3x leverage over a 1-month horizon, suitable for longer-term positioning.

curl -X GET "https://risk.cambrian.network/api/v1/perp-risk-engine?token_address=3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh&entry_price=100000&leverage=3&direction=long&risk_horizon=1mo" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
    "status": "success",
    "riskProbability": 0.0,
    "liquidationPrice": 66643.31698855865,
    "entryPrice": 100000.0,
    "volatility": 0.28422430277073213,
    "drift": 0.1423535200897734,
    "priceChangeNeeded": 0.33356683011441346,
    "sigmasAway": 4.09361931347371,
    "simulationDetails": {
        "totalSimulations": 10000,
        "liquidatedPaths": 0,
        "dataPointsUsed": 541,
        "dataInterval": "variable",
        "riskHorizon": "1mo"
    },
    "visualizationData": {
        "histogram": {
            "bins": [76875.0078125, 78068.484375, 79261.953125, ...],
            "counts": [5, 6, 14, 16, 16, 40, 67, 87, ...]
        }
    }
}

With 3x leverage on WBTC, the position shows zero liquidation risk over one month, requiring a 33.36% drop to $66,643 for liquidation. The positive drift (14.24%) and moderate volatility (28.42%) suggest favorable conditions for this conservative leveraged investment, being 4.09 standard deviations from liquidation.

x402 Payment Option

This endpoint supports pay-per-use access via the x402 payment protocol (v2) — pay $0.05 USDC per request using blockchain micropayments. No API key required.

Quick Start (TypeScript)

npm install @x402/fetch @x402/evm viem

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment(
  "https://deep42.cambrian.network/api/v1/perp-risk-engine"
);
const data = await response.json();

Quick Start (Python)

pip install "x402[httpx]"

import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    async with x402HttpxClient(client) as http:
        response = await http.get("https://deep42.cambrian.network/api/v1/perp-risk-engine")
        print(response.json())

asyncio.run(main())

Payment Flow

  1. Send a normal request to the endpoint (no API key needed)
  2. Server returns 402 Payment Required with payment details
  3. The x402 SDK automatically signs a payment authorization with your wallet
  4. The SDK resubmits the request with the signed payment
  5. Server verifies payment and returns the API response

The x402 SDK handles steps 2–5 automatically.

Network: Base (chain ID 8453) | Currency: USDC | Price: $0.05 per request