I've spent three years building trading tools and data pipelines for crypto funds, and nothing frustrates beginners more than trying to access reliable historical liquidation data. When I first started, I spent weeks trying to piece together fragmented APIs, dealing with rate limits, missing data gaps, and incompatible formats. That's why I'm writing this guide—to save you the headache I went through.

Historical liquidation data is critical for understanding market sentiment, identifying whale activity, backtesting strategies, and managing risk. Bybit, as one of the largest derivatives exchanges, processes billions in liquidations daily. Accessing this data reliably shouldn't require a PhD in API engineering.

What Are Liquidations and Why Do They Matter?

Liquidations occur when a trader's position is automatically closed because their margin has been depleted. When prices move sharply in one direction, mass liquidations cascade through the market—these events often mark local tops and bottoms. Professional traders monitor liquidation clusters to time entries and exits.

Why HolySheep for Bybit Data?

Before diving into code, let me explain why I switched to HolySheep AI for data access. The platform offers:

Method 1: Direct Bybit API (Free but Limited)

Bybit offers a public API for liquidations. However, this method has significant drawbacks: limited historical depth (max 200 records per request), rate limits, and no guarantee of data completeness. Here's how to access it:

# Bybit Public API - Limited Historical Liquidations

Note: This only returns recent data, max 200 records per request


import requests
import time

def get_bybit_liquidations(limit=200):
    """
    Fetch recent liquidations from Bybit public API.
    Maximum 200 records per call. Rate limited to 10 requests/minute.
    """
    url = "https://api.bybit.com/v5/liquidation/snapshot"
    params = {
        "category": "linear",  # USDT perpetual
        "limit": limit
    }
    
    try:
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()
        
        if data.get("retCode") == 0:
            return data.get("result", {}).get("list", [])
        else:
            print(f"API Error: {data.get('retMsg')}")
            return []
    except requests.exceptions.RequestException as e:
        print(f"Connection error: {e}")
        return []


Usage example

liquidations = get_bybit_liquidations(limit=200)
print(f"Retrieved {len(liquidations)} liquidations")
for liq in liquidations[:5]:
    print(f"  {liq.get('symbol')}: ${liq.get('price')} | Size: {liq.get('size')}")

Limitations of this method:

Method 2: HolySheep API (Recommended)

For comprehensive historical access, I recommend HolySheep AI. Their unified API provides clean, normalized liquidation data across exchanges with less than 50ms latency and pricing at ¥1 = $1 (85%+ savings vs ¥7.3 competitors).

# HolySheep AI - Complete Bybit Historical Liquidations

Unified API for Binance, Bybit, OKX, Deribit


import requests
import json
from datetime import datetime, timedelta

HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"  # Get from https://www.holysheep.ai/register

def get_bybit_liquidations_historical(
    symbol: str = "BTCUSDT",
    start_time: int = None,
    end_time: int = None,
    limit: int = 1000
):
    """
    Fetch historical liquidation data from Bybit via HolySheep.
    
    Args:
        symbol: Trading pair (e.g., "BTCUSDT", "ETHUSDT")
        start_time: Unix timestamp in milliseconds (optional)
        end_time: Unix timestamp in milliseconds (optional)
        limit: Max records to return (1-1000)
    
    Returns:
        List of liquidation records with price, size, side, timestamp
    """
    url = f"{HOLYSHEEP_BASE_URL}/liquidation/bybit"
    
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "symbol": symbol,
        "limit": min(limit, 1000)
    }
    
    if start_time:
        payload["start_time"] = start_time
    if end_time:
        payload["end_time"] = end_time
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=30)
        response.raise_for_status()
        data = response.json()
        
        if data.get("success"):
            return data.get("data", {}).get("liquidations", [])
        else:
            print(f"Error: {data.get('message')}")
            return []
            
    except requests.exceptions.RequestException as e:
        print(f"Connection error: {e}")
        return []


Example: Get last 7 days of BTC liquidations

end_ts = int(datetime.now().timestamp() * 1000)
start_ts = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)

liquidations = get_bybit_liquidations_historical(
    symbol="BTCUSDT",
    start_time=start_ts,
    end_time=end_ts,
    limit=500
)

print(f"📊 Retrieved {len(liquidations)} Bybit liquidations")
print(f"   Date range: {datetime.fromtimestamp(start_ts/1000)} to {datetime.fromtimestamp(end_ts/1000)}")
print("\nTop 5 largest liquidations:")
sorted_by_size = sorted(liquidations, key=lambda x: x.get('size', 0), reverse=True)
for liq in sorted_by_size[:5]:
    print(f"   💥 {liq.get('side')} {liq.get('size')} @ ${liq.get('price')} | {liq.get('timestamp')}")

Method 3: HolySheep Trade + Order Book Combo

