Options {ep.name}
{ep.summary}
{ep.description}
Authentication
Every request must include your personal API key. Three transports are supported (in order of preference):
x-api-keyrequest header — recommended for production. Keeps the key out of URLs and access logs.Authorization: Bearer <key>header — for clients that already speak Bearer auth.?apiKey=…query parameter — convenient for browsers, curl, and quick testing (the examples below use this). Note that this puts the key in server access logs and browser history.
Create, rotate, and revoke keys from the{" "} onNavigate && onNavigate("keys")} >API Keys{" "}page.
Supported underlyings
Market-Options serves options on a curated set of US tickers — the
names that drive the bulk of US options volume. A request for any
other ticker returns unsupported_underlying (HTTP 403).
Programmatic clients can fetch the live list from{" "}
GET /api/v1/underlyings (no auth required).
The list is maintained by Market-Options admins and can grow over time. Need a ticker that isn't here? Email{" "} support with the ticker and we'll consider adding it.
Filter your chain — narrow the response, lower the cost
The chain endpoint accepts a long list of filters that narrow the response server-side before it crosses the network. Use them always — unfiltered chains can return tens of thousands of contracts. Because chain billing is per contract, every filter you add directly reduces the credits you spend.
| Request | Approximate rows returned |
|---|---|
/options/chain?underlying=SPY |
~22,000 — every strike × every expiration. Don't. |
/options/chain?underlying=SPY&expiration=2026-06-19 |
~600 — one expiration, all strikes. |
/options/chain?underlying=SPY&dte=30&range=atm&strikeLimit=20 |
~20 — ATM strikes around 30 DTE. The sweet spot for most strategies. |
/options/chain?underlying=SPY&dte=30&side=call&minOpenInterest=1000&minVolume=100 |
~30 — liquid calls only at 30 DTE. |
Full filter list per endpoint is in the table below. Useful combinations:
dte + range=atm + strikeLimit — research / scanning ATM,
minOpenInterest + minVolume — liquid contracts only,
maxBidAskSpread — tradable spreads only,
delta=.30-.60 — directional bets,
weekly=true — short-dated only,
strike=400-410 — range,
strike=>=400 — comparison.
Data delay
Market-Options serves delayed options data. The delay per endpoint reflects how quickly the underlying data actually changes — quotes move every second, expiration lists are stable for the whole day:
/expirations— up to 10 minutes (expirations don't move intraday)./strikes— up to 10 minutes (strike sets rarely change intraday)./chain— up to 45 seconds./quotes— up to 10 seconds./lookup— up to 24 hours (symbol resolution is stable).
If your strategy depends on sub-second quotes, this product is not the right fit — try one of the big providers direct.
Credit billing
Every successful call costs credits. Most endpoints cost a flat 1 credit; the chain endpoint can cost more when it returns many contracts with quote columns.
/expirations,/strikes,/lookup,/quotes— always 1 credit./chainwithout quote columns (bid,ask,mid,last) — 1 credit, regardless of contract count./chainwith quote columns — 1 credit per contract returned. Filters (strikeLimit,dte,side,strike,delta,range) directly reduce the credit cost.- Failures (4xx, 5xx) are not billed.
Every response carries an{" "}
X-Credits-Used{" "}
header with the actual cost of that call. Use it to verify cost during
development and to monitor quota burn in production.
Query parameters
| Name | Type | Description |
|---|---|---|
|
{p.name}
{p.req ? "required" : "optional"}
|
{p.type} | {p.desc} |
Response
On success the gateway returns a JSON object with a status field s set
to "ok" alongside the data. The exact example below is what your client
receives. Timestamps are Unix epoch seconds.
Response fields
| Field | Type | Description |
|---|---|---|
{r[0]} |
{r[1]} | {r[2]} |
Errors
Errors return a JSON body with a stable code, a human message,
and an actionable hint. The gateway emits these:
| Code | Status | When |
|---|---|---|
missing_api_key |
401 | No API key was provided on the request. |
invalid_api_key |
401 | The API key is unknown or has been revoked. |
missing_parameter |
400 | A required query parameter for this endpoint was not provided. |
unknown_parameter |
400 | A parameter was sent that this endpoint does not accept (likely a typo). |
invalid_parameter |
400 | A parameter value failed type / range / format validation. |
invalid_path_symbol |
400 | The symbol in the URL path is not a valid ticker (or OSI symbol for /quotes). |
unsupported_endpoint |
404 | The endpoint name in the path is not one of the five supported endpoints. |
unsupported_underlying |
403 | The requested underlying is not in the curated allowlist. See /api/v1/underlyings for the live list. |
burst_limited |
429 | Per-minute credit limit reached. Free: 60/min. Pro: 10,000/min. The counter resets each minute. |
rate_limited |
429 | You exceeded your daily credit quota (Free tier: 1,000/day). Pro has no daily ceiling. A Retry-After header is included; quota resets at 00:00 UTC. |
data_unavailable |
502 | The requested data could not be retrieved from upstream. Retry shortly. |
momentarily_unavailable |
503 | Data is being refreshed for this query. Retry in a moment. |