> ## 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

# Lit trades

> Receive live lit (exchange-based) trades throughout the trading session.

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

**Coverage:** `lit_trades` streams lit (exchange) prints at or above roughly \$100,000 notional (price x size). Smaller prints are not included. For the complete unfiltered tape across all sizes, use the Kafka `all-trade-report` topic.

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 you wish to stream: `lit_trades` for lit (exchange-based) trades.

Payload format:

```
[
  "lit_trades",
  {
    "symbol": "AAPL",
    "price": "150.25",
    "type": "lit",
    "size": 100,
    "volume": 1000,
    "trade_settlement": "regular",
    "trade_code": "opening_print",
    "ext_hour_sold_codes": null,
    "sale_cond_codes": "cross_trade",
    "executed_at": "2024-09-22T14:30:00Z",
    "trf_executed_at": null,
    "nbbo_bid": "150.20",
    "nbbo_ask": "150.25",
    "nbbo_bid_quantity": 500,
    "nbbo_ask_quantity": 800,
    "sector": "Technology",
    "next_earnings_date": "2024-10-25",
    "avg30_volume": "75000000.0",
    "issue_type": "Common Stock",
    "marketcap": "2400000000000.0"
  }
]
```

### Field reference

| Field | Type | Description |
| - | - | - |
| `symbol` | string | Underlying ticker. |
| `price` | decimal string | Trade price. |
| `size` | int | Trade size in shares. |
| `volume` | int | Cumulative session volume on the symbol as of this trade. |
| `type` | `"lit"` | Always `"lit"` on this channel. |
| `trade_settlement` | string \| null | Settlement type, e.g. `"regular"`, `"cash"`, `"next_day"`, `"seller"`. |
| `trade_code` | string \| null | Special trade code such as `"opening_print"`, `"closing_print"`, `"odd_lot"`, etc. `null` for unflagged trades. |
| `ext_hour_sold_codes` | string \| null | Extended-hours indicator, e.g. `"extended_hours_trade"`. `null` during regular session. |
| `sale_cond_codes` | string \| null | Special sale condition, e.g. `"cross_trade"`, `"derivatively_priced"`. |
| `executed_at` | ISO 8601 string | Trade execution timestamp on the exchange (UTC). |
| `trf_executed_at` | ISO 8601 string \| null | When the print was reported to the TRF. |
| `nbbo_bid` / `nbbo_ask` | decimal string | NBBO at the time of the trade. |
| `nbbo_bid_quantity` / `nbbo_ask_quantity` | int | NBBO size on each side. |
| `sector` | string \| null | GICS-style sector of the underlying. |
| `issue_type` | string \| null | E.g. `"Common Stock"`, `"ETF"`, `"ADR"`. |
| `next_earnings_date` | date string `YYYY-MM-DD` \| null | Next scheduled earnings date for the underlying. |
| `avg30_volume` | decimal string \| null | Average daily share volume over the last 30 trading days. |
| `marketcap` | decimal string \| null | Market capitalization in dollars. |