💻 API Documentation INSTITUTIONAL

REST API for programmatic access with JWT Bearer token authentication

Authentication

All API requests (except /api/health) require JWT Bearer token authentication.

Authorization: Bearer {your_jwt_token}

Token Format: HS256-signed JWT with payload: { "sub": "user_id", "tier": "pro|elite|institutional", "exp": unix_timestamp }

Base URL

https://www.liquidator-indicator.com/api/v1

All traffic is served over HTTPS (TLS). Plain http:// requests are redirected (301) to HTTPS.

API Endpoints

Authentication - Get Token

POST /auth/token

Authenticate with email and password to receive a JWT token for API access.

Request Body (JSON):

{
  "email": "demo@example.com",
  "password": "your_password"
}

Response (200 OK):

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "expires_at_utc": "2026-09-04T12:00:00Z",
    "tier": "institutional"
  },
  "timestamp_utc": "2026-09-04T10:00:00Z",
  "api_version": "1.0.0"
}

Health Check (No Auth)

GET /health

Check if the API is running and healthy.

Response (200 OK):

{
  "status": "healthy",
  "timestamp_utc": "2026-09-03T12:00:00Z",
  "version": "1.0.0"
}

Get Positions

GET /positions?symbol=BTC&limit=100&page=1 PRO+

Retrieve liquidation positions near current market price, tier-limited by maximum position count.

Parameters:

symbol (optional): Filter by symbol (BTC, ETH, SOL, etc.)
limit (optional): Results per page (default 100, max 1000)
page (optional): Page number (default 1)

Tier Limits:

Pro: Max 250 positions, 3% distance from liquidation
Elite: Max 10000 positions, 10% distance from liquidation
Institutional: Max 10000 positions, 15% distance from liquidation

Response (200 OK):

{
  "positions": [
    {
      "id": "gmx-BTC-LONG",
      "exchange": "gmx",
      "symbol": "BTC",
      "position": {
        "side": "LONG",
        "size_usd": "50000.00000000",
        "size_native": "0.64516129",
        "leverage": "2.5000",
        "entry_price": "77500.00000000",
        "current_price": "77687.45000000",
        "liquidation_price": "60000.00000000"
      },
      "liquidation": {
        "distance_to_liquidation_percent": "22.73000000",
        "is_at_risk": false,
        "risk_level": "low"
      },
      "collateral": {
        "total_usd": "20000.00000000",
        "health_factor": "2.50"
      }
    }
  ],
  "pagination": {
    "total_count": 25,
    "page": 1,
    "per_page": 100,
    "has_next": false
  },
  "request_metadata": {
    "response_time_ms": 142,
    "data_freshness_seconds": 2
  }
}

Get Positions Summary

GET /positions/summary?symbol=BTC PRO+

Get summary statistics of liquidation positions.

Response (200 OK):

{
  "summary": {
    "total_positions": 795,
    "total_value_usd": "74882163.00000000",
    "critical_risk_count": 174,
    "high_risk_count": 511,
    "by_exchange": {
      "gains": 535,
      "gmx": 178,
      "drift": 43,
      "hyperliquid": 21,
      "injective": 18
    },
    "largest_position_usd": "16000.00000000",
    "highest_leverage": "400.0000"
  },
  "request_metadata": {
    "request_id": "req_1725435600000",
    "response_time_ms": 125,
    "data_freshness_seconds": 2
  }
}

Get Liquidation Heatmap

GET /heatmap?symbol=BTC&timeframe=5m&include_longs=true&include_shorts=true PRO+

Get liquidation density heatmap at specific price levels for a symbol.

Parameters:

symbol (required): BTC, ETH, SOL, etc.
timeframe (optional): Timeframe for analysis (default 5m)
include_longs (optional): Include long liquidations (default true)
include_shorts (optional): Include short liquidations (default true)

Response (200 OK):

