@intentsolutionsio/crypto-derivatives-tracker 1.0.0 → 1.0.6

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

@@ -25,18 +25,21 @@ Manual monitoring is impractical given the 24/7 nature of crypto markets and the
 ## 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
@@ -47,66 +50,78 @@ Manual monitoring is impractical given the 24/7 nature of crypto markets and the
 ## 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
@@ -117,35 +132,41 @@ Manual monitoring is impractical given the 24/7 nature of crypto markets and the
 ## 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
@@ -187,16 +208,19 @@ Manual monitoring is impractical given the 24/7 nature of crypto markets and the
 ## 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
@@ -206,6 +230,7 @@ Manual monitoring is impractical given the 24/7 nature of crypto markets and the
 ## Examples
 
 ### Example 1: Funding Rate Alert
+
 ```
 User: "What's the funding rate for BTC?"
 
@@ -225,6 +250,7 @@ Arbitrage: None (rates aligned)
 ```
 
 ### Example 2: Liquidation Analysis
+
 ```
 User: "Where are the BTC liquidation levels?"
 

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

@@ -1,15 +1,25 @@
 ---
 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".
+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]
+tags:
+- crypto
+- monitoring
+- tracking-crypto
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Tracking Crypto Derivatives
 
@@ -29,27 +39,32 @@ Aggregate funding rates, open interest, liquidations, and options data across CE
 ## 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
@@ -57,6 +72,7 @@ Aggregate funding rates, open interest, liquidations, and options data across CE
    ```
 
 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
@@ -64,6 +80,7 @@ Aggregate funding rates, open interest, liquidations, and options data across CE
    ```
 
 5. **Calculate basis** for spot-futures arbitrage opportunities:
+
    ```bash
    python derivatives_tracker.py basis BTC
    python derivatives_tracker.py basis BTC --quarterly
@@ -71,6 +88,7 @@ Aggregate funding rates, open interest, liquidations, and options data across CE
    ```
 
 6. **Run full dashboard** for comprehensive derivatives overview:
+
    ```bash
    python derivatives_tracker.py dashboard BTC
    python derivatives_tracker.py dashboard BTC ETH SOL
@@ -100,21 +118,25 @@ See `${CLAUDE_SKILL_DIR}/references/implementation.md` for detailed output forma
 ## 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 %
 ```

package/skills/tracking-crypto-derivatives/references/errors.md

@@ -5,6 +5,7 @@
 ### Authentication Failures
 
 **API Key Invalid**
+
 - Error: `Invalid API key` or `Signature mismatch`
 - Causes: Expired key, wrong permissions, clock drift
 - Solution:
@@ -14,12 +15,14 @@
   4. Check key has futures/derivatives permissions
 
 **IP Whitelist Rejected**
+
 - Error: `IP not in whitelist`
 - Solution: Add current IP to exchange API settings or remove whitelist restriction
 
 ### Rate Limiting
 
 **Too Many Requests**
+
 - Error: `429 Too Many Requests` or `Rate limit exceeded`
 - Threshold varies by exchange:
   - Binance: 1200 requests/minute (weighted)
@@ -33,6 +36,7 @@
   4. Batch requests where possible
 
 **Weight Exceeded**
+
 - Error: `Request weight exceeded`
 - Solution: Some endpoints cost more weight; use lightweight endpoints or wait
 
@@ -41,6 +45,7 @@
 ### Missing or Stale Data
 
 **No Data Available**
+
 - Error: `No funding data available for {symbol}`
 - Causes: Symbol not listed, exchange down, maintenance
 - Solution:
@@ -50,6 +55,7 @@
   4. Use mock data for testing
 
 **Stale Timestamp**
+
 - Error: Data timestamp older than expected
 - Solution:
   1. Check WebSocket connection alive
@@ -60,10 +66,12 @@
 ### Invalid Values
 
 **Negative Funding Rate**
+
 - Not an error - negative funding is valid (shorts pay longs)
 - Just ensure your calculations handle negative correctly
 
 **Zero Open Interest**
+
 - May indicate:
   - New symbol with no positions
   - Data not yet populated
@@ -71,6 +79,7 @@
 - Solution: Filter out or flag as incomplete
 
 **Implausible Values**
+
 - Funding rate > 10% per 8h → likely data error
 - IV > 500% → verify or exclude
 - Solution: Implement sanity checks and outlier filtering
@@ -80,9 +89,11 @@
 ### Division by Zero
 
 **Empty Exchange List**
+
 - Error: `Division by zero` in weighted average
 - Cause: No exchanges returned data
 - Solution:
+
 ```python
 if not exchanges:
     raise ValueError("No exchange data available")