For advanced analysis, combining liquidation data with trades and order book snapshots gives you the full picture. Here's a complete example that fetches liquidations alongside trade data:

# HolySheep AI - Multi-Endpoint Data Suite

Combining liquidations + trades + order book for complete market picture


import requests
import pandas as pd
from datetime import datetime

HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"

class HolySheepClient:
    """Clean client for HolySheep market data endpoints."""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.holysheep.ai/v1"
        self.session = requests.Session()
        self.session.headers.update({"Authorization": f"Bearer {api_key}"})
    
    def get_liquidations(self, exchange: str, symbol: str, **kwargs):
        """Get liquidation data from specified exchange."""
        url = f"{self.base_url}/liquidation/{exchange}"
        response = self.session.post(url, json={"symbol": symbol, **kwargs})
        return response.json()
    
    def get_trades(self, exchange: str, symbol: str, **kwargs):
        """Get recent trades from specified exchange."""
        url = f"{self.base_url}/trade/{exchange}"
        response = self.session.post(url, json={"symbol": symbol, **kwargs})
        return response.json()
    
    def get_orderbook(self, exchange: str, symbol: str, depth: int = 20):
        """Get order book snapshot from specified exchange."""
        url = f"{self.base_url}/orderbook/{exchange}"
        response = self.session.post(url, json={"symbol": symbol, "depth": depth})
        return response.json()


Initialize client

client = HolySheepClient(api_key=API_KEY)


Fetch comprehensive market data for BTCUSDT on Bybit

symbol = "BTCUSDT"

print(f"Fetching comprehensive {symbol} data from Bybit...\n")


1. Get liquidations

liq_response = client.get_liquidations("bybit", symbol, limit=100)
liquidations = liq_response.get("data", {}).get("liquidations", [])
print(f"✅ Liquidations: {len(liquidations)} records")


2. Get recent trades

trade_response = client.get_trades("bybit", symbol, limit=100)
trades = trade_response.get("data", {}).get("trades", [])
print(f"✅ Trades: {len(trades)} records")


3. Get order book snapshot

ob_response = client.get_orderbook("bybit", symbol, depth=50)
orderbook = ob_response.get("data", {})
print(f"✅ Order Book: {len(orderbook.get('bids', []))} bids / {len(orderbook.get('asks', []))} asks")


Convert to DataFrames for analysis

df_liq = pd.DataFrame(liquidations)
df_trades = pd.DataFrame(trades)

if not df_liq.empty:
    df_liq['size_usd'] = df_liq['size'].astype(float) * df_liq['price'].astype(float)
    print(f"\n📈 Liquidation Summary:")
    print(f"   Total liquidations: {len(df_liq)}")
    print(f"   Long liquidations: {len(df_liq[df_liq['side'] == 'Sell'])}")
    print(f"   Short liquidations: {len(df_liq[df_liq['side'] == 'Buy'])}")
    print(f"   Total liquidation value: ${df_liq['size_usd'].sum():,.2f}")

Comparing Data Access Methods

Here's a direct comparison of the three methods covered in this guide:

Feature Bybit Public API HolySheep Basic HolySheep Pro
Historical Depth Last 24 hours 90 days Unlimited (2+ years)
Records per Request 200 max 1,000 10,000
Rate Limits 10 req/min 100 req/min 1,000 req/min
Latency 100-300ms <50ms <30ms
Exchanges Supported Bybit only 4 major exchanges 8+ exchanges
Pricing Free ¥1 = $1 ¥1 = $1 (volume discounts)
Payment Methods N/A WeChat/Alipay/Card WeChat/Alipay/Card/Wire
WebSocket Support Yes Yes Yes (real-time)
SLA Guarantee None 99.5% 99.9%

Who It Is For / Not For

Perfect for:

Probably not for:

Pricing and ROI

HolySheep offers straightforward pricing at ¥1 = $1 USD, which represents an 85%+ savings compared to typical industry rates of ¥7.3 per dollar. Here's the math:

ROI calculation: If you save 2 hours/week by having clean, unified data (instead of stitching together multiple APIs), that's $100-200 in time savings at a $50/month subscription. Plus, avoiding data gaps that could cause a bad trade decision.

Why Choose HolySheep

After testing multiple data providers, here's why HolySheep AI stands out:

  1. Unified API: One endpoint for Bybit, Binance, OKX, Deribit — no more juggling multiple documentation sets
  2. Data Quality: Normalized data format across exchanges (timestamps, field names, etc.)
  3. Performance: Sub-50ms latency means you're not lagging behind the market
  4. Cost Efficiency: ¥1 = $1 pricing with WeChat/Alipay support for seamless payments
  5. Reliability: 99.5-99.9% uptime SLA on paid plans
  6. Developer Experience: Clean REST API + WebSocket, comprehensive documentation

