GET /risk/perp-risk-engine

Overview

The Perp Risk Engine endpoint calculates the liquidation risk probability for a leveraged cryptocurrency futures position. It uses Monte Carlo simulations driven by historical price data to model future price paths and estimate the likelihood that a given position would be liquidated within the specified risk horizon. Internal simulation parameters (lookback window, simulation count, time steps) are automatically derived from the requested risk horizon, so callers only need to supply position-level inputs.

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://api.cambrian.org/risk/perp-risk-engine

Method: GET Authentication: Required via X-API-Key by external API management, or pay per request with x402. The backend does not inspect caller credentials, and x402 does not require an API key.

Query Parameters

Response Field Descriptions

Examples

1. Long Position Liquidation Risk Check

This example checks the 1-day liquidation risk for a 10x long position on a token entered at $2800.

curl -X GET "https://api.cambrian.org/risk/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:

{
  "riskProbability": 1,
  "liquidationPrice": 2519.8038627038927,
  "entryPrice": 2800,
  "volatility": 0.1001591277873362,
  "drift": -0.015741567419845347,
  "priceChangeNeeded": 0,
  "sigmasAway": 0,
  "simulationDetails": {
    "totalSimulations": 10000,
    "liquidatedPaths": 10000,
    "dataPointsUsed": 669,
    "dataInterval": "variable",
    "riskHorizon": "1d"
  },
  "visualizationData": {
    "histogram": {
      "bins": [
        0.9820649027824402,
        0.9828762412071228,
        0.9836876392364502,
        0.9844989776611328,
        0.9853103160858154,
        0.986121654510498,
        0.9869330525398254,
        0.9877443909645081,
        0.9885557293891907,
        0.9893671274185181
      ],
      "counts": [
        3,
        0,
        2,
        7,
        16,
        11,
        20,
        34,
        55,
        78
      ],
      "finalPrices": [
        1.0012284517288208,
        0.996128261089325,
        0.995649516582489,
        0.9971165657043457,
        1.0045466423034668,
        1.0007438659667969,
        0.9913668036460876,
        1.004259467124939,
        1.0026304721832275,
        1.0033494234085083
      ]
    },
    "liquidationThreshold": 2519.8038627038927
  }
}

Note that histogram.bins, histogram.counts, and histogram.finalPrices are limited to their first 10 items in this example response; the live endpoint may return more.

For this position, the simulation returned a riskProbability of 1, indicating that under current volatility and drift conditions, all 10,000 simulated paths resulted in liquidation before the liquidation price of ~$2519.80 was avoided within the 1-day horizon.

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://x402.cambrian.org/risk/perp-risk-engine?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&entry_price=2800&leverage=10&direction=long&risk_horizon=1d");
const data = await response.json();

Quick Start (Python)

pip install "x402[httpx]"

import asyncio
import 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://x402.cambrian.org/risk/perp-risk-engine?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&entry_price=2800&leverage=10&direction=long&risk_horizon=1d")
        print(response.json())

asyncio.run(main())

Payment Flow

1. Send a normal request to the endpoint without an API key.
2. Server returns 402 Payment Required with payment details.
3. The x402 SDK 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