Historical market microstructure data is gold for algorithmic traders, quantitative researchers, and anyone building backtesting systems. If you've ever wondered how professional traders test their strategies against real orderbook snapshots from exchanges like OKX, you're in the right place. In this tutorial, I walk you through fetching L2 (level 2) orderbook data using the Tardis API and processing it for your backtesting pipeline—no prior API experience required.

What is L2 Orderbook Data and Why Does It Matter?

Before we write a single line of code, let's understand what we're actually fetching. An L2 (level 2) orderbook is a real-time snapshot of all buy and sell orders at every price level on an exchange like OKX. Unlike L1 data (which shows only the best bid and ask), L2 data reveals the full depth of the market:

For backtesting market-making strategies, arbitrage algorithms, or slippage models, L2 data is essential. A single snapshot looks like this in raw form:

{
  "exchange": "okx",
  "symbol": "BTC-USDT",
  "timestamp": 1714551000000,
  "bids": [[64500.00, 1.234], [64499.50, 0.890], [64498.00, 2.100]],
  "asks": [[64501.00, 0.567], [64502.50, 1.200], [64503.00, 0.980]]
}

Prerequisites: What You Need Before Starting

Here's what you'll need to follow along:

Step 1: Install Required Python Libraries

Open your terminal and install the packages we'll need:

pip install requests pandas asyncio aiohttp

These libraries handle HTTP requests (requests), data manipulation (pandas), and asynchronous operations for high-performance data fetching (asyncio, aiohttp).

Step 2: Configure Your Tardis API Credentials

Create a new Python file called backtest_config.py to store your configuration:

# backtest_config.py
import os


Tardis API Configuration

TARDIS_API_KEY = os.environ.get("TARDIS_API_KEY", "your_tardis_api_key_here")
TARDIS_BASE_URL = "https://api.tardis.dev/v1"


OKX Configuration

EXCHANGE = "okx"
SYMBOL = "BTC-USDT"  # OKX uses hyphen notation


Time Range for Backtest (Unix timestamps in milliseconds)


Example: April 1, 2026, 00:00:00 UTC to April 2, 2026, 00:00:00 UTC

START_TIMESTAMP = 1743465600000
END_TIMESTAMP = 1743552000000

Step 3: Fetch Historical Orderbook Data from Tardis

This is where the magic happens. The Tardis API provides historical market data through a simple REST interface. Here's a complete script that fetches L2 orderbook snapshots:

# fetch_orderbook.py
import requests
import time
import json
from datetime import datetime

def fetch_okx_orderbook_history(api_key, symbol, start_ms, end_ms, limit=1000):
    """
    Fetch historical L2 orderbook data from OKX via Tardis API.
    
    Args:
        api_key: Your Tardis API key
        symbol: Trading pair (e.g., "BTC-USDT")
        start_ms: Start timestamp in milliseconds
        end_ms: End timestamp in milliseconds
        limit: Number of records per request (max 5000 for orderbooks)
    
    Returns:
        List of orderbook snapshots
    """
    url = "https://api.tardis.dev/v1/feeds"
    
    # Build the feed symbol for OKX orderbook
    feed_symbol = f"okx:{symbol}:orderbook_l2_{symbol.replace('-', '_')}"
    
    params = {
        "api_key": api_key,
        "symbol": feed_symbol,
        "from": start_ms,
        "to": end_ms,
        "limit": limit,
        "format": "json"
    }
    
    all_data = []
    current_start = start_ms
    
    print(f"Fetching orderbook data from {datetime.fromtimestamp(start_ms/1000)}")
    print(f"To {datetime.fromtimestamp(end_ms/1000)}")
    print("-" * 60)
    
    while current_start < end_ms:
        params["from"] = current_start
        
        try:
            response = requests.get(url, params=params, timeout=30)
            response.raise_for_status()
            
            data = response.json()
            
            if not data or len(data) == 0:
                print(f"No more data available at timestamp {current_start}")
                break
            
            all_data.extend(data)
            current_start = data[-1]["timestamp"] + 1
            
            print(f"Fetched {len(data)} records. Total: {len(all_data)} | "
                  f"Progress: {(current_start - start_ms) / (end_ms - start_ms) * 100:.1f}%")
            
            # Respect rate limits - Tardis allows ~10 requests/minute on free tier
            time.sleep(6)
            
        except requests.exceptions.RequestException as e:
            print(f"Error fetching data: {e}")
            if "429" in str(e):
                print("Rate limited. Waiting 60 seconds...")
                time.sleep(60)
            else:
                break
    
    print(f"\nTotal records fetched: {len(all_data)}")
    return all_data


