Implementation Guide

Implementation Guide

Architecture Overview

The crypto derivatives tracker uses a modular architecture with specialized analyzers for each derivatives metric type.

┌─────────────────────────────────────────────────────────────────┐
│                     derivatives_tracker.py                       │
│                       (Main CLI Entry)                           │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│FundingTracker │   │  OIAnalyzer   │   │Liquidation    │
│               │   │               │   │   Monitor     │
└───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                     ExchangeClient                               │
│                  (Unified Data Layer)                            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────┬───────┴───────┬─────────────┐
        ▼             ▼               ▼             ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ Binance │   │  Bybit  │   │   OKX   │   │ Deribit │
   └─────────┘   └─────────┘   └─────────┘   └─────────┘

Step 1: Exchange Client Setup

The ExchangeClient provides a unified interface for all exchanges.

Configuration

Set up API credentials in environment variables or config file:

# Environment-based configuration
import os

config = {
    "binance": {
        "api_key": os.getenv("BINANCE_API_KEY"),
        "api_secret": os.getenv("BINANCE_API_SECRET"),
        "base_url": "https://fapi.binance.com",
    },
    "bybit": {
        "api_key": os.getenv("BYBIT_API_KEY"),
        "api_secret": os.getenv("BYBIT_API_SECRET"),
        "base_url": "https://api.bybit.com",
    },
    "okx": {
        "api_key": os.getenv("OKX_API_KEY"),
        "api_secret": os.getenv("OKX_API_SECRET"),
        "passphrase": os.getenv("OKX_PASSPHRASE"),
        "base_url": "https://www.okx.com",
    },
    "deribit": {
        "client_id": os.getenv("DERIBIT_CLIENT_ID"),
        "client_secret": os.getenv("DERIBIT_CLIENT_SECRET"),
        "base_url": "https://www.deribit.com",
    },
}

Mock Mode

For development and testing, use mock mode:

from exchange_client import ExchangeClient

# Use mock data (no API calls)
client = ExchangeClient(use_mock=True)

# Use live data
client = ExchangeClient(use_mock=False)

Step 2: Funding Rate Tracking

Data Collection

Funding rates are collected every 8 hours on most exchanges:

from funding_tracker import FundingTracker

tracker = FundingTracker()

# Get current funding rates
analysis = tracker.analyze("BTC")

# Access individual exchange rates
for rate in analysis.rates:
    print(f"{rate.exchange}: {rate.rate:.4%} (next: {rate.time_to_payment_str})")

Interpretation Thresholds

Arbitrage Detection

# Find funding rate discrepancies between exchanges
opportunities = tracker.get_arbitrage_opportunities(
    symbols=["BTC", "ETH"],
    min_spread=0.02  # 0.02% minimum spread
)

Step 3: Open Interest Analysis

Data Aggregation

OI is aggregated across exchanges with weighted calculations:

from oi_analyzer import OIAnalyzer

analyzer = OIAnalyzer()
analysis = analyzer.analyze("BTC")

# Weighted average change (by OI size)
print(f"24h Change: {analysis.avg_change_24h}%")

# Market structure
print(f"Trend: {analysis.trend} ({analysis.trend_strength})")

Divergence Detection

Classic OI/Price divergence patterns:

divergence = analyzer.detect_divergence("BTC", price_change_24h=3.5)
if divergence:
    print(f"Signal: {divergence.signal}")
    print(f"Confidence: {divergence.confidence}")

Step 4: Liquidation Monitoring

Level Calculation

Liquidation levels are estimated based on:

• Open positions at each exchange
• Average leverage used
• Maintenance margin requirements

from liquidation_monitor import LiquidationMonitor

monitor = LiquidationMonitor()
summary = monitor.get_summary("BTC", current_price=Decimal("67500"))

# Cascade risk assessment
print(f"Risk: {summary.cascade_risk}")  # low, medium, high, critical

Cascade Risk Thresholds

Heatmap Generation

# Get structured data for visualization
heatmap = monitor.generate_heatmap_data(
    symbol="BTC",
    current_price=Decimal("67500"),
    levels=5  # 5 levels above and below
)

Step 5: Options Analysis

IV Interpretation

Implied volatility is compared to historical ranges:

from options_analyzer import OptionsAnalyzer

analyzer = OptionsAnalyzer()
analysis = analyzer.analyze("BTC")

# IV interpretation
if analysis.iv_interpretation == "high":
    print("IV elevated - consider selling premium")
elif analysis.iv_interpretation == "low":
    print("IV compressed - consider buying premium")

