# Contracts

Look up options contracts in bulk or fetch a single contract by its options ticker. Results include contract type, exercise style, expiration, strike, and related reference fields.

> **Quick definition: options contracts are the point-in-time reference records that tell your application which OCC tickers existed, what they represented, and how they should be joined to chains, quotes, trades, and aggregates.**

New to the contract fields? Start with [How Options Work](/how-options-work), [Strike Price Explained](/strike-price-explained), and [Option Expiration Explained](/option-expiration-explained).

<div data-try-url="/v1/options/contracts/?underlying_ticker=NFLX&limit=10"></div>

Related guides: [OCC Option Symbol Format Explained](/occ-option-symbol-format) and [Option Expiration Date Filters](/option-expiration-date-filter-api)

## Why contracts matter

Contracts are the universe boundary for options workflows. A chain snapshot tells you what the market looks like now, but the contracts endpoint tells you which instruments match a ticker, expiration, strike, contract type, and historical `as_of` date. That difference matters when a backtest or scanner must avoid choosing contracts that were not listed yet.

Use contracts before you request quote or trade history when the workflow starts from an underlying symbol rather than a known OCC ticker. Store the returned contract ticker with every downstream quote, trade, aggregate, snapshot, and fill decision. That makes the research artifact debuggable because every price series can be traced back to the exact listed instrument.

| Workflow need | Contract endpoint role | Follow-up endpoint |
| --- | --- | --- |
| Rebuild a historical universe | Request `underlying_ticker`, `expiration_date`, and `as_of` so the run sees the listed contracts for that research date. | [Quotes](/docs/quotes) or [Trades](/docs/trades) with explicit timestamp windows. |
| Build an expiration picker | Filter contracts or fetch listed expirations, then show only available dates and strikes. | [Option chain snapshot](/docs/option-chain) for the selected date. |
| Validate a saved OCC ticker | Fetch the detail endpoint and confirm strike, expiration, contract type, and deliverables. | [Contract snapshot](/docs/option-contract-snapshot) for current state. |
| Handle corporate actions | Inspect `additional_underlyings`, `shares_per_contract`, and correction fields before sizing. | Store adjusted deliverables in the strategy artifact. |

## Failure modes

The most common error is treating today's contract list as if it existed on a prior research date. For backtests, pass `as_of` and record it. The second common error is assuming every valid stock ticker has the expiration or strike your strategy wants. Fetch contracts or expirations first, then reject empty universes explicitly instead of silently selecting the nearest current contract.

For current snapshots, a contract can return 404 after it expires or leaves the current snapshot feed. That does not mean historical reference data is gone. Use the contract detail endpoint with `as_of` for reference, then historical quotes, trades, or aggregates for the market state you need.

## Endpoints

```
GET /v1/options/contracts
GET /v1/options/contracts/{options_ticker}
```

---

## List contracts