Step-by-Step: Getting Your First Liquidation Data

Here's the complete beginner workflow:

  1. Step 1: Sign up for HolySheep AI (free credits included)
  2. Step 2: Navigate to Dashboard → API Keys → Create new key
  3. Step 3: Copy the code examples above, replace YOUR_HOLYSHEEP_API_KEY
  4. Step 4: Run the basic example to verify connectivity
  5. Step 5: Scale up to production queries

Screenshot hint: Look for the "API Keys" tab in your HolySheep dashboard. Click "Generate New Key", give it a name like "Python Trading Bot", and copy the key that appears. Keep it secret!

Common Errors and Fixes

Error 1: "401 Unauthorized - Invalid API Key"

This error occurs when your API key is missing, incorrect, or expired.

# ❌ WRONG - Common mistakes
headers = {"Authorization": "YOUR_API_KEY"}  # Missing "Bearer "
headers = {"Authorization": "bearer your_key"}  # Case-sensitive, must be "Bearer"


✅ CORRECT - Proper authentication

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}


Or using the client class (recommended)

class HolySheepClient:
    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}"  # Note the capital B
        })

Error 2: "429 Rate Limit Exceeded"

You're hitting request limits. Implement exponential backoff:

import time
import requests

def fetch_with_retry(url, headers, payload, max_retries=3):
    """Fetch with exponential backoff for rate limits."""
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=payload, timeout=30)
            
            if response.status_code == 429:
                # Rate limited - wait and retry with backoff
                wait_time = 2 ** attempt  # 1s, 2s, 4s
                print(f"Rate limited. Waiting {wait_time}s before retry...")
                time.sleep(wait_time)
                continue
                
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    
    return None


Usage

data = fetch_with_retry(url, headers, payload)

Error 3: "Invalid timestamp format" or Empty results

Timestamps must be in milliseconds, not seconds:

from datetime import datetime, timezone


❌ WRONG - Unix timestamp in seconds (most common mistake)

start_time = 1700000000  # This will fail or return empty


✅ CORRECT - Unix timestamp in milliseconds

start_time = int(datetime.now(timezone.utc).timestamp() * 1000)

Result: 1700000000000



Helper function for clean timestamp conversion

def to_milliseconds(dt: datetime) -> int:
    """Convert datetime to milliseconds for HolySheep API."""
    return int(dt.timestamp() * 1000)


Usage

from datetime import timedelta
end = datetime.now(timezone.utc)
start = end - timedelta(days=7)

payload = {
    "start_time": to_milliseconds(start),
    "end_time": to_milliseconds(end)
}

Error 4: Symbol not found / Invalid symbol format

Bybit uses specific symbol formats. BTCUSDT, not BTC/USDT:

# ✅ CORRECT Bybit symbol formats
SYMBOLS = {
    "BTCUSDT": "Bitcoin USDT Perpetual",
    "ETHUSDT": "Ethereum USDT Perpetual",
    "SOLUSDT": "Solana USDT Perpetual",
    "BTCUSD": "Bitcoin USD Perpetual (inverse)",
}


Helper to validate symbol

def validate_bybit_symbol(symbol: str) -> bool:
    """Check if symbol is valid for Bybit API."""
    valid_symbols = ["BTCUSDT", "ETHUSDT", "SOLUSDT", "AVAXUSDT", 
                     "BNBUSDT", "XRPUSDT", "ADAUSDT", "DOGEUSDT"]
    return symbol.upper() in valid_symbols


Usage

symbol = "btcusdt"  # lowercase works
if validate_bybit_symbol(symbol):
    liquidations = get_bybit_liquidations_historical(symbol=symbol.upper())
else:
    print(f"Invalid symbol: {symbol}")

Advanced Tips for Production Use

Based on my hands-on experience building trading systems:

  1. Cache aggressively: Liquidations don't change. Cache responses for 60+ seconds
  2. Batch requests: Fetch 7 days at a time instead of querying every minute
  3. Monitor your usage: HolySheep dashboard shows real-time credit consumption
  4. Set up alerts: Monitor for API errors and rate limits
  5. Use WebSocket for real-time: Subscribe to live liquidation feeds instead of polling

Conclusion and Buying Recommendation

If you need Bybit historical liquidation data for trading, research, or risk management, HolySheep AI is the clear winner. The combination of ¥1 = $1 pricing, WeChat/Alipay support, sub-50ms latency, and free signup credits makes it accessible for beginners while scalable enough for institutions.

Start with the free tier to test, then upgrade when you're ready. The time you save from dealing with messy API documentation and incomplete data will pay for itself within the first week.

👉 Sign up for HolySheep AI — free credits on registration

Related Resources

Related Articles