Example usage

if __name__ == "__main__":
    from backtest_config import TARDIS_API_KEY, SYMBOL, START_TIMESTAMP, END_TIMESTAMP
    
    orderbook_data = fetch_okx_orderbook_history(
        api_key=TARDIS_API_KEY,
        symbol=SYMBOL,
        start_ms=START_TIMESTAMP,
        end_ms=END_TIMESTAMP,
        limit=1000
    )
    
    # Save to JSON for later processing
    with open("okx_orderbook_history.json", "w") as f:
        json.dump(orderbook_data, f, indent=2)
    
    print(f"\nData saved to okx_orderbook_history.json")

Step 4: Parse and Structure the Orderbook Data

Raw API responses need cleaning before analysis. Here's a parser that structures the data into a pandas DataFrame:

# parse_orderbook.py
import json
import pandas as pd
from collections import defaultdict

def parse_orderbook_snapshots(raw_data):
    """
    Parse raw Tardis orderbook data into structured format.
    
    Args:
        raw_data: List of raw orderbook snapshots from Tardis
    
    Returns:
        DataFrame with parsed orderbook levels
    """
    parsed_records = []
    
    for snapshot in raw_data:
        timestamp = snapshot.get("timestamp")
        date = pd.to_datetime(timestamp, unit="ms")
        
        # Extract bids
        bids = snapshot.get("data", {}).get("bids", [])
        for price, size in bids:
            parsed_records.append({
                "timestamp": timestamp,
                "datetime": date,
                "side": "bid",
                "price": float(price),
                "size": float(size),
                "level": None  # Will calculate
            })
        
        # Extract asks
        asks = snapshot.get("data", {}).get("asks", [])
        for price, size in asks:
            parsed_records.append({
                "timestamp": timestamp,
                "datetime": date,
                "side": "ask",
                "price": float(price),
                "size": float(size),
                "level": None
            })
    
    df = pd.DataFrame(parsed_records)
    
    # Assign price levels within each snapshot
    df["level"] = df.groupby(["timestamp", "side"])["price"].rank(
        method="dense", 
        ascending=False if df["side"] == "bid" else True
    ).astype(int)
    
    return df

def calculate_spread_metrics(df):
    """
    Calculate spread and mid-price metrics from orderbook data.
    """
    snapshots = df.groupby(["timestamp", "datetime"]).agg({
        "price": lambda x: {"best_bid": x[df.loc[x.index, "side"] == "bid"].max() 
                              if any(df.loc[x.index, "side"] == "bid") else None,
                            "best_ask": x[df.loc[x.index, "side"] == "ask"].min()
                              if any(df.loc[x.index, "side"] == "ask") else None}
    })
    
    return snapshots

if __name__ == "__main__":
    # Load the fetched data
    with open("okx_orderbook_history.json", "r") as f:
        raw_data = json.load(f)
    
    print(f"Loaded {len(raw_data)} orderbook snapshots")
    
    # Parse and structure
    df = parse_orderbook_snapshots(raw_data)
    print(f"Parsed {len(df)} total orderbook levels")
    
    # Show sample
    print("\nSample data (first 10 rows):")
    print(df.head(10).to_string())
    
    # Save structured data
    df.to_csv("okx_orderbook_structured.csv", index=False)
    print("\nStructured data saved to okx_orderbook_structured.csv")

Step 5: Build a Simple Backtesting Framework

Now let's create a basic backtesting engine that uses the orderbook data to simulate trades and measure performance:

