Market Structure API (GEX)

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

Query parameters

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=YYYY-MM-DD" \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace YYYY-MM-DD with a retained trading date. A weekend, holiday, future date, or session outside retention can return 404.

Response shape

Top-level:

Symbol metadata

Volatility values are annualized decimals where applicable (0.22 means 22%); IV rank and percentile are 0–1 fractions. Nullable fields are null when unavailable. The optional realized-volatility fields may also be absent on older snapshots.

structure highlights

Days to expiration are calendar days measured from meta.effective_date: all includes every unexpired expiration, zero_dte is 0 days, weekly is 1–7 days, and monthly is 8–31 days. These are day ranges, not exchange expiration-series labels. A scope with no applicable contracts is null.

Each expirations entry contains expiration_date (YYYY-MM-DD) and a strikes array. Each strike contains numeric strike, call_oi, put_oi, call_gex, and put_gex; put GEX is signed negative. OI totals are contract counts and GEX is in USD for a 1% underlying move.

structure.scopes.<scope> levels

Levels are only inside a scope, for example data.structure.scopes.all.gamma_flip. structure has no top-level gamma_flip, max_pain, or wall fields.

flow highlights

intraday_gex highlights

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).
• Session flow and data.intraday_gex normally update about every five minutes during the regular session. Use meta.flow_as_of and meta.intraday_gex_as_of separately from meta.structure_as_of; this cadence does not promise fresh values for every symbol on every interval.
• Structural strike GEX, walls, Gamma Flip, Max Pain, OI, and expiration aggregates update when a newer full-chain structural snapshot becomes available. They do not follow each trade update in the Option Chain API.
• data.intraday_gex is null when no summary is available for the symbol. Its timestamp describes the summary update across the response's session, not a per-contract observation time. A zero flow total alone is not a completeness indicator.
• Structural snapshots include unexpired supported standard contracts, including contracts with no trades. A root without supported structure data can return 404 even when the Option Chain API has contract rows for it.
• 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

Errors return { "error": { "code": "...", "message": "..." } }. A 403 (SUBSCRIPTION_REQUIRED) also carries reason and billing_url inside error:

{
  "error": {
    "code": "SUBSCRIPTION_REQUIRED",
    "message": "An active or trialing subscription is required.",
    "reason": "NO_ACTIVE_SUBSCRIPTION",
    "billing_url": "/billing"
  }
}

reason is always NO_ACTIVE_SUBSCRIPTION: the API key is valid, but its account has no active or trialing Pro subscription. A Pro subscription whose renewal payment failed more than 7 days into the unpaid billing period gets the same response until the invoice is paid. billing_url is the path on https://www.optiondata.io where the account owner can restore Pro access. Do not retry until access is restored.

FAQ

Q: Rate limits and access?
A: Requires trialing or active Pro + API key. The current default is about 60 requests / 60 seconds per customer on this endpoint, for trial and paid users, enforced on a best-effort basis. HTTP 429 includes Retry-After.

Planned, not yet active: trial 30/minute and 1,200/hour; paid Pro 60/minute and 3,600/hour. Once enabled, both limits apply per customer across their keys and IPs; reaching either triggers rate limiting. No effective date has been announced. Enterprise limits are contract-specific. See API rate limits for the complete policy. Subscription access remains the same as Option Chain and Historical SQL.

Q: Freshness?
A: Structural levels update on builds (structure_as_of). Some intraday GEX fields can refresh about every five minutes in session—use response meta timestamps.

Q: History range?
A: Dated snapshots cover recent retained trading sessions; availability varies by date and option root, and older sessions age out over time. Request the required date explicitly and handle 404 when it is unavailable. A dated snapshot is session-level data, not an intraday replay. For individual trades, Historical SQL covers the past 15 days on paid plans.

Q: Free trial / extension?
A: Complete qualification, then explicitly activate the 14-day Pro trial when you are ready. Eligible trial users can receive 50% off for life with a promotion code from Sales; contact Sales for the code, then enter it on Billing before the trial ends. Trials are not auto-extended.

Q: Market Structure vs Option Chain?
A: Structure for GEX/walls/max pain dashboards; Option Chain for filterable contract quotes/Greeks.

Related

• Product page: /market_structure
• Option chain API: /docs/option-chain-api/
• Realtime flow: /docs/realtime-option-trades-api/