Docs/Option Chain API
API referenceOption Chain API
POST /api/option-chain reference: full U.S. option chains with strikes, expirations, bid/ask, OI, IV, and Greeks.
On this page
Beta. This API is in beta testing. The request and response schema (fields, units, and semantics) may change.
The Option Chain API exposes per-contract chain rows for an underlying, for a given trading date:
POST https://www.optiondata.io/api/option-chain
It is included with the realtime plan — both trialing and active realtime subscriptions get full access.
Authentication
Send Authorization: Bearer YOUR_API_KEY for API clients. The header takes precedence over the legacy body api_key; malformed authorization is rejected. If neither is supplied, the portal can use the signed-in session. Live access requires an active or trialing Pro subscription.
Request
JSON and form (application/x-www-form-urlencoded / multipart/form-data) bodies are supported. Field names are snake_case.
Required:
symbol: one underlying ticker (uppercased by the server; 1–16 chars).
Optional:
api_key:cus_...(raw Stripe customer id) or a generatedapikey_...token. If omitted, the signed-in session is used.date:YYYY-MM-DD. If omitted, the latest available date inmv_contract_rank_flowis used.expiration_date:YYYY-MM-DD.put_call:CALLorPUT.strike: exact strike price.strike_min,strike_max: inclusive strike bounds; either bound may be used alone.
Source and semantics
Reads mv_contract_rank_flow, a per-contract-per-day materialized mart, with aggregate-state merge functions grouped by option_symbol for the requested date. Several fields are derived in the query (see the Response tables). Prices are in USD; Greeks/IV are decimals (e.g. IV 0.22 = 22%).
Response — core fields (always returned)
{ "data": [ ... ], "meta": { "trading_date": "YYYY-MM-DD", "as_of": "..." } }
| Field | Type | Notes |
|---|---|---|
symbol | string | Underlying ticker |
option_symbol | string | OCC option symbol |
put_call | CALL | PUT | |
strike | number | null | Strike price |
expiration_date | string | null | YYYY-MM-DD |
bid | number | null | Best bid |
ask | number | null | Best ask |
last_price | number | null | Latest trade price |
open_interest | integer string | null | JSON decimal string from ClickHouse Int64 |
open_interest_change | integer string | null | open_interest − prior-day OI; null when prior-day OI is unavailable |
volume | integer string | null | Daily volume as a JSON decimal string |
implied_volatility | number | null | Decimal |
delta / gamma / theta / vega | number | null | Greeks (decimal) |
Numeric fields are null when the value is unavailable for a contract. This endpoint returns chain fields only; use the realtime WebSocket for flow fields such as premium, size, and trade count.
open_interest, open_interest_change, and volume are serialized as decimal strings to preserve the existing ClickHouse Int64 wire behavior. Parse them with an integer type that is safe in your language; do not assume every 64-bit integer can be represented exactly by a JavaScript number.
Response — meta
| Field | Notes |
|---|---|
trading_date | Trading session returned, in YYYY-MM-DD format |
as_of | Most recent data update represented in the response, as a UTC ISO timestamp or null |
Errors
All errors return { "error": { "code": "...", "message": "..." } } with an HTTP status:
| Status | Meaning |
|---|---|
400 | Invalid body or failed request validation |
401 | Could not resolve a customer (missing/invalid api_key and no session) |
403 | Resolved, but no active/trialing realtime subscription |
422 | Request was too broad for the response guardrail |
429 | Rate limited; honor Retry-After |
504 | Query timed out |
500 | Unexpected server error |
FAQ
Q: How often should I poll?
A: Broad/full-chain: about every 5 minutes. Narrow symbol/expiry/strike: every 1–2 minutes. Faster polling rarely helps and may hit rate limits.
Q: Rate and size limits?
A: 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 20/minute and 600/hour; paid Pro 60/minute and 3,000/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.
Response-size behavior is unchanged: over-broad chains are rejected instead of returning partial results—use expiration, put/call, or strike filters.
Q: History range and delay?
A: Chain sessions from about 2026-02-20 forward (grows each trading day). Use as_of for freshness. For trade ticks back to 2025-02-18, use Historical SQL (≥15-minute delay).
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 the first year, with next steps shown inside the authenticated portal. Trials are not auto-extended.
Q: WebSocket full chain?
A: No. Chains are REST only; WebSocket is trades/flow.
Ask ChatGPT or Claude Code
Copy this prompt, paste it into ChatGPT, Claude, Claude Code, Cursor, or Codex, then add your question. It tells the model to read our public docs first — no API key needed for that step.
You are helping me use OptionData (https://www.optiondata.io/), an OPRA-licensed U.S. equity options data API.
Before answering, fetch these public files (no login required) and treat them as the source of truth:
- https://www.optiondata.io/llms.txt — short product map (same content as https://www.optiondata.io/llm.txt)
- https://www.optiondata.io/llms-full.txt — full API reference
- https://www.optiondata.io/openapi.json — HTTP OpenAPI
Do not invent endpoints, fields, tables, or limits. Prefer `Authorization: Bearer apikey_…` for HTTP APIs. Realtime uses `wss://ws.optiondata.io` with a `token` query parameter.
Products:
- Realtime trades WebSocket: wss://ws.optiondata.io
- Historical SQL: POST https://www.optiondata.io/api/historical/sql
- Option chain: POST https://www.optiondata.io/api/option-chain
- Market structure: GET https://www.optiondata.io/api/v1/market-structure/{symbol}
I am asking about: Option Chain API
- Markdown: https://www.optiondata.io/md/option-chain-api/
- HTML docs: https://www.optiondata.io/docs/option-chain-api/
My question: