Analyzing Options Flow

Analyzing Options Flow

Overview

Track and analyze crypto options flow on centralized derivatives exchanges (Deribit, OKX, Bybit) to identify institutional positioning, gauge market sentiment, and detect unusual activity in BTC and ETH options markets.

Prerequisites

• API credentials for at least one crypto derivatives exchange (Deribit API key recommended; OKX or Bybit as alternatives)
• Python 3.8+ with requests and websocket-client libraries installed
• Optional: pandas and numpy for advanced statistical analysis of flow data
• Understanding of options terminology: strike price, expiry, implied volatility, delta, gamma, open interest, and premium
• Network access to exchange WebSocket feeds for real-time flow monitoring

Instructions

1. Load exchange API credentials from ${CLAUDE_SKILL_DIR}/config/crypto-apis.env using the Read tool to authenticate against derivatives exchange endpoints. 2. Run Bash(crypto:options-*) to connect to the Deribit options data feed and pull the current options chain for BTC or ETH, including all active strikes and expiries. 3. Retrieve open interest data across all strike prices and expiration dates to build an open interest heatmap showing where positions are concentrated. 4. Calculate the aggregate put/call ratio by volume and by open interest to assess overall market sentiment (ratio above 1.0 indicates bearish bias; below 1.0 indicates bullish). 5. Filter for block trades exceeding a configurable notional threshold (e.g., $500K+) to isolate institutional-sized activity from retail noise. 6. Analyze the implied volatility term structure across expiry dates to detect vol compression (potential breakout ahead) or vol expansion (uncertainty increasing). 7. Track max pain levels for upcoming expiries by computing the strike price at which the most options expire worthless, indicating likely price magnetism near expiry. 8. Compare recent flow data against historical baselines (7-day and 30-day rolling averages) to flag statistically unusual positioning. 9. Generate a flow summary report with actionable signals: bullish large-block calls, bearish put sweeps, IV skew shifts, and OI buildup at key strikes. 10. Export results using --format json or --format csv for integration with trading dashboards or alerting systems.

See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation workflow.

Output

• Options chain tables showing strike, expiry, bid/ask, IV, delta, gamma, open interest, and volume for each contract
• Put/call ratio summary (by volume and open interest) with historical comparison
• Block trade log listing timestamp, direction (buy/sell), strike, expiry, size, premium, and implied volatility
• Open interest heatmap data mapping strike prices against expiration dates with position concentration
• Max pain calculation per expiry date with the optimal pain strike and dollar value at risk
• Implied volatility term structure curves across near-term and far-term expiries
• Unusual activity alerts flagging trades exceeding 2 standard deviations from the rolling average
• JSON or CSV export files for downstream analysis and dashboard integration

Error Handling

Examples

BTC Options Sentiment Snapshot

# Pull current BTC options chain and compute put/call ratios
python options_flow.py btc --summary

Returns the aggregate put/call ratio, top 5 strikes by open interest, max pain for the nearest expiry, and the current implied volatility at-the-money. A put/call ratio of 0.65 with heavy call OI at the $120K strike suggests bullish institutional positioning.

Detect Institutional Block Trades

# Filter for block trades above $1M notional in the last 24 hours
python options_flow.py btc --blocks --min-notional 1000000 --period 24h  # 1000000 = 1M limit

Lists all block trades exceeding the threshold with direction inference (aggressor side), strike, expiry, premium paid, and IV at execution. Useful for spotting large directional bets before they move the underlying.

ETH Implied Volatility Term Structure

# Generate IV term structure for ETH across all active expiries
python options_flow.py eth --iv-curve --format json > eth_iv_term.json

Exports the IV term structure as JSON. Flat or inverted term structures (near-term IV higher than far-term) often precede sharp directional moves, while steep upward-sloping curves indicate calm near-term expectations.

Resources

• Deribit API Documentation -- primary exchange for crypto options data, WebSocket and REST endpoints
• Laevitas Analytics -- crypto derivatives analytics dashboard with options flow visualization
• Greeks.live -- real-time crypto options analytics and block trade tracking
• Amberdata Derivatives -- institutional-grade crypto derivatives data API
• The Block Research -- aggregated crypto options market data and charts

