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

# Options Screener

> Discover and filter option contracts by underlying ticker with optional constraints on Greeks, implied volatility, days to expiry, strike price, and expiry date. Supports live and historical screening.

<Info>**Python function:** `screenOptions()`</Info>

| Specification      | Value                                                           |
| ------------------ | --------------------------------------------------------------- |
| Delivery Frequency | continuous                                                      |
| Data Frequency     | daily snapshot, real-time                                       |
| Reporting Lag      | Live: real-time; Historical: daily snapshots                    |
| Coverage           | 5,000+ U.S. equity options symbols, all strikes and expirations |
| Availability       | Free                                                            |

# Product Overview

## Overview

The Options Screener allows you to discover and filter option contracts for any underlying ticker. Given one or more underlying symbols, it returns all available option contracts with their Greeks, implied volatility, volume, and open interest — optionally filtered by contract type, days to expiry, strike range, expiry date range, and Greek/IV thresholds.

The screener supports two modes:

* **Historical:** Screen contracts as they existed on a specific past trading date.
* **Live:** Screen today's available contracts (falls back to the previous trading day if today's data is not yet published).

## Data Pipeline

### Historical Screening

Historical option chain data is sourced from archived daily snapshots:

* **Daily chain snapshots:** Each trading day, a snapshot of all active option contracts is captured with Greeks, IV, volume, and open interest.
* **Smoothed Greeks:** Greeks and implied volatilities come from the same Smooth Market Value (SMV) pipeline described in the **Options Greeks & Implied Volatility** reference — ensuring consistent, non-arbitrageable values.

### Live Screening

Live screening queries real-time option chain data:

* **Real-time chain:** The current option chain is fetched from the live market data feed, including real-time Greeks computed from the latest 1-minute snapshots.
* **Pagination:** For underlyings with large option chains (thousands of strikes × multiple expirations), results are paginated and assembled automatically.

## Coverage

* **Underlying symbols:** 5,000+ U.S. equities and ETFs with listed options.
* **Contract types:** Calls, puts, or both.
* **Expirations:** All standard and weekly expirations.
* **History:** Daily snapshots available for historical screening.

## Supported Modes

| Mode       | Trigger               | Behavior                                                                                    |
| ---------- | --------------------- | ------------------------------------------------------------------------------------------- |
| Historical | `trade_date` provided | Screens contracts for the given date.                                                       |
| Live       | `trade_date` omitted  | Uses today's date; falls back to previous trading day if today's data is not yet available. |

# Querying the Data

## Basic Usage

```python theme={null}
from scalarlib import screenOptions

# All AAPL options on a given date
contracts = screenOptions(tickers=['AAPL'], trade_date='2026-02-06')
aapl_df = contracts['AAPL']

# Live screening (today's contracts)
contracts = screenOptions(tickers=['NVDA'])

# Filtered: short-dated calls with delta and IV constraints
contracts = screenOptions(
    tickers=['AAPL', 'MSFT'],
    trade_date='2026-02-06',
    contract_type='call',
    days_to_expiry=(5, 30),
    delta_range=(0.2, 0.8),
    iv_range=(0.1, 0.5)
)

# Extract symbols for use in getOptionsQuotes
symbols = contracts['AAPL']['symbol'].tolist()
quotes = getOptionsQuotes(tickers=symbols, start='2026-02-01', end='2026-02-06')
```

## Parameters

| Parameter           | Type           | Required | Description                                                              |
| ------------------- | -------------- | -------- | ------------------------------------------------------------------------ |
| `tickers`           | list of str    | Yes      | Underlying ticker symbols (e.g., `['AAPL', 'NVDA']`).                    |
| `trade_date`        | str            | No       | Date to screen (`'YYYY-MM-DD'`). Default: today (live mode).             |
| `contract_type`     | str            | No       | `'call'`, `'put'`, or `None` for both. Default: `None`.                  |
| `days_to_expiry`    | tuple of float | No       | `(min, max)` days to expiry filter.                                      |
| `strike_range`      | tuple of float | No       | `(min, max)` strike price filter.                                        |
| `expiry_date_range` | tuple of str   | No       | `('YYYY-MM-DD', 'YYYY-MM-DD')` earliest and latest expiry.               |
| `delta_range`       | tuple of float | No       | `(min, max)` delta filter.                                               |
| `gamma_range`       | tuple of float | No       | `(min, max)` gamma filter.                                               |
| `theta_range`       | tuple of float | No       | `(min, max)` theta filter.                                               |
| `vega_range`        | tuple of float | No       | `(min, max)` vega filter.                                                |
| `iv_range`          | tuple of float | No       | `(min, max)` implied volatility filter (e.g., `(0.1, 0.5)` for 10%–50%). |

# Column Definitions

## Screen Options Schema

| Column           | Type    | Description                                                   |
| ---------------- | ------- | ------------------------------------------------------------- |
| `symbol`         | string  | Option symbol in OPRA format (e.g., `AAPL260211C00275000`).   |
| `ticker`         | string  | Underlying ticker (e.g., `AAPL`).                             |
| `contract_type`  | string  | `"call"` or `"put"`.                                          |
| `expiry_date`    | string  | Expiration date.                                              |
| `strike_price`   | float64 | Strike price.                                                 |
| `trade_date`     | string  | The screening date.                                           |
| `delta`          | float64 | Option delta (consistent across call/put at the same strike). |
| `gamma`          | float64 | Option gamma.                                                 |
| `theta`          | float64 | Option theta (daily time decay).                              |
| `vega`           | float64 | Option vega.                                                  |
| `implied_vol`    | float64 | Smoothed mid implied volatility.                              |
| `days_to_expiry` | float64 | Calendar days until expiration.                               |
| `volume`         | float64 | Daily trading volume.                                         |
| `open_interest`  | float64 | Open interest.                                                |

## Typical Workflow

The options screener is typically the first step in an options analysis workflow:

1. **Screen:** Use `screenOptions` to discover available contracts matching your criteria.
2. **Quote:** Pass the resulting symbols to `getOptionsQuotes` for detailed quote data with full Greeks.
3. **Analyze:** Use the quote data for pricing analysis, strategy construction, or risk management.