WebSocket - Unusual Whales Docs

Stream live data over a WebSocket connection. Requires the Advanced tier or above. You can find fully-functional streaming examples here:

Stream Greeks by Strike and by Expiry to a DuckDB Database (python): https://github.com/unusual-whales/api-examples/tree/main/examples/ws-stream-spot-greeks-by-strike-by-expiry
Stream Flow Alerts to a SQLite Database (python): https://github.com/unusual-whales/api-examples/tree/main/examples/ws-stream-flow-alerts-to-sqlite
Stream Periscope Greek Exposure to a Partitioned Parquet Store (python): https://github.com/unusual-whales/api-examples/tree/main/examples/ws-stream-periscope-greek-exposure
Stream Multiple Channels to Multiple Outfiles (python): https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output
Stream Multiple Channels to Multiple Outfiles (javascript): https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs

If you are an AI agent or working with an AI agent there is a websocket Skill available at: https://unusualwhales.com/skills/websocket.md

Connecting

Connect to the socket with your API token on the query string, then join a channel.

wss://api.unusualwhales.com/socket?token=YOUR_API_KEY

Join a channel by sending:

{ "channel": "option_trades:SPY", "msg_type": "join" }

A successful join is acknowledged with:

["option_trades:SPY", { "response": {}, "status": "ok" }]

Data frames then arrive as ["<channel>", { ... }]. Send a real User-Agent on the handshake. Scope a channel to a ticker with a colon, for example gex_strike:SPY. See Channels for every channel.

Connect with websocat

For a python example script that streams gex by ticker (gex:TICKER), flow alerts (flow-alerts), and all TSLA option trades (option_trades:TSLA), see our “examples” repo on Github: https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output We will use websocat to demonstrate how to connect to the WebSocket server.

websocat "wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN>"
{"channel":"option_trades","msg_type":"join"}

The server will then reply with

["option_trades",{"response":{},"status":"ok"}]

indicating that the connection was successful. You will then receive data in the following format:

[<CHANNEL_NAME>, <PAYLOAD>]

during market hours. To receive the trades only for a specific ticker, use the following command:

{"channel":"option_trades:TSLA","msg_type":"join"}

You can join multiple channels with the same websocket connection:

websocat "wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN>"
{"channel":"option_trades","msg_type":"join"}
["option_trades",{"response":{},"status":"ok"}]
{"channel":"option_trades:JPM","msg_type":"join"}
["option_trades:JPM",{"response":{},"status":"ok"}]

Channels

The following channels are available:

Channel	Description
`option_trades`	Receive live option trades throughout the trading session. Expect 6-10M records per day.
`option_trades:TICKER`	Similar to `option_trades` but receive all trades only for the specified ticker.
`flow-alerts`	Receive live flow alerts (all of them unfiltered). This data can be used to build views like https://unusualwhales.com/option-flow-alerts.
`price`	Receive live price updates for every ticker at once.
`price:TICKER`	Receive live price updates for the given ticker.
`news`	Receive live headline news (Truth Social posts + aggregator news).
`lit_trades`	Receive live lit (exchange-based) trades throughout the trading session.
`off_lit_trades`	Receive live off-lit (dark pool) trades throughout the trading session.
`gex`	Receive live gex updates for every ticker at once.
`gex:TICKER`	Receive live gex update for the given ticker.
`gex_strike`	Receive live gex strike updates for every strike of every ticker.
`gex_strike:TICKER`	Receive live gex strike updates for every strike of the given ticker.
`gex_strike_expiry`	Receive live gex strike updates for every strike & expiry of every ticker.
`gex_strike_expiry:TICKER`	Receive live gex strike updates for every strike & expiry of the given ticker.
`periscope`	Receive live periscope market-maker greek exposures (gamma/charm/vanna) per strike & expiry for every index ticker (SPX, VIX, XSP, NANOS). Not available on the enterprise and enterprise startup plans.
`periscope:TICKER`	Receive live periscope market-maker greek exposures per strike & expiry for the given index ticker. Not available on the enterprise and enterprise startup plans.
`greeks`	Receive live per-contract option greeks (first- and second-order) for every contract of every underlying.
`greeks:TICKER`	Receive live per-contract option greeks (first- and second-order) for every contract of the given underlying.
`market_tide`	Receive live updates of both the market tide and the otm market tide.
`otm_market_tide`	Receive live updates of only the otm market tide. It carries the `otm_net_*` values of `market_tide` under unprefixed names.
`net_flow:TICKER`	Receive live net call/put premium and volume aggregates for the specified ticker to build a net prem view.
`interval_flow`	Receive per interval option flow statistics for a ticker (sweeps, floors, multilegs, Greek flows, IV, net prem). Use this to build alert systems to spot spikes in tickers
`contract_screener`	Receive live option contract snapshots (Greeks, side volumes, OI growth indicators). This your entry point to build a screener on top of option contracts.
`trading_halts`	Receive live trading state changes (halts, resumes, LULD pauses) for individual tickers.
`custom_alerts`	Receive notifications matching the alert configurations on your own Unusual Whales account.
`futures_trades`	Receive live CME futures trade prints across all contracts. Available on the Advanced API tier, or with the `futures` add-on — email [email protected], [email protected] or [email protected] for access.
`futures:TICKER`	Similar to `futures_trades` but only for the specified dated contract, e.g. `futures:ESU6`. Available on the Advanced API tier, or with the `futures` add-on.
`futures_blocks`	Receive live CME block trades in futures contracts and multi-leg futures strategies, across all symbols. Available on the Advanced API tier, or with the `futures` add-on.
`futures_blocks:SYMBOL`	Similar to `futures_blocks` but only for the specified contract or strategy symbol, e.g. `futures_blocks:ESZ6`. Available on the Advanced API tier, or with the `futures` add-on.
`interpolated_iv`	Receive live interpolated IV and expected move updates at fixed horizons (1-365 days) for every ticker at once.
`interpolated_iv:TICKER`	Receive live interpolated IV and expected move updates at fixed horizons for the given ticker.
`iv_term_structure`	Receive live ATM IV and expected move updates per real option expiry for every ticker at once.
`iv_term_structure:TICKER`	Receive live ATM IV and expected move updates per real option expiry for the given ticker.
`risk_reversal_skew`	Receive live 25- and 10-delta risk reversal skew (put IV minus call IV) per expiry for every ticker at once.
`quotes`	Receive live best bid and ask (top of book) updates for every ticker at once. This is a high volume firehose - prefer `quotes:TICKER` unless you need the full tape.
`quotes:TICKER`	Receive live best bid and ask (top of book) updates for the given ticker.
`greek_flow`	Receive live delta & vega flow from option trades for every ticker at once, bucketed to the minute and updated about once a second.
`greek_flow:TICKER`	The same for the given ticker. Silent while that ticker has no option trades.
`greek_flow_expiry`	Same as `greek_flow`, additionally broken out by option expiry, for every ticker at once.
`greek_flow_expiry:TICKER`	Per-minute delta & vega flow broken out by option expiry for the given ticker.
`stock_screener`	Receive the live stock screener row of every ticker (option flow, price, volatility, open interest, GEX, fundamentals, quote and daily technical indicators).