Error Handling Reference

Common issues and solutions:

API Rate Limit Exceeded

• Error: Too many requests to crypto data API
• Solution: Implement request throttling; use caching for frequently accessed data; upgrade API tier if needed

Blockchain RPC Errors

• Error: Cannot connect to blockchain node or timeout
• Solution: Switch to backup RPC endpoint; verify network connectivity; check if node is synced

Invalid Address or Transaction

• Error: Blockchain address format invalid or transaction not found
• Solution: Validate address checksums; verify network (mainnet vs testnet); allow time for transaction confirmation

Exchange API Authentication Failed

• Error: Invalid API key or signature mismatch
• Solution: Regenerate API keys; verify permissions (read/trade); check system clock synchronization for signatures

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

Examples

Example 1: BTC Options Sentiment Dashboard

Generate a comprehensive sentiment snapshot for Bitcoin options covering put/call ratios, max pain, and open interest concentration.

Command:

python options_flow.py btc --summary --expiry nearest-3

Output:

BTC Options Sentiment Snapshot
══════════════════════════════════════════════════════════════
Underlying: BTC/USD @ $104,250
Timestamp:  2026-03-17T14:30:00Z
Source:     Deribit

Aggregate Put/Call Ratio
────────────────────────
  By Volume:         0.62  (Bullish — calls dominating)
  By Open Interest:  0.71  (Moderately Bullish)
  7-Day Average:     0.78
  30-Day Average:    0.85
  Signal: Volume P/C ratio 21% below 30-day average → unusual call buying

Max Pain Analysis (Nearest 3 Expiries)
────────────────────────────────────────
  Expiry       Max Pain    Distance   Magnet Strength
  2026-03-21   $102,000    -2.2%      Strong (3 days to expiry)
  2026-03-28   $100,000    -4.1%      Moderate
  2026-04-25   $105,000    +0.7%      Weak (far expiry)

Top 5 Strikes by Open Interest
──────────────────────────────
  Strike      Type   OI (contracts)  Notional ($M)   IV
  $110,000    Call   12,450          $1,298          52.3%
  $100,000    Put    11,200          $1,168          54.1%
  $120,000    Call    9,800          $1,022          58.7%
  $105,000    Call    8,650          $902            49.8%
  $ 95,000    Put    7,300          $761            56.2%

Interpretation:
  Heavy call OI at $110K-$120K suggests institutional upside positioning.
  Put protection concentrated at $100K and $95K as downside hedges.
  Call-heavy OI skew supports bullish medium-term outlook.

Example 2: Detecting Institutional Block Trades

Filter for large-notional block trades that indicate institutional positioning rather than retail activity.

Command:

python options_flow.py btc --blocks \
  --min-notional 500000 \
  --period 24h \
  --format table

Output:

BTC Block Trades (>$500K notional, last 24h)
══════════════════════════════════════════════════════════════

  Time (UTC)   Direction  Strike    Expiry      Size    Premium    IV     Notional
  ─────────────────────────────────────────────────────────────────────────────────
  14:22:05     BUY CALL   $120,000  2026-06-27  500     $1,850    61.2%  $925,000
  13:45:30     BUY PUT    $ 95,000  2026-04-25  800     $720      55.8%  $576,000
  11:02:18     SELL CALL  $130,000  2026-09-26  1,200   $980      64.5%  $1,176,000
  09:15:44     BUY CALL   $110,000  2026-06-27  650     $3,200    53.1%  $2,080,000
  08:30:02     BUY CALL   $115,000  2026-04-25  400     $1,450    56.9%  $580,000
  04:18:55     BUY PUT    $ 90,000  2026-06-27  900     $640      58.3%  $576,000

Summary:
  Total blocks: 6
  Net direction: Bullish (4 call buys vs 1 put buy, 1 call sell)
  Largest: $2.08M notional call buy at $110K June expiry
  Notable: $1.17M covered call sell at $130K Sept → institution capping upside

