--- title: "Filtered options chain" method: GET path: "/options/chain" tags: ["Options"] --- # Filtered options chain `GET /options/chain` ## Request - Base URL: `https://docs.backquant.com/v2` - URL: `https://docs.backquant.com/v2/options/chain` - Auth: API key in header `X-API-Key` Per-contract data (greeks, OI, IV, bid/ask) plus aggregate stats. Filters supported: * `expiries` — CSV of tokens (e.g. `28MAR25,25APR25`). * `dte_min` / `dte_max` — days-to-expiry bounds. * `oi_min` / `oi_max` — open interest bounds. * `delta_min` / `delta_max` — applied to |delta| (0..1). * `strike_min` / `strike_max` — absolute strike bounds. * `moneyness_min` / `moneyness_max` — strike / spot ratio bounds, e.g. `0.9..1.1` keeps strikes within ±10% of spot. Useful for cross-symbol screens since it normalises the strike grid. * `option_type` — `call`, `put`, or `both`. Two layers of projection: * `fields` (top-level): comma-sep subset of `aggregates,available_expiries,contracts` — drops whole sections of the response, e.g. `?fields=contracts` to skip aggregates. * `include` (per-contract): comma-sep subset of `bid_ask,gex,greeks,iv,oi,volume` — keeps only the named sub-sections of each contract dict. Core identity fields (`strike,expiry,dte,type`) are always present. Default is every section, matching v1 shape. Payload is capped at `?max_contracts=` (default 2000, hard ceiling 5000). On overflow the response is truncated to the closest-to-spot subset and `truncated=true` is set with `total_matching_count` so the client knows to narrow the filter. Response is cached for 30s keyed by the exact filter combination, so repeated calls with identical filters are sub-millisecond. ## Query parameters - `symbol` 'BTCUSDT' | 'ETHUSDT' | 'SOLUSDT' | 'HYPEUSDT': Trading symbol: BTCUSDT, ETHUSDT, SOLUSDT, or HYPEUSDT. - `expiries` string, nullable: CSV of expiry tokens (e.g. 28MAR25,25APR25) - `dte_min` integer, nullable: Inclusive lower bound on days-to-expiry. - `dte_max` integer, nullable: Inclusive upper bound on days-to-expiry. - `oi_min` number, nullable: Minimum open interest per contract. - `oi_max` number, nullable: Maximum open interest per contract. - `delta_min` number, nullable: Minimum |delta| (0..1). - `delta_max` number, nullable: Maximum |delta| (0..1). - `strike_min` number, nullable: Minimum strike price (absolute). - `strike_max` number, nullable: Maximum strike price (absolute). - `moneyness_min` number, nullable: Strike/spot lower bound (e.g. `0.9` for ATM-10%). - `moneyness_max` number, nullable: Strike/spot upper bound (e.g. `1.1` for ATM+10%). - `option_type` 'call' | 'put' | 'both': Filter to call, put, or both contract types. - `max_contracts` integer: Cap on the number of contracts returned (default 2000, hard ceiling 5000). When more contracts match the filters, the response is truncated to the closest-to-spot subset and `truncated=true` is set with `total_matching_count` so the client knows to narrow the filter. - `fields` string, nullable: Top-level projection: aggregates,available_expiries,contracts - `include` string, nullable: Per-contract projection: bid_ask,gex,greeks,iv,oi,volume. Default is all sections. ## Headers - `X-API-Key` string, nullable ## Response `200` Successful Response - ChainResponse - `success` true - `data` ChainData, required - `contracts` OptionContract[], nullable - `strike` number, nullable - `expiry` string, nullable - `dte` integer, nullable - `type` 'call' | 'put', nullable - `oi` number, nullable - `iv` number, nullable - `mark` number, nullable - `bid` number, nullable - `ask` number, nullable - `volume` number, nullable - `notional_volume` number, nullable - `trade_count` integer, nullable - `delta` number, nullable - `gamma` number, nullable - `theta` number, nullable - `vega` number, nullable - `vanna` number, nullable - `charm` number, nullable - `gex` number, nullable - `aggregates` ChainAggregates - `net_gex` number, required - `call_gex` number, required - `put_gex` number, required - `total_oi` number, required - `call_oi` number, required - `put_oi` number, required - `pcr` number, nullable - `atm_iv` number, nullable - `contract_count` integer, required - `available_expiries` string[], nullable - `truncated` boolean, nullable: True when the matching set exceeded `max_contracts`. - `total_matching_count` integer, nullable: Total contracts matching the filters (pre-truncation). - `max_contracts` integer, nullable - `meta` V2Meta, required: The meta block returned alongside every v2 response. Every field after `version`/`timestamp` is optional because endpoints attach different combinations — e.g. `/v2/status` skips `symbol`, the chain endpoint sets `extra.filter_hash`, etc. Listing them here means SDKs get a typed accessor for each instead of a generic `meta: dict`. - `version` '2.0', required: API version tag. - `timestamp` string, required: ISO 8601 wall-clock when the response was built. - `request_id` string, nullable: X-Request-ID for tracing across logs / Sentry. - `symbol` string, nullable: Symbol the response is about, if applicable. - `spot_price` number, nullable: Current spot price for the symbol. - `computed_at` string, nullable: ISO 8601 of when the underlying cache value was last written. - `freshness_seconds` number, nullable: `now - computed_at` in seconds; useful for staleness alarms. - `source` string[], nullable: Upstream venue list the data flowed through. - `exchanges_filtered` string[], nullable: Echo of the `?exchanges=` filter when one was applied. - `rate_limit` object, nullable: `{limit, remaining, reset}` echo of the rate-limit headers. - `extra` object, nullable: Open dict for endpoint-specific metadata (filter_hash, etc.). ## Other responses - `401`: Invalid or missing API key - `404`: Not Found - `422`: Validation error on query parameters - `429`: Rate limit exceeded --- [API](https://skmtc.dev/backquant/apis/backquant-api-v2.md) · [All operations](https://skmtc.dev/backquant/apis/backquant-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/backquant/apis/backquant-api-v2/revisions/3c1c96b3cc24?raw)