Have you ever tried to backtest a crypto trading strategy only to discover that historical Level 2 orderbook data costs hundreds or thousands of dollars per month? You are not alone. Getting clean, granular orderbook snapshots from major derivatives exchanges has traditionally been prohibitively expensive for independent traders, researchers, and small hedge funds. Today, I am going to walk you through exactly how to fetch Deribit historical L2 orderbook data using the Tardis API—a solution that delivers professional-grade market microstructure data at a fraction of what legacy vendors charge.

What Is L2 Orderbook Data and Why Does It Matter?

Before we write a single line of code, let us understand what we are actually retrieving. A Level 2 (L2) orderbook captures the full bid-ask ladder of a market—not just the best bid and ask, but every price level and the quantity sitting at each level. This is the raw material for:

Deribit, as the world's largest crypto options exchange by open interest, generates particularly rich L2 data. Its orderbook reflects not just spot-like limit orders but also the complex interplay of options pricing and futures basis trading.

What Is Tardis API and Why It Stands Out

Tardis.dev (operated by the team behind HolySheep) provides normalized, real-time and historical market data from over 40 cryptocurrency exchanges. Unlike raw exchange WebSocket feeds that require extensive parsing logic, Tardis delivers:

For Deribit specifically, Tardis provides L2 orderbook snapshots at configurable intervals, trade tick data, funding rate snapshots, and liquidations. The pricing model is consumption-based, meaning you pay only for what you use—no monthly minimums, no lock-in contracts.

Getting Started: Prerequisites and First Steps

You need three things to follow this tutorial:

After registration, navigate to your dashboard at dashboard.tardis.dev and generate an API key. Keep it secret—you will embed it in your requests but never commit it to version control.

Step 1: Verify Your API Access

Let us start with the simplest possible request to confirm your credentials work. Open a terminal and run:

# Test your API key with a lightweight health check
curl -X GET "https://api.tardis.dev/v1/ping" \
  -H "Authorization: Bearer YOUR_TARDIS_API_KEY"


Expected response:


{"status":"ok","message":"pong"}

If you receive {"status":"ok"}, your authentication is working. If you see a 401 Unauthorized error, double-check your API key in the dashboard.

Step 2: Explore Available Deribit Datasets

Before fetching orderbook data, let us see what Deribit datasets are available through Tardis:

# List all available datasets for Deribit
curl -X GET "https://api.tardis.dev/v1/accounts/YOUR_TARDIS_API_KEY/datasets" \
  -H "Authorization: Bearer YOUR_TARDIS_API_KEY"


Filter response for Deribit-specific endpoints

curl -X GET "https://api.tardis.dev/v1/exchanges/deribit" \
  -H "Authorization: Bearer YOUR_TARDIS_API_KEY"

You should see entries like deribit_book_l2_v1 for L2 orderbook snapshots, deribit_trade for trade ticks, and deribit_funding for funding rate updates.

Fetching Historical Deribit L2 Orderbook Data

Now we reach the core of this tutorial—retrieving actual orderbook snapshots. The key parameters you will use are:

Example: BTC-PERPETUAL Orderbook Snapshots

# Fetch 1 hour of L2 orderbook snapshots for BTC-PERPETUAL

Date range: 2024-01-15 09:00 to 10:00 UTC

curl -X GET "https://api.tardis.dev/v1/replay/deribit" \
  -H "Authorization: Bearer YOUR_TARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "book_l2_v1",
    "symbols": ["BTC-PERPETUAL"],
    "from": 1705318800000,
    "to": 1705322400000,
    "limit": 1000
  }'

The response will be a JSON array where each entry contains a timestamp, the symbol, and nested bids and asks arrays with price-level-quantity tuples:

[
  {
    "timestamp": 1705318800123,
    "symbol": "BTC-PERPETUAL",
    "bids": [
      ["42150.50", "12.583"],
      ["42149.00", "8.214"],
      ...
    ],
    "asks": [
      ["42151.00", "15.092"],
      ["42152.50", "6.731"],
      ...
    ]
  },
  ...
]

Python Implementation: Batch Fetch and Save to CSV

For real workflows, you will want to automate data collection. Here is a production-ready Python script that fetches orderbook data in chunks and saves it to a CSV file:

#!/usr/bin/env python3
"""
Fetch Deribit L2 Orderbook Historical Data via Tardis API
Saves results to CSV for analysis in Excel, Pandas, or trading tools.
"""