Flow Analysis:
  The $2.08M call purchase at $110K June expiry is 3.2 standard deviations
  above the 30-day average block size. Combined with the $925K call at $120K,
  institutions are positioning for a $110K-$120K move by Q2.

  The $1.17M call SELL at $130K Sept suggests a large holder is writing
  covered calls, capping their upside exposure at $130K. This is consistent
  with a moderately bullish but not euphoric institutional stance.

Example 3: Implied Volatility Term Structure Analysis

Generate the IV term structure curve to detect vol compression or expansion that may precede a directional move.

Command:

python options_flow.py eth --iv-curve --strikes atm --format json

Output (formatted for readability):

{
  "underlying": "ETH/USD",
  "spotPrice": 3850.00,
  "timestamp": "2026-03-17T14:30:00Z",
  "termStructure": [
    {
      "expiry": "2026-03-21",
      "daysToExpiry": 4,
      "atmStrike": 3850,
      "iv": 72.5,
      "ivChange7d": +8.2,
      "signal": "elevated"
    },
    {
      "expiry": "2026-03-28",
      "daysToExpiry": 11,
      "atmStrike": 3850,
      "iv": 65.3,
      "ivChange7d": +3.1,
      "signal": "normal"
    },
    {
      "expiry": "2026-04-25",
      "daysToExpiry": 39,
      "atmStrike": 3850,
      "iv": 58.7,
      "ivChange7d": -1.2,
      "signal": "normal"
    },
    {
      "expiry": "2026-06-27",
      "daysToExpiry": 102,
      "atmStrike": 3850,
      "iv": 55.2,
      "ivChange7d": -0.5,
      "signal": "normal"
    },
    {
      "expiry": "2026-09-26",
      "daysToExpiry": 193,
      "atmStrike": 3850,
      "iv": 54.8,
      "ivChange7d": +0.3,
      "signal": "normal"
    }
  ],
  "analysis": {
    "shape": "inverted",
    "nearTermPremium": 17.7,
    "interpretation": "Near-term IV (72.5%) is 17.7 points above far-term (54.8%). Inverted term structure indicates the market expects a significant move within the next 1-2 weeks. Historical precedent: ETH IV inversions of >15 points have preceded 10%+ moves within 10 days in 78% of cases over the past 12 months."
  }
}

Example 4: Open Interest Heatmap Data

Build an open interest heatmap showing position concentration across strikes and expiration dates.

Command:

python options_flow.py btc --oi-heatmap --format csv > btc_oi_heatmap.csv

CSV output (excerpt):

expiry,strike,call_oi,put_oi,total_oi,dominant_side,concentration_pct
2026-03-21,95000,120,2450,2570,PUT,1.8
2026-03-21,100000,850,4200,5050,PUT,3.5
2026-03-21,105000,3100,1800,4900,CALL,3.4
2026-03-21,110000,5200,600,5800,CALL,4.0
2026-03-28,95000,300,3100,3400,PUT,2.4
2026-03-28,100000,1200,5500,6700,PUT,4.7
2026-03-28,105000,4800,2200,7000,CALL,4.9
2026-03-28,110000,7500,900,8400,CALL,5.9
2026-04-25,100000,2000,8200,10200,PUT,7.1
2026-04-25,110000,9800,1100,10900,CALL,7.6
2026-04-25,120000,12450,400,12850,CALL,9.0

Interpretation:

Hotspots (highest concentration):
  1. $120K Call, Apr 25: 12,450 OI (9.0%) → major upside target
  2. $110K Call, Apr 25: 9,800 OI (7.6%) → secondary resistance
  3. $100K Put, Apr 25: 8,200 OI (7.1%) → major support level

Market positioning map:
  Below $100K: Put-heavy (downside protection zone)
  $100K-$105K: Mixed (battle zone)
  Above $105K: Call-heavy (upside conviction zone)
  $120K+: Extreme call concentration (strong conviction target)

Example 5: Unusual Activity Alerts

Flag trades that deviate significantly from historical baselines, indicating potential insider knowledge or large directional bets.

Command:

python options_flow.py btc --unusual --threshold 2.0 --period 7d

Output:

Unusual Options Activity Report — BTC
══════════════════════════════════════════════════════════════
Period: 2026-03-10 to 2026-03-17
Threshold: >2.0 standard deviations from 30-day rolling average

