💻 API Documentation INSTITUTIONAL

REST API for programmatic access with JWT Bearer token authentication

Experimental: The cascade endpoints (marked EXPERIMENTAL) are in a validation phase. Detection logic, thresholds, and response fields may change without notice while performance is measured on live data. Use cascade output as one input alongside your own analysis. The positions, heatmap, liquidation events, and OHLCV endpoints are not affected.

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&max_distance_pct=15 PRO+

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

Parameters:

symbol (optional): Filter by symbol (BTC, ETH, SOL, etc.)
limit (optional): Results per page (default 50, max 1000)
page (optional): Page number (default 1)
max_distance_pct (optional): Caller-controlled distance filter (0-100). API applies minimum of caller's value and tier cap for security. Example: max_distance_pct=5 returns positions within 5% of liquidation (or tier cap, whichever is lower).

Tier Limits (Distance from Liquidation):

Pro: Max 250 positions, 3% max distance (caller cannot exceed this)
Elite: Max 10000 positions, 10% max distance (caller cannot exceed this)
Institutional: Max 10000 positions, 15% max distance (caller cannot exceed this)

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": {
    "request_id": "req_1725435600000",
    "response_time_ms": 142,
    "tier_config_revision": 5,
    "data_freshness_seconds": 2,
    "distance_filter_applied_pct": 15.0
  }
}

About distance_filter_applied_pct: This metadata field shows the actual distance filter that was applied to retrieve results. If you provided max_distance_pct=5 on an Institutional tier account (15% cap), this field shows 5.0 (the minimum). This allows you to verify what filtering was performed.

Get Positions Summary

GET /positions/summary?symbol=BTC&max_distance_pct=15 PRO+

Get summary statistics of liquidation positions.

Parameters:

symbol (optional): Filter by symbol (BTC, ETH, SOL, etc.)
max_distance_pct (optional): Caller-controlled distance filter (0-100). API applies minimum of caller's value and tier cap for security. Example: max_distance_pct=5 returns summary of positions within 5% of liquidation (or tier cap, whichever is lower).

Tier Limits (Distance from Liquidation):

Pro: 3% max distance (caller cannot exceed this)
Elite: 10% max distance (caller cannot exceed this)
Institutional: 15% max distance (caller cannot exceed this)

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"
  },
  "distance_filter_applied_pct": 15.0,
  "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. Results are filtered by tier-based distance cap and collector freshness based on timeframe.

Parameters:

symbol (required): BTC, ETH, SOL, etc.
timeframe (optional): Timeframe for collector freshness filtering (5m, 15m, 1h, 4h, 1d). Only data fresher than this timeframe is included. Default: 5m
include_longs (optional): Include long liquidations (default true)
include_shorts (optional): Include short liquidations (default true)

Tier Limits (Distance from Current Price):

Pro: Heatmap shows zones within 3% distance
Elite: Heatmap shows zones within 10% distance
Institutional: Heatmap shows zones within 15% distance

Supported Timeframes: 5m (300s), 15m (900s), 1h (3600s), 4h (14400s), 1d (86400s). Undocumented timeframes return 400 Bad Request.

Response (200 OK):

{
  "data": {
    "symbol": "BTC",
    "timeframe": "5m",
    "current_price": "77687.45000000",
    "timeframe_cutoff_applied_seconds": 300,
    "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]
    }
  },
  "request_metadata": {
    "response_time_ms": 156,
    "tier_config_revision": 5
  }
}

About timeframe_cutoff_applied_seconds: This metadata field shows the collector freshness cutoff that was applied. Value is in seconds. Example: for timeframe=5m, this shows 300 (5 minutes in seconds). This proves that only data fresher than this cutoff was included in the heatmap. Collectors like Drift that are older than this cutoff are excluded.

Get Cascade Detection Analysis EXPERIMENTAL

GET /cascade/<symbol>?max_distance_pct=10 ELITE+

Analyze cascade liquidation risk with position freshness validation, direction alignment, and real-time funding rate multipliers. Detects when liquidations in one zone could trigger cascading liquidations across multiple price levels.

