OptionWhales Contracts API
The contracts API from OptionWhales — 9 operation(s) for contracts.
The contracts API from OptionWhales — 9 operation(s) for contracts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/optionwhales-io:optionwhales-io-contracts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: OptionWhales Pro Contracts API
description: Premium API for intent flow, momentum, abnormal trades, earnings intelligence, economic events, directional scores, GEX, dark pool, implied-volatility analytics, open interest, and an MCP server for AI agents
version: 1.2.0
tags:
- name: Contracts
paths:
/v1/contracts/chain/{ticker}:
get:
tags:
- Contracts
summary: Contracts Chain
description: Option chain for an underlying (from the last OI snapshot; OI>0) (Pro+).
operationId: contracts_chain_v1_contracts_chain__ticker__get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: date
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Session YYYY-MM-DD; default latest
title: Date
description: Session YYYY-MM-DD; default latest
- name: expiry
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to one expiry YYYY-MM-DD
title: Expiry
description: Filter to one expiry YYYY-MM-DD
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: call | put
title: Type
description: call | put
- name: min_oi
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Min Oi
- name: limit
in: query
required: false
schema:
type: integer
maximum: 10000
minimum: 1
default: 2000
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/atm/{ticker}:
get:
tags:
- Contracts
summary: Contracts Atm
description: Near-spot (ATM) strikes grouped by expiry (Pro+).
operationId: contracts_atm_v1_contracts_atm__ticker__get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: date
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Date
- name: width
in: query
required: false
schema:
type: number
maximum: 0.5
exclusiveMinimum: 0.0
default: 0.05
title: Width
- name: per_expiry
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 20
title: Per Expiry
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/expiries/{ticker}:
get:
tags:
- Contracts
summary: Contracts Expiries
description: Per-expiry OI breakdown for an underlying (Pro+).
operationId: contracts_expiries_v1_contracts_expiries__ticker__get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: date
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Date
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/{occ}/historic:
get:
tags:
- Contracts
summary: Contract Historic
description: Daily OHLC bars for one contract over [from, to] — ~1yr look-back (Pro+).
operationId: contract_historic_v1_contracts__occ__historic_get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: from
in: query
required: true
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
title: From
- name: to
in: query
required: true
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
title: To
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/{occ}/intraday:
get:
tags:
- Contracts
summary: Contract Intraday
description: Intraday minute bars for one contract on a date — recent-window only (Pro+).
operationId: contract_intraday_v1_contracts__occ__intraday_get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: date
in: query
required: true
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
title: Date
- name: timespan
in: query
required: false
schema:
type: integer
maximum: 60
minimum: 1
default: 1
title: Timespan
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/{occ}/trades:
get:
tags:
- Contracts
summary: Contract Trades
description: Per-contract time & sales for a date — metered, bounded to `limit` (Pro+).
operationId: contract_trades_v1_contracts__occ__trades_get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: date
in: query
required: true
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
title: Date
- name: limit
in: query
required: false
schema:
type: integer
maximum: 5000
minimum: 1
default: 1000
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/{occ}/volume-profile:
get:
tags:
- Contracts
summary: Contract Volume Profile
description: Volume-by-price-level for a contract on a date, + POC + VWAP (Pro+).
operationId: contract_volume_profile_v1_contracts__occ__volume_profile_get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: date
in: query
required: true
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
title: Date
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/{occ}/oi-history:
get:
tags:
- Contracts
summary: Contract Oi History
description: 'Per-contract OI/IV/greeks trajectory across the last `days` twice-daily
snapshots (~Nov-2025 on) (Pro+).'
operationId: contract_oi_history_v1_contracts__occ__oi_history_get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: days
in: query
required: false
schema:
type: integer
maximum: 30
minimum: 1
description: Number of recent snapshot dates
default: 10
title: Days
description: Number of recent snapshot dates
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/contracts/{occ}:
get:
tags:
- Contracts
summary: Contract Profile
description: Per-contract profile — OCC parse + OI/IV/greeks/quote as-of the snapshot (Pro+).
operationId: contract_profile_v1_contracts__occ__get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: date
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Date
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError