# Option Chain Quickstart

> Request the latest OptionData option chain for one underlying, inspect response freshness, and narrow chains that exceed response guardrails.

The Option Chain API returns per-contract chain rows for one underlying. Omit `date` to use the latest available trading session.

## 1. Request a chain

Store your API key in `OPTIONDATA_API_KEY`, then run:

```bash
curl -X POST https://www.optiondata.io/api/option-chain \
  -H "Authorization: Bearer $OPTIONDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "put_call": "CALL"
  }'
```

The response contains:

- `data`: per-contract rows such as strike, expiration, bid/ask, open interest, IV, and Greeks.
- `meta.trading_date`: the trading session returned.
- `meta.as_of`: the latest update represented in the response, or `null` when unavailable.

![Annotated OptionData option-chain page showing the REST endpoint and full option-chain documentation link](/docs/option-chain-quickstart/option-chain-page-annotated.png)

*The overview card distinguishes one-request full chains from the latest-or-historical session mode.*

## 2. Narrow a large chain

If the request returns HTTP `422`, narrow it with one or more supported filters:

```json
{
  "symbol": "AAPL",
  "expiration_date": "YYYY-MM-DD",
  "put_call": "CALL",
  "strike_min": 150,
  "strike_max": 250
}
```

Use an expiration date that exists in the current chain. The endpoint rejects over-broad requests instead of silently returning a partial chain.

## 3. Choose a polling interval

- Broad or full-chain workflows: approximately every five minutes.
- Narrow symbol/expiry/strike workflows: approximately every one to two minutes.
- Honor HTTP `429` and its `Retry-After` header.

Faster polling rarely improves a chain workflow and can exhaust the per-key rate limit.

## 4. Understand access errors

- `401`: missing or invalid key.
- `403`: recognized customer without active/trialing entitlement.
- `422`: request too broad.
- `504`: query timed out; narrow the filters.

The Option Chain endpoint returns chain state, not the live trade stream. Use [Realtime WebSocket Quickstart](/docs/realtime-websocket-quickstart) for trades and flow.

See [Option Chain API](/docs/option-chain-api) for the complete request and response contract.