Developer Resources
Everything you need to integrate with CryptoHFTData. Explore our API endpoints, Python SDK, and historical data format.
Liquidations
Get Liquidation Data
Retrieve liquidation events for futures contracts including liquidation price, quantity, and direction.
Python SDK Usage
Understanding Liquidations
- Long Liquidations: Occur when long positions are forcibly closed due to losses
- Short Liquidations: Occur when short positions are forcibly closed due to losses
- High liquidation volume: Often indicates high volatility or over-leveraged positions
Data Format - CommonLiquidation
Liquidation data is stored using the CommonLiquidation structure, which captures forced position closures with comprehensive order execution details and timing information:
Schema Overview
Each liquidation event contains timing information, symbol data, and detailed order execution metrics including side, price, quantity, and order status. The side field indicates which type of position was liquidated.
Field Definitions
| Field | Type | Nullable | Description |
|---|---|---|---|
| received_time | INT64 | No | Unix timestamp (nanoseconds) when our system received the liquidation event |
| event_time | INT64 | No | Unix timestamp (exchange dependent on timescale) when the exchange generated the event |
| symbol | STRING | No | Trading pair symbol (e.g., 'BTCUSDT') |
| side | STRING | No | Side of the liquidation order ("BUY" = short position liquidated, "SELL" = long position liquidated) |
| order_type | STRING | No | Type of liquidation order (e.g., "MARKET", "LIMIT") |
| time_in_force | STRING | No | Order time-in-force policy (e.g., "IOC", "FOK", "GTC") |
| quantity | STRING | No | Total order quantity being liquidated (stored as string for precision) |
| price | STRING | No | Liquidation order price (stored as string for precision) |
| average_price | STRING | No | Average execution price across all fills (stored as string for precision) |
| order_status | STRING | No | Current status of the liquidation order (e.g., "FILLED", "PARTIALLY_FILLED") |
| last_filled_quantity | STRING | No | Quantity filled in the most recent execution (stored as string for precision) |
| filled_quantity | STRING | No | Total quantity filled so far (stored as string for precision) |
| trade_time | INT64 | No | Unix timestamp when the liquidation trade occurred |
Liquidation Side Interpretation
Buy Liquidations (Short Squeeze)
side = "Buy" means short positions were liquidated
- Short positions forced to close
- Buy orders executed to cover shorts
- Usually happens when price rises sharply
- Creates additional upward price pressure
Sell Liquidations (Long Squeeze)
side = "Sell" means long positions were liquidated
- Long positions forced to close
- Sell orders executed to close longs
- Usually happens when price falls sharply
- Creates additional downward price pressure
Working with the Data
Want to go deeper?
For a comprehensive tutorial on liquidation analysis, including cascade detection and price zone identification, check out our blog post: Liquidation Analysis: Understanding Forced Selling in Crypto Markets