Flow Data

curl --request GET \
  --url https://api.unusualwhales.com/api/option-contract/{id}/flow \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/option-contract/{id}/flow"

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/option-contract/{id}/flow', 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/option-contract/{id}/flow",
  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/option-contract/{id}/flow"

	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/option-contract/{id}/flow")

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

{
  "ask_vol": 2,
  "bid_vol": 1,
  "canceled": false,
  "delta": "0.610546281537814",
  "er_time": "postmarket",
  "ewma_nbbo_ask": "21.60",
  "ewma_nbbo_bid": "21.45",
  "exchange": "MXOP",
  "executed_at": "2024-08-21T13:50:52.278Z",
  "expiry": "2025-01-17T00:00:00.000Z",
  "flow_alert_id": null,
  "full_name": "NVIDIA CORP",
  "gamma": "0.00775013889662635",
  "id": "8ef90a2d-d881-41de-98c9-c1de4318dcb5",
  "implied_volatility": "0.604347250962543",
  "industry_type": "Semiconductors",
  "marketcap": "3130350000000.00",
  "mid_vol": 30,
  "multi_vol": 30,
  "nbbo_ask": "21.60",
  "nbbo_ask_size": 24,
  "nbbo_ask_time": "2024-08-21T13:50:52.274Z",
  "nbbo_bid": "21.45",
  "nbbo_bid_size": 17,
  "nbbo_bid_time": "2024-08-21T13:50:52.271Z",
  "next_earnings_date": "2024-08-28T00:00:00.000Z",
  "no_side_vol": 0,
  "open_interest": 6016,
  "option_chain_id": "NVDA250117C00124000",
  "option_type": "call",
  "premium": "2150.00",
  "price": "21.50",
  "report_flags": [],
  "rho": "0.2316546330093438",
  "rule_id": null,
  "sector": "Technology",
  "size": 1,
  "stock_multi_vol": 0,
  "strike": "124.0000000000",
  "tags": [
    "bid_side",
    "bearish",
    "earnings_next_week"
  ],
  "theo": "21.49999999999999",
  "theta": "-0.0640155364004474",
  "underlying_price": "128.16",
  "underlying_symbol": "NVDA",
  "upstream_condition_detail": "auto",
  "vega": "0.3140468475903719",
  "volume": 33
}