Parameters:

symbol (required): BTC, ETH, SOL, LTC, LINK, DOGE, ADA, XRP, BNB, ARB, AVAX, POL
max_distance_pct (optional, float): Only alert on zones within X% distance from current price (0-100, tier-limited, default 10)
limit (optional, int): Cascade signals per page (default 100, tier-limited)
page (optional, int): Page number, 1-indexed (default 1)

Phase A Features:

Position Freshness Validation: Ensures position data is recent (≤ 3x user threshold). Prevents alerts from stale 120s+ old data.
Direction Alignment Check: Validates cascade direction matches current 5-minute price momentum. Prevents opposite-direction alerts.
Funding Rate Multiplier: Fetches live funding rates from 20 exchanges. Adjusts cascade probability based on leverage bias (longs vs shorts).

Real-Time Funding Data: Funding rates are fetched from cache updated every 5 seconds by funding_oi_tracker WebSocket collectors. Data includes all 20 major exchanges (Hyperliquid, Binance, Bybit, OKX, Gate.io, MEXC, BitMEX, Deribit, KuCoin, Bitget, etc.)

Error Handling & Safety: The endpoint is designed to never trap users with missing data. Graceful fallbacks ensure reliable responses:

Missing Exchanges: If an exchange doesn't have funding data, endpoint skips it silently (no error)
Invalid Data (NaN/Infinite): Malformed funding values are automatically filtered and replaced with 1.0x multiplier
Stale Cache: If funding cache older than 5 minutes, cascade signals still returned but marked is_fresh=false in validation
No Position Data: Returns empty cascade_signals array with validation explaining why (stale positions or misaligned trend)
Partial Failures: Some exchanges may error - others still included. Multi-exchange consensus prevents single-point failures

What Users Can Expect:

✅ Always 200 OK response (never 5xx errors from funding issues)
✅ Validation flags show data quality (is_fresh, is_aligned) so users know to interpret with caution if false
✅ Falls back safely to 1.0x multiplier if any exchange unavailable
✅ Empty cascade_signals with explanation is preferable to broken/wrong signals

Response (200 OK):

