---
title: "ATM IV by tenor"
method: GET
path: "/options/iv/term-structure"
tags: ["Options"]
---

# ATM IV by tenor

`GET /options/iv/term-structure`

## Request

- Base URL: `https://docs.backquant.com/v2`
- URL: `https://docs.backquant.com/v2/options/iv/term-structure`
- Auth: API key in header `X-API-Key`

At-the-money implied volatility for each active expiration.

Filters:
* `exchanges` — comma-separated venue filter.
* `dte_max` — drop tenors with DTE > dte_max (focus on the front   of the curve).
* `historical_compare_days=N` — also include the constant-maturity   ATM IV from N days ago, sourced from the `iv_history` Postgres   table. Returned as a separate `historical` block under   `compare`. Different shape from the live curve — historical is   by DTE-bucket (7/14/30/60/90/180/365) since that's how the   worker stores it; the client can interpolate onto the live   tenor grid for visualisation.

## Query parameters

- `symbol` 'BTCUSDT' | 'ETHUSDT' | 'SOLUSDT' | 'HYPEUSDT': Trading symbol: BTCUSDT, ETHUSDT, SOLUSDT, or HYPEUSDT.
- `exchanges` string, nullable: Comma-separated venue filter
- `dte_max` integer, nullable: Drop tenors with DTE greater than this value.
- `historical_compare_days` integer, nullable: Days back for historical CMT IV comparison (1–365).

## Headers

- `X-API-Key` string, nullable

## Response `200`

Successful Response

- IvTermStructureResponse
  - `success` true
  - `data` IvTermStructureData, required: The shape varies slightly by collector version — we document the fields we know about and leave room for additional ones via extra=allow.
    - `expiries` string[], nullable
    - `dtes` integer[], nullable
    - `days_to_expiry` integer[], nullable
    - `atm_iv` number[], nullable
    - `ts` string, nullable
    - `spot_price` number, nullable
    - `filtered_dte_window` object, nullable
    - `compare` IvTermCompare
      - `days_ago` integer, required
      - `target_date` string, required
      - `historical` IvTermHistoricalBucket[], required
        - `dte_bucket` integer, required
        - `atm_iv` number, nullable
        - `ts` string, required
      - `shape` string, nullable
      - `matched_count` integer, nullable
      - `available` boolean, nullable
      - `reason` string, 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)