@intentsolutionsio/crypto-derivatives-tracker 1.0.0 → 1.0.3

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

package/skills/tracking-crypto-derivatives/scripts/basis_calculator.py

@@ -12,7 +12,7 @@ Calculates futures basis and spreads with:
 from dataclasses import dataclass
 from decimal import Decimal
 from typing import Dict, List, Optional
-from datetime import datetime, date
+from datetime import datetime
 
 from exchange_client import ExchangeClient, BasisData, Exchange
 
@@ -26,8 +26,8 @@ class BasisAnalysis:
     basis_data: List[BasisData]
     avg_basis_pct: float
     avg_annualized: float
-    market_structure: str          # "contango", "backwardation", "mixed"
-    structure_strength: str        # "strong", "moderate", "weak"
+    market_structure: str  # "contango", "backwardation", "mixed"
+    structure_strength: str  # "strong", "moderate", "weak"
     best_carry_expiry: Optional[str]
     best_carry_yield: float
     timestamp: datetime
@@ -45,8 +45,8 @@ class CarryOpportunity:
     basis_pct: float
     days_to_expiry: int
     annualized_yield: float
-    direction: str                 # "long_basis" or "short_basis"
-    strategy: str                  # Trade description
+    direction: str  # "long_basis" or "short_basis"
+    strategy: str  # Trade description
     risk_notes: str
 
 
@@ -62,8 +62,8 @@ class BasisCalculator:
     """
 
     # Structure interpretation
-    STRONG_BASIS = 5.0             # >5% annualized is strong
-    MODERATE_BASIS = 2.0           # >2% is moderate
+    STRONG_BASIS = 5.0  # >5% annualized is strong
+    MODERATE_BASIS = 2.0  # >2% is moderate
 
     def __init__(
         self,
@@ -213,19 +213,21 @@ class BasisCalculator:
                             )
                             risk_notes = "Borrowing costs apply; squeeze risk in tight markets"
 
-                        opportunities.append(CarryOpportunity(
-                            symbol=symbol,
-                            exchange=basis.exchange,
-                            expiry=basis.expiry,
-                            spot_price=analysis.spot_price,
-                            futures_price=basis.futures_price,
-                            basis_pct=basis.basis_pct,
-                            days_to_expiry=basis.days_to_expiry,
-                            annualized_yield=basis.annualized_pct,
-                            direction=direction,
-                            strategy=strategy,
-                            risk_notes=risk_notes,
-                        ))
+                        opportunities.append(
+                            CarryOpportunity(
+                                symbol=symbol,
+                                exchange=basis.exchange,
+                                expiry=basis.expiry,
+                                spot_price=analysis.spot_price,
+                                futures_price=basis.futures_price,
+                                basis_pct=basis.basis_pct,
+                                days_to_expiry=basis.days_to_expiry,
+                                annualized_yield=basis.annualized_pct,
+                                direction=direction,
+                                strategy=strategy,
+                                risk_notes=risk_notes,
+                            )
+                        )
             except Exception:
                 continue
 
@@ -251,10 +253,7 @@ class BasisCalculator:
         analysis = self.analyze(symbol, spot_price)
 
         # Sort by days to expiry
-        sorted_basis = sorted(
-            analysis.basis_data,
-            key=lambda b: b.days_to_expiry
-        )
+        sorted_basis = sorted(analysis.basis_data, key=lambda b: b.days_to_expiry)
 
         return [
             {