Liquidation

CEX futures liquidation data: recent events, firehose feed, heatmaps, maps, and bucketed history.

Usage

Sync

from datamaxi import Datamaxi

maxi = Datamaxi(api_key="YOUR_API_KEY")

# Recent liquidation events for a single futures symbol
events = maxi.liquidation(exchange="binance", symbol="BTC-USDT", limit=100)

# Firehose: most recent events across every symbol
feed = maxi.liquidation.feed(limit=100)

# Token x exchange liquidation heatmap over a rolling window
heatmap = maxi.liquidation.heatmap(window="1h", topN=10)

# Liquidation KPI stats over a rolling window
stats = maxi.liquidation.stats(window="1h")

# Coinglass-style liquidation map (price x leverage tier)
liq_map = maxi.liquidation.map(base="BTC", exchange="binance", quote="USDT")

# Bucketed long / short liquidation USD time series + price line
history = maxi.liquidation.symbol_history(
    symbol="BTC",
    quote="USDT",
    exchange="binance",
    interval="5m",
    window="24h",
)

Async

import asyncio
from datamaxi.aio import AsyncDatamaxi


async def main():
    async with AsyncDatamaxi(api_key="YOUR_API_KEY") as client:
        # Recent liquidation events for a single futures symbol
        events = await client.liquidation(exchange="binance", symbol="BTC-USDT", limit=100)

        # Firehose: most recent events across every symbol
        feed = await client.liquidation.feed(limit=100)

        # Token x exchange liquidation heatmap over a rolling window
        heatmap = await client.liquidation.heatmap(window="1h", topN=10)

        # Liquidation KPI stats over a rolling window
        stats = await client.liquidation.stats(window="1h")

        # Coinglass-style liquidation map (price x leverage tier)
        liq_map = await client.liquidation.map(base="BTC", exchange="binance", quote="USDT")

        # Bucketed long / short liquidation USD time series + price line
        history = await client.liquidation.symbol_history(
            symbol="BTC",
            quote="USDT",
            exchange="binance",
            interval="5m",
            window="24h",
        )


asyncio.run(main())

Notes

• heatmap and stats accept window of 1h, 4h, or 24h; heatmap's topN must be between 1 and 30.
• symbol_history accepts interval of 5m, 15m, or 1h and window of 24h, 72h, or 7d.

Bases: Resource

Client to fetch CEX futures liquidation data from DataMaxi+ API.

Parameters:

• api_key (str, default: None ) –

  The DataMaxi+ API key

• **kwargs (Any, default: {} ) –

  Keyword arguments used by datamaxi.api.API.

__call__

__call__(
    exchange: str, symbol: str, limit: int = 100
) -> Dict[str, Any]

Recent liquidation events for a specific futures symbol.

GET /api/v1/liquidation

Parameters:

• exchange (str) –

  Exchange name (e.g. binance).

• symbol (str) –

  Exchange-native API symbol (e.g. BTC-USDT).

• limit (int, default: 100 ) –

  Max events to return (server caps).

Returns:

• Dict[str, Any] –

  Liquidation events response.

feed

feed(
    limit: int = 100,
    exchange: Optional[str] = None,
    base: Optional[str] = None,
    min_volume_usd: Optional[float] = None,
) -> Dict[str, Any]

Firehose: most recent liquidation events across every symbol.

GET /api/v1/liquidation/feed

Parameters:

• limit (int, default: 100 ) –

  Max events to return.

• exchange (str, default: None ) –

  Optional exchange filter.

• base (str, default: None ) –

  Optional base asset filter (case-insensitive).

• min_volume_usd (float, default: None ) –

  Minimum VolumeUsd filter.

heatmap

heatmap(
    window: str = "1h", topN: int = 10
) -> Dict[str, Any]

Token × exchange liquidation heatmap over a rolling window.

GET /api/v1/liquidation/heatmap

Parameters:

• window (str, default: '1h' ) –

  Rolling window (1h, 4h, or 24h).

• topN (int, default: 10 ) –

  Top N tokens by total (1-30).

map

map(
    base: str,
    exchange: str = "binance",
    quote: str = "USDT",
) -> Dict[str, Any]

Coinglass-style liquidation map (price × leverage tier).

GET /api/v1/liquidation/map

Parameters:

• base (str) –

  Base asset (e.g. BTC).

• exchange (str, default: 'binance' ) –

  Exchange (default binance).

• quote (str, default: 'USDT' ) –

  Quote asset (default USDT).

stats

stats(
    window: str = "1h",
    exchange: Optional[str] = None,
    min_volume_usd: Optional[float] = None,
) -> Dict[str, Any]

Liquidation KPI stats over a rolling window.

GET /api/v1/liquidation/stats

Parameters:

• window (str, default: '1h' ) –

  Rolling window (1h, 4h, or 24h).

• exchange (str, default: None ) –

  Optional exchange filter.

• min_volume_usd (float, default: None ) –

  Minimum VolumeUsd filter.

symbol_history

symbol_history(
    symbol: str,
    quote: str = "USDT",
    exchange: Optional[str] = None,
    interval: Interval = "5m",
    window: str = "24h",
) -> Dict[str, Any]

Bucketed long / short liquidation USD time series + price line.

GET /api/v1/liquidation/symbol-history

Parameters:

• symbol (str) –

  Base asset (e.g. BTC).

• quote (str, default: 'USDT' ) –

  Quote asset (default USDT).

• exchange (str, default: None ) –

  Optional exchange filter for the liquidation aggregation. Price line stays on Binance unless set.

• interval (str, default: '5m' ) –

  Bucket interval (5m, 15m, or 1h).

• window (str, default: '24h' ) –

  Lookback window (24h, 72h, or 7d).