{
  "data": {
    "symbol": "BTC",
    "current_price": "77687.45000000",
    "heatmap": [
      {
        "price_level": "77700.00000000",
        "liquidation_count": 5,
        "total_value_usd": "450000.00000000",
        "long_value_usd": "300000.00000000",
        "short_value_usd": "150000.00000000",
        "density": 0.09,
        "risk_score": 0.85
      }
    ],
    "summary": {
      "highest_density_price": "76500.00000000",
      "total_liquidation_value": "15500000.00000000",
      "price_range": [70000, 85000]
    }
  },
  "response_time_ms": 156
}

Get OHLCV Candles

GET /ohlcv?symbol=BTC&timeframe=5m&limit=100 PRO+

Get historical OHLCV candle data for backtesting and analysis.

Parameters:

symbol (required): BTC, ETH, SOL, etc.
timeframe (required): 1m, 5m, 15m, 1h, 4h, 1d, etc.
limit (optional): Number of candles (default 100, max 1000)

Response (200 OK):

{
  "data": {
    "symbol": "BTC",
    "timeframe": "5m",
    "candles": [
      {
        "timestamp_utc": "2026-09-03T01:45:00.000000Z",
        "open": "77328.00000000",
        "high": "77468.00000000",
        "low": "77274.00000000",
        "close": "77312.00000000",
        "volume_usd": "2500000.00000000",
        "volume_native": "32.25800000"
      }
    ]
  },
  "pagination": {
    "total_count": 100,
    "page": 1,
    "per_page": 100,
    "has_next": false
  },
  "response_time_ms": 87
}

Get Available Symbols

GET /symbols PRO+

List all available trading symbols by tier.

Response (200 OK):

{
  "data": {
    "tier": "institutional",
    "symbols": ["BTC", "ETH", "SOL", "LTC", "LINK", "DOGE", "ADA", "XRP", "BNB", "ARB", "AVAX", "POL"],
    "count": 12
  },
  "timestamp_utc": "2026-09-04T10:00:00Z",
  "api_version": "1.0.0"
}

Get Available Exchanges

GET /exchanges PRO+

List all supported exchanges by tier.

Response (200 OK):

{
  "data": {
    "tier": "institutional",
    "exchanges": ["hyperliquid", "hyperliquid_full_scan", "gmx", "gains", "injective", "drift"],
    "count": 6
  },
  "timestamp_utc": "2026-09-04T10:00:00Z",
  "api_version": "1.0.0"
}

Rate Limiting

API requests are rate-limited based on subscription tier, applied per user per minute:

Pro: 600 requests/minute
Elite: 1200 requests/minute
Institutional: 1800 requests/minute
Starter: 0 requests/minute (API blocked for Starter tier)

When rate limit exceeded, the API returns 429 Too Many Requests.

Error Handling

Errors are returned with appropriate HTTP status codes and error details:

400 Bad Request: Invalid parameters
401 Unauthorized: Missing or invalid JWT token
403 Forbidden: Insufficient tier or permissions (e.g., Starter tier blocked)
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error (contact support)

Error Response Format:

{
  "error": "InvalidParameter",
  "message": "symbol parameter is required",
  "request_id": "req_abc123def456"
}

Response Format

All successful responses follow this envelope structure:

{
  "data": { /* endpoint-specific data */ },
  "pagination": { /* if applicable */ },
  "request_metadata": {
    "response_time_ms": 142,
    "data_freshness_seconds": 2,
    "api_version": "1.0.0"
  }
}

Example: Python Client

import requests

# Step 1: Authenticate and get token
auth_response = requests.post(
    "https://www.liquidator-indicator.com/api/auth/token",
    json={
        "email": "your_email@example.com",
        "password": "your_password"
    }
)
token = auth_response.json()["data"]["token"]

# Step 2: Use token to fetch positions
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
    "https://www.liquidator-indicator.com/api/v1/positions?symbol=BTC&limit=5",
    headers=headers
)
positions = response.json()["positions"]
print(positions)

Support

For API questions and support, refer to the documentation or contact: nexus2.0.2026@gmail.com