> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polaris.supply/llms.txt
> Use this file to discover all available pages before exploring further.

# Option Tickers

> Query normalized option ticker events for a whole option chain or one exact contract.

Use the option ticker method to read venue-published prices, implied volatility,
open interest, and Greeks for option contracts. Each event identifies both the
normalized underlying market and the exact venue-native contract.

## Option identity

Option data uses three separate identifiers:

| Field        | Meaning               | Example               |
| ------------ | --------------------- | --------------------- |
| `source`     | Recorder or venue     | `deribit`             |
| `market`     | Normalized underlying | `BTC`                 |
| `instrument` | Exact option contract | `BTC-29MAR24-50000-C` |

Pass the underlying as `market`. Omit the query's `instrument` to read every
contract in that option chain, or provide one exact instrument to filter the
results. Empty instrument filters are invalid, and every returned
`option_ticker` event has a non-empty `instrument`.

## Methods

| SDK        | Method                              | Returns                                                  |
| ---------- | ----------------------------------- | -------------------------------------------------------- |
| Python     | `option_tickers(...)`               | Single-pass iterator of typed option ticker dictionaries |
| Rust       | `option_tickers(OptionTickerQuery)` | `HistoricalStream<OptionTickerEvent>`                    |
| TypeScript | `optionTickers(options)`            | `Promise<OptionTickerEvent[]>`                           |

### Python signature

```python theme={null}
option_tickers(source, market, instrument=None, from_=None, to=None, allow_gaps=False)
```

### Parameters

| Parameter        | Type                               | Required | Notes                                                                                  |
| ---------------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `source`         | string                             | Yes      | Option data source ID                                                                  |
| `market`         | string                             | Yes      | Normalized underlying, such as `BTC`                                                   |
| `instrument`     | string                             | No       | Exact venue-native contract; omit for the whole chain                                  |
| `from_` / `from` | string, datetime, date, or integer | No       | Inclusive start time                                                                   |
| `to`             | string, datetime, date, or integer | No       | Exclusive end time                                                                     |
| `allow_gaps`     | boolean                            | No       | Python and Rust only; return covered rows and warn instead of failing on coverage gaps |

## Query a whole chain

Omit `instrument` to return every contract stored under the underlying market.

<CodeGroup>
  ```python Python theme={null}
  from itertools import islice

  from polaris_data import PolarisClient

  with PolarisClient() as client:
      tickers = client.option_tickers(
          source="deribit",
          market="BTC",
      )
      print(list(islice(tickers, 2)))
  ```

  ```rust Rust theme={null}
  use futures_util::StreamExt;
  use polaris_data::{OptionTickerQuery, PolarisClient};

  #[tokio::main]
  async fn main() -> Result<(), Box<dyn std::error::Error>> {
      let client = PolarisClient::builder().build()?;
      let mut tickers = client
          .option_tickers(OptionTickerQuery {
              source: "deribit".into(),
              market: "BTC".into(),
              instrument: None,
              from: None,
              to: None,
              allow_gaps: false,
          })
          .await?;

      while let Some(ticker) = tickers.next().await {
          println!("{:?}", ticker?);
      }
      Ok(())
  }
  ```

  ```typescript TypeScript theme={null}
  import { PolarisClient } from "polaris-data";

  await using client = new PolarisClient();

  const tickers = await client.optionTickers({
    source: "deribit",
    market: "BTC",
  });

  console.log(tickers.slice(0, 2));
  ```
</CodeGroup>

## Filter one contract

Set `instrument` when you only need one exact contract:

<CodeGroup>
  ```python Python theme={null}
  tickers = client.option_tickers(
      source="deribit",
      market="BTC",
      instrument="BTC-29MAR24-50000-C",
  )
  ```

  ```rust Rust theme={null}
  let query = OptionTickerQuery {
      source: "deribit".into(),
      market: "BTC".into(),
      instrument: Some("BTC-29MAR24-50000-C".into()),
      from: None,
      to: None,
      allow_gaps: false,
  };
  let tickers = client.option_tickers(query).await?;
  ```

  ```typescript TypeScript theme={null}
  const tickers = await client.optionTickers({
    source: "deribit",
    market: "BTC",
    instrument: "BTC-29MAR24-50000-C",
  });
  ```
</CodeGroup>

Filtering is exact after surrounding whitespace is removed from the query. The
SDK does not substitute `market` when an event is missing its instrument;
malformed option ticker rows fail decoding.

## Event shape

```json theme={null}
{
  "collector_timestamp": 1704067200100,
  "collector_sequence": 1,
  "exchange_timestamp": 1704067199000,
  "exchange_sequence": null,
  "source": "deribit",
  "market": "BTC",
  "instrument": "BTC-29MAR24-50000-C",
  "type": "option_ticker",
  "data": {
    "mark_price": "0.0175",
    "bid_price": "0.0170",
    "ask_price": "0.0180",
    "mark_iv": "0.8359",
    "open_interest": "42",
    "greeks": {
      "delta": "0.431",
      "gamma": "0.00008"
    }
  }
}
```

Ticker payloads are partial venue-published updates. A missing field means the
venue did not publish that value in the event; it does not mean zero.

### Price and size fields

* `mark_price`, `last_price`, `index_price`, `underlying_price`, `forward_price`
* `bid_price`, `bid_size`, `ask_price`, `ask_size`
* `open_interest`, `volume_24h`, `turnover_24h`

### Volatility and Greeks

* `mark_iv`, `bid_iv`, and `ask_iv` are annualized implied volatilities expressed as decimal strings.
* `greeks.delta`, `greeks.gamma`, `greeks.vega`, `greeks.theta`, and `greeks.rho` retain the venue's convention as decimal strings.

### Units

* `premium_currency` identifies the premium denomination when the venue provides it.
* `quantity_unit` identifies the contract quantity unit when the venue provides it.

All numeric ticker payload values use decimal strings so standardization does
not lose venue precision.

## Realtime filtering

Realtime streams use the same identity split. Pass the underlying in `markets`
and optionally add one exact `instrument`. Omitting it subscribes to the whole
chain.

<CodeGroup>
  ```python Python theme={null}
  with client.stream(
      source="deribit",
      markets=["BTC"],
      instrument="BTC-29MAR24-50000-C",
  ) as events:
      for event in events:
          print(event)
  ```

  ```rust Rust theme={null}
  use polaris_data::StreamQuery;

  let events = client.stream(StreamQuery {
      source: "deribit".into(),
      markets: vec!["BTC".into()],
      instrument: Some("BTC-29MAR24-50000-C".into()),
      include_buffer: false,
      materialize_orderbooks: true,
  }).await?;
  ```

  ```typescript TypeScript theme={null}
  const events = client.stream({
    source: "deribit",
    markets: ["BTC"],
    instrument: "BTC-29MAR24-50000-C",
  });
  ```
</CodeGroup>

## Related documentation

* [Options guide](/guides/options) for market discovery and chain-snapshot analysis
* [Event envelope](/concepts/event-envelope) for shared identity and timestamp fields
* [Events](/schemas/events) for mixed standardized event streams
* [Market coverage](/markets/market-coverage) for available datasets
* [Snapshots](/reference/snapshots) for snapshot-first historical reads