Options Strategy Backtesting: Connecting HolySheep AI to Tardis Deribit Options Chain & IV Surface Archival Data

Real-Time Options Chain WebSocket Integration

For live strategy execution or intraday backtesting, connect via HolySheep's WebSocket relay. This delivers sub-50ms latency on Deribit options order book updates, verified in our Singapore deployment at 47ms average round-trip.

import asyncio
import websockets
import json
from dataclasses import dataclass
from typing import Optional

@dataclass
class OptionContract:
    instrument_name: str      # e.g., "BTC-27DEC2024-95000-C"
    strike: int
    expiry: str
    kind: str                 # "call" or "put"
    bid_price: float
    ask_price: float
    bid_iv: float
    ask_iv: float
    delta: float
    gamma: float
    theta: float
    vega: float
    orderbook_bid_depth: int
    orderbook_ask_depth: int

class HolySheepOptionsWebSocket:
    def __init__(self, api_key: str, on_message_callback=None):
        self.api_key = api_key
        self.on_message_callback = on_message_callback
        self.ws: Optional[websockets.WebSocketClientProtocol] = None
        self.reconnect_delay = 1
        self.max_reconnect_delay = 60
        
    async def connect(self):
        """Establish WebSocket connection to HolySheep Deribit options feed."""
        uri = "wss://api.holysheep.ai/v1/ws/deribit/options"
        headers = [("Authorization", f"Bearer {self.api_key}")]
        
        try:
            self.ws = await websockets.connect(uri, extra_headers=dict(headers))
            await self.subscribe_to_chain(["BTC", "ETH"])
            print(f"Connected to HolySheep options feed — latency target: <50ms")
        except websockets.exceptions.InvalidStatusCode as e:
            if e.status_code == 401:
                raise AuthException("Invalid API key—check dashboard at holysheep.ai/register")
            raise

    async def subscribe_to_chain(self, currencies: list):
        """Subscribe to options chain updates for specified currencies."""
        subscribe_msg = {
            "type": "subscribe",
            "channels": ["options_chain"],
            "params": {
                "currencies": currencies,
                "include_greeks": True,
                "include_orderbooks": True,
                "book_depth": 5  # Top 5 levels per side
            }
        }
        await self.ws.send(json.dumps(subscribe_msg))
        print(f"Subscribed to {', '.join(currencies)} options chains")

    async def listen(self):
        """Main event loop for processing options chain updates."""
        async for message in self.ws:
            data = json.loads(message)
            
            if data.get("type") == "options_chain_update":
                contracts = self._parse_chain_update(data)
                
                # Filter for ATM contracts (delta nearest 0.5)
                atm_contracts = [
                    c for c in contracts 
                    if 0.45 <= c.delta <= 0.55
                ]
                
                if atm_contracts and self.on_message_callback:
                    self.on_message_callback(atm_contracts, data.get("timestamp"))
                    
            elif data.get("type") == "error":
                print(f"Feed error: {data.get('message')}")

    def _parse_chain_update(self, data: dict) -> list[OptionContract]:
        """Parse raw Deribit options chain update into structured contracts."""
        contracts = []
        for option in data.get("options", []):
            contracts.append(OptionContract(
                instrument_name=option["instrument_name"],
                strike=option["strike"],
                expiry=option["expiry"],
                kind=option["kind"],
                bid_price=option["best_bid_price"],
                ask_price=option["best_ask_price"],
                bid_iv=option["bid_iv"],
                ask_iv=option["ask_iv"],
                delta=option.get("greeks", {}).get("delta", 0),
                gamma=option.get("greeks", {}).get("gamma", 0),
                theta=option.get("greeks", {}).get("theta", 0),
                vega=option.get("greeks", {}).get("vega", 0),
                orderbook_bid_depth=len(option.get("orderbook", {}).get("bids", [])),
                orderbook_ask_depth=len(option.get("orderbook", {}).get("asks", []))
            ))
        return contracts

Example: Real-time IV arbitrage signal generator
async def iv_arbitrage_signal(contracts: list[OptionContract], ts: int):
    """Detect IV discrepancy between put and call at same strike (put-call parity violation)."""
    strikes = {}
    for c in contracts:
        if c.strike not in strikes:
            strikes[c.strike] = {"call": None, "put": None}
        if c.kind == "call":
            strikes[c.strike]["call"] = c
        else:
            strikes[c.strike]["put"] = c
    
    for strike, pair in strikes.items():
        if pair["call"] and pair["put"]:
            mid_iv_spread = (pair["call"].ask_iv - pair["put"].bid_iv)
            # Flag spreads exceeding 2% for manual review
            if mid_iv_spread > 0.02:
                print(f"[{ts}] IV arb signal: strike {strike}, spread {mid_iv_spread:.2%}")

Run the websocket client
async def main():
    client = HolySheepOptionsWebSocket(
        api_key=HOLYSHEEP_API_KEY,
        on_message_callback=iv_arbitrage_signal
    )
    await client.connect()
    await client.listen()

asyncio.run(main())

# Problem: WebSocket rejects connection with 401 status
Root cause: API key not properly passed in headers

FIX: Ensure Authorization header is a dict, not tuple list
headers = {"Authorization": f"Bearer {HOLYSHEEP_API_KEY}"}
ws = await websockets.connect(uri, extra_headers=headers)  # ✅ Correct

WRONG: 
headers = [("Authorization", f"Bearer {HOLYSHEEP_API_KEY}")]
ws = await websockets.connect(uri, extra_headers=dict(headers))  # ❌ Double-conversion issue

# Problem: IV surface requests return 429 after ~20 queries
Root cause: Exceeding HolySheep's rate limit for archival endpoints

FIX: Implement exponential backoff and request batching
async def safe_fetch_iv_surface(fetcher, expiry, start_ts, end_ts, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await fetcher.fetch_iv_surface(expiry, start_ts, end_ts)
        except RateLimitException:
            wait = 2 ** attempt + random.uniform(0, 1)
            print(f"Rate limited—retrying in {wait:.1f}s")
            await asyncio.sleep(wait)
    
    # Fallback: request aggregated surface instead of full chain
    return await fetcher.fetch_aggregated_surface(expiry, start_ts, end_ts)

# Problem: delta, gamma, theta, vega all return None or 0
Root cause: Forgot to set include_greeks: True in subscription payload

FIX: Always include Greeks in subscription parameters
subscribe_msg = {
    "type": "subscribe",
    "channels": ["options_chain"],
    "params": {
        "currencies": ["BTC"],
        "include_greeks": True,      # Must be True
        "greeks_precision": "high", # Request full precision Greeks
        "include_orderbooks": True,
        "book_depth": 10
    }
}

Also check: Greeks are only populated for strikes within 20% of spot
Far-OTM/ITM contracts may have null Greeks due to illiquidity

# Problem: IV surface returns empty snapshots array
Root cause: Expiry string format mismatch with Deribit conventions

Deribit uses: DDMMMYY format (e.g., "27DEC24" NOT "12/27/2024")
HolySheep accepts: "27DEC2024" or "27DEC24"

FIX: Standardize expiry parsing
from datetime import datetime

def normalize_expiry(dt: datetime) -> str:
    return dt.strftime("%d%b%Y").upper()  # "27DEC2024"

Usage:
expiry = normalize_expiry(datetime(2024, 12, 27))
iv_df = await fetcher.fetch_iv_surface(expiry=expiry, start_ts=start, end_ts=end)