Граббінг даних ліквідацій з бірж

Парсинг даних ликвидаций з бирж

Дані про ликвидації — один з найцінніших on-chain та off-chain сигналів для трейдерів. Різкий зріст ликвидаций лонгів → потенційне продовження падіння. Каскад ликвидаций шортів → можливий short squeeze. Проблема: біржи відають ці дані по-різному, багато обмежують історичну глибину, а REST та WebSocket API ведуть себе непередбачуване під навантаженням.

Джерела даних: CeFi vs DeFi

Централізовані біржі

Binance — найліквідніший джерело. WebSocket endpoint wss://fstream.binance.com/ws/!forceOrder@arr стримить всі ликвидації по всім фючерсним парам в реальному часі. Формат события:

{
  "e": "forceOrder",
  "E": 1704067200000,
  "o": {
    "s": "BTCUSDT",
    "S": "SELL",           // SELL = long liquidation
    "o": "LIMIT",
    "f": "IOC",
    "q": "0.014",          // quantity
    "p": "41850.00",       // price
    "ap": "41800.00",      // average price
    "X": "FILLED",
    "l": "0.014",
    "z": "0.014",
    "T": 1704067200000
  }
}

Історичні дані доступні через REST тільки за останню годину (/fapi/v1/forceOrders). Для більш глибокої історії — потрібно постійно писати дані самостійно з момента запуску.

OKX — WebSocket channel liquidation-orders з фільтром по інструменту. Схожа структура, інші імена полів. REST історія — 3 місяці через /api/v5/public/liquidation-orders.

Bybit — WebSocket topic liquidation.{symbol}. Історичні дані через /v5/market/recent-trade (ликвидації приходять як особливий тип трейдів).

Bitmex — WebSocket liquidation channel. Один з найстаріших джерел, дані з 2014 року через API.

Deribit — опціон та фьючерси на BTC/ETH. WebSocket liquidations.{instrument}. Важливий для розуміння опціонного ринку.

Децентралізовані біржі

DeFi perps ликвидації — це on-chain события, більш надійне джерело:

GMX v2 — событие PositionLiquidated (або OrderCancelled з reason LIQUIDATION) в EventEmitter контракті на Arbitrum. Всі дані on-chain, історичні дані через The Graph subgraph або прямий парсинг.

dYdX v4 — Cosmos-based chain, ликвидації як on-chain транзакції. Парсинг через Cosmos RPC або Indexer API.

Hyperliquid — свій L1, API з повною історією ликвидаций.

Aave v3, Compound v3 — lending ликвидації через LiquidationCall / AbsorbCollateral события. Це не perps, але важливий компонент загальної картини ликвидаций.

Реалізація WebSocket collector

import WebSocket from 'ws';

interface LiquidationEvent {
  exchange: string;
  symbol: string;
  side: 'long' | 'short';  // якась сторона була ликвідирована
  price: number;
  quantity: number;
  quantity_usd: number;
  timestamp: number;
  raw: Record<string, unknown>;
}

class BinanceLiquidationCollector {
  private ws: WebSocket;
  private reconnectDelay = 1000;

  async connect(onEvent: (event: LiquidationEvent) => Promise<void>) {
    this.ws = new WebSocket('wss://fstream.binance.com/ws/!forceOrder@arr');

    this.ws.on('message', async (data) => {
      const raw = JSON.parse(data.toString());
      const event = this.normalize(raw);
      await onEvent(event);
    });

    this.ws.on('close', () => {
      // Exponential backoff reconnect
      setTimeout(() => {
        this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
        this.connect(onEvent);
      }, this.reconnectDelay);
    });

    this.ws.on('open', () => {
      this.reconnectDelay = 1000; // reset on success
    });
  }

