@intentsolutionsio/crypto-derivatives-tracker 1.0.0

package/skills/tracking-crypto-derivatives/PRD.md

@@ -0,0 +1,258 @@
+# PRD: Crypto Derivatives Tracker
+
+## Summary
+
+**One-liner**: Track cryptocurrency futures, options, and perpetual swaps with comprehensive market analysis
+**Domain**: Cryptocurrency / Derivatives Trading
+**Users**: Derivatives Traders, Arbitrage Specialists, Risk Managers
+
+---
+
+## Problem Statement
+
+Crypto derivatives markets generate massive amounts of data across multiple exchanges - funding rates, open interest, liquidations, options flow, and basis spreads. Traders need to:
+
+1. Monitor funding rates across 5+ exchanges simultaneously
+2. Track open interest changes to gauge market positioning
+3. Identify liquidation clusters and cascade risks
+4. Analyze options flow for smart money signals
+5. Find basis trading and funding arbitrage opportunities
+
+Manual monitoring is impractical given the 24/7 nature of crypto markets and the speed at which conditions change. A unified tool that aggregates derivatives data and generates actionable insights is essential.
+
+---
+
+## Target Users
+
+### Persona 1: Derivatives Day Trader
+- **Background**: Full-time crypto trader focusing on perpetual swaps
+- **Goals**: Profit from funding rate extremes, OI divergences, and liquidation cascades
+- **Pain Points**: Data fragmented across exchanges, misses funding changes
+- **Success Criteria**: Consistent funding capture, early entry before liquidation cascades
+
+### Persona 2: Basis Arbitrageur
+- **Background**: Market-neutral trader running cash-and-carry strategies
+- **Goals**: Lock in risk-free returns via spot-futures basis trades
+- **Pain Points**: Manual basis calculations, timing entry/exit around funding
+- **Success Criteria**: Captures basis premium with minimal directional risk
+
+### Persona 3: Options Flow Analyst
+- **Background**: Institutional researcher tracking smart money via options
+- **Goals**: Identify unusual options activity and positioning before moves
+- **Pain Points**: Options data scattered, hard to interpret Greeks at scale
+- **Success Criteria**: Detects smart money positioning ahead of price moves
+
+---
+
+## User Stories
+
+### US-1: Funding Rate Monitoring (Critical)
+**As a** derivatives trader
+**I want to** see funding rates across all major exchanges in one view
+**So that** I can identify arbitrage opportunities and sentiment extremes
+
+**Acceptance Criteria**:
+- Display funding rates for BTC, ETH, SOL across Binance, Bybit, OKX, Deribit
+- Show current, 24h average, and 7d average rates
+- Calculate annualized funding yield
+- Alert when funding exceeds configurable threshold (default: 0.1%)
+
+### US-2: Open Interest Analysis (Critical)
+**As a** derivatives trader
+**I want to** track open interest changes by exchange and contract type
+**So that** I can gauge market positioning and trend strength
+
+**Acceptance Criteria**:
+- Show total OI in USD and BTC/ETH equivalent
+- Display 24h, 7d, 30d OI changes
+- Compare OI across exchanges (market share)
+- Analyze OI vs price divergences
+
+### US-3: Liquidation Monitoring (Critical)
+**As a** derivatives trader
+**I want to** see liquidation levels and recent liquidation events
+**So that** I can avoid cascade zones and position for liquidation-driven moves
+
+**Acceptance Criteria**:
+- Display liquidation heatmap with price levels
+- Show recent large liquidations (>$100K)
+- Calculate long/short liquidation zones
+- Estimate cascade risk at key levels
+
+### US-4: Basis Tracking (High)
+**As a** basis arbitrageur
+**I want to** see spot-futures basis across all expiries
+**So that** I can identify cash-and-carry opportunities
+
+**Acceptance Criteria**:
+- Calculate perpetual-spot basis (real-time)
+- Calculate quarterly-spot basis with annualized yield
+- Compare basis across exchanges
+- Signal when basis exceeds profitability threshold
+
+### US-5: Options Flow Analysis (High)
+**As an** options analyst
+**I want to** track unusual options activity and positioning
+**So that** I can identify smart money moves
+
+**Acceptance Criteria**:
+- Show large options trades (premium > $100K)
+- Display put/call ratio by volume and OI
+- Calculate max pain for upcoming expiries
+- Analyze implied volatility levels and skew
+
+### US-6: Multi-Asset Dashboard (Medium)
+**As a** portfolio manager
+**I want to** see derivatives metrics for multiple assets
+**So that** I can monitor my entire derivatives exposure
+
+**Acceptance Criteria**:
+- Support BTC, ETH, SOL, and major altcoins
+- Display comparative funding rates
+- Show aggregate OI across assets
+- Highlight assets with extreme metrics
+
+---
+
+## Functional Requirements
+
+### REQ-1: Multi-Exchange Data Aggregation
+- Fetch funding rates from Binance, Bybit, OKX, Deribit, BitMEX
+- Aggregate open interest across exchanges
+- Support both USDT-margined and coin-margined contracts
+
+### REQ-2: Funding Rate Analysis
+- Current funding rate with countdown to next payment
+- Historical funding (24h, 7d, 30d averages)
+- Funding arbitrage opportunities between exchanges
+- Annualized funding yield calculation
+
+### REQ-3: Open Interest Analytics
+- Total OI by asset and exchange
+- OI change tracking (1h, 24h, 7d)
+- Long/short ratio by exchange
+- OI vs price divergence detection
+
+### REQ-4: Liquidation Intelligence
+- Real-time liquidation tracking
+- Liquidation heatmap generation
+- Cascade risk estimation
+- Historical liquidation analysis
+
+### REQ-5: Options Market Data
+- Implied volatility by strike and expiry
+- Put/call ratio tracking
+- Max pain calculation
+- Options flow for large trades
+
+### REQ-6: Basis Calculations
+- Perpetual basis (funding-implied)
+- Quarterly futures basis
+- Annualized yield calculation
+- Basis convergence alerts
+
+---
+
+## API Integrations
+
+| Source | Data Provided | Rate Limits |
+|--------|---------------|-------------|
+| Binance Futures | Funding, OI, liquidations | 1200/min |
+| Bybit | Funding, OI, positions | 120/min |
+| OKX | Funding, OI, options | 60/min |
+| Deribit | Options, funding, OI | 10K/day |
+| Coinglass | Aggregated derivatives | API key required |
+
+---
+
+## Success Metrics
+
+1. **Data Freshness**: All metrics updated within 5 seconds
+2. **Exchange Coverage**: 5+ CEX, 3+ DEX protocols supported
+3. **Alert Accuracy**: 90%+ of funding extremes detected
+4. **User Satisfaction**: Clear, actionable output format
+
+---
+
+## Non-Goals
+
+- **Not** executing trades or managing positions
+- **Not** providing financial advice or guaranteed signals
+- **Not** real-time order book depth analysis
+- **Not** custom strategy backtesting
+- **Not** portfolio accounting or tax reporting
+
+---
+
+## Risk Considerations
+
+### Market Risks
+- Funding rates can flip rapidly during volatility
+- Liquidation cascades can gap through levels
+- Options pricing models have limitations
+
+### Data Risks
+- Exchange API outages or rate limits
+- Delayed or stale data during high volatility
+- Inconsistent data formats between exchanges
+
+### User Risks
+- Over-reliance on signals without risk management
+- Misinterpretation of complex derivatives metrics
+- Leverage amplifies both gains and losses
+
+---
+
+## Examples
+
+### Example 1: Funding Rate Alert
+```
+User: "What's the funding rate for BTC?"
+
+Output:
+BTC PERPETUAL FUNDING RATES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Exchange    Current    24h Avg    7d Avg    Next Payment
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Binance     +0.0150%   +0.0120%   +0.0080%  2h 15m
+Bybit       +0.0180%   +0.0140%   +0.0100%  2h 15m
+OKX         +0.0130%   +0.0110%   +0.0090%  2h 15m
+Deribit     +0.0200%   +0.0150%   +0.0120%  2h 15m
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Annualized: +15.77% (based on current rates)
+Sentiment: Moderately Bullish
+Arbitrage: None (rates aligned)
+```
+
+### Example 2: Liquidation Analysis
+```
+User: "Where are the BTC liquidation levels?"
+
+Output:
+BTC LIQUIDATION HEATMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Current Price: $67,500
+
+LONG LIQUIDATIONS (below current):
+  $65,000: $125M at risk (HIGH DENSITY)
+  $62,500: $85M at risk
+  $60,000: $210M at risk (CRITICAL CLUSTER)
+
+SHORT LIQUIDATIONS (above current):
+  $70,000: $95M at risk
+  $72,500: $145M at risk (HIGH DENSITY)
+  $75,000: $180M at risk
+
+Last 24h Liquidations:
+  Longs: $45.2M | Shorts: $32.8M
+  Largest: $5.2M long at $66,800
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Version History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0.0 | 2025-01-15 | Jeremy Longshore | Initial PRD |

package/skills/tracking-crypto-derivatives/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: tracking-crypto-derivatives
+description: |
+  Track cryptocurrency futures, options, and perpetual swaps with funding rates, open interest, liquidations, and comprehensive derivatives market analysis.
+  Use when monitoring derivatives markets, analyzing funding rates, tracking open interest, finding liquidation levels, or researching options flow.
+  Trigger with phrases like "funding rate", "open interest", "perpetual swap", "futures basis", "liquidation levels", "options flow", "put call ratio", "derivatives analysis", or "BTC perps".
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(crypto:derivatives-*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [crypto, monitoring, tracking-crypto]
+---
+# Tracking Crypto Derivatives
+
+## Overview
+
+Aggregate funding rates, open interest, liquidations, and options data across CEX and DEX derivatives exchanges to produce actionable trading insights.
+
+**Supported Markets**: Perpetual Swaps (Binance, Bybit, OKX, Deribit, BitMEX), Quarterly Futures, Options (Deribit, OKX, Bybit), DEX Perpetuals (dYdX, GMX, Drift Protocol).
+
+## Prerequisites
+
+- Python 3.8+ installed
+- Network access to exchange APIs
+- Optional: API keys for higher rate limits
+- Understanding of derivatives concepts (funding, OI, basis)
+
+## Instructions
+
+1. **Check funding rates** across exchanges to identify sentiment and arbitrage opportunities:
+   ```bash
+   python derivatives_tracker.py funding BTC
+   python derivatives_tracker.py funding BTC ETH SOL
+   python derivatives_tracker.py funding BTC --history 7d
+   ```
+   - Positive funding (>0.01%): Longs pay shorts, bullish sentiment
+   - Negative funding (<-0.01%): Shorts pay longs, bearish sentiment
+   - Extreme funding (>0.1%): Potential contrarian opportunity
+
+2. **Analyze open interest** to gauge market positioning and trend strength:
+   ```bash
+   python derivatives_tracker.py oi BTC
+   python derivatives_tracker.py oi BTC --changes
+   python derivatives_tracker.py oi BTC --divergence
+   ```
+   - Rising OI + Rising Price = strong bullish trend
+   - Rising OI + Falling Price = strong bearish trend
+   - Falling OI + Rising Price = short covering rally
+   - Falling OI + Falling Price = long liquidations
+
+3. **Monitor liquidations** to find support/resistance clusters:
+   ```bash
+   python derivatives_tracker.py liquidations BTC
+   python derivatives_tracker.py liquidations BTC --recent
+   python derivatives_tracker.py liquidations BTC --min-size 100000  # 100000 = minimum USD liquidation size filter
+   ```
+
+4. **Analyze options market** for IV, put/call ratio, and max pain:
+   ```bash
+   python derivatives_tracker.py options BTC
+   python derivatives_tracker.py options BTC --pcr
+   python derivatives_tracker.py options BTC --expiry 2025-01-31  # 2025 = target expiry year
+   ```
+
+5. **Calculate basis** for spot-futures arbitrage opportunities:
+   ```bash
+   python derivatives_tracker.py basis BTC
+   python derivatives_tracker.py basis BTC --quarterly
+   python derivatives_tracker.py basis --all
+   ```
+
+6. **Run full dashboard** for comprehensive derivatives overview:
+   ```bash
+   python derivatives_tracker.py dashboard BTC
+   python derivatives_tracker.py dashboard BTC ETH SOL
+   python derivatives_tracker.py dashboard BTC --output json
+   ```
+
+## Output
+
+The skill produces structured reports per market type:
+
+- **Funding Rate Report**: Current, 24h avg, 7d avg rates per exchange with annualized yield and sentiment
+- **Open Interest Report**: OI per exchange with 24h/7d changes, share %, and long/short ratio
+- **Liquidation Heatmap**: Long/short liquidation clusters by price level with USD density
+- **Options Overview**: Put/call ratio, IV rank, max pain, and large flow alerts
+- **Basis Report**: Spot-perp and quarterly basis with annualized carry rates
+
+See `${CLAUDE_SKILL_DIR}/references/implementation.md` for detailed output format examples.
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ERR_RATE_LIMIT` | Too many API requests | Reduce frequency or add API key |
+| `ERR_EXCHANGE_DOWN` | Exchange API unavailable | Try alternative exchange |
+| `ERR_SYMBOL_INVALID` | Wrong symbol format | Use BTC, ETH (not BTCUSDT) |
+
+## Examples
+
+**Morning derivatives check** - Scan funding, OI, and liquidations for top assets:
+```bash
+python derivatives_tracker.py dashboard BTC ETH SOL
+```
+
+**Funding rate arbitrage** - Alert when funding exceeds threshold for cash-and-carry:
+```bash
+python derivatives_tracker.py funding BTC --alert-threshold 0.08
+```
+
+**Pre-expiry options analysis** - Check max pain and IV before Friday expiry:
+```bash
+python derivatives_tracker.py options BTC --expiry friday
+```
+
+**Basis trading scan** - Find all pairs with annualized yield above 5%:
+```bash
+python derivatives_tracker.py basis --all --min-yield 5  # 5 = minimum annualized yield %
+```
+
+## Resources
+
+- **Coinglass**: Aggregated derivatives data
+- **Exchange APIs**: Binance, Bybit, OKX, Deribit
+- **The Graph**: DEX perpetuals data
+- `${CLAUDE_SKILL_DIR}/references/implementation.md` - Detailed output formats, options/basis guides, key concepts

