@intentsolutionsio/crypto-derivatives-tracker 1.0.0

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

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""
+Open Interest analyzer.
+
+Analyzes open interest across exchanges with:
+- Multi-exchange aggregation
+- Trend analysis
+- OI vs price divergence detection
+- Long/short ratio tracking
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Dict, List, Optional
+from datetime import datetime
+
+from exchange_client import ExchangeClient, OpenInterest, Exchange
+
+
+@dataclass
+class OIAnalysis:
+    """Aggregated open interest analysis."""
+
+    symbol: str
+    exchanges: List[OpenInterest]
+    total_oi_usd: Decimal
+    total_oi_contracts: Decimal
+    avg_change_24h: float
+    avg_change_7d: float
+    weighted_long_ratio: float
+    dominant_exchange: str
+    dominant_share: float
+    trend: str                  # "increasing", "decreasing", "stable"
+    trend_strength: str         # "strong", "moderate", "weak"
+    timestamp: datetime
+
+    @property
+    def is_increasing(self) -> bool:
+        """Check if OI is increasing."""
+        return self.avg_change_24h > 2.0
+
+    @property
+    def is_decreasing(self) -> bool:
+        """Check if OI is decreasing."""
+        return self.avg_change_24h < -2.0
+
+    @property
+    def long_percentage(self) -> float:
+        """Calculate long percentage from ratio."""
+        return self.weighted_long_ratio / (1 + self.weighted_long_ratio) * 100
+
+
+@dataclass
+class OIDivergence:
+    """OI vs Price divergence signal."""
+
+    symbol: str
+    oi_direction: str           # "up" or "down"
+    price_direction: str        # "up" or "down"
+    oi_change_pct: float
+    price_change_pct: float
+    signal: str                 # "bullish", "bearish", "short_squeeze", "long_liquidation"
+    description: str
+    confidence: str             # "high", "medium", "low"
+
+
+class OIAnalyzer:
+    """
+    Analyzes open interest patterns and signals.
+
+    Features:
+    - Multi-exchange aggregation
+    - Trend detection
+    - Divergence analysis
+    - Long/short positioning
+    """
+
+    # Trend thresholds
+    STRONG_CHANGE = 10.0        # >10% is strong
+    MODERATE_CHANGE = 5.0       # >5% is moderate
+
+    def __init__(
+        self,
+        client: Optional[ExchangeClient] = None,
+    ):
+        """
+        Initialize OI analyzer.
+
+        Args:
+            client: Exchange client for data fetching
+        """
+        self.client = client or ExchangeClient(use_mock=True)
+
+    def analyze(
+        self,
+        symbol: str,
+        exchanges: Optional[List[Exchange]] = None,
+    ) -> OIAnalysis:
+        """
+        Analyze open interest for a symbol.
+
+        Args:
+            symbol: Trading symbol (e.g., "BTC")
+            exchanges: Exchanges to include
+
+        Returns:
+            OIAnalysis with all metrics
+        """
+        # Fetch OI from all exchanges
+        oi_list = self.client.get_all_open_interest(symbol, exchanges)
+
+        if not oi_list:
+            raise ValueError(f"No OI data available for {symbol}")
+
+        # Calculate totals
+        total_usd = sum(float(oi.oi_usd) for oi in oi_list)
+        total_contracts = sum(float(oi.oi_contracts) for oi in oi_list)
+
+        # Calculate weighted averages
+        avg_24h = sum(
+            oi.change_24h_pct * float(oi.oi_usd) for oi in oi_list
+        ) / total_usd
+        avg_7d = sum(
+            oi.change_7d_pct * float(oi.oi_usd) for oi in oi_list
+        ) / total_usd
+
+        # Weighted long ratio
+        weighted_long = sum(
+            oi.long_ratio * float(oi.oi_usd) for oi in oi_list
+        ) / total_usd
+
+        # Find dominant exchange
+        dominant = max(oi_list, key=lambda x: x.oi_usd)
+        dominant_share = float(dominant.oi_usd) / total_usd * 100
+
+        # Determine trend
+        trend, strength = self._analyze_trend(avg_24h, avg_7d)
+
+        return OIAnalysis(
+            symbol=symbol,
+            exchanges=oi_list,
+            total_oi_usd=Decimal(str(int(total_usd))),
+            total_oi_contracts=Decimal(str(int(total_contracts))),
+            avg_change_24h=round(avg_24h, 2),
+            avg_change_7d=round(avg_7d, 2),
+            weighted_long_ratio=round(weighted_long, 2),
+            dominant_exchange=dominant.exchange,
+            dominant_share=round(dominant_share, 1),
+            trend=trend,
+            trend_strength=strength,
+            timestamp=datetime.now(),
+        )
+
+    def _analyze_trend(
+        self,
+        change_24h: float,
+        change_7d: float,
+    ) -> tuple:
+        """
+        Analyze OI trend from changes.
+
+        Returns:
+            (trend, strength) tuple
+        """
+        # Determine direction from 24h change
+        if change_24h > 2.0:
+            trend = "increasing"
+        elif change_24h < -2.0:
+            trend = "decreasing"
+        else:
+            trend = "stable"
+
+        # Determine strength from magnitude
+        abs_change = abs(change_24h)
+        if abs_change >= self.STRONG_CHANGE:
+            strength = "strong"
+        elif abs_change >= self.MODERATE_CHANGE:
+            strength = "moderate"
+        else:
+            strength = "weak"
+
+        return trend, strength
+
+    def detect_divergence(
+        self,
+        symbol: str,
+        price_change_24h: float,
+    ) -> Optional[OIDivergence]:
+        """
+        Detect OI vs price divergence.
+
+        Classic interpretation:
+        - Rising OI + Rising Price = Strong bullish trend
+        - Rising OI + Falling Price = Strong bearish trend
+        - Falling OI + Rising Price = Short covering (weak rally)
+        - Falling OI + Falling Price = Long liquidation (weak selloff)
+
+        Args:
+            symbol: Trading symbol
+            price_change_24h: Price change in last 24h (%)
+
+        Returns:
+            OIDivergence if divergence detected
+        """
+        analysis = self.analyze(symbol)
+        oi_change = analysis.avg_change_24h
+
+        oi_dir = "up" if oi_change > 0 else "down"
+        price_dir = "up" if price_change_24h > 0 else "down"
+
+        # Determine signal
+        if oi_change > 2 and price_change_24h > 2:
+            signal = "bullish"
+            desc = "Rising OI confirms bullish trend - new longs entering"
+            confidence = "high" if oi_change > 5 else "medium"
+        elif oi_change > 2 and price_change_24h < -2:
+            signal = "bearish"
+            desc = "Rising OI during selloff - new shorts entering"
+            confidence = "high" if oi_change > 5 else "medium"
+        elif oi_change < -2 and price_change_24h > 2:
+            signal = "short_squeeze"
+            desc = "Falling OI during rally - short covering, may be weak"
+            confidence = "medium"
+        elif oi_change < -2 and price_change_24h < -2:
+            signal = "long_liquidation"
+            desc = "Falling OI during selloff - long liquidations, may find support"
+            confidence = "medium"
+        else:
+            return None  # No significant divergence
+
+        return OIDivergence(
+            symbol=symbol,
+            oi_direction=oi_dir,
+            price_direction=price_dir,
+            oi_change_pct=oi_change,
+            price_change_pct=price_change_24h,
+            signal=signal,
+            description=desc,
+            confidence=confidence,
+        )
+
+    def get_market_share(
+        self,
+        symbol: str,
+    ) -> List[Dict]:
+        """
+        Get OI market share by exchange.
+
+        Args:
+            symbol: Trading symbol
+
+        Returns:
+            List of exchange market shares
+        """
+        analysis = self.analyze(symbol)
+        total = float(analysis.total_oi_usd)
+
+        shares = []
+        for oi in analysis.exchanges:
+            share = float(oi.oi_usd) / total * 100
+            shares.append({
+                "exchange": oi.exchange,
+                "oi_usd": float(oi.oi_usd),
+                "share_pct": round(share, 1),
+                "change_24h": oi.change_24h_pct,
+                "long_ratio": oi.long_ratio,
+            })
+
+        return sorted(shares, key=lambda x: x["oi_usd"], reverse=True)
+
+
+def demo():
+    """Demonstrate OI analyzer."""
+    analyzer = OIAnalyzer()
+
+    print("=" * 70)
+    print("OPEN INTEREST ANALYZER")
+    print("=" * 70)
+
+    # Analyze BTC OI
+    analysis = analyzer.analyze("BTC")
+
+    print(f"\n📈 {analysis.symbol} OPEN INTEREST ANALYSIS")
+    print("-" * 60)
+
+    print(f"\n{'Exchange':<12} {'OI (USD)':>14} {'24h Chg':>10} {'7d Chg':>10} {'Share':>8}")
+    print("-" * 60)
+
+    for oi in sorted(analysis.exchanges, key=lambda x: x.oi_usd, reverse=True):
+        share = float(oi.oi_usd) / float(analysis.total_oi_usd) * 100
+        print(
+            f"{oi.exchange:<12} "
+            f"${float(oi.oi_usd)/1e9:>12.2f}B "
+            f"{oi.change_24h_pct:>+9.1f}% "
+            f"{oi.change_7d_pct:>+9.1f}% "
+            f"{share:>7.1f}%"
+        )
+
+    print("-" * 60)
+    print(f"\nTotal OI: ${float(analysis.total_oi_usd)/1e9:.2f}B")
+    print(f"24h Change: {analysis.avg_change_24h:+.1f}%")
+    print(f"7d Change: {analysis.avg_change_7d:+.1f}%")
+    print(f"\nLong/Short Ratio: {analysis.weighted_long_ratio:.2f} ({analysis.long_percentage:.1f}% long)")
+    print(f"Trend: {analysis.trend_strength.title()} {analysis.trend.title()}")
+    print(f"Dominant Exchange: {analysis.dominant_exchange} ({analysis.dominant_share:.1f}%)")
+
+    # Check for divergence
+    print("\n" + "=" * 70)
+    print("DIVERGENCE ANALYSIS")
+    print("=" * 70)
+
+    # Simulate price change
+    price_change = 3.5  # Example: +3.5% price move
+    divergence = analyzer.detect_divergence("BTC", price_change)
+
+    if divergence:
+        print(f"\n🔍 Divergence Detected!")
+        print(f"   OI:    {divergence.oi_direction} ({divergence.oi_change_pct:+.1f}%)")
+        print(f"   Price: {divergence.price_direction} ({divergence.price_change_pct:+.1f}%)")
+        print(f"   Signal: {divergence.signal.upper()}")
+        print(f"   {divergence.description}")
+        print(f"   Confidence: {divergence.confidence}")
+    else:
+        print("\nNo significant divergence detected")
+
+    # Market share breakdown
+    print("\n" + "=" * 70)
+    print("MARKET SHARE BREAKDOWN")
+    print("=" * 70)
+
+    shares = analyzer.get_market_share("BTC")
+    for s in shares:
+        bar = "█" * int(s["share_pct"] / 2)
+        print(f"{s['exchange']:<12} {bar} {s['share_pct']:.1f}%")
+
+
+if __name__ == "__main__":
+    demo()

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

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""
+Options market analyzer.
+
+Analyzes crypto options markets with:
+- Implied volatility tracking
+- Put/call ratio analysis
+- Max pain calculation
+- Options flow detection
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Dict, List, Optional
+from datetime import datetime, date
+
+from exchange_client import ExchangeClient, OptionsSnapshot
+
+
+@dataclass
+class OptionsAnalysis:
+    """Comprehensive options analysis."""
+
+    symbol: str
+    snapshot: OptionsSnapshot
+    iv_interpretation: str          # "high", "normal", "low"
+    iv_percentile: float            # Estimated percentile (0-100)
+    sentiment_from_pcr: str         # "bullish", "bearish", "neutral"
+    sentiment_from_skew: str        # "bullish", "bearish", "neutral"
+    overall_sentiment: str
+    max_pain_distance_pct: float    # Distance from current to max pain
+    expiry_pressure: str            # "high", "medium", "low"
+    timestamp: datetime
+
+
+@dataclass
+class OptionsFlow:
+    """Significant options trade."""
+
+    symbol: str
+    expiry: str
+    strike: Decimal
+    option_type: str                # "call" or "put"
+    side: str                       # "buy" or "sell"
+    size_contracts: int
+    premium_usd: Decimal
+    iv_at_trade: float
+    interpretation: str
+    timestamp: datetime
+
+
+class OptionsAnalyzer:
+    """
+    Analyzes crypto options markets.
+
+    Features:
+    - IV analysis and percentile ranking
+    - Put/call ratio interpretation
+    - Max pain calculation
+    - Flow analysis
+    """
+
+    # IV interpretation thresholds
+    HIGH_IV = 70.0
+    LOW_IV = 40.0
+
+    # Put/call interpretation
+    BEARISH_PCR = 1.2   # Above this is bearish
+    BULLISH_PCR = 0.7   # Below this is bullish
+
+    def __init__(
+        self,
+        client: Optional[ExchangeClient] = None,
+    ):
+        """
+        Initialize options analyzer.
+
+        Args:
+            client: Exchange client for data fetching
+        """
+        self.client = client or ExchangeClient(use_mock=True)
+
+    def analyze(
+        self,
+        symbol: str,
+        expiry: Optional[str] = None,
+        current_price: Optional[Decimal] = None,
+    ) -> OptionsAnalysis:
+        """
+        Analyze options market for a symbol.
+
+        Args:
+            symbol: Trading symbol (e.g., "BTC")
+            expiry: Target expiry date (default: nearest)
+            current_price: Current spot price
+
+        Returns:
+            OptionsAnalysis with all metrics
+        """
+        # Fetch options snapshot
+        snapshot = self.client.get_options_snapshot(symbol, expiry)
+
+        if snapshot is None:
+            raise ValueError(f"No options data available for {symbol}")
+
+        # Set default price if not provided
+        if current_price is None:
+            if symbol == "BTC":
+                current_price = Decimal("67500")
+            elif symbol == "ETH":
+                current_price = Decimal("2500")
+            else:
+                current_price = Decimal("100")
+
+        # Interpret IV
+        iv_interp, iv_pctl = self._interpret_iv(snapshot.atm_iv, symbol)
+
+        # Interpret put/call ratio
+        pcr_sentiment = self._interpret_pcr(snapshot.put_call_ratio_volume)
+
+        # Interpret skew (simplified - just using PCR OI as proxy)
+        skew_sentiment = self._interpret_pcr(snapshot.put_call_ratio_oi)
+
+        # Overall sentiment (combine signals)
+        overall = self._combine_sentiment(pcr_sentiment, skew_sentiment)
+
+        # Max pain distance
+        max_pain_dist = (
+            (float(snapshot.max_pain) - float(current_price))
+            / float(current_price) * 100
+        )
+
+        # Expiry pressure (days until expiry)
+        expiry_pressure = self._assess_expiry_pressure(snapshot.expiry)
+
+        return OptionsAnalysis(
+            symbol=symbol,
+            snapshot=snapshot,
+            iv_interpretation=iv_interp,
+            iv_percentile=iv_pctl,
+            sentiment_from_pcr=pcr_sentiment,
+            sentiment_from_skew=skew_sentiment,
+            overall_sentiment=overall,
+            max_pain_distance_pct=round(max_pain_dist, 2),
+            expiry_pressure=expiry_pressure,
+            timestamp=datetime.now(),
+        )
+
+    def _interpret_iv(
+        self,
+        iv: float,
+        symbol: str,
+    ) -> tuple:
+        """
+        Interpret implied volatility.
+
+        Returns:
+            (interpretation, estimated_percentile)
+        """
+        # Adjust thresholds by asset (crypto generally high IV)
+        high = self.HIGH_IV
+        low = self.LOW_IV
+
+        if iv >= high:
+            interp = "high"
+            pctl = min(100, 50 + (iv - high))
+        elif iv <= low:
+            interp = "low"
+            pctl = max(0, 50 - (low - iv))
+        else:
+            interp = "normal"
+            pctl = 50 + ((iv - 55) / 15 * 30)  # Scale around 55
+
+        return interp, round(pctl, 0)
+
+    def _interpret_pcr(self, pcr: float) -> str:
+        """Interpret put/call ratio."""
+        if pcr >= self.BEARISH_PCR:
+            return "bearish"
+        elif pcr <= self.BULLISH_PCR:
+            return "bullish"
+        else:
+            return "neutral"
+
+    def _combine_sentiment(self, pcr_sent: str, skew_sent: str) -> str:
+        """Combine sentiment signals."""
+        if pcr_sent == skew_sent:
+            return pcr_sent
+        elif pcr_sent == "neutral":
+            return skew_sent
+        elif skew_sent == "neutral":
+            return pcr_sent
+        else:
+            return "mixed"
+
+    def _assess_expiry_pressure(self, expiry: str) -> str:
+        """Assess expiry pressure based on days remaining."""
+        try:
+            exp_date = datetime.strptime(expiry, "%Y-%m-%d").date()
+            days = (exp_date - date.today()).days
+
+            if days <= 2:
+                return "high"
+            elif days <= 7:
+                return "medium"
+            else:
+                return "low"
+        except Exception:
+            return "unknown"
+
+    def get_max_pain_levels(
+        self,
+        symbol: str,
+        expiries: Optional[List[str]] = None,
+    ) -> List[Dict]:
+        """
+        Get max pain levels for multiple expiries.
+
+        Args:
+            symbol: Trading symbol
+            expiries: List of expiry dates
+
+        Returns:
+            List of max pain levels by expiry
+        """
+        if expiries is None:
+            # Default expiries (next few Fridays)
+            expiries = ["2025-01-17", "2025-01-24", "2025-01-31"]
+
+        levels = []
+        for exp in expiries:
+            try:
+                snapshot = self.client.get_options_snapshot(symbol, exp)
+                if snapshot:
+                    levels.append({
+                        "expiry": exp,
+                        "max_pain": float(snapshot.max_pain),
+                        "call_oi": float(snapshot.total_call_oi),
+                        "put_oi": float(snapshot.total_put_oi),
+                        "pcr_oi": snapshot.put_call_ratio_oi,
+                    })
+            except Exception:
+                continue
+
+        return levels
+
+    def generate_mock_flow(
+        self,
+        symbol: str,
+        count: int = 5,
+    ) -> List[OptionsFlow]:
+        """
+        Generate mock options flow data.
+
+        In production, this would track actual large trades.
+        """
+        import random
+
+        if symbol == "BTC":
+            base_price = 67500
+        elif symbol == "ETH":
+            base_price = 2500
+        else:
+            base_price = 100
+
+        flows = []
+        for i in range(count):
+            opt_type = random.choice(["call", "put"])
+            # Strikes around current price
+            strike = base_price * (1 + random.uniform(-0.15, 0.15))
+            strike = round(strike / 1000) * 1000  # Round to nearest 1000
+
+            size = random.randint(100, 2000)
+            premium = size * random.uniform(500, 5000)
+
+            # Interpretation based on type and likely direction
+            if opt_type == "call":
+                interp = "Bullish positioning" if random.random() > 0.3 else "Covered call selling"
+            else:
+                interp = "Bearish bet" if random.random() > 0.5 else "Protective put"
+
+            flows.append(OptionsFlow(
+                symbol=symbol,
+                expiry="2025-01-31",
+                strike=Decimal(str(int(strike))),
+                option_type=opt_type,
+                side=random.choice(["buy", "sell"]),
+                size_contracts=size,
+                premium_usd=Decimal(str(int(premium))),
+                iv_at_trade=round(55 + random.uniform(-10, 15), 1),
+                interpretation=interp,
+                timestamp=datetime.now(),
+            ))
+
+        return sorted(flows, key=lambda x: x.premium_usd, reverse=True)
+
+
+def demo():
+    """Demonstrate options analyzer."""
+    analyzer = OptionsAnalyzer()
+
+    print("=" * 70)
+    print("OPTIONS MARKET ANALYZER")
+    print("=" * 70)
+
+    # Analyze BTC options
+    analysis = analyzer.analyze("BTC", current_price=Decimal("67500"))
+
+    print(f"\n📊 {analysis.symbol} OPTIONS ANALYSIS")
+    print("-" * 50)
+
+    snap = analysis.snapshot
+    print(f"\nExpiry: {snap.expiry}")
+    print(f"Exchange: {snap.exchange}")
+
+    print(f"\nImplied Volatility:")
+    print(f"   ATM IV: {snap.atm_iv:.1f}%")
+    print(f"   Interpretation: {analysis.iv_interpretation.upper()}")
+    print(f"   IV Rank: {analysis.iv_percentile:.0f}th percentile")
+
+    print(f"\nPut/Call Analysis:")
+    print(f"   PCR (Volume): {snap.put_call_ratio_volume:.2f}")
+    print(f"   PCR (OI): {snap.put_call_ratio_oi:.2f}")
+    print(f"   Sentiment: {analysis.sentiment_from_pcr.upper()}")
+
+    print(f"\nMax Pain:")
+    print(f"   Price: ${snap.max_pain:,.0f}")
+    print(f"   Distance: {analysis.max_pain_distance_pct:+.1f}% from current")
+
+    print(f"\nOpen Interest:")
+    print(f"   Calls: ${float(snap.total_call_oi)/1e9:.2f}B")
+    print(f"   Puts:  ${float(snap.total_put_oi)/1e9:.2f}B")
+
+    print(f"\nOverall Sentiment: {analysis.overall_sentiment.upper()}")
+    print(f"Expiry Pressure: {analysis.expiry_pressure.upper()}")
+
+    # Max pain levels
+    print("\n" + "-" * 50)
+    print("MAX PAIN BY EXPIRY")
+    print("-" * 50)
+
+    levels = analyzer.get_max_pain_levels("BTC")
+    print(f"\n{'Expiry':<12} {'Max Pain':>12} {'Call OI':>12} {'Put OI':>12} {'PCR':>6}")
+    print("-" * 50)
+    for lvl in levels:
+        print(
+            f"{lvl['expiry']:<12} "
+            f"${lvl['max_pain']:>10,.0f} "
+            f"${lvl['call_oi']/1e9:>10.1f}B "
+            f"${lvl['put_oi']/1e9:>10.1f}B "
+            f"{lvl['pcr_oi']:>5.2f}"
+        )
+
+    # Options flow
+    print("\n" + "-" * 50)
+    print("SIGNIFICANT OPTIONS FLOW (Simulated)")
+    print("-" * 50)
+
+    flows = analyzer.generate_mock_flow("BTC", count=5)
+    print(f"\n{'Type':<6} {'Strike':>10} {'Size':>8} {'Premium':>12} {'Interpretation':<25}")
+    print("-" * 70)
+    for flow in flows:
+        print(
+            f"{flow.option_type.upper():<6} "
+            f"${float(flow.strike):>8,.0f} "
+            f"{flow.size_contracts:>8} "
+            f"${float(flow.premium_usd):>10,.0f} "
+            f"{flow.interpretation:<25}"
+        )
+
+
+if __name__ == "__main__":
+    demo()