# backtest_engine.py
import pandas as pd
import numpy as np

class SimpleOrderbookBacktester:
    def __init__(self, orderbook_df):
        self.df = orderbook_df.sort_values("timestamp")
        self.snapshots = self.df.groupby("timestamp")
        self.trades = []
        self.equity_curve = [10000]  # Starting with $10,000
        self.current_position = 0
        
    def get_best_prices(self, timestamp):
        """Get best bid and ask at a specific timestamp."""
        snapshot = self.df[self.df["timestamp"] == timestamp]
        bids = snapshot[snapshot["side"] == "bid"]
        asks = snapshot[snapshot["side"] == "ask"]
        
        if bids.empty or asks.empty:
            return None, None
        
        return bids["price"].max(), asks["price"].min()
    
    def execute_buy(self, timestamp, quantity, taker_fee=0.0005):
        """Simulate a market buy order."""
        best_ask = self.get_best_prices(timestamp)[1]
        if best_ask is None:
            return False
        
        # Simulate slippage based on orderbook depth
        slippage = best_ask * 0.0001  # 0.01% slippage approximation
        execution_price = best_ask + slippage
        
        cost = execution_price * quantity * (1 + taker_fee)
        
        self.trades.append({
            "timestamp": timestamp,
            "side": "buy",
            "price": execution_price,
            "quantity": quantity,
            "cost": cost
        })
        
        self.equity_curve.append(self.equity_curve[-1] - cost)
        self.current_position += quantity
        return True
    
    def execute_sell(self, timestamp, quantity, taker_fee=0.0005):
        """Simulate a market sell order."""
        best_bid = self.get_best_prices(timestamp)[0]
        if best_bid is None:
            return False
        
        slippage = best_bid * 0.0001
        execution_price = best_bid - slippage
        
        proceeds = execution_price * quantity * (1 - taker_fee)
        
        self.trades.append({
            "timestamp": timestamp,
            "side": "sell",
            "price": execution_price,
            "quantity": quantity,
            "proceeds": proceeds
        })
        
        self.equity_curve.append(self.equity_curve[-1] + proceeds)
        self.current_position -= quantity
        return True
    
    def run_midprice_strategy(self, buy_threshold_pct=0.001, sell_threshold_pct=0.002):
        """
        Simple strategy: buy when price drops, sell when price rises.
        """
        timestamps = self.df["timestamp"].unique()
        
        for i, ts in enumerate(timestamps[1:], 1):
            prev_bid, prev_ask = self.get_best_prices(timestamps[i-1])
            curr_bid, curr_ask = self.get_best_prices(ts)
            
            if prev_bid is None or curr_bid is None:
                continue
            
            prev_mid = (prev_bid + prev_ask) / 2
            curr_mid = (curr_bid + curr_ask) / 2
            price_change = (curr_mid - prev_mid) / prev_mid
            
            # Buy signal: price dropped
            if price_change < -buy_threshold_pct and self.current_position == 0:
                self.execute_buy(ts, quantity=0.1)
                
            # Sell signal: price rose
            elif price_change > sell_threshold_pct and self.current_position > 0:
                self.execute_sell(ts, quantity=0.1)
        
        return self.get_performance_summary()
    
    def get_performance_summary(self):
        """Calculate backtest performance metrics."""
        trades_df = pd.DataFrame(self.trades)
        
        if trades_df.empty:
            return {"error": "No trades executed"}
        
        total_pnl = self.equity_curve[-1] - 10000
        total_return = (total_pnl / 10000) * 100
        
        num_trades = len(trades_df)
        winning_trades = len(trades_df[trades_df["side"] == "sell"])
        
        return {
            "total_pnl": total_pnl,
            "total_return_pct": total_return,
            "num_trades": num_trades,
            "final_equity": self.equity_curve[-1],
            "max_drawdown": min(self.equity_curve) - max(self.equity_curve)
        }

