ARD: Crypto Derivatives Tracker

ARD: Crypto Derivatives Tracker

Architecture Pattern

Multi-Exchange Aggregation with Real-Time Processing

This skill aggregates derivatives data from multiple exchanges, normalizes formats, and provides unified analysis across funding rates, open interest, liquidations, and options markets.

Architectural Overview

┌─────────────────────────────────────────────────────────────────────┐
│                    derivatives_tracker.py (CLI)                     │
│       funding | oi | liquidations | options | basis commands        │
└─────────────────────────────────────────────────────────────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ FundingTracker  │    │   OIAnalyzer    │    │LiquidationMonitor│
│ Multi-exchange  │    │ Position data   │    │ Heatmap & alerts │
│ rate aggregation│    │ trend analysis  │    │ cascade risk     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         └────────────────────────┼────────────────────────┘
                                  ▼
                    ┌─────────────────────────┐
                    │    ExchangeClient       │
                    │  Unified API interface  │
                    │  Rate limit handling    │
                    └─────────────────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         ▼                        ▼                        ▼
    ┌─────────┐            ┌─────────┐            ┌─────────┐
    │ Binance │            │  Bybit  │            │ Deribit │
    │   API   │            │   API   │            │   API   │
    └─────────┘            └─────────┘            └─────────┘

Workflow

Step 1: Exchange Client Initialization

Configure API connections for each supported exchange with rate limiting.

Step 2: Data Fetching

Parallel fetch from all exchanges for:

• Funding rates (perpetuals)
• Open interest (futures + perps)
• Recent liquidations
• Options data (Deribit primarily)

Step 3: Data Normalization

Standardize formats across exchanges:

• Convert funding to 8-hour basis
• Normalize OI to USD equivalent
• Unify liquidation formats

Step 4: Analysis & Aggregation

• Calculate weighted averages
• Detect divergences
• Generate signals

Step 5: Output

Present in requested format (console/JSON).

Data Flow

Exchange APIs          Normalization           Analysis              Output
┌───────────┐         ┌───────────┐         ┌───────────┐         ┌───────┐
│ Binance   │─────────│ Funding   │─────────│ Rate      │─────────│Console│
│ funding   │         │ Normalize │         │ Comparison│         │ JSON  │
└───────────┘         └───────────┘         └───────────┘         └───────┘
     │                      │                     │
┌───────────┐         ┌───────────┐         ┌───────────┐
│ Bybit     │─────────│ OI        │─────────│ Trend     │
│ OI data   │         │ Normalize │         │ Analysis  │
└───────────┘         └───────────┘         └───────────┘
     │                      │                     │
┌───────────┐         ┌───────────┐         ┌───────────┐
│ Deribit   │─────────│ Options   │─────────│ Flow      │
│ options   │         │ Normalize │         │ Analysis  │
└───────────┘         └───────────┘         └───────────┘

Progressive Disclosure Strategy

Level 1: Quick Summary

Single-line current funding rate or OI.

BTC Funding: +0.015% (Binance) | OI: $18.5B (+2.3% 24h)

Level 2: Standard Report

Tabular view across exchanges with key metrics.

BTC FUNDING RATES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Exchange    Current    24h Avg    Annualized
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Binance     +0.0150%   +0.0120%   +16.43%
Bybit       +0.0180%   +0.0140%   +19.71%
...

Level 3: Deep Analysis

Full derivatives dashboard with all metrics, signals, and risk assessment.

Tool Permission Strategy

allowed-tools: Read, Write, Edit, Grep, Glob, Bash(crypto:derivatives-*)

Tool Justification

Directory Structure

skills/tracking-crypto-derivatives/
├── SKILL.md                     # Core skill instructions
├── PRD.md                       # Product requirements
├── ARD.md                       # This file
├── scripts/
│   ├── derivatives_tracker.py   # Main CLI entry point
│   ├── exchange_client.py       # Unified exchange interface
│   ├── funding_tracker.py       # Funding rate analysis
│   ├── oi_analyzer.py           # Open interest analysis
│   ├── liquidation_monitor.py   # Liquidation tracking
│   ├── options_analyzer.py      # Options market analysis
│   ├── basis_calculator.py      # Basis/arbitrage calculations
│   └── formatters.py            # Output formatting
├── config/
│   └── settings.yaml            # Exchange configs, thresholds
└── references/
    ├── errors.md                # Error handling guide
    ├── examples.md              # Usage examples
    └── implementation.md        # Implementation details

