Messages
{
"message": "ping",
"content": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a"
}
}{
"message": "subscribe",
"content": {
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"market": "BTC-USDT",
"expiration": "24JUN26",
"strike": "62000",
"type": "C"
}
}{
"message": "unsubscribe",
"content": {
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"optionsPublicOrderBook"
],
"market": "BTC-USDT",
"expiration": "24JUN26",
"strike": "62000",
"type": "C"
}
}{
"resultType": "pong",
"data": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a",
"statusCode": 200
}
}{
"resultType": "subscribed",
"data": {
"activeSubscriptions": [
"optionsOrders",
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"requestedSubscriptions": [
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"statusCode": 200
}
}{
"resultType": "subscribe",
"data": {
"statusCode": 400,
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"error": "wrong_product_subscriptions"
}
}{
"resultType": "unsubscribed",
"data": {
"activeSubscriptions": [
"optionsOrders",
"optionsPositions",
"optionsOpenOrders"
],
"requestedUnsubscriptions": [
"optionsPublicOrderBook"
],
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"statusCode": 200
}
}{
"resultType": "unsubscribe",
"data": {
"statusCode": 400,
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"error": "invalid_subscriptions"
}
}{
"resultType": "connectionShutdown",
"data": {
"forceCloseInMs": 60000,
"statusCode": 200,
"ts": 1785258083038
}
}WS Reference
Common Requests
Available on every connection: ping, subscribe, and unsubscribe, plus the connection shutdown notice.
WSS
?product=options&market=
{market}
&expiration=
{expiration}
&strike=
{strike}
&type=
{type}
Prefer the application-level
ping message over WebSocket control frames when validating connectivity. Because it is handled as a normal data message, it confirms end-to-end reachability across the same path used by your subscriptions and requests. Control frames are processed separately by WebSocket infrastructure and can still succeed when application data is not flowing reliably.Supported Streams
| Subscription Value | Description |
|---|---|
optionsOrders | Order Creation Stream — create, modify, and cancel orders, with fill notifications. Subscribed by default when you connect, unless the subscriptions query parameter replaces it |
optionsContracts | Contracts Stream — contract definitions with mark price, IV, and Greeks, scoped by underlying and expiration date |
optionsQuotes | Quotes Stream — top-of-book bid/ask with IV, scoped by underlying and expiration date |
optionsPublicOrderBook | Order Book Stream — order book snapshots and deltas for a single contract |
optionsPublicTrades | Public Trades Stream — public trade executions for a single contract |
optionsPositions | Positions Stream — your open positions |
optionsOpenOrders | Open Orders Stream — your open orders and incremental updates |
optionsRecentOrders | Recent Orders Stream — your recent order history |
optionsSettlements | Settlements Stream — your settlement results at expiry |
optionsAccountSummary | Account Summary Stream — balance, margin used, and PnL |
optionsAccountSummary is account-wide — any contract filter on the request is ignored for it. Note that emitOptionsAccountSummary returns the current snapshot and does not subscribe you: without an active optionsAccountSummary subscription its response never reaches you.Subscribe / Unsubscribe Behavior
- Streams can be requested at connect with the
subscriptionsquery parameter, or added and removed afterwards withsubscribeandunsubscribe - Subscriptions are scoped by product: only options streams can be subscribed on a
product=optionsconnection — a perpetuals stream name is rejected withwrong_product_subscriptions - Requests are all-or-nothing: a single unrecognized stream name rejects the whole request with
invalid_subscriptions, and none of the listed streams are subscribed or unsubscribed - Subscriptions are tracked per stream and market: re-subscribing a stream for a market it is already active on, or unsubscribing it from a market it is not, is a no-op
- Subscribing a stream to a second market adds to it — it does not replace the first;
market: ALLsupersedes every specific market for that stream - Other subscriptions remain unaffected
- Changes apply immediately
- Safe to call repeatedly (idempotent)
- Does not affect other connections
- Does not require reconnecting
market in a subscribe composes with expiration, strike, and type into a contract filter exactly as described in Contract Filter, and defaults to the connection’s own filter when all four are omitted.
Multiple Markets
market is always a single string, never an array — to follow a stream on several markets, send one subscribe per market:
{
"message": "subscribe",
"content": {
"subscriptions": ["optionsQuotes"],
"market": "BTC-USDT"
}
}
{
"message": "subscribe",
"content": {
"subscriptions": ["optionsQuotes"],
"market": "ETH-USDT"
}
}
{
"resultType": "subscribed",
"data": {
"activeSubscriptions": ["optionsOrders", "optionsQuotes"],
"requestedSubscriptions": ["optionsQuotes"],
"statusCode": 200
}
}
activeSubscriptions and requestedSubscriptions are flat lists of stream names carrying no market information — a stream subscribed across several markets appears once. Track which markets each stream is active for client-side.market: ALL supersedes every specific market it was active on, dropping them. Afterwards, subscribing that stream to a specific market is a no-op — the wildcard already covers it.
Unsubscribe Market Selection
Anunsubscribe removes the listed streams for one market or for every market they are active on — the composed contract filter must match the one the stream was subscribed with. market selects what is removed:
market in the request | What is removed |
|---|---|
Omitted, blank, or ALL | The listed streams on every market they are active on |
A market (e.g. BTC-USDT), optionally narrowed by expiration, strike, and type | Only the subscription matching that composed filter |
Omitting
market on an unsubscribe, or sending ALL, removes the listed streams from every market they are active on — not from the connection’s own market. This is the opposite of subscribe, where omitting market falls back to the connection’s filter. To remove a stream from one market only, name that market explicitly.On failure the
resultType is subscribe / unsubscribe — not subscribed / unsubscribed, which confirm success only.Connection Shutdown
A connection may receive an unpromptedconnectionShutdown message, carrying the deadline by which it must be re-established.
Reconnect at any point before the deadline. The existing connection stays fully active and keeps delivering messages until it elapses, so opening the new connection first and dropping the old one once it is subscribed avoids any gap in coverage. Read forceCloseInMs from the message rather than assuming a fixed value.
A connection still open when the deadline passes is closed with WebSocket close code 1012, and messages published between that point and your reconnect are missed. Supplying a sessionId recovers missed order events on the reconnect; see WebSocket Session.Messages
{
"message": "ping",
"content": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a"
}
}{
"message": "subscribe",
"content": {
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"market": "BTC-USDT",
"expiration": "24JUN26",
"strike": "62000",
"type": "C"
}
}{
"message": "unsubscribe",
"content": {
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"optionsPublicOrderBook"
],
"market": "BTC-USDT",
"expiration": "24JUN26",
"strike": "62000",
"type": "C"
}
}{
"resultType": "pong",
"data": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a",
"statusCode": 200
}
}{
"resultType": "subscribed",
"data": {
"activeSubscriptions": [
"optionsOrders",
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"requestedSubscriptions": [
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"statusCode": 200
}
}{
"resultType": "subscribe",
"data": {
"statusCode": 400,
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"error": "wrong_product_subscriptions"
}
}{
"resultType": "unsubscribed",
"data": {
"activeSubscriptions": [
"optionsOrders",
"optionsPositions",
"optionsOpenOrders"
],
"requestedUnsubscriptions": [
"optionsPublicOrderBook"
],
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"statusCode": 200
}
}{
"resultType": "unsubscribe",
"data": {
"statusCode": 400,
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"error": "invalid_subscriptions"
}
}{
"resultType": "connectionShutdown",
"data": {
"forceCloseInMs": 60000,
"statusCode": 200,
"ts": 1785258083038
}
}market
type:string
required
A specific market (e.g. BTC-USDT) or ALL.
expiration
type:string
required
Contract expiration, e.g. 24JUN26. Requires market; omit to match every expiration.
strike
type:string
required
Strike price, e.g. 62000. Requires expiration; omit to match every strike.
type
type:string
required
C (call) or P (put). Requires strike; omit to match both.
Sec-WebSocket-Protocol
type:httpApiKey
Supply as authorization#<JWT> during the WebSocket handshake.
Ping
type:object
Subscribe
type:object
Add one or more streams to the current connection, for one or more markets.
Unsubscribe
type:object
Remove one or more streams from the current connection, for one market or all.
Pong
type:object
Subscribed
type:object
Success response to subscribe. Subscription lists are flat stream names; track markets client-side.
Subscribe — Error
type:object
Validation failure response to subscribe. Note resultType is subscribe on failure, not subscribed.
Unsubscribed
type:object
Success response to unsubscribe. Subscription lists are flat stream names; track markets client-side.
Unsubscribe — Error
type:object
Validation failure response to unsubscribe. Note resultType is unsubscribe on failure, not unsubscribed. The errors are the same as for subscribe.
Connection Shutdown
type:object
Pushed before the connection is closed, carrying the deadline by which it must be re-established.