> ## Documentation Index
> Fetch the complete documentation index at: https://api.unusualwhales.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer <API_KEY>`). Create and manage API tokens at https://unusualwhales.com/dashboard/api.
> For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp.
> Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md

# Option trades

> Receive live option trades throughout the trading session. Expect 6-10M records per day.

**NOTE:**
This is the documentation for websocket channels `option_trades` and `option_trades:<TICKER>`.
Websocket access for personal use is only available through the [Advanced plan](https://unusualwhales.com/pricing?product=api).

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)

Connect to the websocket URI:

`wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN>`

then `join` the channel(s) you wish to stream, for example `option_trades` for all tickers or `option_trades:TSLA` for TSLA transactions only.

Payload format:

```
{
    "id":"a4dc6020-0611-4c23-b0bc-99944c7348ab",
    "underlying_symbol":"UVIX",
    "executed_at":1726670167412,
    "nbbo_bid":"0.01",
    "nbbo_bid_size":37,
    "nbbo_bid_time":1726670167388,
    "nbbo_ask":"0.09",
    "nbbo_ask_size":18,
    "nbbo_ask_time":1726670167401,
    "size":1,
    "price":"0.01",
    "option_symbol":"UVIX240920C00025000",
    "created_at":1726670167461,
    "report_flags":[

    ],
    "tags":[
      "bid_side",
      "bearish",
      "etf"
    ],
    "expiry":"2024-09-20",
    "option_type":"call",
    "open_interest":410,
    "strike":"25.0000000000",
    "premium":"1.00",
    "volume":105,
    "underlying_price":"4.9261",
    "ewma_nbbo_ask":"0.09",
    "ewma_nbbo_bid":"0.01",
    "implied_volatility":"8.46381958089369",
    "delta":"0.01132315610146539",
    "theta":"-0.02291485773244166",
    "gamma":"0.00962272181839715",
    "vega":"0.0001082948756510385",
    "rho":"0.000002508438316242667",
    "theo":"0.01",
    "trade_code":"slan",
    "exchange":"XCBO",
    "ask_vol":10,
    "bid_vol":95,
    "no_side_vol":0,
    "mid_vol":0,
    "multi_vol":0,
    "stock_multi_vol":0
}
```

### Field reference

| Field | Type | Description |
| - | - | - |
| `id` | uuid string | Unique trade identifier. Use this to dedupe and to cross-reference `flow-alerts.trade_ids`. |
| `underlying_symbol` | string | Underlying ticker (e.g. `AAPL`, `SPX`). |
| `executed_at` | int (ms) | Trade execution time, unix epoch milliseconds (UTC). |
| `nbbo_bid` / `nbbo_ask` | decimal string | NBBO at the time of the trade. |
| `nbbo_bid_size` / `nbbo_ask_size` | int or null | Quoted size in contracts at the corresponding NBBO price. `null` when quote metadata is unavailable. |
| `nbbo_bid_time` / `nbbo_ask_time` | int (ms) or null | Last update time for the corresponding NBBO quote, in unix epoch milliseconds (UTC). `null` when quote metadata is unavailable. |
| `ewma_nbbo_bid` / `ewma_nbbo_ask` | decimal string | Exponentially-weighted moving average of the NBBO; smoother reference price for noisy quotes. |
| `size` | int | Number of contracts in this trade. |
| `price` | decimal string | Per-contract price. |
| `premium` | decimal string | Total dollar premium for the trade (`size * price * multiplier`). The multiplier is `100` for most contracts; `NANOS` uses `1` and `XSP` uses `10`. |
| `option_symbol` | string | OSI option chain id (e.g. `UVIX240920C00025000`). |
| `expiry` | date string `YYYY-MM-DD` | Contract expiration. |
| `option_type` | `"call"` \| `"put"` | |
| `strike` | decimal string | Strike price. |
| `open_interest` | int | Open interest as of the most recent trading day's close. |
| `volume` | int | Cumulative session volume on this contract up to and including this trade. |
| `underlying_price` | decimal string | Spot price of the underlying at the time of the trade. Empty string when `tags` contains `"index"`. |
| `implied_volatility`, `delta`, `theta`, `gamma`, `vega`, `rho`, `theo` | decimal string | Greeks and theoretical price computed from the NBBO mid at trade time. |
| `trade_code` | string | Upstream condition codes (comma-separated), e.g. `"slan"`, `"auto"`, `"slan,isoi"`. |
| `exchange` | string | OPRA exchange identifier (`XCBO`, `MPRL`, `XPHL`, ...). |
| `report_flags` | string\[] | Out-of-band reporting flags from upstream (e.g. `"cross_trade"`). Empty for normal prints. |
| `tags` | string\[] | Side and classification tags. Side: `"ask_side"` / `"bid_side"` / `"mid_side"` / `"no_side"`. Classification: `"bullish"` / `"bearish"`, plus `"index"`, `"etf"`, `"china"`, `"volatility"`, `"dividend"`, `"arbitrage"`. |
| `ask_vol` / `bid_vol` / `mid_vol` / `no_side_vol` | int | Cumulative session volume on this contract attributed to each side (NBBO at trade time). Sums to `volume` minus `multi_vol` and `stock_multi_vol`. |
| `multi_vol` | int | Cumulative session volume from multi-leg option trades. |
| `stock_multi_vol` | int | Cumulative session volume from option-stock combos (delta-neutral packages, etc.). |