API Integration Architecture

Exchange Client Interface

class ExchangeClient:
    """Unified interface for all exchanges."""

    def get_funding_rate(self, symbol: str) -> FundingRate
    def get_open_interest(self, symbol: str) -> OpenInterest
    def get_liquidations(self, symbol: str, limit: int) -> List[Liquidation]
    def get_options_data(self, symbol: str) -> OptionsData

Supported Exchanges

Rate Limiting Strategy

RATE_LIMITS = {
    "binance": {"requests_per_minute": 1200, "weight_per_request": 1},
    "bybit": {"requests_per_minute": 120, "weight_per_request": 1},
    "okx": {"requests_per_minute": 60, "weight_per_request": 1},
    "deribit": {"requests_per_day": 10000, "weight_per_request": 1},
}

Data Models

FundingRate

@dataclass
class FundingRate:
    exchange: str
    symbol: str
    rate: Decimal           # Current 8-hour rate
    predicted_rate: Decimal # Next predicted rate
    next_payment: datetime  # Time until next payment
    annualized: float       # Annualized yield

OpenInterest

@dataclass
class OpenInterest:
    exchange: str
    symbol: str
    oi_usd: Decimal         # Total OI in USD
    oi_contracts: Decimal   # Total contracts
    change_24h_pct: float   # 24h change
    change_7d_pct: float    # 7d change
    long_ratio: float       # Long/short ratio

Liquidation

@dataclass
class Liquidation:
    exchange: str
    symbol: str
    side: str               # "long" or "short"
    price: Decimal
    quantity: Decimal
    value_usd: Decimal
    timestamp: datetime

OptionsSnapshot

@dataclass
class OptionsSnapshot:
    symbol: str
    expiry: date
    atm_iv: float           # At-the-money IV
    put_call_ratio: float   # By volume
    put_call_oi: float      # By open interest
    max_pain: Decimal       # Max pain price
    total_oi_usd: Decimal

Error Handling Strategy

Exchange Errors

Data Quality

Composability & Stacking

Works With

Output Formats

• Console: Formatted tables and reports
• JSON: Machine-readable for pipelines
• CSV: Export for spreadsheet analysis

Performance & Scalability

Caching Strategy

CACHE_TTL = {
    "funding_rates": 60,      # 1 minute
    "open_interest": 30,      # 30 seconds
    "liquidations": 10,       # 10 seconds
    "options_data": 300,      # 5 minutes
}

Parallel Fetching

async def fetch_all_funding(symbols: List[str]) -> Dict[str, FundingRate]:
    """Fetch funding from all exchanges in parallel."""
    tasks = [
        fetch_funding(exchange, symbol)
        for exchange in EXCHANGES
        for symbol in symbols
    ]
    return await asyncio.gather(*tasks)

Testing Strategy

Unit Tests

• Funding rate calculations
• OI normalization
• Liquidation aggregation
• Basis calculations

Integration Tests

• Exchange API connectivity
• Rate limit handling
• Error recovery

Mock Data

• Simulated exchange responses
• Historical liquidation data
• Options chain snapshots

Security & Compliance

API Key Handling

• Keys stored in environment variables or config
• Read-only permissions only (no trading)
• No key logging in outputs

Data Privacy

• No personal data collected
• No trading history stored
• Analysis only, no execution

Monitoring & Alerts

Alert Thresholds (Configurable)

alerts:
  funding_extreme: 0.1      # 0.1% 8-hour funding
  oi_change_large: 15       # 15% OI change
  liquidation_large: 1000000 # $1M liquidation
  iv_extreme: 100           # 100% IV

Alert Outputs

• Console warnings with emoji indicators
• JSON alerts for webhook integration
• Summary at end of report