Periscope

NOTE: This is the documentation for websocket channels periscope and periscope:<TICKER>. Websocket access for personal use is only available through the Advanced plan. These channels are not available on the enterprise and enterprise startup plans; joining them returns an error. You can find fully-functional examples that stream data from many channels here:

Connect to the websocket URI: wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN> then join the channel you wish to stream: periscope for every index ticker at once, or periscope:SPX for a single ticker. Payload format: Format for periscope:<TICKER>:

[
  "periscope:SPX",
  {
    "ticker": "SPX",
    "timestamp": 1726670396000,
    "total_rows": 11987,
    "has_more": true,
    "rows": [
      {
        "strike": "5200",
        "expiry": "2026-07-02",
        "gamma": 1234.5,
        "charm": -12.3,
        "vanna": 4.5
      },
      {
        "strike": "5225",
        "expiry": "2026-07-02",
        "gamma": 987.6,
        "charm": -10.1,
        "vanna": 3.2
      }
    ]
  }
]

The global periscope channel streams the same envelope frames for every index ticker, tagged periscope (the ticker field distinguishes them):

[
  "periscope",
  {
    "ticker": "SPX",
    "timestamp": 1726670396000,
    "total_rows": 11987,
    "has_more": true,
    "rows": [
      {
        "strike": "5200",
        "expiry": "2026-07-02",
        "gamma": 1234.5,
        "charm": -12.3,
        "vanna": 4.5
      }
    ]
  }
]

Each frame carries a batch of up to 1024 strike/expiry rows. A full snapshot spans several frames; all frames of one snapshot share the same timestamp, and a new timestamp starts the next snapshot (snapshots are published about once a minute). has_more is true on every frame but the last one of a snapshot, so the frame with "has_more": false closes the board. Sum the rows lengths across frames with the same timestamp and compare against total_rows to verify you received the complete snapshot.

Field	Type	Description
`ticker`	string	Index ticker (SPX, VIX, XSP, NANOS).
`timestamp`	int (ms)	Snapshot time, unix epoch milliseconds. Shared by every frame of the snapshot.
`total_rows`	int	Row count of the whole snapshot.
`has_more`	bool	More frames of this snapshot follow; `false` on the last frame.
`rows`	array	Up to 1024 rows per frame.
`rows[].strike`	decimal string	Strike price.
`rows[].expiry`	date string `YYYY-MM-DD`	Contract expiration.
`rows[].gamma`, `rows[].charm`, `rows[].vanna`	float	Market-maker greek exposure at this strike & expiry.

Overview

Channels