{
  "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

option-contract

Flow Data

Returns the last 50 option trades for the given option chain. Optionally a min premium and a side can be supplied in the query for further filtering. If no date is specified data for the last trading day is being returned.

For CBOE index tickers such as SPX or VIX the index price is returned as null and the row is marked missing_periscope. If the request filters with min_underlying_price, max_underlying_price, min_stock_price, max_stock_price, min_diff, max_diff, min_implied_move, max_implied_move, min_return_on_capital, max_return_on_capital, min_return_on_capital_perc or max_return_on_capital_perc, rows for these index tickers are left out of the response. CBOE index prices require provisioned access and CBOE approval. Contact [email protected], [email protected] or [email protected] to request access.

GET

api

option-contract

{id}

flow

Flow Data

curl --request GET \
  --url https://api.unusualwhales.com/api/option-contract/{id}/flow \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/option-contract/{id}/flow"

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/option-contract/{id}/flow', 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/option-contract/{id}/flow",
  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/option-contract/{id}/flow"

	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/option-contract/{id}/flow")

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

{
  "ask_vol": 2,
  "bid_vol": 1,
  "canceled": false,
  "delta": "0.610546281537814",
  "er_time": "postmarket",
  "ewma_nbbo_ask": "21.60",
  "ewma_nbbo_bid": "21.45",
  "exchange": "MXOP",
  "executed_at": "2024-08-21T13:50:52.278Z",
  "expiry": "2025-01-17T00:00:00.000Z",
  "flow_alert_id": null,
  "full_name": "NVIDIA CORP",
  "gamma": "0.00775013889662635",
  "id": "8ef90a2d-d881-41de-98c9-c1de4318dcb5",
  "implied_volatility": "0.604347250962543",
  "industry_type": "Semiconductors",
  "marketcap": "3130350000000.00",
  "mid_vol": 30,
  "multi_vol": 30,
  "nbbo_ask": "21.60",
  "nbbo_ask_size": 24,
  "nbbo_ask_time": "2024-08-21T13:50:52.274Z",
  "nbbo_bid": "21.45",
  "nbbo_bid_size": 17,
  "nbbo_bid_time": "2024-08-21T13:50:52.271Z",
  "next_earnings_date": "2024-08-28T00:00:00.000Z",
  "no_side_vol": 0,
  "open_interest": 6016,
  "option_chain_id": "NVDA250117C00124000",
  "option_type": "call",
  "premium": "2150.00",
  "price": "21.50",
  "report_flags": [],
  "rho": "0.2316546330093438",
  "rule_id": null,
  "sector": "Technology",
  "size": 1,
  "stock_multi_vol": 0,
  "strike": "124.0000000000",
  "tags": [
    "bid_side",
    "bearish",
    "earnings_next_week"
  ],
  "theo": "21.49999999999999",
  "theta": "-0.0640155364004474",
  "underlying_price": "128.16",
  "underlying_symbol": "NVDA",
  "upstream_condition_detail": "auto",
  "vega": "0.3140468475903719",
  "volume": 33
}

{
  "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

string

required

An option contract in the OSI format.

Example:

"TSLA230526P00167500"

Query Parameters

side

enum<string>

default:ALL

The side of a stock trade. Must be one of ASK, BID, MID. If not set, will return all side's trades.

Available options:

ALL,

ASK,

BID,

MID

Example:

"ASK"

min_premium

integer

default:0

The minimum premium requested trades should have.

Required range: x >= 0

Example:

50000

limit

integer

How many items to return. If no limit is given, returns all matching data. Min: 1.

Required range: x >= 1

Example:

10

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"

Response

ask_vol

integer

The amount of volume that happened on the ask side.

Ask side is defined as (ask + bid) / 2 < fill price.

Example:

119403

bid_vol

integer

The amount of volume that happened on the bid side.

Bid side is defined as (ask + bid) / 2 > fill price.

Example:

122789

canceled

boolean

Whether the option trade was canceled.

Example:

false

delta

string

The delta of the option trade.

Example:

"0.610546281537814"

er_time

enum<string>

The time when the earnings will be released.

Available options:

unknown,

afterhours,

premarket

Example:

"premarket"

ewma_nbbo_ask

string

The exponentially weighted moving average of the National Best Bid and Offer ask side.

Example:

"21.60"

ewma_nbbo_bid

string

The exponentially weighted moving average of the National Best Bid and Offer bid side.

Example:

"21.45"

exchange

string

The exchange the option trade was executed on.

Example:

"MXOP"

executed_at

string<date-time>

The option trade execution time as an ISO 8601 UTC timestamp. The WebSocket option_trades channel represents this field as Unix epoch milliseconds instead.

Example:

"2024-08-21T13:50:52.278Z"

expiry

string

The contract expiry date in ISO format.

Example:

"2023-12-22T00:00:00.000Z"

flow_alert_id

string

The flow alert ID of the option trade.

If the flow alert ID is null, it means that there is no flow alert associated with the option trade.

full_name

string

Full name of the ticker.

Example:

"APPLE"

gamma

string

The gamma of the option trade.

Example:

"0.00775013889662635"

string

The ID of the option trade.

Example:

"8ef90a2d-d881-41de-98c9-c1de4318dcb5"

implied_volatility

string

The implied volatility of the option trade.

Example:

"0.604347250962543"

industry_type

string

The industry type of the ticker.

Example:

"Semiconductors"

is_agg

boolean

Whether this response item combines related option transactions executed at the same time into a single transaction.

Example:

true

issue_type

string | null

Example:

"Common Stock"

marketcap

string

The marketcap of the underlying ticker. If the issue type of the ticker is ETF then the marketcap represents the AUM.

Example:

"2965813810400"

mid_vol

integer

The amount of volume that happened in the middle of the ask and bid.

Mid is defined as (ask + bid) / 2 == fill price.

Example:

22707

multi_vol

integer

The amount of volume that happened as part of a multileg trade with another contract. This can be spreads/rolls/condors/butterflies and more.

Example:

7486

nbbo_ask

string

The National Best Bid and Offer (NBBO) ask price at the time of the trade.

Example:

"21.60"

nbbo_ask_size

integer<int64> | null

The quoted size in contracts at the NBBO ask price. null when quote metadata is unavailable.

Example:

24

nbbo_ask_time

string<date-time> | null

The last update time for the NBBO ask quote as an ISO 8601 UTC timestamp. null when quote metadata is unavailable. The WebSocket option_trades channel represents this field as Unix epoch milliseconds instead.

Example:

"2024-08-21T13:50:52.274Z"

nbbo_bid

string

The National Best Bid and Offer (NBBO) bid price at the time of the trade.

Example:

"21.45"

nbbo_bid_size

integer<int64> | null

The quoted size in contracts at the NBBO bid price. null when quote metadata is unavailable.

Example:

17

nbbo_bid_time

string<date-time> | null

The last update time for the NBBO bid quote as an ISO 8601 UTC timestamp. null when quote metadata is unavailable. The WebSocket option_trades channel represents this field as Unix epoch milliseconds instead.

Example:

"2024-08-21T13:50:52.271Z"

next_earnings_date

string<date>

The next earnings date of the ticker. Null if either unknown as of now or if the ticker does not have any earnings such as an ETF

Example:

"2023-10-26T00:00:00.000Z"

no_side_vol

integer

The amount of volume that happened on no identifiable side. This can be late, out of sequence and/or cross transactions.

Example:

0

open_interest

integer

The open interest for the contract.

Example:

18680

option_chain_id

string

The option symbol of the contract.

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 multiplied by 1,000.

option_type

enum<string>

The option type of the contract.

Available options:

call,

put

Example:

"call"

premium

string

The premium of the option trade.

Example:

"2150.00"

price

string

The fill price of the option trade.

Example:

"21.50"

report_flags

string[]

The report flags of the option trade.

Example:

"cross_trade"

rho

string

The rho of the option trade.

Example:

"0.2316546330093438"

rule_id

string

The rule ID of the option trade that represents the rule that made up the flow alert

sector

enum<string>

The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index.

Available options:

Basic Materials,

Communication Services,

Consumer Cyclical,

Consumer Defensive,

Energy,

Financial Services,

Healthcare,

Industrials,

Real Estate,

Technology,

Utilities

Example:

"Technology"

size

integer

The size of the option trade.

Example:

1

stock_multi_vol

integer

The amount of volume that happened as part of a stock transaction and possibly other option contracts. This can be covered calls and more.

Example:

52

strike

string

The contract strike.

Example:

"375"

Docs

Endpoints

Flow Data

Authorizations

Path Parameters

Query Parameters

Response