{
  "api_version": "1.0.0",
  "data": {
    "cascade_signals": [
      {
        "cascade_probability": 63.5,
        "chain_length": 3,
        "chain_target_price": 76555.72669576,
        "direction_validation": "no_history",
        "funding_multiplier": 1.0,
        "is_aligned": true,
        "is_fresh": false,
        "risk_level": "HIGH",
        "trigger_zone": {
          "dominant_side": "long",
          "position_count": 14,
          "price_mean": 78032.08890133207,
          "price_range": [
            77665.26730657731,
            78320.43569140599
          ],
          "total_usd": 301140.31329755497
        }
      },
      {
        "cascade_probability": 60.2,
        "chain_length": 2,
        "chain_target_price": 79014.10156627,
        "direction_validation": "no_history",
        "funding_multiplier": 1.0,
        "is_aligned": true,
        "is_fresh": false,
        "risk_level": "HIGH",
        "trigger_zone": {
          "dominant_side": "long",
          "position_count": 10,
          "price_mean": 79723.7212056005,
          "price_range": [
            79439.45667424498,
            80069.968700475
          ],
          "total_usd": 534178.0457557226
        }
      },
      {
        "cascade_probability": 83.5,
        "chain_length": 2,
        "chain_target_price": 80553.63970819,
        "direction_validation": "no_history",
        "funding_multiplier": 1.0,
        "is_aligned": true,
        "is_fresh": false,
        "risk_level": "CRITICAL",
        "trigger_zone": {
          "dominant_side": "long",
          "position_count": 29,
          "price_mean": 81331.8056198665,
          "price_range": [
            80982.81742067334,
            81716.7835714868
          ],
          "total_usd": 10059245.945880584
        }
      },
      {
        "cascade_probability": 83.0,
        "chain_length": 2,
        "chain_target_price": 83203.5054131,
        "direction_validation": "no_history",
        "funding_multiplier": 1.0,
        "is_aligned": true,
        "is_fresh": false,
        "risk_level": "CRITICAL",
        "trigger_zone": {
          "dominant_side": "long",
          "position_count": 28,
          "price_mean": 83942.90888195942,
          "price_range": [
            83622.4268002695,
            84277.77123554893
          ],
          "total_usd": 456382.05636051
        }
      },
      {
        "cascade_probability": 100.0,
        "chain_length": 4,
        "chain_target_price": 87143.72058883,
        "direction_validation": "no_history",
        "funding_multiplier": 1.0,
        "is_aligned": true,
        "is_fresh": false,
        "risk_level": "CRITICAL",
        "trigger_zone": {
          "dominant_side": "short",
          "position_count": 23,
          "price_mean": 84813.47651154907,
          "price_range": [
            84406.99305462823,
            85207.84887447837
          ],
          "total_usd": 639480.1414181989
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "has_next": true,
      "has_prev": false,
      "page_size": 5,
      "total_pages": 2,
      "total_signals": 9
    },
    "symbol": "BTC"
  },
  "message": "",
  "status": "success",
  "timestamp_utc": "2026-10-02T20:06:18.321122Z"
}

Cascade Signal Fields:

trigger_zone: Primary liquidation cluster that could trigger the cascade
cascade_probability: 0-100 likelihood that liquidations will propagate down the chain
chain_length: Number of zones involved in the cascade chain
chain_target_price: Estimated final price if cascade executes fully
direction_validation: Validation status of cascade direction (values: "no_history", "aligned", "divergent")
is_fresh: Position data is recent enough (passes freshness validation)
is_aligned: Cascade direction matches current price momentum (prevents false alerts)
funding_multiplier: Adjustment factor based on funding rate (1.0x = neutral, >1.0x = higher risk)
risk_level: LOW, MEDIUM, HIGH, or CRITICAL based on probability and chain length

Trigger Zone Fields:

dominant_side: Primary position direction in the zone ("long" or "short")
position_count: Number of liquidatable positions in this zone
price_mean: Average entry price of positions in the zone
price_range: [min_price, max_price] - the price band containing clustered positions
total_usd: Total notional value of positions at risk in USD

Access Control: Requires Elite tier or higher. Returns 403 Forbidden for Pro/Starter users.

Get Liquidation Events

GET /cascade/data/liquidation_events/<symbol>?limit=100&page=1 PRO+

Access real-time liquidation events from the Liquidation Event Aggregator. Returns paginated events collected from multiple exchanges with timestamp, side, price, and value information for liquidation pattern analysis.

Parameters:

symbol (required): BTC, ETH, SOL, LTC, LINK, DOGE, ADA, XRP, BNB, ARB, AVAX, POL
limit (optional): Events per page (default 100, max 1000 for Elite, 5000 for Institutional)
page (optional): Page number, 1-indexed (default 1)

Response (200 OK):

{
  "api_version": "1.0.0",
  "data": {
    "symbol": "BTC",
    "phase": "Liquidation Event Aggregator",
    "phase_description": "Collects real-time liquidation events from 15 exchanges",
    "liquidation_events": [
      {
        "timestamp": "2026-10-02 19:24:49.399106+00:00",
        "exchange": "phemex",
        "side": "BUY",
        "price": 84135.6,
        "quantity": 0.171,
        "value_usd": 14387.187600000005
      },
      {
        "timestamp": "2026-10-02 19:24:36.817087+00:00",
        "exchange": "phemex",
        "side": "BUY",
        "price": 84089.8,
        "quantity": 0.266,
        "value_usd": 22367.8868
      },
      {
        "timestamp": "2026-10-02 19:24:35+00:00",
        "exchange": "mexc",
        "side": "SELL",
        "price": 84132.52,
        "quantity": 0.13214357,
        "value_usd": 11117.5715458964
      }
    ],
    "pagination": {
      "current_page": 1,
      "has_next": true,
      "has_prev": false,
      "page_size": 3,
      "total_events": 1200,
      "total_pages": 400
    },
    "summary": {
      "data_age_seconds": 0,
      "event_count_by_exchange": {
        "mexc": 1,
        "phemex": 2
      },
      "events_on_page": 3,
      "exchanges": [
        "mexc",
        "phemex"
      ]
    }
  },
  "message": "",
  "status": "success",
  "timestamp_utc": "2026-10-02T19:24:57.780028Z"
}

Use Cases: Liquidation pattern analysis, exchange-specific research, timing correlation, event volume measurement

Get Hawkes Features EXPERIMENTAL

GET /cascade/data/hawkes_features/<symbol> ELITE+

Access Hawkes Feature Extraction data with cascade-relevant metrics updated every 10 seconds. Returns baseline intensity, cascade intensity, and self-excitement ratios per exchange for advanced cascade analysis.

Parameters:

symbol (required): BTC, ETH, SOL, LTC, LINK, DOGE, ADA, XRP, BNB, ARB, AVAX, POL
limit (optional, int): Features per exchange (default 50, tier-limited)
page (optional, int): Page number, 1-indexed (default 1)

Response (200 OK):

{
  "api_version": "1.0.0",
  "data": {
    "hawkes_features": {
      "binance": [
        {
          "baseline_intensity": 0.0,
          "cascade_candidate": false,
          "cascade_intensity": 0.0,
          "event_count_5s": 0,
          "event_count_60s": 0,
          "self_excitement_ratio": 0.0,
          "timestamp": "2026-10-02T20:03:35.098635+00:00"
        },
        {
          "baseline_intensity": 0.0,
          "cascade_candidate": false,
          "cascade_intensity": 0.0,
          "event_count_5s": 0,
          "event_count_60s": 0,
          "self_excitement_ratio": 0.0,
          "timestamp": "2026-10-02T19:48:20.187071+00:00"
        }
      ],
      "bitfinex": [...],
      "bybit": [...],
      "htx": [...],
      "mexc": [...],
      "phemex": [...]
    },
    "pagination": {
      "current_page": 1,
      "has_next": true,
      "has_prev": false,
      "page_size": 5,
      "total_features": 21,
      "total_pages": 5
    },
    "phase": "Hawkes Feature Extractor",
    "phase_description": "Extracts cascade features every 10 seconds",
    "symbol": "BTC"
  },
  "message": "",
  "status": "success",
  "timestamp_utc": "2026-10-02T20:06:05.200066Z"
}

Feature Definitions:

baseline_intensity (μ): Average events/sec over 60-second window
cascade_intensity: Events/sec in current 5-second window
self_excitement_ratio: cascade_intensity / baseline_intensity
cascade_candidate: True if ratio ≥ 2.0x AND ≥3 events in 5s
event_count_60s: Total events in 60-second window
event_count_5s: Events in current 5-second window

Use Cases: Feature engineering, ML model training, intensity benchmarking, exchange comparison

Get Hawkes Models EXPERIMENTAL

GET /cascade/data/hawkes_models/<symbol> ELITE+

Access Hawkes Detector models per exchange. μ, α, β are re-estimated by maximum likelihood on the liquidation event times about every 10 minutes; intensity_now and the cascade call are re-evaluated every 60 seconds. Entries written before this revision have fit_valid: false.

Parameters:

symbol (required): BTC, ETH, SOL, LTC, LINK, DOGE, ADA, XRP, BNB, ARB, AVAX, POL
limit (optional, int): Models per exchange (default 20, tier-limited)
page (optional, int): Page number, 1-indexed (default 1)

Response (200 OK):

{
  "api_version": "1.0.0",
  "data": {
    "hawkes_models": {
      "binance": [
        {
          "active_events": 0.0,
          "alpha": 0.109343718,
          "alpha_mu_ratio": 9.98,
          "beta": 0.148561,
          "branching_ratio": 0.736,
          "cascade_confidence": 0.0,
          "fit_valid": true,
          "intensity_now": 0.054591329,
          "is_cascade": false,
          "mu": 0.010950325,
          "n_events": 903,
          "timestamp": "2026-10-08T18:33:40.283094+00:00",
          "volume_5m_usd": 3643269.62,
          "volume_gate_usd": 5221518.0
        },
        {
          "active_events": 0.0,
          "alpha": 0.109343718,
          "alpha_mu_ratio": 9.98,
          "beta": 0.148561,
          "branching_ratio": 0.736,
          "cascade_confidence": 0.0,
          "fit_valid": true,
          "intensity_now": 0.010950325,
          "is_cascade": false,
          "mu": 0.010950325,
          "n_events": 896,
          "timestamp": "2026-10-08T18:32:39.155372+00:00",
          "volume_5m_usd": 994762.26,
          "volume_gate_usd": 5221518.0
        }
      ],
      "bitfinex": [...],
      "bybit": [...],
      "gateio": [...],
      "htx": [...],
      "mexc": [...],
      "okx": [...],
      "phemex": [...]
    },
    "pagination": {
      "current_page": 1,
      "has_next": true,
      "has_prev": false,
      "page_size": 5,
      "total_models": 144,
      "total_pages": 29
    },
    "phase": "Hawkes Detector",
    "phase_description": "Fits Hawkes models every 60 seconds",
    "symbol": "BTC"
  },
  "message": "",
  "status": "success",
  "timestamp_utc": "2026-10-08T18:33:53.058331Z"
}

Model Parameters:

μ (mu): Background liquidation rate (events/sec)
α (alpha): Intensity jump per event (events/sec)
β (beta): Decay rate (1/sec)
alpha_mu_ratio: α / μ
branching_ratio: α / β, kept below 1 (stable process)
intensity_now: Model intensity λ(now) = μ + α·Σ exp(−β(now − tᵢ)) (events/sec)
active_events: Events in the last 5 seconds when the entry was written
n_events: Events in the 6-hour fit window
fit_valid: false when the window had too few events to fit; no cascade can be called
volume_5m_usd: The symbol's liquidation volume (all exchanges) over the last 5 minutes, in USD
volume_gate_usd: The symbol's own volume threshold (95th percentile of 5-minute liquidation volume, refreshed daily); 0 = gate off
is_cascade: fit_valid AND cascade_confidence at or above the cascade threshold AND at least 3 active_events AND volume_5m_usd at or above volume_gate_usd
cascade_confidence: Self-excited share of λ(now), 1 − μ/λ(now) (0-1)

Use Cases: Model parameter analysis, cascade strength comparison, fingerprinting by exchange, model validation

Get Cascade Consensus EXPERIMENTAL

GET /cascade/data/cascade_consensus?symbol=BTC&min_confidence=0.6 ELITE+

Access multi-exchange Cascade Consensus predictions aggregated every 60 seconds. Combines Hawkes Detector results across exchanges with agreement scoring for high-confidence cascade signals.

Parameters:

symbol (optional): Filter to specific symbol. If omitted, returns all symbols
min_confidence (optional, float): Filter to consensus_confidence >= this value (0.0-1.0, default 0.0)
limit (optional, int): Symbols per page (default 100, tier-limited)
page (optional, int): Page number, 1-indexed (default 1)

Response (200 OK):

{
  "api_version": "1.0.0",
  "data": {
    "cascade_consensus": {
      "BTC": {
        "avg_alpha": 0.866006,
        "cascade_signal": false,
        "consensus_confidence": 0.5,
        "details": {
          "binance": {
            "alpha": 0.0,
            "alpha_mu_ratio": 0.0,
            "beta": 1.499844,
            "cascade_confidence": 0.0,
            "intensity_now": 0.0,
            "mu": 0.057143
          },
          "bitfinex": {
            "alpha": 0.065267,
            "alpha_mu_ratio": 65.267,
            "beta": 0.120702,
            "cascade_confidence": 0.0,
            "intensity_now": 0.0,
            "mu": 0.0001
          }
        },
        "exchange_agreement": 0.0,
        "exchange_count": 6,
        "exchanges": [
          "binance",
          "bitfinex",
          "bybit",
          "htx",
          "mexc",
          "phemex"
        ],
        "max_alpha": 5.000232,
        "min_alpha": 0.0,
        "timestamp": "2026-10-02T20:05:42.161942+00:00",
        "total_exchanges": 6
      }
    },
    "pagination": {
      "current_page": 1,
      "has_next": false,
      "has_prev": false,
      "page_size": 5,
      "total_pages": 1,
      "total_symbols": 1
    },
    "phase": "Cascade Consensus",
    "phase_description": "Aggregates multi-exchange predictions every 60 seconds"
  },
  "message": "",
  "status": "success",
  "timestamp_utc": "2026-10-02T20:06:13.376960Z"
}

Consensus Metrics:

cascade_signal: True if consensus_confidence ≥ 0.6
consensus_confidence: 0-1 aggregated confidence score
exchange_count: Exchanges detecting cascade
total_exchanges: Total exchanges with data
exchange_agreement: 0-1 agreement quality (α consistency)
avg_alpha / min_alpha / max_alpha: Self-excitement statistics
details: Per-exchange model parameters (μ, α, β, ratios)

Use Cases: Multi-exchange validation, agreement analysis, high-confidence signal filtering, exchange disagreement research

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"
}

Get API Version & Revision Tracking

GET /version PRO+

Get API version information with dual revision tracking for configuration changes and measurement segmentation.

Two Independent Revision Counters:

tier_config_revision: Increments when API features, tier limits, or configuration changes (new parameters, distance caps, symbols, exchanges, rate limits, etc.)
measurement_revision: Increments ONLY when actual data changes (data collection improvements, data quality fixes). Use this to segment measurements and backtests without fragmenting on feature releases.

When to use: Poll this endpoint periodically to detect changes. When tier_config_revision increments, check what changed in the API. When measurement_revision increments, know your data has changed.

Response (200 OK):

{
  "status": "success",
  "data": {
    "version": "1.0.0",
    "tier_config_revision": 5,
    "measurement_revision": 2,
    "tier_config_revision_notes": {
      "1": "Initial API release with /positions, /heatmap, /ohlcv endpoints",
      "2": "Added heatmap tier-capping and fixed band sum reconciliation",
      "3": "Added max_distance_pct parameter to /positions endpoint",
      "4": "Resolved timing issue - all symbols now have complete OHLCV data",
      "5": "Added max_distance_pct support to /positions/summary endpoint"
    },
    "measurement_revision_notes": {
      "1": {"note": "Initial data release", "affects_data": null},
      "2": {"note": "OHLCV backfill completed for all symbols; heatmap tier-capping reconciliation fixed", "affects_data": true}
    },
    "last_coverage_update": "2026-09-29T12:00:00Z"
  },
  "timestamp_utc": "2026-09-29T12:30:45Z",
  "api_version": "1.0.0"
}

Key Difference: tier_config_revision tracks ALL changes (API features go 1→5), while measurement_revision tracks ONLY data changes (only goes 1→2). This prevents your backtest measurements from fragmenting when we add API features.

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

IMPORTANT: Different API endpoints use different response envelope formats.

Format 1: Top-Level Data (Positions Endpoints)

The following endpoints return data directly at the top level:

GET /api/v1/positions
GET /api/v1/positions/summary

Response Structure:

{
  "status": "success",
  "positions": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 840,
    "has_next": false
  },
  "distance_filter_applied_pct": 15,
  "response_time_ms": 125
}

Format 2: Data-Wrapped (Data & Version Endpoints)

The following endpoints wrap data in a "data" object:

GET /api/v1/heatmap
GET /api/v1/cascade/<symbol>
GET /api/v1/ohlcv
GET /api/v1/version

Response Structure:

{
  "status": "success",
  "data": {
    "version": "1.0.0",
    "tier_config_revision": 5,
    "measurement_revision": 2,
    "tier_config_revision_notes": {...},
    "measurement_revision_notes": {...},
    "last_coverage_update": "2026-09-29T14:35:00Z"
  },
  "response_time_ms": 50
}

Why two formats? Positions endpoints return data at top level for direct access. Data/version endpoints wrap content in "data" for consistency with metadata fields.

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