ALERT 1 — HIGH SEVERITY (3.2 sigma)
  Instrument: BTC-25APR26-120000-C
  Activity:   1,850 contracts traded (vs 30-day avg: 320/day)
  Direction:  Net BUY (aggressor: buyer on 87% of volume)
  Premium:    $2.4M total premium spent
  IV Impact:  IV rose from 56% to 61% during the session
  Timeframe:  Concentrated in a 45-minute window (09:00-09:45 UTC)
  Signal:     Institutional call accumulation ahead of major expiry

ALERT 2 — MODERATE SEVERITY (2.4 sigma)
  Instrument: BTC-28MAR26-95000-P
  Activity:   920 contracts traded (vs 30-day avg: 180/day)
  Direction:  Net BUY (aggressor: buyer on 72% of volume)
  Premium:    $380K total premium spent
  IV Impact:  IV unchanged (absorbed by market makers)
  Timeframe:  Spread across full session
  Signal:     Protective put buying, possibly hedging a large spot position

ALERT 3 — MODERATE SEVERITY (2.1 sigma)
  Instrument: BTC-25APR26-110000-C / BTC-25APR26-130000-C (spread)
  Activity:   600 contracts of bull call spread
  Direction:  BUY 110K/SELL 130K (defined risk bullish)
  Max Profit: $20K per spread if BTC > $130K at expiry
  Premium:    $1.1M net debit
  Signal:     Institutional risk-defined bet on $110K-$130K range by April

No further alerts above threshold.

Example 6: Multi-Exchange Comparison

Compare options data across Deribit, OKX, and Bybit to find arbitrage opportunities or exchange-specific positioning.

Command:

python options_flow.py btc --compare-exchanges --strike 110000 --expiry 2026-04-25

Output:

Cross-Exchange Comparison: BTC $110K Call, Apr 25 2026
══════════════════════════════════════════════════════════════

  Metric           Deribit      OKX          Bybit
  ──────────────────────────────────────────────────
  Bid              $3,180       $3,150       $3,140
  Ask              $3,220       $3,280       $3,310
  Spread           $40 (1.3%)   $130 (4.1%)  $170 (5.4%)
  IV (mid)         53.1%        53.8%        54.2%
  24h Volume       1,240        380          95
  Open Interest    9,800        2,100        450
  Last Trade       14:28 UTC    14:15 UTC    13:02 UTC

Analysis:
  Deribit: Tightest spreads, highest liquidity. Primary price discovery venue.
  OKX: Slight IV premium (+0.7%) — may indicate local demand from Asian flow.
  Bybit: Widest spreads, lowest volume. Not recommended for large orders.

  Arb opportunity: Buy on Bybit ($3,140 ask) / Sell on Deribit ($3,180 bid)
  = $40/contract edge. However, cross-exchange settlement risk and fees likely
  consume most of this edge. Only viable for market makers with both venues.

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

Implementation Guide

Step 1: Configure Data Sources

Set up connections to crypto data providers:

1. Use Read tool to load API credentials from ${CLAUDE_SKILL_DIR}/config/crypto-apis.env 2. Configure blockchain RPC endpoints for target networks 3. Set up exchange API connections if required 4. Verify rate limits and subscription tiers 5. Test connectivity and authentication

Step 2: Query Crypto Data

Retrieve relevant blockchain and market data:

1. Use Bash(crypto:options-*) to execute crypto data queries 2. Fetch real-time prices, volumes, and market cap data 3. Query blockchain for on-chain metrics and transactions 4. Retrieve exchange order book and trade history 5. Aggregate data from multiple sources for accuracy

Step 3: Analyze and Process

Process crypto data to generate insights:

• Calculate key metrics (returns, volatility, correlation)
• Identify patterns and anomalies in data
• Apply technical indicators or on-chain signals
• Compare across timeframes and assets
• Generate actionable insights and alerts

Step 4: Generate Reports

Document findings in ${CLAUDE_SKILL_DIR}/crypto-reports/:

• Market summary with key price movements
• Detailed analysis with charts and metrics
• Trading signals or opportunity recommendations
• Risk assessment and position sizing guidance
• Historical context and trend analysis

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)