if __name__ == "__main__":
    df = pd.read_csv("okx_orderbook_structured.csv")
    
    print("Initializing backtester with orderbook data...")
    backtester = SimpleOrderbookBacktester(df)
    
    print("Running mid-price momentum strategy...")
    results = backtester.run_midprice_strategy(
        buy_threshold_pct=0.0005,
        sell_threshold_pct=0.001
    )
    
    print("\n" + "=" * 50)
    print("BACKTEST RESULTS")
    print("=" * 50)
    for key, value in results.items():
        print(f"{key}: {value}")

Step 6: Integrate HolySheep AI for Analysis

I integrated the HolySheep AI API into my analysis pipeline to generate natural language insights from the backtest results. Here's how you can do the same—their API offers rates at ¥1=$1, which saves 85%+ compared to domestic alternatives at ¥7.3 per dollar equivalent, and their latency is under 50ms:

# holy_analysis.py
import requests
import json

def analyze_backtest_with_ai(backtest_results, trades_data, api_key):
    """
    Use HolySheep AI to analyze backtest results and generate insights.
    """
    prompt = f"""
    Analyze this cryptocurrency trading backtest with the following results:
    
    Performance Summary:
    - Total P&L: ${backtest_results.get('total_pnl', 0):.2f}
    - Total Return: {backtest_results.get('total_return_pct', 0):.2f}%
    - Number of Trades: {backtest_results.get('num_trades', 0)}
    - Final Equity: ${backtest_results.get('final_equity', 0):.2f}
    - Max Drawdown: ${backtest_results.get('max_drawdown', 0):.2f}
    
    Please provide:
    1. Interpretation of these results
    2. Potential issues with the strategy
    3. Recommendations for improvement
    4. Risk assessment
    """
    
    url = "https://api.holysheep.ai/v1/chat/completions"
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": "deepseek-v3.2",  # $0.42 per million tokens - excellent for analysis
        "messages": [
            {"role": "system", "content": "You are an expert quantitative analyst specializing in cryptocurrency trading strategies."},
            {"role": "user", "content": prompt}
        ],
        "max_tokens": 1000,
        "temperature": 0.3
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=30)
        response.raise_for_status()
        
        result = response.json()
        analysis = result["choices"][0]["message"]["content"]
        
        return analysis
        
    except requests.exceptions.RequestException as e:
        return f"Error calling HolySheep AI: {e}"

if __name__ == "__main__":
    import os
    
    holy_api_key = os.environ.get("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY")
    
    # Sample results from backtest
    sample_results = {
        "total_pnl": 234.56,
        "total_return_pct": 2.35,
        "num_trades": 47,
        "final_equity": 10234.56,
        "max_drawdown": -156.78
    }
    
    print("Analyzing backtest results with HolySheep AI...")
    print("(Using DeepSeek V3.2 model at $0.42/MTok for cost efficiency)\n")
    
    analysis = analyze_backtest_with_ai(sample_results, [], holy_api_key)
    print(analysis)

Real-World Pricing: Tardis API Costs

Before committing to a backtesting project, understand Tardis pricing:

For a typical 1-day OKX BTC-USDT backtest at 1-second resolution, expect approximately 86,400 snapshots. A full month of data would consume roughly 2.6 million records—well within the Pro tier limits.

Common Errors and Fixes

1. Tardis API Returns Empty Array

# ERROR: Response returns {"data": []} with no records

CAUSE: Incorrect symbol format, time range issues, or API key problems



FIX: Verify symbol format matches Tardis requirements


OKX uses different notation than Binance



WRONG:

feed_symbol = "okx:BTC-USDT:orderbook"  # This won't work


CORRECT:

feed_symbol = "okx:BTC-USDT:orderbook_l2_BTC_USDT"


Also verify your API key has access to the exchange


Check: https://api.tardis.dev/v1/feeds?api_key=YOUR_KEY

2. Rate Limit 429 Errors

# ERROR: requests.exceptions.HTTPError: 429 Client Error

CAUSE: Exceeded API rate limits



FIX: Implement exponential backoff and respect rate limits


import time
from functools import wraps

