Massive Options Data
Data supply layer for US options market data. Wraps the Massive (Polygon)
options REST endpoints with a thin, predictable Python interface.
This skill does NOT generate strategies, signals, rankings, or trading
advice — it only exposes options data.
Plan: Developer — REAL field availability
We are on Massive Options Developer ($79/mo). Build your callers against
what's actually present in the API responses:
| Field |
Developer returns? |
Notes |
details.* (ticker, strike, expiration, type) |
✅ |
Always present. |
implied_volatility |
✅ |
Per contract, 15-min delayed. |
greeks (delta, gamma, theta, vega) |
✅ |
Per contract, 15-min delayed. |
open_interest |
✅ |
Per contract, previous session. |
day.{open,high,low,close,volume,vwap} |
✅ |
Option prices (previous session OHLC), 15-min delayed. |
underlying_asset.ticker |
✅ |
Always present. |
underlying_asset.price |
✅ |
Current underlying price, 15-min delayed. |
last_trade (price, size, timestamp) |
✅ |
Last trade, 15-min delayed. |
last_quote (bid/ask) |
❌ |
Still not returned on Developer. Cannot calculate real-time spread. |
| Historical IV / IV Rank / IV Percentile |
❌ |
Not exposed on any plan; build your own historical series. |
ATM filtering now uses real underlying price:
chain = massive_option_chain_snapshot("AAPL")
# No need for twelvedata — underlying price is now included!
spot_price = chain["results"][0]["underlying_asset"]["price"]
atm_low, atm_high = spot_price * 0.95, spot_price * 1.05
for contract in chain["results"]:
strike = contract["details"]["strike_price"]
if atm_low <= strike <= atm_high:
# This is an ATM contract
If you need real-time bid/ask quotes, upgrade to Advanced ($199/mo).
Pagination — required for any DTE-range scan
Chain snapshots paginate by ticker sort order. A 250-row first page often
covers just one expiration. To get all contracts in a DTE window you MUST
walk next_url (see massive_paginate in exports.py). Skipping this is
the #1 reason a "0 results" scan looks broken.
Typical chain sizes for a single underlying with one expiration window can
exceed 450 contracts. Allow at least 4 pages.
Script Usage
python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/massive-options-data")
from exports import (
massive_option_chain_snapshot,
massive_option_contract_snapshot,
massive_option_trades,
massive_option_quotes,
massive_option_aggregates,
massive_list_contracts,
massive_paginate,
)
snap = massive_option_chain_snapshot(underlying="SPY", limit=10)
print(json.dumps(snap.get("results", [])[:2], indent=2))
EOF
Functions (exports.py)
| Function |
Endpoint |
Purpose |
massive_option_chain_snapshot(underlying, **filters) |
GET /v3/snapshot/options/{underlying} |
Full chain snapshot (price/greeks/IV/OI; quote+trade missing on Starter). |
massive_option_contract_snapshot(underlying, option_ticker) |
GET /v3/snapshot/options/{underlying}/{contract} |
Single contract snapshot. |
massive_list_contracts(underlying_ticker=None, **filters) |
GET /v3/reference/options/contracts |
Reference list of option contracts (active or expired). |
massive_option_trades(option_ticker, **range) |
GET /v3/trades/{option_ticker} |
Historical trade ticks. Available on Developer+. |
massive_option_quotes(option_ticker, **range) |
GET /v3/quotes/{option_ticker} |
Historical NBBO quotes. Still returns 403 on Developer. Requires Advanced. |
massive_option_aggregates(option_ticker, multiplier, timespan, from_, to, **opts) |
GET /v2/aggs/ticker/{ticker}/range/... |
OHLCV bars. Minute + second bars on Developer, all bars on Advanced. |
massive_paginate(url, params=None, max_pages=20) |
— |
Walk next_url cursor pagination. |
All functions return the raw JSON from upstream. HTTP errors raise via
Response.raise_for_status().
Hardening notes
- Probe first, code second. Before writing a filter pipeline against a
new endpoint, dump one full record and inspect actual fields. Saves hours
of "why is everything filtered out?" debugging.
- Null handling.
greeks, last_quote, last_trade may be absent;
keep as None, never fabricate.
- Caller-id. Every call should include a
caller_id so transparent-proxy
can attribute usage.
Credentials
Set MASSIVE_API_KEY via the agent's secure input flow. The key is injected
by sc-proxy when present; the local script also reads it from the
environment so it works in BYOK setups.
Source of truth
1---
2name: massive-options-data
3version: 1.3.1
4description: |
5 US options data: chain snapshots, contracts, trades, quotes, greeks, IV, OI.
6
7 Use when pulling option chains or contract metrics for analysis (e.g. AAPL Jan calls, SPY chain, NVDA IV, weekly puts).
8delivery: script
9metadata:
10 source: https://skillmd.com/skills/starchild-ai-agent/massive-options-data
11 starchild:
12 emoji: "🧩"
13 skillKey: massive-options-data
14 requires:
15 env:
16 - MASSIVE_API_KEY
17
18user-invocable: false
19disable-model-invocation: false
20
21---
22
23# Massive Options Data
24
25Data supply layer for US options market data. Wraps the Massive (Polygon)
26options REST endpoints with a thin, predictable Python interface.
27
28This skill does NOT generate strategies, signals, rankings, or trading
29advice — it only exposes options data.
30
31## Plan: Developer — REAL field availability
32
33We are on **Massive Options Developer ($79/mo)**. Build your callers against
34what's actually present in the API responses:
35
36| Field | Developer returns? | Notes |
37|---|---|---|
38| `details.*` (ticker, strike, expiration, type) | ✅ | Always present. |
39| `implied_volatility` | ✅ | Per contract, 15-min delayed. |
40| `greeks` (delta, gamma, theta, vega) | ✅ | Per contract, 15-min delayed. |
41| `open_interest` | ✅ | Per contract, previous session. |
42| `day.{open,high,low,close,volume,vwap}` | ✅ | **Option prices** (previous session OHLC), 15-min delayed. |
43| `underlying_asset.ticker` | ✅ | Always present. |
44| `underlying_asset.price` | ✅ | **Current underlying price**, 15-min delayed. |
45| `last_trade` (price, size, timestamp) | ✅ | **Last trade**, 15-min delayed. |
46| `last_quote` (bid/ask) | ❌ | **Still not returned** on Developer. Cannot calculate real-time spread. |
47| Historical IV / IV Rank / IV Percentile | ❌ | Not exposed on any plan; build your own historical series. |
48
49**ATM filtering now uses real underlying price:**
50```python
51chain = massive_option_chain_snapshot("AAPL")
52# No need for twelvedata — underlying price is now included!
53spot_price = chain["results"][0]["underlying_asset"]["price"]
54atm_low, atm_high = spot_price * 0.95, spot_price * 1.05
55for contract in chain["results"]:
56 strike = contract["details"]["strike_price"]
57 if atm_low <= strike <= atm_high:
58 # This is an ATM contract
59```
60
61If you need real-time bid/ask quotes, upgrade to **Advanced ($199/mo)**.
62
63## Pagination — required for any DTE-range scan
64
65Chain snapshots paginate by `ticker` sort order. A 250-row first page often
66covers just one expiration. To get all contracts in a DTE window you MUST
67walk `next_url` (see `massive_paginate` in `exports.py`). Skipping this is
68the #1 reason a "0 results" scan looks broken.
69
70Typical chain sizes for a single underlying with one expiration window can
71exceed 450 contracts. Allow at least 4 pages.
72
73## Script Usage
74
75```bash
76python3 - <<'EOF'
77import sys, json
78sys.path.insert(0, "/data/workspace/skills/massive-options-data")
79from exports import (
80 massive_option_chain_snapshot,
81 massive_option_contract_snapshot,
82 massive_option_trades,
83 massive_option_quotes,
84 massive_option_aggregates,
85 massive_list_contracts,
86 massive_paginate,
87)
88
89snap = massive_option_chain_snapshot(underlying="SPY", limit=10)
90print(json.dumps(snap.get("results", [])[:2], indent=2))
91EOF
92```
93
94## Functions (`exports.py`)
95
96| Function | Endpoint | Purpose |
97|---|---|---|
98| `massive_option_chain_snapshot(underlying, **filters)` | `GET /v3/snapshot/options/{underlying}` | Full chain snapshot (price/greeks/IV/OI; quote+trade missing on Starter). |
99| `massive_option_contract_snapshot(underlying, option_ticker)` | `GET /v3/snapshot/options/{underlying}/{contract}` | Single contract snapshot. |
100| `massive_list_contracts(underlying_ticker=None, **filters)` | `GET /v3/reference/options/contracts` | Reference list of option contracts (active or expired). |
101| `massive_option_trades(option_ticker, **range)` | `GET /v3/trades/{option_ticker}` | Historical trade ticks. **Available on Developer+.** |
102| `massive_option_quotes(option_ticker, **range)` | `GET /v3/quotes/{option_ticker}` | Historical NBBO quotes. **Still returns 403 on Developer.** Requires Advanced. |
103| `massive_option_aggregates(option_ticker, multiplier, timespan, from_, to, **opts)` | `GET /v2/aggs/ticker/{ticker}/range/...` | OHLCV bars. Minute + second bars on Developer, all bars on Advanced. |
104| `massive_paginate(url, params=None, max_pages=20)` | — | Walk `next_url` cursor pagination. |
105
106All functions return the raw JSON from upstream. HTTP errors raise via
107`Response.raise_for_status()`.
108
109## Hardening notes
110
111- **Probe first, code second.** Before writing a filter pipeline against a
112 new endpoint, dump one full record and inspect actual fields. Saves hours
113 of "why is everything filtered out?" debugging.
114- **Null handling.** `greeks`, `last_quote`, `last_trade` may be absent;
115 keep as `None`, never fabricate.
116- **Caller-id.** Every call should include a `caller_id` so transparent-proxy
117 can attribute usage.
118
119## Credentials
120
121Set `MASSIVE_API_KEY` via the agent's secure input flow. The key is injected
122by sc-proxy when present; the local script also reads it from the
123environment so it works in BYOK setups.
124
125## Source of truth
126- Massive options docs: https://massive.com/docs/rest/options/overview
127- Follow official field names; when upstream changes the contract, update
128 this skill rather than papering over it in callers.