# WebSocket channels `GET` `https://api.unusualwhales.com/api/socket` Returns the available WebSocket channels for connections. ## Websocket Guide #You can find fully-functional examples that stream data from many channels here: - Python: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output) - Javascript: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs) If you are an AI or work with AI there is an available websocket skill at: https://unusualwhales.com/skills/websocket.md 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](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. | | market_tide | Receive live updates of both the market tide and the otm market tide. | | 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 oskar@unusualwhales.com 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. | | 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. | The `option_trades` channel will stream all 6,000,000 option trades in real-time, `option_trades:` will stream all option trades for the given ticker in real-time. `flow-alerts` will stream from the alerts [page](https://unusualwhales.com/option-flow-alerts?limit=50) ## Connect 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](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output) We will use [websocat](https://github.com/vi/websocat) to demonstrate how to connect to the WebSocket server. ```bash websocat "wss://api.unusualwhales.com/socket?token=" {"channel":"option_trades","msg_type":"join"} ``` The server will then reply with ```bash ["option_trades",{"response":{},"status":"ok"}] ``` indicating that the connection was successful. You will then receive data in the following format: ```bash [, ] ``` during market hours. To receive the trades only for a specific ticker, use the following command: ```bash {"channel":"option_trades","msg_type":"join"} ``` You can join multiple channels with the same websocket connection: ```bash websocat "wss://api.unusualwhales.com/socket?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"}] ``` ## Using a client If you are using Python, you can use the [websocket-client](https://github.com/websocket-client/websocket-client) library to connect to the server. ```python 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=", 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() ## Historic data To download/access historic data, use the endpoint [/api/option-trades/full-tape](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionTradeController.full_tape) ## Authentication ``` Authorization: Bearer YOUR_API_KEY ``` ## Example ### curl ```bash curl -X GET "https://api.unusualwhales.com/api/socket" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" ``` ### Python ```python import http.client conn = http.client.HTTPSConnection("api.unusualwhales.com") headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"} conn.request("GET", "/api/socket", headers=headers) response = conn.getresponse() print(response.read().decode("utf-8")) ``` ## Response Example ```json { "data": [] } ```