The only thing that behaves differently from an equity option is the underlying symbol, and it differs between two endpoint families rather than being one rule. The snapshot endpoints return the same contracts for I:SPX and SPX, but only the prefixed form returns Greeks and implied volatility, while the reference endpoints accept only the bare form and answer the prefixed one with an empty list rather than an error.
Applies to
- Plans: an Options subscription. Indices subscriptions cover index values, not index options.
- Endpoints: /v3/snapshot/options/{underlyingAsset}, /v3/reference/options/contracts, /v3/trades/{optionsTicker}, /v3/quotes/{optionsTicker} and /v2/aggs/ticker/{optionsTicker}.
- Asset classes: index options such as SPX, SPXW, NDX, VIX and RUT.
How to query an index option chain
Ask the snapshot endpoint for the chain, with the index prefixed:
curl -X GET "https://api.massive.com/v3/snapshot/options/I:SPX?limit=1&apiKey=YOUR_API_KEY"
Response
{
"results": [
{
"details": { "ticker": "O:SPXW260911C02800000", "contract_type": "call",
"expiration_date": "2026-09-11", "strike_price": 2800 },
"underlying_asset": { "ticker": "I:SPX" },
"open_interest": 0
}
],
"status": "OK"
}
The chain comes back in symbol order and the near-dated contracts roll off as they expire, so the particular contract you see first will not be the one above.
Then ask the reference endpoint for contract definitions, with the bare symbol:
curl -X GET "https://api.massive.com/v3/reference/options/contracts?underlying_ticker=SPX&limit=1&apiKey=YOUR_API_KEY"
Response
{
"results": [{ "ticker": "O:SPX260918C00200000" }],
"status": "OK"
}
Once you hold a contract ticker such as O:SPXW260915C07600000, every other options endpoint takes it directly, with no prefix rules to think about.
Which form of the symbol to use where
The two endpoint families differ, and neither answers the wrong form with an error: the reference one returns an empty list, and the snapshot returns contracts with no Greeks:
| Endpoint family | Underlying form | Example |
|---|---|---|
| Snapshot and chain | Prefixed. SPX returns the same contracts with an empty greeks object and no implied volatility | I:SPX |
| Reference contracts | Bare only. The prefixed form returns nothing | SPX |
| Trades, quotes, aggregates | The contract ticker itself | O:SPXW260915C07600000 |
Why index options need a different prefix
Index options need a different prefix because the underlying is not a security you can trade. SPX on its own is not a ticker Massive can price, so the index namespace uses I: to keep index values apart from equities, and the snapshot endpoints resolve the underlying by looking it up. The reference endpoints are indexing a text field on the contract instead, and the contract records the underlying as the bare root symbol, so they need it in that form.
The same reasoning is why an ETF option needs no prefix at all. SPY is a stock, so underlying_ticker=SPY works on both families, and that is often the simplest way to get index-like options exposure without the prefix rules.
If you see an error
"status": "OK" with an empty results array from /v3/reference/options/contracts is usually the prefixed form. Drop the I:. From the snapshot, an empty list is not the prefix, because the bare form returns the same contracts: look at your filters, or at whether the underlying has a chain at all.
Snapshot contracts that all have an empty greeks object and no implied_volatility are what the bare symbol returns. Ask for /v3/snapshot/options/I:SPX rather than /v3/snapshot/options/SPX.
{"status":"NOT_AUTHORIZED"} means your plan lacks Options. An Indices subscription covers index values and does not include options on those indices.
A contract ticker that returns no trades is usually a strike with no volume rather than missing data. Confirm with the chain snapshot, which reports open_interest.