The option_trades channel will stream all 6,000,000 option trades in real-time, option_trades:<TICKER> will stream all option trades for the given ticker in real-time. flow-alerts will stream from the alerts page

Using a client

If you are using Python, you can use the websocket-client library to connect to the server.

import websocket
import time
import rel
import json

def on_message(ws, msg):
    msg = json.loads(msg)
    channel, payload = msg
    print(f"Got a message on channel {channel}: Payload: {payload}")

def on_error(ws, error):
    print(error)

def on_close(ws, close_status_code, close_msg):
    print("### closed ###")

def on_open(ws):
    print("Opened connection")
    msg = {"channel":"option_trades","msg_type":"join"}
    ws.send(json.dumps(msg))

if __name__ == "__main__":
    websocket.enableTrace(False)
    ws = websocket.WebSocketApp("wss://api.unusualwhales.com/socket?token=<YOUR_TOKEN>",
                              on_open=on_open,
                              on_message=on_message,
                              on_error=on_error,
                              on_close=on_close)

    ws.run_forever(dispatcher=rel, reconnect=5)  # Set dispatcher to automatic reconnection, 5 second reconnect delay if connection closed unexpectedly
    rel.signal(2, rel.abort)  # Keyboard Interrupt
    rel.dispatch()

Connections

Connect each API token from a single machine. The same token connected from more than one machine at a time is not supported and results in dropped connections. Use a separate token per host.

Buffering

Buffer incoming messages and write them on an interval rather than once per message. A consumer that writes to storage on every payload will fall behind on high-volume channels and be dropped as a slow client. Flush on a timer, for example once per second, or after a set number of records, whichever comes first. Reference consumers:

Buffer to SQLite, flush once per second: ws-stream-flow-alerts-to-sqlite
Buffer to DuckDB, flush every second or every 500 records, whichever comes first: ws-stream-spot-greeks-by-strike-by-expiry

Recovery

The stream has no replay, resume, or sequence numbers. Messages missed during a disconnect are not redelivered on reconnect. For delivery guaranteed across gaps, use Kafka which has a retention period of 72h. The gex_strike data has no intraday REST backfill, so capture it live.

Historic data

To download/access historic data, use the endpoint /api/option-trades/full-tape

The `price` channel

Subscribe to price with no ticker to receive live prices for all tickers on one connection. price:{TICKER} streams a single ticker. To follow many tickers, subscribe once to price rather than opening a price:{TICKER} subscription per symbol.

Periscope values

On the periscope channels, the streamed gamma, charm, and vanna are net Market Maker greek exposure, not the dollarized *_per_one_percent_move_oi values returned by the REST spot-exposures endpoints. They are on different scales, so do not compare them directly.

​Connecting

​Connect with websocat

​Channels

​Using a client

​Connections

​Buffering

​Recovery

​Historic data

​The price channel

​Periscope values