Put/Call Ratio

Max Pain Calculation

Max pain is the strike price where options writers have minimum payout:

levels = analyzer.get_max_pain_levels("BTC")
for level in levels:
    print(f"{level['expiry']}: ${level['max_pain']:,.0f}")

Step 6: Basis Calculations

Term Structure Analysis

from basis_calculator import BasisCalculator

calc = BasisCalculator()
analysis = calc.analyze("BTC", spot_price=Decimal("67500"))

# Market structure
print(f"Structure: {analysis.market_structure}")  # contango or backwardation

Carry Trade Identification

opportunities = calc.find_carry_opportunities(
    symbols=["BTC", "ETH"],
    min_yield=5.0  # Minimum 5% annualized
)

for opp in opportunities:
    print(f"{opp.symbol}: {opp.annualized_yield:.1f}% yield")
    print(f"  Strategy: {opp.strategy}")

Step 7: Report Generation

Console Output

from formatters import ConsoleFormatter

console = ConsoleFormatter(width=70)

# Create headers and sections
print(console.header("BTC DERIVATIVES"))
print(console.section("FUNDING RATES"))

JSON Export

from formatters import JSONFormatter

json_fmt = JSONFormatter(indent=2)

# Export analysis results
report = json_fmt.derivatives_dashboard(
    symbol="BTC",
    funding=funding_data,
    oi=oi_data,
    liquidations=liq_data
)

# Write to file
with open("report.json", "w") as f:
    f.write(report)

Performance Considerations

Caching

Cache static data that doesn't change frequently:

from functools import lru_cache
from datetime import datetime, timedelta

@lru_cache(maxsize=100)
def get_max_pain_cached(symbol, expiry):
    # Only recalculate every 15 minutes
    cache_key = (symbol, expiry, datetime.now().strftime("%Y%m%d%H%M")[:11])
    return calculate_max_pain(symbol, expiry)

Rate Limiting

Implement proper rate limiting for API calls:

import time
from collections import defaultdict

class RateLimiter:
    def __init__(self, calls_per_minute=60):
        self.calls_per_minute = calls_per_minute
        self.calls = defaultdict(list)

    def wait_if_needed(self, exchange):
        now = time.time()
        minute_ago = now - 60

        # Clean old calls
        self.calls[exchange] = [
            t for t in self.calls[exchange] if t > minute_ago
        ]

        if len(self.calls[exchange]) >= self.calls_per_minute:
            sleep_time = 60 - (now - self.calls[exchange][0])
            time.sleep(sleep_time)

        self.calls[exchange].append(now)

Parallel Fetching

Fetch from multiple exchanges in parallel:

import asyncio
from concurrent.futures import ThreadPoolExecutor

async def fetch_all_funding(symbols):
    with ThreadPoolExecutor(max_workers=5) as executor:
        loop = asyncio.get_event_loop()
        tasks = [
            loop.run_in_executor(executor, fetch_funding, symbol)
            for symbol in symbols
        ]
        return await asyncio.gather(*tasks)

Testing

Unit Tests

def test_funding_sentiment():
    tracker = FundingTracker()

    # High positive funding should be bullish
    sentiment, strength = tracker._analyze_sentiment(0.05)
    assert sentiment == "bullish"
    assert strength == "strong"

    # Negative funding should be bearish
    sentiment, strength = tracker._analyze_sentiment(-0.03)
    assert sentiment == "bearish"

Mock Testing

def test_with_mock_data():
    client = ExchangeClient(use_mock=True)
    tracker = FundingTracker(client=client)

    analysis = tracker.analyze("BTC")
    assert analysis.weighted_avg is not None
    assert len(analysis.rates) > 0

Deployment

Environment Variables

Required for production:

# Exchange API Keys
export BINANCE_API_KEY="your-key"
export BINANCE_API_SECRET="your-secret"
export BYBIT_API_KEY="your-key"
export BYBIT_API_SECRET="your-secret"

# Optional: Deribit for options data
export DERIBIT_CLIENT_ID="your-id"
export DERIBIT_CLIENT_SECRET="your-secret"

Running the CLI

# Install dependencies
pip install -r requirements.txt

# Run analysis
python derivatives_tracker.py funding BTC
python derivatives_tracker.py dashboard BTC ETH SOL --format json

Scheduling

For continuous monitoring, schedule regular runs:

# Cron job every 15 minutes
*/15 * * * * cd /path/to/skill && python derivatives_tracker.py dashboard BTC ETH >> /var/log/derivatives.log 2>&1