package/skills/tracking-crypto-derivatives/config/settings.yaml

@@ -0,0 +1,152 @@
+# Crypto Derivatives Tracker Configuration
+# ==========================================
+
+# General settings
+general:
+  # Default output format: console or json
+  default_format: console
+
+  # Default symbols to track
+  default_symbols:
+    - BTC
+    - ETH
+
+  # Cache TTL in seconds
+  cache_ttl: 300
+
+  # Request timeout in seconds
+  request_timeout: 30
+
+# Exchange configuration
+exchanges:
+  # Enabled exchanges for data collection
+  enabled:
+    - binance
+    - bybit
+    - okx
+    - deribit
+    - bitmex
+
+  # Primary exchange for each data type
+  primary:
+    funding: binance
+    open_interest: binance
+    liquidations: binance
+    options: deribit
+    basis: binance
+
+  # Rate limits (requests per minute)
+  rate_limits:
+    binance: 1200
+    bybit: 120
+    okx: 60
+    deribit: 100
+    bitmex: 30
+
+# Funding rate settings
+funding:
+  # Interpretation thresholds (8-hour rate as percentage)
+  thresholds:
+    extreme: 0.08    # Above this is extreme
+    strong: 0.03     # Above this is strong
+    neutral: 0.005   # Below this is neutral
+
+  # Minimum spread for arbitrage alerts (percentage)
+  min_arb_spread: 0.02
+
+  # Alert on extreme funding
+  alert_extreme: true
+
+# Open interest settings
+open_interest:
+  # Trend detection thresholds (24h change percentage)
+  thresholds:
+    strong_change: 10.0    # >10% is strong move
+    moderate_change: 5.0   # >5% is moderate
+
+  # Divergence detection minimum change
+  divergence_min_change: 2.0
+
+# Liquidation settings
+liquidations:
+  # Cascade risk thresholds (USD within 5% of price)
+  cascade_thresholds:
+    critical: 500000000   # $500M
+    high: 200000000       # $200M
+    medium: 100000000     # $100M
+
+  # Minimum liquidation size to track (USD)
+  min_liquidation_size: 100000
+
+  # Large liquidation threshold (USD)
+  large_liquidation_threshold: 1000000
+
+# Options settings
+options:
+  # IV interpretation thresholds (percentage)
+  iv_thresholds:
+    high: 70.0
+    low: 40.0
+
+  # Put/call ratio interpretation
+  pcr_thresholds:
+    bearish: 1.2    # Above this is bearish
+    bullish: 0.7    # Below this is bullish
+
+  # Days until expiry for pressure levels
+  expiry_pressure:
+    high: 2      # <= 2 days
+    medium: 7    # <= 7 days
+
+# Basis settings
+basis:
+  # Structure interpretation thresholds (annualized percentage)
+  structure_thresholds:
+    strong: 5.0      # >5% annualized is strong
+    moderate: 2.0    # >2% is moderate
+
+  # Minimum yield for carry trade alerts
+  min_carry_yield: 5.0
+
+# Output formatting
+formatting:
+  # Console width
+  console_width: 70
+
+  # Number of decimal places
+  decimals:
+    rate: 4
+    percentage: 2
+    currency: 0
+
+  # Currency formatting
+  currency:
+    symbol: "$"
+    thousands_separator: ","
+    decimal_separator: "."
+
+# Alerts and notifications
+alerts:
+  # Enable alerts
+  enabled: false
+
+  # Alert conditions
+  conditions:
+    extreme_funding: true
+    high_cascade_risk: true
+    large_liquidation: true
+    oi_divergence: true
+
+  # Webhook URL for alerts (optional)
+  webhook_url: ""
+
+# Logging
+logging:
+  # Log level: DEBUG, INFO, WARNING, ERROR
+  level: INFO
+
+  # Log file path (optional)
+  file: ""
+
+  # Log format
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"