Option Chains

curl --request GET \
  --url https://api.unusualwhales.com/api/stock/{ticker}/option-chains \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/stock/{ticker}/option-chains"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/stock/{ticker}/option-chains', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/stock/{ticker}/option-chains",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/stock/{ticker}/option-chains"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/stock/{ticker}/option-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    "AAPL230908C00175000",
    "AAPL231020C00185000",
    "AAPL230908C00180000",
    "AAPL230908C00182500",
    "AAPL230908C00185000",
    "AAPL230908C00187500",
    "AAPL230908P00172500",
    "AAPL230908P00175000",
    "AAPL230908P00177500",
    "AAPL230908C00177500",
    "AAPL230915C00177500",
    "AAPL230915C00180000",
    "AAPL230915C00185000",
    "AAPL230915C00187500",
    "AAPL230915C00192500",
    "AAPL230915C00195000",
    "AAPL230915C00200000"
  ]
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "payment_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds.",
  "reason": "payment_failed",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

Something went wrong

stock

Option Chains

Returns all option symbols for the given ticker that were present at the given day.

If no date is given, returns data for the current/last market day.

You can use the following regex to extract underlying ticker, option type, expiry & strike: ^(?<symbol>[\w]*)(?<expiry>(\d{2})(\d{2})(\d{2}))(?<type>[PC])(?<strike>\d{8})$

Keep in mind that the strike needs to be divided by 1,000.

With greeks=true, the response is paginated. Rows are sorted by expires, then strike, then option_symbol, all ascending. limit sets the page size and page selects the page, starting at 0. Without greeks=true, the response contains every option symbol and limit and page have no effect.

GET

api

stock

{ticker}

option-chains

Option Chains

curl --request GET \
  --url https://api.unusualwhales.com/api/stock/{ticker}/option-chains \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/stock/{ticker}/option-chains"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/stock/{ticker}/option-chains', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/stock/{ticker}/option-chains",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/stock/{ticker}/option-chains"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/stock/{ticker}/option-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    "AAPL230908C00175000",
    "AAPL231020C00185000",
    "AAPL230908C00180000",
    "AAPL230908C00182500",
    "AAPL230908C00185000",
    "AAPL230908C00187500",
    "AAPL230908P00172500",
    "AAPL230908P00175000",
    "AAPL230908P00177500",
    "AAPL230908C00177500",
    "AAPL230915C00177500",
    "AAPL230915C00180000",
    "AAPL230915C00185000",
    "AAPL230915C00187500",
    "AAPL230915C00192500",
    "AAPL230915C00195000",
    "AAPL230915C00200000"
  ]
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "payment_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds.",
  "reason": "payment_failed",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

Something went wrong

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

ticker

string

required

A single ticker

Example:

"AAPL"

Query Parameters

date

string

A trading date in the format of YYYY-MM-DD. This is optional and by default the last trading date.

Example:

"2024-01-18T00:00:00.000Z"

greeks

boolean

When true, return an enriched row per contract (strike, expiry, type, NBBO, IV, OI, volume, delta, gamma, theta, vega, rho, last_tape_time) instead of the default array of option-symbol strings. Enriched rows are paginated with limit and page.

limit

integer

default:500

How many enriched rows to return when greeks=true. Max: 500. Min: 1. Returns up to 500 when omitted. How many items to return. Max: 500. Min: 1. Returns up to 500 when omitted.

Required range: 1 <= x <= 500

Example:

10

page

integer

Page number of enriched rows when greeks=true. Starts on page 0. Page number (use with limit). Starts on page 0.

Example:

1

Response

Option chains response

All option chains for a given ticker. By default data is an array of option-symbol strings.

Pass greeks=true to instead get an enriched object per contract with strike, expiry, type, NBBO (nbbo_bid/nbbo_ask), implied_volatility, open_interest, volume, delta, gamma, theta, vega, rho and last_tape_time. Enriched rows are sorted by expires, strike and option_symbol and returned in pages of up to 500. Use limit and page to read the rest of the chain.

Example enriched row (greeks=true):

{
  "option_symbol": "AAPL231020C00185000",
  "strike": 185,
  "expires": "2023-10-20",
  "option_type": "call",
  "nbbo_bid": 4.35,
  "nbbo_ask": 4.45,
  "implied_volatility": 0.2612,
  "open_interest": 1200,
  "volume": 842,
  "delta": 0.4573,
  "gamma": 0.021,
  "theta": -0.085,
  "vega": 0.112,
  "rho": 0.045,
  "last_tape_time": "2023-09-08T19:59:59Z"
}

Docs

Endpoints

Option Chains

Authorizations

Path Parameters

Query Parameters

Response