Option Chain API

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 generated apikey_... token. If omitted, the signed-in session is used.
• date: YYYY-MM-DD. Defaults to the latest available trading session. Check meta.trading_date for the date returned; an explicit date is never substituted with another session. An impossible calendar date (for example 2026-02-30) returns 400; a date with no stored session (weekend, holiday, future, or outside retention) returns 404.
• expiration_date: YYYY-MM-DD; must be a real calendar date.
• put_call: CALL or PUT.
• strike: exact positive strike price; cannot be combined with strike_min or strike_max.
• strike_min, strike_max: inclusive strike bounds; either bound may be used alone.

Strike bounds must be positive, and strike_min must not exceed strike_max.

Source and semantics

Responses include the complete available chain inventory matching your filters, including contracts with no trades. During U.S. market hours, newer trade-derived values are normally incorporated about every 90 seconds: quotes, Greeks, IV, volume, open interest, and last price. Contracts without a newer trade retain their chain values until a newer chain snapshot is available. This cadence is an expected update interval, not a guarantee that every contract's quotes or Greeks refresh on each interval. Prices are in USD; Greeks/IV are decimals (e.g. IV 0.22 = 22%).

Before a new session's chain is available, requests without date can return the previous session. Always check meta.trading_date instead of assuming that the latest available session is today's date.

If intraday updates are temporarily unavailable, a response can retain earlier chain values. Check both meta.trading_date and meta.as_of before treating a response as current. An explicit historical date selects that session's stored chain; it does not replay the chain at a particular time within the session.

Response — core fields (always returned)

{ "data": [ ... ], "meta": { "trading_date": "YYYY-MM-DD", "as_of": "..." } }

Numeric fields are null when the value is unavailable for a contract. bid and ask come from the quote attached to the contract's latest trade in the meta.trading_date session, so a contract that last traded early in the day carries that earlier quote. bid and ask are null together, and implied_volatility and the Greeks are null together. A single 0, such as a bid of 0 with a positive ask, is a real value. 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 so that 64-bit values stay exact. 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

Errors

All errors return { "error": { "code": "...", "message": "..." } } with an HTTP status. A chain that exists but has no contract matching your filters is not an error: it returns 200 with an empty data array.

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 customer was resolved, but 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: How often should I poll?
A: The latest session updates about every 90 seconds during market hours, so poll every one to two minutes at most and compare meta.as_of before doing new work. A contract without a recent trade keeps its last chain value, so an update does not refresh every Greek. Faster polling returns the same data and may hit rate limits.

Q: Rate and size limits?
A: Keep sustained traffic at one request per second per customer and short bursts to 10 requests or fewer, for example when fetching several expirations. Current throttling is best-effort; this is client usage guidance, not a guaranteed global quota. HTTP 429 includes a Retry-After header; wait that long before retrying. See API rate limits for the complete policy.

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 individual trades, use Historical SQL: paid access covers the past 15 days (≥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 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: WebSocket full chain?
A: No. Chains are REST only; WebSocket is trades/flow.