Returns a reference index of options contracts. You can scan the full universe or narrow results with filters (underlying, expiration, strike, contract type, and more). By default, expired contracts are excluded. A single contract is loaded with **`GET /v1/options/contracts/{options_ticker}/`**. The list URL does **not** accept a `ticker` query parameter (requests that include it receive **400**).

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `underlying_ticker` | string | No | Limit to contracts for this underlying equity ticker (for example `NFLX`). |
| `contract_type` | string | No | Filter by contract type (for example `call` or `put`). |
| `expiration_date` | string | No | Filter by expiration, format `YYYY-MM-DD`. |
| `as_of` | string | No | Treat contracts as of this calendar date, format `YYYY-MM-DD`. Defaults to today when omitted. |
| `strike_price` | number | No | Filter by exact strike price. |
| `expired` | boolean | No | Include expired contracts when `true`. Default is `false`. |
| `underlying_ticker.gte` | string | No | Range filter: underlying ticker greater than or equal. |
| `underlying_ticker.gt` | string | No | Range filter: underlying ticker greater than. |
| `underlying_ticker.lte` | string | No | Range filter: underlying ticker less than or equal. |
| `underlying_ticker.lt` | string | No | Range filter: underlying ticker less than. |
| `expiration_date.gte` | string | No | Range filter: expiration on or after this date (`YYYY-MM-DD`). |
| `expiration_date.gt` | string | No | Range filter: expiration after this date. |
| `expiration_date.lte` | string | No | Range filter: expiration on or before this date. |
| `expiration_date.lt` | string | No | Range filter: expiration before this date. |
| `strike_price.gte` | number | No | Range filter: strike greater than or equal. |
| `strike_price.gt` | number | No | Range filter: strike greater than. |
| `strike_price.lte` | number | No | Range filter: strike less than or equal. |
| `strike_price.lt` | number | No | Range filter: strike less than. |
| `sort` | string | No | Field name used for ordering. |
| `order` | string | No | Sort direction for the `sort` field. |
| `limit` | integer | No | Maximum number of results per request. Default is **10**, maximum is **1000**. |
| `page` | string | No | Pagination continuation. When `next_url` is present, request that full URL (recommended), or call this endpoint with the `page` query string from `next_url`. |

### Pagination

Use `limit` (up to 1000) together with `sort`, `order`, and filters such as expiration or strike ranges to narrow results. When more rows exist, the response includes **`next_url`**: a complete URL for the next page. Request it with the same API key and repeat until `next_url` is absent.

### Response (list)

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Outcome of the request (for example `OK`). |
| `request_id` | string | Identifier for this request (assigned by CuteMarkets). |
| `results` | array | Contract objects matching the query. |
| `next_url` | string | Present when another page of results exists. Full URL for the next request. |

Each element of `results` may include:

| Field | Type | Description |
| --- | --- | --- |
| `ticker` | string | Options contract ticker. |
| `underlying_ticker` | string | Underlying symbol. |
| `contract_type` | string | Typically `call`, `put`, or rarely `other`. |
| `exercise_style` | string | One of `american`, `european`, or `bermudan`. |
| `expiration_date` | string | Expiration date, `YYYY-MM-DD`. |
| `strike_price` | number | Strike price. |
| `shares_per_contract` | number | Contract size in shares. |
| `primary_exchange` | string | MIC code of the primary listing exchange. |
| `cfi` | string | Six-letter CFI code ([ISO 10962](https://en.wikipedia.org/wiki/ISO_10962)). |
| `correction` | integer | Correction number for this contract record, when present. |
| `additional_underlyings` | array | Optional deliverables or extra underlyings (for example after corporate actions). Objects may include `underlying`, `type`, and `amount`. |

### Example request (list)

```bash
curl \
  "https://api.cutemarkets.com/v1/options/contracts/?underlying_ticker=NFLX&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Sample response (list)

```json
{
  "results": [
    {
      "cfi": "OCASPS",
      "contract_type": "call",
      "exercise_style": "american",
      "expiration_date": "2026-04-02",
      "primary_exchange": "BATO",
      "shares_per_contract": 100,
      "strike_price": 40,
      "ticker": "O:NFLX260402C00040000",
      "underlying_ticker": "NFLX"
    },
    {
      "cfi": "OCASPS",
      "contract_type": "call",
      "exercise_style": "american",
      "expiration_date": "2026-04-02",
      "primary_exchange": "BATO",
      "shares_per_contract": 100,
      "strike_price": 45,
      "ticker": "O:NFLX260402C00045000",
      "underlying_ticker": "NFLX"
    }
  ],
  "status": "OK",
  "request_id": "cm_6e2beadb22f8498885af015fde6bfab2"
}
```

---

## Contract detail

Returns reference data for **one** options contract: type (call/put), exercise style, expiration, strike, shares per contract, underlying symbol, primary exchange, and related metadata. Use it to confirm contract specifications, align chain or strategy logic, or integrate contract definitions into tooling.

<div data-try-url="/v1/options/contracts/O:NFLX260402C00075000/"></div>

### Endpoint

```
GET /v1/options/contracts/{options_ticker}
```

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `options_ticker` | string | Yes | Options contract ticker in full form (for example `O:NFLX260402C00075000`). The path segment is the contract identifier; it is not repeated as a query parameter. |

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `as_of` | string | No | Return the contract as it was defined on this calendar date, format `YYYY-MM-DD`. When omitted, defaults to today. |

### Historical reference behavior

`as_of` is for contract **reference data**: expiration, strike, contract type, deliverables, and related metadata as of a date. It does not return a quote, mark, trade, IV, or Greeks. For expired or same-week contracts, use `as_of` to confirm the contract definition, then use quotes/trades with timestamp filters to reconstruct prior market state. Current snapshot endpoints may return **404** after a contract expires or leaves the current snapshot feed.

### Response (detail)

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Outcome of the request (for example `OK`). |
| `request_id` | string | Unique identifier for this request, assigned by CuteMarkets. |
| `results` | object | The contract record for the requested ticker. |

Fields on `results`:

| Field | Type | Description |
| --- | --- | --- |
| `ticker` | string | Options contract ticker. |
| `underlying_ticker` | string | Underlying equity symbol. |
| `contract_type` | string | Typically `call`, `put`, or rarely `other`. |
| `exercise_style` | string | One of `american`, `european`, or `bermudan`. |
| `expiration_date` | string | Expiration date, `YYYY-MM-DD`. |
| `strike_price` | number | Strike price. |
| `shares_per_contract` | number | Shares represented per contract. |
| `primary_exchange` | string | MIC code of the primary listing exchange. |
| `cfi` | string | Six-letter CFI code ([ISO 10962](https://en.wikipedia.org/wiki/ISO_10962)). |
| `correction` | integer | Correction revision for this contract record, when present. |
| `additional_underlyings` | array | Optional. Extra deliverables or underlyings (for example after splits or mergers). Objects may include `underlying`, `type`, and `amount`. See the [Options Industry Council FAQ on corporate actions](https://www.optionseducation.org/referencelibrary/faq/splits-mergers-spinoffs-bankruptcies) for context. |

### Example request (detail)

```bash
curl \
  "https://api.cutemarkets.com/v1/options/contracts/O:NFLX260402C00075000/" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Optional historical as-of:

```bash
curl \
  "https://api.cutemarkets.com/v1/options/contracts/O:NFLX260402C00075000/?as_of=2026-01-15" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Sample response (detail)

```json
{
  "results": {
    "cfi": "OCASPS",
    "contract_type": "call",
    "exercise_style": "american",
    "expiration_date": "2026-04-02",
    "primary_exchange": "BATO",
    "shares_per_contract": 100,
    "strike_price": 75,
    "ticker": "O:NFLX260402C00075000",
    "underlying_ticker": "NFLX"
  },
  "status": "OK",
  "request_id": "cm_dae7973c238245a5bf0525814f03e3aa"
}
```

Some contracts include `additional_underlyings` when deliverables are not a single equity only, for example after mergers or spinoffs:

```json
{
  "results": {
    "additional_underlyings": [
      { "amount": 44, "type": "equity", "underlying": "VMW" },
      { "amount": 6.53, "type": "currency", "underlying": "USD" }
    ],
    "cfi": "OCASPS",
    "contract_type": "call",
    "exercise_style": "american",
    "expiration_date": "2021-11-19",
    "primary_exchange": "BATO",
    "shares_per_contract": 100,
    "strike_price": 85,
    "ticker": "O:AAPL211119C00085000",
    "underlying_ticker": "AAPL"
  },
  "status": "OK",
  "request_id": "cm_9f3e2d1c0b4a5e6d7c8b9a0f1e2d3c4b"
}
```