  private normalize(raw: any): LiquidationEvent {
    return {
      exchange: 'binance',
      symbol: raw.o.s,
      side: raw.o.S === 'SELL' ? 'long' : 'short',
      price: parseFloat(raw.o.ap),
      quantity: parseFloat(raw.o.q),
      quantity_usd: parseFloat(raw.o.ap) * parseFloat(raw.o.q),
      timestamp: raw.E,
      raw,
    };
  }
}

Для мультибіржевого collector — один інтерфейс LiquidationCollector з реалізаціями per exchange. Нормалізація в єдиний формат критична: у кожної біржі свої conventions для side, price, quantity.

Зберігання та агрегація

Ликвидації — time-series дані. TimescaleDB — оптимальний вибір:

CREATE TABLE liquidations (
  time        TIMESTAMPTZ NOT NULL,
  exchange    TEXT NOT NULL,
  symbol      TEXT NOT NULL,
  base_asset  TEXT NOT NULL,    -- BTC, ETH, SOL
  side        TEXT NOT NULL,    -- 'long' | 'short'
  price       NUMERIC(20, 8),
  quantity    NUMERIC(20, 8),
  quantity_usd NUMERIC(20, 2),
  raw         JSONB
);

SELECT create_hypertable('liquidations', 'time');

-- Індекс для швидких запитів по активу
CREATE INDEX ON liquidations (base_asset, time DESC);

Continuous aggregates для аналітики:

-- Агрегат по хвилинам для кожного активу
CREATE MATERIALIZED VIEW liquidations_1m
WITH (timescaledb.continuous) AS
SELECT
  time_bucket('1 minute', time) AS bucket,
  base_asset,
  exchange,
  SUM(CASE WHEN side = 'long' THEN quantity_usd ELSE 0 END) AS long_liq_usd,
  SUM(CASE WHEN side = 'short' THEN quantity_usd ELSE 0 END) AS short_liq_usd,
  COUNT(*) AS count
FROM liquidations
GROUP BY bucket, base_asset, exchange;

Метрики та індикатори

Корисні похідні метрики з raw даних ликвидаций:

Cumulative liquidation volume — сума ликвидаций за період. Різкий зріст > 3 стандартних відхилення від скользячого середнього — сигнал каскаду.

Long/Short ratio ликвидаций — якщо 80%+ ликвидаций однієї сторони — напрямний сигнал.

Liquidation clusters — цінові рівні з високою концентрацією ликвидаций. Використовуються як рівні підтримки/сопротивління (де знаходяться liquidation engines бирж).

import pandas as pd
import numpy as np

def detect_liquidation_cascade(
    df: pd.DataFrame,
    window_minutes: int = 5,
    std_multiplier: float = 3.0,
) -> pd.Series:
    """
    df: DataFrame з колонками ['time', 'quantity_usd']
    Повертає bool Series: True там де каскад ликвидаций
    """
    rolling = df.set_index('time')['quantity_usd'].rolling(f'{window_minutes}T')
    mean = rolling.mean()
    std = rolling.std()
    current = df.set_index('time')['quantity_usd']
    return current > (mean + std_multiplier * std)

Обмеження та edge cases

Біржі не завжди відають всі дані. Деякі біржі агрегують дрібні ликвидації або вводять затримку. Історичні дані можуть бути ревідовані.

Diffs у нормалізації. У Binance S: "SELL" означає ликвідацію long позиції (примусова продаж). У інших бирж логіка може бути зворотною — завжди верифікуйте логіку side.

WebSocket message lag. Binance WS іноді доставляє события з затримкою 1-5 секунд при високій навантаженню на ринку — саме коли дані найбільш важливі. Timestamp у raw события — це час ликвідації, а не доставки.

Cross-exchange deduplication. Одна крупна позиція може бути ликвідирована через кілька ордерів, які приходять як окремі события.

Стек та сроки

Collector для 5 бирж + on-chain GMX/Aave + TimescaleDB зберігання + базовий API: 3-4 тижні. Кастомний dashboard з liquidation heatmap та каскад-детектором — ще 1-2 тижні.