@@ -94,8 +105,10 @@ if total == 0:
 ### Decimal Precision
 
 **Precision Loss**
+
 - Error: Incorrect basis calculations due to floating point
 - Solution: Use `Decimal` for all price/rate calculations
+
 ```python
 from decimal import Decimal, ROUND_HALF_UP
 basis = (futures - spot) / spot
@@ -105,9 +118,11 @@ basis_pct = float(basis.quantize(Decimal('0.0001')))
 ### Date Handling
 
 **Invalid Expiry Format**
+
 - Error: `strptime` fails on expiry string
 - Cause: Different exchange formats (YYYYMMDD vs YYYY-MM-DD)
 - Solution:
+
 ```python
 formats = ['%Y-%m-%d', '%Y%m%d', '%d%b%y']
 for fmt in formats:
@@ -119,6 +134,7 @@ raise ValueError(f"Unknown expiry format: {expiry}")
 ```
 
 **Expiry Already Passed**
+
 - Warning: Analyzing expired contract
 - Solution: Filter to active expiries only
 
@@ -127,6 +143,7 @@ raise ValueError(f"Unknown expiry format: {expiry}")
 ### Connection Failures
 
 **Connection Timeout**
+
 - Error: `Connection timed out`
 - Solution:
   1. Increase timeout: `timeout=30`
@@ -135,6 +152,7 @@ raise ValueError(f"Unknown expiry format: {expiry}")
   4. Check network connectivity
 
 **SSL Certificate Error**
+
 - Error: `SSL: CERTIFICATE_VERIFY_FAILED`
 - Solution:
   1. Update CA certificates
@@ -143,6 +161,7 @@ raise ValueError(f"Unknown expiry format: {expiry}")
 ### WebSocket Issues
 
 **Disconnected**
+
 - Error: WebSocket connection closed unexpectedly
 - Solution:
   1. Implement reconnection logic
@@ -201,22 +220,27 @@ def record_failure(exchange):
 ## Common Issues by Exchange
 
 ### Binance
+
 - Issue: Weight limits are complex (different endpoints cost different)
 - Solution: Track weight counter from response headers
 
 ### Bybit
+
 - Issue: V5 API has different structure than V3
 - Solution: Use unified V5 endpoints consistently
 
 ### OKX
+
 - Issue: Requires specific headers for authentication
 - Solution: Include `OK-ACCESS-*` headers correctly
 
 ### Deribit
+
 - Issue: Options data requires authentication
 - Solution: Use API key even for read-only data
 
 ### BitMEX
+
 - Issue: Rate limits are very strict
 - Solution: Aggressive caching, minimal polling
 

package/skills/tracking-crypto-derivatives/references/examples.md

@@ -5,11 +5,13 @@
 ### Funding Rate Analysis
 
 **Basic funding rate check:**
+
 ```bash
 python derivatives_tracker.py funding BTC
 ```
 
 Output:
+
 ```
 ======================================================================
                      BTC FUNDING RATE ANALYSIS
@@ -32,6 +34,7 @@ Sentiment: 🟢 Moderate Bullish
 ```
 
 **JSON export:**
+
 ```bash
 python derivatives_tracker.py funding BTC --format json
 ```
@@ -39,11 +42,13 @@ python derivatives_tracker.py funding BTC --format json
 ### Open Interest Analysis
 
 **Basic OI check:**
+
 ```bash
 python derivatives_tracker.py oi BTC
 ```
 
 Output:
+
 ```
 ======================================================================
                     BTC OPEN INTEREST ANALYSIS
@@ -68,11 +73,13 @@ Dominant Exchange: Binance (41.3%)
 ```
 
 **With divergence analysis:**
+
 ```bash
 python derivatives_tracker.py oi BTC --price-change 3.5
 ```
 
 Output includes:
+
 ```
 ────────────────────────────────────────────────────────────────────────
 DIVERGENCE ANALYSIS
