Docs/Market Structure API (GEX)
Market Structure API (GEX)
GET /api/v1/market-structure/:symbol reference: structural Gamma Exposure, intraday GEX, Gamma Flip, walls, Max Pain, IV context, session flow, and symbol metadata.
Open product page →
The Market Structure API returns a precomputed, symbol-level snapshot of full-chain dealer-positioning structure (GEX), open interest walls, Max Pain, volatility context, and five-minute session flow plus intraday GEX summaries.
GET https://www.optiondata.io/api/v1/market-structure/:symbol
Included with the realtime plan (trialing or active). Authenticate with a signed API key.
Authentication
Send your API key as:
Authorization: Bearer YOUR_API_KEY
YOUR_API_KEY may be a raw Stripe customer id (cus_...) or a portal-minted apikey_... token.
Path parameters
| Name | Required | Description |
|---|
symbol | Yes | Underlying option root (e.g. SPY, SPXW, AAPL). Uppercased server-side. |
Query parameters
| Name | Required | Description |
|---|
date | No | YYYY-MM-DD retained historical snapshot. Omit for the active/latest snapshot. |
Example
curl "https://www.optiondata.io/api/v1/market-structure/SPY" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://www.optiondata.io/api/v1/market-structure/SPY?date=2026-07-24" \
-H "Authorization: Bearer YOUR_API_KEY"
Response shape
Top-level:
| Field | Type | Description |
|---|
data.symbol | string | Exact option root requested |
data.symbol_meta | object | Underlying metadata and volatility context |
data.flow | object | Lightweight traded-flow overlay for the symbol |
data.intraday_gex | object | null | Latest full-chain summary GEX and spot |
data.structure | object | Full-chain GEX, OI, levels, strike-by-expiration aggregates |
meta.effective_date | string | Snapshot trading date (YYYY-MM-DD) |
meta.structure_as_of | string | UTC time when structure metrics were produced |
meta.flow_as_of | string | UTC time of the flow overlay |
meta.intraday_gex_as_of | string | null | UTC time of the intraday GEX summary |
symbol_meta highlights
| Field | Type | Description |
|---|
underlying_type | STOCK | ETF | INDEX | null | Underlying classification |
description | string | Company, fund, or index name |
open / high / low / close / last | number | Snapshot-date underlying prices |
iv30 | number | null | Interpolated 30-day ATM implied volatility (decimal) |
iv_rank_1y / iv_percentile_1y | number | null | One-year IV rank / percentile as 0–1 fractions |
skew_25d_30d | number | null | 30-day 25-delta put/call skew |
iv_term_slope_30_90 | number | null | 30-to-90-day IV term slope |
structure highlights
| Field | Type | Description |
|---|
spot | number | Underlying price used for exposure calculations |
call_oi / put_oi | number | All-scope open-interest contract totals |
call_gex / put_gex | number | All-scope dollar GEX for a 1% move; put GEX is signed negative |
scopes.all / zero_dte / weekly / monthly | object | null | Levels scoped by DTE bucket |
gamma_flip | number | null | Nearest repriced zero-net-GEX underlying level |
max_pain | number | null | Strike with lowest multiplier-adjusted aggregate payout |
call_gex_wall / put_gex_wall | number | null | Strongest call/put GEX strike on the corresponding side of spot |
call_oi_wall / put_oi_wall | number | null | Highest call/put OI strike on the corresponding side of spot |
expirations | array | Full-chain strike aggregates grouped by expiration |
flow highlights
| Field | Type | Description |
|---|
call_premium / put_premium | number | Session option premium by side (USD) |
bullish_dex / bearish_dex | number | Bullish and bearish delta-exposure flow totals |
trade_count | number | Option trades represented by the overlay |
traded_contract_count | number | Distinct contracts with trades |
intraday_gex highlights
| Field | Type | Description |
|---|
spot | number | Latest positive underlying price used for the summary |
call_gex | number | Full-chain positive call dollar GEX, including zero-trade contracts |
put_gex | number | Full-chain signed-negative put dollar GEX, including zero-trade contracts |
Semantics notes
- Dealer positioning is a model, not reported dealer inventory. Put GEX uses a documented dealer-short-put signing convention.
- Net GEX can be derived as
call_gex + put_gex (put already signed).
data.intraday_gex and meta.intraday_gex_as_of can refresh every five minutes during the regular session. Structural strike GEX, walls, Gamma Flip, Max Pain, OI, expirations, and meta.structure_as_of change only during structural builds.- Put/call OI ratio can be derived as
put_oi / call_oi when call_oi > 0.
- Prefer Market Structure for positioning dashboards; use the Option Chain API when you need filterable contract-level quotes and Greeks.
Errors
| Status | Meaning |
|---|
400 | Invalid symbol or date |
401 | Missing or invalid API key |
403 | No active/trialing realtime entitlement |
404 | Snapshot not found for symbol/date |
429 | Rate limited |
500 | Unexpected server error |
Related