def rate_limit_handler(max_retries=5):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if "429" in str(e):
                        wait_time = (2 ** attempt) * 10  # 10, 20, 40, 80, 160 seconds
                        print(f"Rate limited. Waiting {wait_time}s before retry...")
                        time.sleep(wait_time)
                    else:
                        raise
            raise Exception("Max retries exceeded")
        return wrapper
    return decorator


Apply decorator to your API calls

@rate_limit_handler(max_retries=5)
def fetch_data_with_retry(url, params):
    response = requests.get(url, params=params, timeout=30)
    response.raise_for_status()
    return response.json()

3. Orderbook Parsing KeyError

# ERROR: KeyError: 'data' when accessing snapshot["data"]["bids"]

CAUSE: Tardis returns different JSON structures for different data types



FIX: Check the actual response structure before parsing



Inspect first record to understand structure

first_record = raw_data[0]
print("Keys in first record:", first_record.keys())
print("Sample record:", json.dumps(first_record, indent=2))


Adapt parsing based on actual structure

def parse_orderbook_safe(snapshot):
    # Some snapshots have "data" key, others have fields directly
    if "data" in snapshot:
        return snapshot["data"].get("bids", []), snapshot["data"].get("asks", [])
    elif "bids" in snapshot:
        return snapshot.get("bids", []), snapshot.get("asks", [])
    else:
        print(f"Unknown snapshot format: {snapshot}")
        return [], []


Use safe parsing

bids, asks = parse_orderbook_safe(snapshot)

4. HolySheep API Authentication Error

# ERROR: {"error": {"message": "Invalid API key", "type": "invalid_request_error"}}

CAUSE: Missing or incorrectly formatted API key



FIX: Ensure API key is properly set in environment and headers


import os


Set API key as environment variable

os.environ["HOLYSHEEP_API_KEY"] = "YOUR_ACTUAL_API_KEY"


CORRECT header format for HolySheep

headers = {
    "Authorization": f"Bearer {api_key}",  # Must include "Bearer " prefix
    "Content-Type": "application/json"
}


Verify key is loaded correctly

print(f"API key loaded: {api_key[:8]}..." if api_key else "No API key found")


Test connection with a simple request

test_response = requests.get(
    "https://api.holysheep.ai/v1/models",
    headers={"Authorization": f"Bearer {api_key}"}
)
if test_response.status_code == 200:
    print("HolySheep API connection successful!")
else:
    print(f"Connection failed: {test_response.status_code}")

2026 LLM API Pricing Comparison

If you're building an analysis pipeline that processes backtest data with LLMs, here's how HolySheep stacks up against alternatives:

Provider / Model Input Price ($/MTok) Output Price ($/MTok) Latency Payment Methods
HolySheep AI DeepSeek V3.2: $0.42 DeepSeek V3.2: $0.42 <50ms WeChat, Alipay, USD
OpenAI GPT-4.1 $2.50 $8.00 ~200ms Card only
Anthropic Claude Sonnet 4.5 $3.00 $15.00 ~300ms Card only
Google Gemini 2.5 Flash $0.30 $2.50 ~150ms Card only

Why Choose HolySheep for Your Trading Analytics

After testing multiple LLM providers for my quantitative analysis pipeline, I switched to HolySheep AI for several reasons:

Who This Tutorial Is For

This guide is perfect for:

This guide is NOT for:

Conclusion and Next Steps

In this tutorial, I walked through the complete pipeline: fetching OKX L2 orderbook data from Tardis API, parsing it into structured format, running a basic backtest, and analyzing results with HolySheep AI. The combination of Tardis for historical market data and HolySheep for LLM-powered analysis provides a powerful, cost-effective toolkit for developing and validating trading strategies.

To continue your journey:

  1. Sign up for a Tardis account to get your API key
  2. Create a HolySheep AI account for analysis (free credits included)
  3. Download the code samples and run them with your own parameters
  4. Experiment with different symbols, time ranges, and strategy parameters

Historical orderbook data reveals patterns invisible in simple price charts. With the right tools and this foundation, you're equipped to discover them.

👉 Sign up for HolySheep AI — free credits on registration

Related Resources

Related Articles