@@ -89,11 +96,13 @@ DIVERGENCE ANALYSIS
 ### Liquidation Monitoring
 
 **Basic liquidation summary:**
+
 ```bash
 python derivatives_tracker.py liquidations BTC
 ```
 
 Output:
+
 ```
 ======================================================================
                      BTC LIQUIDATION MONITOR
@@ -127,11 +136,13 @@ SHORT LIQUIDATIONS (above $67,500):
 ```
 
 **With large liquidation history:**
+
 ```bash
 python derivatives_tracker.py liquidations BTC --large
 ```
 
 Adds:
+
 ```
 ────────────────────────────────────────────────────────────────────────
 RECENT LARGE LIQUIDATIONS (>$1M)
@@ -147,11 +158,13 @@ OKX        short  $68,100       $2.9M        2h ago
 ### Options Analysis
 
 **Basic options summary:**
+
 ```bash
 python derivatives_tracker.py options BTC
 ```
 
 Output:
+
 ```
 ======================================================================
                       BTC OPTIONS ANALYSIS
@@ -183,6 +196,7 @@ Expiry Pressure: LOW
 ```
 
 **With max pain levels and options flow:**
+
 ```bash
 python derivatives_tracker.py options BTC --max-pain --flow
 ```
@@ -190,11 +204,13 @@ python derivatives_tracker.py options BTC --max-pain --flow
 ### Basis Analysis
 
 **Basic basis/spread check:**
+
 ```bash
 python derivatives_tracker.py basis BTC
 ```
 
 Output:
+
 ```
 ======================================================================
                        BTC BASIS ANALYSIS
@@ -226,6 +242,7 @@ TERM STRUCTURE
 ```
 
 **With carry trade scanner:**
+
 ```bash
 python derivatives_tracker.py basis BTC --carry
 ```
@@ -233,11 +250,13 @@ python derivatives_tracker.py basis BTC --carry
 ### Multi-Asset Dashboard
 
 **Quick market overview:**
+
 ```bash
 python derivatives_tracker.py dashboard BTC ETH SOL
 ```
 
 Output:
+
 ```
 ======================================================================
                     CRYPTO DERIVATIVES DASHBOARD

package/skills/tracking-crypto-derivatives/references/implementation.md

@@ -3,6 +3,7 @@
 ## Detailed Output Formats
 
 ### Funding Rate Report
+
 ```
 BTC PERPETUAL FUNDING RATES
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -18,6 +19,7 @@ Sentiment: Moderately Bullish
 ```
 
 ### Open Interest Report
+
 ```
 BTC OPEN INTEREST ANALYSIS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -34,6 +36,7 @@ Long/Short Ratio: 1.15 (53.5% long)
 ```
 
 ### Liquidation Heatmap
+
 ```
 BTC LIQUIDATION LEVELS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -55,6 +58,7 @@ SHORT LIQUIDATIONS (above):
 ## Options Analysis Deep Dive
 
 ### Options Commands
+
 ```bash
 # Get options overview
 python derivatives_tracker.py options BTC
@@ -70,6 +74,7 @@ python derivatives_tracker.py options BTC --flow
 ```
 
 ### Options Insights
+
 - **High IV rank** (>80): Options expensive, consider selling
 - **Low IV rank** (<20): Options cheap, consider buying
 - **Max pain**: Price where most options expire worthless
@@ -77,6 +82,7 @@ python derivatives_tracker.py options BTC --flow
 ## Basis Trading Guide
 
 ### Basis Commands
+
 ```bash
 # Get spot-perp basis
 python derivatives_tracker.py basis BTC
@@ -89,6 +95,7 @@ python derivatives_tracker.py basis --all
 ```
 
 ### Basis Trading Interpretation
+
 - **Positive basis**: Futures > Spot (contango, normal)
 - **Negative basis**: Futures < Spot (backwardation)
 - **Cash-and-carry**: Buy spot + sell futures when basis high
@@ -104,6 +111,7 @@ python derivatives_tracker.py basis --all
 ## Risk Warning
 
 Derivatives are leveraged instruments with high risk of loss.
+
 - Funding costs accumulate over time
 - Liquidations can happen rapidly
 - Options can expire worthless