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
- Load exchange API credentials from
${CLAUDE_SKILL_DIR}/config/crypto-apis.env using the Read tool to authenticate against derivatives exchange endpoints.
- 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.
- Retrieve open interest data across all strike prices and expiration dates to build an open interest heatmap showing where positions are concentrated.
- 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).
- Filter for block trades exceeding a configurable notional threshold (e.g., $500K+) to isolate institutional-sized activity from retail noise.
- Analyze the implied volatility term structure across expiry dates to detect vol compression (potential breakout ahead) or vol expansion (uncertainty increasing).
- 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.
- Compare recent flow data against historical baselines (7-day and 30-day rolling averages) to flag statistically unusual positioning.
- Generate a flow summary report with actionable signals: bullish large-block calls, bearish put sweeps, IV skew shifts, and OI buildup at key strikes.
- 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
| Error |
Cause |
Solution |
API Rate Limit Exceeded |
Too many requests to the derivatives exchange API |
Implement request throttling with 100ms minimum between calls; use WebSocket feeds for real-time data instead of polling REST endpoints; upgrade API tier if needed |
Cannot connect to blockchain node or timeout |
RPC endpoint unreachable when resolving on-chain settlement data |
Switch to a backup RPC endpoint; verify network connectivity; confirm the node is fully synced |
Invalid API key or signature mismatch |
Exchange API authentication failure |
Regenerate API keys on the exchange; verify key permissions include read access to derivatives data; check system clock synchronization (HMAC signatures require accurate timestamps) |
No options data for instrument |
Queried an expired or non-existent options contract |
Verify the instrument name matches exchange conventions (e.g., BTC-28MAR25-100000-C on Deribit); check that the expiry has not already passed |
WebSocket connection dropped |
Exchange feed disconnection due to inactivity or network issue |
Implement automatic reconnection with exponential backoff; send periodic ping frames to maintain the connection |
Insufficient historical data |
Baseline period too short for statistical comparison |
Extend the rolling window from 7 days to 30 days; ensure the data collection pipeline has been running long enough to accumulate history |
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
1---2name: analyzing-options-flow3description: Track crypto options flow to identify institutional positioning and market sentiment. Use when tracking institutional options flow. Trigger with phrases like "track options flow", "analyze derivatives", or "check institutional".4license: MIT5---6# Analyzing Options Flow
7
8## Overview
9
10Track 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.
11
12## Prerequisites
13
14- API credentials for at least one crypto derivatives exchange (Deribit API key recommended; OKX or Bybit as alternatives)
15- Python 3.8+ with `requests` and `websocket-client` libraries installed
16- Optional: `pandas` and `numpy` for advanced statistical analysis of flow data
17- Understanding of options terminology: strike price, expiry, implied volatility, delta, gamma, open interest, and premium
18- Network access to exchange WebSocket feeds for real-time flow monitoring
19
20## Instructions
21
221. Load exchange API credentials from `${CLAUDE_SKILL_DIR}/config/crypto-apis.env` using the Read tool to authenticate against derivatives exchange endpoints.
232. 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.
243. Retrieve open interest data across all strike prices and expiration dates to build an open interest heatmap showing where positions are concentrated.
254. 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).
265. Filter for block trades exceeding a configurable notional threshold (e.g., $500K+) to isolate institutional-sized activity from retail noise.
276. Analyze the implied volatility term structure across expiry dates to detect vol compression (potential breakout ahead) or vol expansion (uncertainty increasing).
287. 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.
298. Compare recent flow data against historical baselines (7-day and 30-day rolling averages) to flag statistically unusual positioning.
309. Generate a flow summary report with actionable signals: bullish large-block calls, bearish put sweeps, IV skew shifts, and OI buildup at key strikes.
3110. Export results using `--format json` or `--format csv` for integration with trading dashboards or alerting systems.
32
33See `${CLAUDE_SKILL_DIR}/references/implementation.md` for the full implementation workflow.
34
35## Output
36
37- Options chain tables showing strike, expiry, bid/ask, IV, delta, gamma, open interest, and volume for each contract
38- Put/call ratio summary (by volume and open interest) with historical comparison
39- Block trade log listing timestamp, direction (buy/sell), strike, expiry, size, premium, and implied volatility
40- Open interest heatmap data mapping strike prices against expiration dates with position concentration
41- Max pain calculation per expiry date with the optimal pain strike and dollar value at risk
42- Implied volatility term structure curves across near-term and far-term expiries
43- Unusual activity alerts flagging trades exceeding 2 standard deviations from the rolling average
44- JSON or CSV export files for downstream analysis and dashboard integration
45
46## Error Handling
47
48| Error | Cause | Solution |
49|-------|-------|----------|
50| `API Rate Limit Exceeded` | Too many requests to the derivatives exchange API | Implement request throttling with 100ms minimum between calls; use WebSocket feeds for real-time data instead of polling REST endpoints; upgrade API tier if needed |
51| `Cannot connect to blockchain node or timeout` | RPC endpoint unreachable when resolving on-chain settlement data | Switch to a backup RPC endpoint; verify network connectivity; confirm the node is fully synced |
52| `Invalid API key or signature mismatch` | Exchange API authentication failure | Regenerate API keys on the exchange; verify key permissions include read access to derivatives data; check system clock synchronization (HMAC signatures require accurate timestamps) |
53| `No options data for instrument` | Queried an expired or non-existent options contract | Verify the instrument name matches exchange conventions (e.g., `BTC-28MAR25-100000-C` on Deribit); check that the expiry has not already passed |
54| `WebSocket connection dropped` | Exchange feed disconnection due to inactivity or network issue | Implement automatic reconnection with exponential backoff; send periodic ping frames to maintain the connection |
55| `Insufficient historical data` | Baseline period too short for statistical comparison | Extend the rolling window from 7 days to 30 days; ensure the data collection pipeline has been running long enough to accumulate history |
56
57## Examples
58
59### BTC Options Sentiment Snapshot
60
61```bash
62# Pull current BTC options chain and compute put/call ratios
63python options_flow.py btc --summary
64```
65
66Returns 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.
67
68### Detect Institutional Block Trades
69
70```bash
71# Filter for block trades above $1M notional in the last 24 hours
72python options_flow.py btc --blocks --min-notional 1000000 --period 24h # 1000000 = 1M limit
73```
74
75Lists 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.
76
77### ETH Implied Volatility Term Structure
78
79```bash
80# Generate IV term structure for ETH across all active expiries
81python options_flow.py eth --iv-curve --format json > eth_iv_term.json
82```
83
84Exports 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.
85
86## Resources
87
88- [Deribit API Documentation](https://docs.deribit.com/) -- primary exchange for crypto options data, WebSocket and REST endpoints
89- [Laevitas Analytics](https://app.laevitas.ch/) -- crypto derivatives analytics dashboard with options flow visualization
90- [Greeks.live](https://www.greeks.live/) -- real-time crypto options analytics and block trade tracking
91- Amberdata Derivatives -- institutional-grade crypto derivatives data API
92- [The Block Research](https://www.theblock.co/data/crypto-markets/options) -- aggregated crypto options market data and charts
gabrielmoreira