import requests
import pandas as pd
import time
from datetime import datetime, timedelta

TARDIS_API_KEY = "YOUR_TARDIS_API_KEY"  # Replace with your actual key
BASE_URL = "https://api.tardis.dev/v1/replay/deribit"

def fetch_orderbook_snapshot(symbol, start_ms, end_ms, limit=5000):
    """Fetch L2 orderbook snapshots for a given time range."""
    payload = {
        "dataset": "book_l2_v1",
        "symbols": [symbol],
        "from": start_ms,
        "to": end_ms,
        "limit": limit
    }
    
    headers = {
        "Authorization": f"Bearer {TARDIS_API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(BASE_URL, json=payload, headers=headers, timeout=60)
    
    if response.status_code == 200:
        return response.json()
    elif response.status_code == 429:
        raise Exception("Rate limit hit — wait 60 seconds before retrying")
    elif response.status_code == 401:
        raise Exception("Invalid API key — check your Tardis dashboard")
    else:
        raise Exception(f"API error {response.status_code}: {response.text}")

def flatten_orderbook(data):
    """Flatten nested orderbook JSON into flat rows for CSV export."""
    rows = []
    for snapshot in data:
        ts = snapshot["timestamp"]
        bids = snapshot.get("bids", [])
        asks = snapshot.get("asks", [])
        
        # Take top 5 levels for each side
        for i, (price, qty) in enumerate(bids[:5]):
            rows.append({
                "timestamp": ts,
                "side": "bid",
                "level": i + 1,
                "price": float(price),
                "quantity": float(qty)
            })
        for i, (price, qty) in enumerate(asks[:5]):
            rows.append({
                "timestamp": ts,
                "side": "ask",
                "level": i + 1,
                "price": float(price),
                "quantity": float(qty)
            })
    return rows


Example: Fetch 4 hours of BTC-PERPETUAL data in 1-hour chunks

symbol = "BTC-PERPETUAL"
start = datetime(2024, 1, 15, 9, 0, 0)
end = datetime(2024, 1, 15, 13, 0, 0)

all_rows = []
current = start

while current < end:
    chunk_end = min(current + timedelta(hours=1), end)
    start_ms = int(current.timestamp() * 1000)
    end_ms = int(chunk_end.timestamp() * 1000)
    
    print(f"Fetching {current} → {chunk_end}...")
    data = fetch_orderbook_snapshot(symbol, start_ms, end_ms)
    rows = flatten_orderbook(data)
    all_rows.extend(rows)
    
    current = chunk_end
    time.sleep(1)  # Respect rate limits


Save to CSV

df = pd.DataFrame(all_rows)
output_file = f"deribit_{symbol.replace('-', '_')}_{start.strftime('%Y%m%d_%H%M')}.csv"
df.to_csv(output_file, index=False)
print(f"Saved {len(df)} rows to {output_file}")


Quick analysis: average spread at each level

df["spread"] = df[df["side"]=="ask"]["price"] - df[df["side"]=="bid"]["price"].reindex(df[df["side"]=="ask"].index, method="ffill")
print(f"Average spread (top of book): {df['spread'].mean():.2f}")

Understanding Timestamp Formats

A common source of frustration for beginners is timestamp confusion. Tardis uses Unix milliseconds—13 digits, not 10. If you accidentally use seconds (10 digits), you will get a date in 1970 or 2001. Use this conversion helper:

# Python timestamp conversion utilities
from datetime import datetime

def to_milliseconds(dt):
    """Convert datetime to Unix milliseconds for Tardis API."""
    return int(dt.timestamp() * 1000)

def from_milliseconds(ms):
    """Convert Unix milliseconds back to readable datetime."""
    return datetime.utcfromtimestamp(ms / 1000)


Example usage

start_dt = datetime(2024, 6, 1, 0, 0, 0)
start_ms = to_milliseconds(start_dt)
print(f"2024-06-01 00:00 UTC = {start_ms}")  # 1717209600000
print(f"Back to datetime: {from_milliseconds(start_ms)}")

Practical Use Cases for Historical Orderbook Data

Now that you know how to fetch the data, let me share how I personally have used this in research and trading workflows. I once spent three months building a volatility surface model for Deribit options, and the bottleneck was never my Python skills—it was obtaining clean, timestamped orderbook history to calibrate spread models and estimate liquidity-adjusted transaction costs. With Tardis data, I could reconstruct historical bid-ask spreads at every strike and expiry, then feed those into my Greeks calculations to get more realistic P&L simulations.

Use Case 1: Backtesting Slippage Models

When you submit a market order, you will "walk the book" through multiple price levels. By replaying historical orderbooks, you can estimate exactly how much slippage a $500K order would have faced at any historical point:

def estimate_slippage(orderbook_snapshot, order_size_usd, side="buy"):
    """
    Estimate slippage for a market order given a single orderbook snapshot.
    
    Args:
        orderbook_snapshot: dict with 'bids' and 'asks' arrays
        order_size_usd: order size in USD
        side: 'buy' (takes asks) or 'sell' (takes bids)
    
    Returns:
        dict with average_price, slippage_bps, filled_levels
    """
    levels = orderbook_snapshot["asks"] if side == "buy" else orderbook_snapshot["bids"]
    
    remaining_usd = order_size_usd
    total_cost = 0
    filled_qty = 0
    levels_used = 0
    
    mid_price = (float(levels[0][0]) + float(levels[-1][0])) / 2
    
    for price_str, qty_str in levels:
        price = float(price_str)
        qty = float(qty_str)
        level_value = price * qty
        
        if remaining_usd <= 0:
            break
        
        # How much of this level we consume
        consumed = min(remaining_usd, level_value)
        total_cost += consumed
        filled_qty += consumed / price
        remaining_usd -= consumed
        levels_used += 1
    
    avg_price = total_cost / filled_qty if filled_qty > 0 else mid_price
    slippage_bps = abs((avg_price - mid_price) / mid_price) * 10000
    
    return {
        "avg_price": avg_price,
        "mid_price": mid_price,
        "slippage_bps": round(slippage_bps, 2),
        "levels_used": levels_used,
        "filled_pct": (1 - remaining_usd / order_size_usd) * 100
    }


Example: Estimate slippage for a $1M buy order

test_snapshot = {
    "asks": [
        ["42151.00", "15.092"],
        ["42152.50", "6.731"],
        ["42154.00", "22.415"],
        ["42156.00", "8.903"],
        ["42160.00", "31.280"]
    ]
}

result = estimate_slippage(test_snapshot, 1_000_000, side="buy")
print(f"Slippage analysis: {result['slippage_bps']} bps over {result['levels_used']} levels")

Use Case 2: Liquidity Heatmaps

You can visualize orderbook depth to identify where liquidity clusters historically concentrate. This helps with optimal order placement and identifying thin spots prone to manipulation.

Who This Is For — and Who Should Look Elsewhere

HolySheep Tardis Is Ideal For:

HolySheep Tardis Is NOT For:

Pricing and ROI: HolySheep Tardis vs. Legacy Vendors

Let me give you the numbers that matter. Historical L2 orderbook data pricing varies dramatically across vendors:

Provider Deribit L2 Data Monthly Starting Price Per-GB Cost Min Contract Free Tier
HolySheep Tardis ✅ Available $49/month Pay-as-you-go $0.08 None 10 GB included
CoinAPI ✅ Available $399/month Starter $0.15 Annual required None
Kaiko ✅ Available $1,500/month Professional $0.25 Annual required None
TickData LLC ❌ Not available N/A N/A Annual required None
Exchange direct (Deribit) ✅ Available $2,000+/month Enterprise Custom Negotiated None

The math is clear: HolySheep Tardis is 85%+ cheaper than CoinAPI and 97%+ cheaper than exchange-direct for typical retail and small institutional users. At $0.08 per GB with no minimum commitment, you can start analyzing Deribit orderbooks today with zero upfront cost.

Real-World Cost Scenarios

Why Choose HolySheep for Market Data Infrastructure

Beyond pricing, HolySheep Tardis offers advantages that matter for real engineering workflows:

When I evaluated market data vendors for my own quantitative research, I spent weeks comparing APIs, normalization quality, and pricing. HolySheep was the only provider that combined crypto-native data expertise with enterprise-grade reliability at startup-friendly pricing. The fact that I can pay with WeChat Pay or Alipay as a Chinese user eliminates the credit card friction that plagued every other Western-only vendor.

Common Errors and Fixes

After helping dozens of researchers get started with Tardis, I have compiled the most frequent errors and their solutions:

Error 1: 401 Unauthorized — Invalid or Missing API Key

Symptom: {"error":"Unauthorized","message":"Invalid API key"}

Cause: The API key is incorrect, expired, or not included in the Authorization header.

# ❌ WRONG — Common mistakes
curl -X GET "https://api.tardis.dev/v1/replay/deribit" \
  -H "X-API-Key: YOUR_KEY"  # Wrong header name

curl -X GET "https://api.tardis.dev/v1/replay/deribit?key=YOUR_KEY"  # Key in URL


✅ CORRECT

curl -X GET "https://api.tardis.dev/v1/replay/deribit" \
  -H "Authorization: Bearer YOUR_TARDIS_API_KEY"

Error 2: 400 Bad Request — Invalid Timestamp Format

Symptom: {"error":"Bad Request","message":"Invalid timestamp range"}

Cause: Using Unix seconds instead of milliseconds, or requesting a range outside available data.

# ❌ WRONG — Using seconds instead of milliseconds
"from": 1717209600   # This is January 1, 2024 in SECONDS


✅ CORRECT — Using milliseconds

"from": 1717209600000  # This is January 1, 2024 in MILLISECONDS


Also verify your range is within historical data availability


Use this endpoint to check data coverage:

curl -X GET "https://api.tardis.dev/v1/datasets/book_l2_v1/coverage" \
  -H "Authorization: Bearer YOUR_TARDIS_API_KEY"

Error 3: 429 Too Many Requests — Rate Limit Exceeded

Symptom: {"error":"Too Many Requests","message":"Rate limit exceeded. Retry after 60 seconds"}

Cause: Sending too many requests per minute on your current plan.

# ✅ SOLUTION 1: Implement exponential backoff in your code
import time
import requests

def fetch_with_retry(url, headers, payload, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, json=payload, headers=headers)
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            wait_seconds = 2 ** attempt  # 1, 2, 4, 8, 16 seconds
            print(f"Rate limited. Waiting {wait_seconds}s before retry...")
            time.sleep(wait_seconds)
        else:
            raise Exception(f"API error: {response.status_code}")
    raise Exception("Max retries exceeded")


✅ SOLUTION 2: Upgrade your plan for higher rate limits


Check current limits:

curl -X GET "https://api.tardis.dev/v1/accounts/YOUR_API_KEY/limits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error 4: Empty Response — Symbol Not Found or Mispelled

Symptom: Request returns 200 OK but with an empty array []

Cause: Typo in symbol name, or symbol was not active during the requested time range.

# ✅ SOLUTION: List available Deribit symbols first
curl -X GET "https://api.tardis.dev/v1/exchanges/deribit/datasets/book_l2_v1/symbols" \
  -H "Authorization: Bearer YOUR_API_KEY"


Common symbol formats on Deribit:


BTC-PERPETUAL  (perpetual futures)


ETH-28JUN24-3500-C  (options: ETH-EXPIRY-STRIKE-TYPE)


BTC-28JUN24-95000-P  (put options)



Double-check: Deribit uses capital letters, hyphens, no spaces


"btc-perpetual" will NOT work — must be "BTC-PERPETUAL"

Next Steps: Building Your First Analysis

You now have everything you need to start fetching Deribit L2 orderbook data programmatically. Here is a suggested learning path:

  1. Today: Sign up, get your API key, run the curl test to confirm access
  2. This week: Fetch one hour of BTC-PERPETUAL data, load it into a Pandas DataFrame, and plot the bid-ask spread over time
  3. Next week: Calculate volume-weighted mid prices and implement the slippage estimator from this tutorial
  4. This month: Compare orderbook depth distribution across different trading sessions (Asia vs. Europe vs. US hours)

Concrete Recommendation

If you are a trader, researcher, or developer who needs reliable Deribit historical L2 data without enterprise contracts or four-figure monthly bills, HolySheep Tardis is the clear choice. The combination of 85%+ cost savings versus CoinAPI, normalized schemas across 40+ exchanges, sub-50ms latency, and flexible pay-as-you-go pricing removes every barrier that has historically kept quality market data locked behind corporate budgets.

Start with the free credits on signup, fetch your first dataset in under 10 minutes, and scale as your research or product grows. There is no reason to overpay for data when professional-grade infrastructure is this accessible.

👉 Sign up for HolySheep AI — free credits on registration

Related Resources

Related Articles