> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Common Requests
> Available on every connection: ping, subscribe, and unsubscribe, plus the connection shutdown notice.
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](/latest/options/websocket-api/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](/latest/options/websocket-api/contracts-stream) — contract definitions with mark price, IV, and Greeks, scoped by underlying and expiration date |
| `optionsQuotes` | [Quotes Stream](/latest/options/websocket-api/quotes-stream) — top-of-book bid/ask with IV, scoped by underlying and expiration date |
| `optionsPublicOrderBook` | [Order Book Stream](/latest/options/websocket-api/order-book-stream) — order book snapshots and deltas for a single contract |
| `optionsPublicTrades` | [Public Trades Stream](/latest/options/websocket-api/public-trades-stream) — public trade executions for a single contract |
| `optionsPositions` | [Positions Stream](/latest/options/websocket-api/positions-stream) — your open positions |
| `optionsOpenOrders` | [Open Orders Stream](/latest/options/websocket-api/open-orders-stream) — your open orders and incremental updates |
| `optionsRecentOrders` | [Recent Orders Stream](/latest/options/websocket-api/recent-orders-stream) — your recent order history |
| `optionsSettlements` | [Settlements Stream](/latest/options/websocket-api/settlements-stream) — your settlement results at expiry |
| `optionsAccountSummary` | [Account Summary Stream](/latest/options/websocket-api/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 `subscriptions` query parameter, or added and removed afterwards with `subscribe` and `unsubscribe`
* Subscriptions are scoped by product: only options streams can be subscribed on a `product=options` connection — a perpetuals stream name is rejected with `wrong_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: ALL` supersedes 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](/latest/options/websocket-api/overview#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:
```json theme={null}
{
"message": "subscribe",
"content": {
"subscriptions": ["optionsQuotes"],
"market": "BTC-USDT"
}
}
```
```json theme={null}
{
"message": "subscribe",
"content": {
"subscriptions": ["optionsQuotes"],
"market": "ETH-USDT"
}
}
```
The connection now receives quotes for both BTC-USDT and ETH-USDT contracts. Each request is confirmed with the same flat list:
```json theme={null}
{
"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.
Subscribing a stream with `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
An `unsubscribe` 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 unprompted `connectionShutdown` 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](/latest/websocket-session).
## AsyncAPI
````yaml latest/options/asyncapi/options-ws.yaml commonRequests
id: commonRequests
title: Common Requests
description: >
Requests and responses available on every connection regardless of active
subscriptions.
servers:
- id: sandbox
protocol: wss
host: ws.sandbox.rails.xyz
bindings: []
variables: []
address: >-
?product=options&market={market}&expiration={expiration}&strike={strike}&type={type}
parameters:
- id: market
jsonSchema:
type: string
description: A specific market (e.g. `BTC-USDT`) or `ALL`.
default: BTC-USDT
description: A specific market (e.g. `BTC-USDT`) or `ALL`.
type: string
required: true
deprecated: false
- id: expiration
jsonSchema:
type: string
description: >-
Contract expiration, e.g. `24JUN26`. Requires `market`; omit to match
every expiration.
default: 24JUN26
description: >-
Contract expiration, e.g. `24JUN26`. Requires `market`; omit to match
every expiration.
type: string
required: true
deprecated: false
- id: strike
jsonSchema:
type: string
description: >-
Strike price, e.g. `62000`. Requires `expiration`; omit to match every
strike.
default: '62000'
description: >-
Strike price, e.g. `62000`. Requires `expiration`; omit to match every
strike.
type: string
required: true
deprecated: false
- id: type
jsonSchema:
type: string
description: '`C` (call) or `P` (put). Requires `strike`; omit to match both.'
default: C
description: '`C` (call) or `P` (put). Requires `strike`; omit to match both.'
type: string
required: true
deprecated: false
bindings: []
operations:
- &ref_1
id: ping
title: Ping
description: Application-level heartbeat, available with or without a subscription.
type: receive
messages:
- &ref_8
id: pingRequest
contentType: application/json
payload:
- name: Ping
type: object
properties:
- name: message
type: string
description: Always `ping`.
required: true
- name: content
type: object
required: false
properties:
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
message:
type: string
description: Always `ping`.
x-parser-schema-id:
content:
type: object
properties:
clientRequestId:
type: string
format: uuid
description: Client-generated UUID for correlation
x-parser-schema-id:
x-parser-schema-id:
required:
- message
x-parser-schema-id:
title: Ping
example: |-
{
"message": "ping",
"content": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: pingRequest
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: commonRequests
- &ref_4
id: pong
title: Pong
type: send
messages:
- &ref_11
id: pongResponse
contentType: application/json
payload:
- name: Pong
type: object
properties:
- name: resultType
type: string
description: Always `pong`.
required: true
- name: data
type: object
required: true
properties:
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: statusCode
type: integer
description: Always `200`.
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `pong`.
x-parser-schema-id:
data:
type: object
properties:
clientRequestId:
type: string
description: Client-generated UUID for correlation
x-parser-schema-id:
statusCode:
type: integer
description: Always `200`.
x-parser-schema-id:
required:
- statusCode
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Pong
example: |-
{
"resultType": "pong",
"data": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a",
"statusCode": 200
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: pongResponse
bindings: []
extensions: *ref_0
- &ref_2
id: subscribe
title: Subscribe
description: >-
Add one or more streams to the current connection, for one market or
several.
type: receive
messages:
- &ref_9
id: subscribeRequest
contentType: application/json
payload:
- name: Subscribe
description: >-
Add one or more streams to the current connection, for one or more
markets.
type: object
properties:
- name: message
type: string
description: Always `subscribe`.
required: true
- name: content
type: object
required: true
properties:
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: subscriptions
type: array
description: One or more subscriptions to add
required: true
properties:
- name: item
type: string
enumValues:
- optionsOrders
- optionsContracts
- optionsQuotes
- optionsPublicOrderBook
- optionsPublicTrades
- optionsPositions
- optionsOpenOrders
- optionsRecentOrders
- optionsSettlements
- optionsAccountSummary
required: false
- name: market
type: string
description: >
A market, e.g. `BTC-USDT`, or `ALL` for every market.
Always a single string, never an array — send one
`subscribe` per market to follow several. Composes with
`expiration`, `strike`, and `type` into a contract filter
exactly as on the connection URL (a packed contract name
is rejected). Omitting all four applies the connection's
own filter. Defaults to the connection's market
required: false
- name: expiration
type: string
description: Contract expiration, e.g. `24JUN26`. Requires `market`
required: false
- name: strike
type: string
description: Strike price, e.g. `62000`. Requires `expiration`
required: false
- name: type
type: string
description: '`C` (call) or `P` (put). Requires `strike`'
enumValues:
- C
- P
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
message:
type: string
description: Always `subscribe`.
x-parser-schema-id:
content:
type: object
properties:
clientRequestId:
type: string
format: uuid
description: Client-generated UUID for correlation
x-parser-schema-id:
subscriptions:
type: array
description: One or more subscriptions to add
items:
type: string
enum:
- optionsOrders
- optionsContracts
- optionsQuotes
- optionsPublicOrderBook
- optionsPublicTrades
- optionsPositions
- optionsOpenOrders
- optionsRecentOrders
- optionsSettlements
- optionsAccountSummary
x-parser-schema-id:
x-parser-schema-id:
market:
type: string
description: >
A market, e.g. `BTC-USDT`, or `ALL` for every market. Always
a single string, never an array — send one `subscribe` per
market to follow several. Composes with `expiration`,
`strike`, and `type` into a contract filter exactly as on
the connection URL (a packed contract name is rejected).
Omitting all four applies the connection's own filter.
Defaults to the connection's market
x-parser-schema-id:
expiration:
type: string
description: Contract expiration, e.g. `24JUN26`. Requires `market`
x-parser-schema-id:
strike:
type: string
description: Strike price, e.g. `62000`. Requires `expiration`
x-parser-schema-id:
type:
type: string
enum:
- C
- P
description: '`C` (call) or `P` (put). Requires `strike`'
x-parser-schema-id:
required:
- subscriptions
x-parser-schema-id:
required:
- message
- content
x-parser-schema-id:
title: Subscribe
description: >-
Add one or more streams to the current connection, for one or more
markets.
example: |-
{
"message": "subscribe",
"content": {
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"market": "BTC-USDT",
"expiration": "24JUN26",
"strike": "62000",
"type": "C"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribeRequest
bindings: []
extensions: *ref_0
- &ref_5
id: subscribed
title: Subscribed
description: Confirmation (200) or error response (400) to `subscribe`.
type: send
messages:
- &ref_12
id: subscribedResponse
contentType: application/json
payload:
- name: Subscribed
description: >-
Success response to `subscribe`. Subscription lists are flat
stream names; track markets client-side.
type: object
properties:
- name: resultType
type: string
description: Always `subscribed`.
required: true
- name: data
type: object
required: true
properties:
- name: activeSubscriptions
type: array
description: >
All currently active subscriptions after the operation. A
flat list of stream names carrying no market information
required: true
properties:
- name: item
type: string
required: false
- name: requestedSubscriptions
type: array
description: The specific subscriptions that were requested to be added
required: true
properties:
- name: item
type: string
required: false
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: statusCode
type: integer
description: Always `200`.
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `subscribed`.
x-parser-schema-id:
data:
type: object
properties:
activeSubscriptions:
type: array
description: >
All currently active subscriptions after the operation. A
flat list of stream names carrying no market information
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
requestedSubscriptions:
type: array
description: The specific subscriptions that were requested to be added
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
clientRequestId:
type: string
description: Client-generated UUID for correlation
x-parser-schema-id:
statusCode:
type: integer
description: Always `200`.
x-parser-schema-id:
required:
- activeSubscriptions
- requestedSubscriptions
- statusCode
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Subscribed
description: >-
Success response to `subscribe`. Subscription lists are flat stream
names; track markets client-side.
example: |-
{
"resultType": "subscribed",
"data": {
"activeSubscriptions": [
"optionsOrders",
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"requestedSubscriptions": [
"optionsPositions",
"optionsOpenOrders",
"optionsPublicOrderBook"
],
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"statusCode": 200
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribedResponse
- &ref_13
id: subscribeError
contentType: application/json
payload:
- name: Subscribe — Error
description: >
Validation failure response to `subscribe`. Note `resultType` is
`subscribe` on failure, not `subscribed`.
type: object
properties:
- name: resultType
type: string
description: Always `subscribe`.
required: true
- name: data
type: object
required: true
properties:
- name: statusCode
type: integer
description: Always `400`.
required: true
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: error
type: string
description: >
`invalid_subscriptions` — `subscriptions` is missing,
empty, not an array, or contains any name that is not a
valid options stream (one bad name rejects the whole
request); `wrong_product_subscriptions` — `subscriptions`
contains a perpetuals stream name; the remaining slugs
report an invalid contract filter (`market`, `expiration`,
`strike`, `type`), with the same meaning as at the
handshake
enumValues:
- invalid_subscriptions
- wrong_product_subscriptions
- market_required
- invalid_market
- legacy_options_market
- missing_expiration
- missing_strike
- invalid_expiration
- invalid_strike
- invalid_type
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `subscribe`.
x-parser-schema-id:
data:
type: object
properties:
statusCode:
type: integer
description: Always `400`.
x-parser-schema-id:
clientRequestId:
type: string
description: Client-generated UUID for correlation
x-parser-schema-id:
error:
type: string
enum:
- invalid_subscriptions
- wrong_product_subscriptions
- market_required
- invalid_market
- legacy_options_market
- missing_expiration
- missing_strike
- invalid_expiration
- invalid_strike
- invalid_type
description: >
`invalid_subscriptions` — `subscriptions` is missing, empty,
not an array, or contains any name that is not a valid
options stream (one bad name rejects the whole request);
`wrong_product_subscriptions` — `subscriptions` contains a
perpetuals stream name; the remaining slugs report an
invalid contract filter (`market`, `expiration`, `strike`,
`type`), with the same meaning as at the handshake
x-parser-schema-id:
required:
- statusCode
- error
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Subscribe — Error
description: >
Validation failure response to `subscribe`. Note `resultType` is
`subscribe` on failure, not `subscribed`.
example: |-
{
"resultType": "subscribe",
"data": {
"statusCode": 400,
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"error": "wrong_product_subscriptions"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribeError
bindings: []
extensions: *ref_0
- &ref_3
id: unsubscribe
title: Unsubscribe
description: >-
Remove one or more streams from the current connection, for one market or
every market.
type: receive
messages:
- &ref_10
id: unsubscribeRequest
contentType: application/json
payload:
- name: Unsubscribe
description: >-
Remove one or more streams from the current connection, for one
market or all.
type: object
properties:
- name: message
type: string
description: Always `unsubscribe`.
required: true
- name: content
type: object
required: true
properties:
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: subscriptions
type: array
description: One or more subscriptions to remove
required: true
properties:
- name: item
type: string
enumValues:
- optionsOrders
- optionsContracts
- optionsQuotes
- optionsPublicOrderBook
- optionsPublicTrades
- optionsPositions
- optionsOpenOrders
- optionsRecentOrders
- optionsSettlements
- optionsAccountSummary
required: false
- name: market
type: string
description: >
A market, e.g. `BTC-USDT`. Omitting it, or sending `ALL`,
removes the listed streams from **every market they are
active on** — unlike `subscribe`, it does not fall back to
the connection's own market. Composes with `expiration`,
`strike`, and `type` into a contract filter exactly as on
the connection URL
required: false
- name: expiration
type: string
description: Contract expiration, e.g. `24JUN26`. Requires `market`
required: false
- name: strike
type: string
description: Strike price, e.g. `62000`. Requires `expiration`
required: false
- name: type
type: string
description: '`C` (call) or `P` (put). Requires `strike`'
enumValues:
- C
- P
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
message:
type: string
description: Always `unsubscribe`.
x-parser-schema-id:
content:
type: object
properties:
clientRequestId:
type: string
format: uuid
description: Client-generated UUID for correlation
x-parser-schema-id:
subscriptions:
type: array
description: One or more subscriptions to remove
items:
type: string
enum:
- optionsOrders
- optionsContracts
- optionsQuotes
- optionsPublicOrderBook
- optionsPublicTrades
- optionsPositions
- optionsOpenOrders
- optionsRecentOrders
- optionsSettlements
- optionsAccountSummary
x-parser-schema-id:
x-parser-schema-id:
market:
type: string
description: >
A market, e.g. `BTC-USDT`. Omitting it, or sending `ALL`,
removes the listed streams from **every market they are
active on** — unlike `subscribe`, it does not fall back to
the connection's own market. Composes with `expiration`,
`strike`, and `type` into a contract filter exactly as on
the connection URL
x-parser-schema-id:
expiration:
type: string
description: Contract expiration, e.g. `24JUN26`. Requires `market`
x-parser-schema-id:
strike:
type: string
description: Strike price, e.g. `62000`. Requires `expiration`
x-parser-schema-id:
type:
type: string
enum:
- C
- P
description: '`C` (call) or `P` (put). Requires `strike`'
x-parser-schema-id:
required:
- subscriptions
x-parser-schema-id:
required:
- message
- content
x-parser-schema-id:
title: Unsubscribe
description: >-
Remove one or more streams from the current connection, for one market
or all.
example: |-
{
"message": "unsubscribe",
"content": {
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"optionsPublicOrderBook"
],
"market": "BTC-USDT",
"expiration": "24JUN26",
"strike": "62000",
"type": "C"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribeRequest
bindings: []
extensions: *ref_0
- &ref_6
id: unsubscribed
title: Unsubscribed
description: Confirmation (200) or error response (400) to `unsubscribe`.
type: send
messages:
- &ref_14
id: unsubscribedResponse
contentType: application/json
payload:
- name: Unsubscribed
description: >-
Success response to `unsubscribe`. Subscription lists are flat
stream names; track markets client-side.
type: object
properties:
- name: resultType
type: string
description: Always `unsubscribed`.
required: true
- name: data
type: object
required: true
properties:
- name: activeSubscriptions
type: array
description: >
All currently active subscriptions after the operation. A
flat list of stream names carrying no market information
required: true
properties:
- name: item
type: string
required: false
- name: requestedUnsubscriptions
type: array
description: >-
The specific subscriptions that were requested to be
removed
required: true
properties:
- name: item
type: string
required: false
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: statusCode
type: integer
description: Always `200`.
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `unsubscribed`.
x-parser-schema-id:
data:
type: object
properties:
activeSubscriptions:
type: array
description: >
All currently active subscriptions after the operation. A
flat list of stream names carrying no market information
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
requestedUnsubscriptions:
type: array
description: The specific subscriptions that were requested to be removed
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
clientRequestId:
type: string
description: Client-generated UUID for correlation
x-parser-schema-id:
statusCode:
type: integer
description: Always `200`.
x-parser-schema-id:
required:
- activeSubscriptions
- requestedUnsubscriptions
- statusCode
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Unsubscribed
description: >-
Success response to `unsubscribe`. Subscription lists are flat stream
names; track markets client-side.
example: |-
{
"resultType": "unsubscribed",
"data": {
"activeSubscriptions": [
"optionsOrders",
"optionsPositions",
"optionsOpenOrders"
],
"requestedUnsubscriptions": [
"optionsPublicOrderBook"
],
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"statusCode": 200
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribedResponse
- &ref_15
id: unsubscribeError
contentType: application/json
payload:
- name: Unsubscribe — Error
description: >
Validation failure response to `unsubscribe`. Note `resultType` is
`unsubscribe` on failure, not `unsubscribed`. The errors are the
same as for `subscribe`.
type: object
properties:
- name: resultType
type: string
description: Always `unsubscribe`.
required: true
- name: data
type: object
required: true
properties:
- name: statusCode
type: integer
description: Always `400`.
required: true
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: error
type: string
description: >
`invalid_subscriptions` — `subscriptions` is missing,
empty, not an array, or contains any name that is not a
valid options stream (one bad name rejects the whole
request); `wrong_product_subscriptions` — `subscriptions`
contains a perpetuals stream name; the remaining slugs
report an invalid contract filter (`market`, `expiration`,
`strike`, `type`), with the same meaning as at the
handshake
enumValues:
- invalid_subscriptions
- wrong_product_subscriptions
- market_required
- invalid_market
- legacy_options_market
- missing_expiration
- missing_strike
- invalid_expiration
- invalid_strike
- invalid_type
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `unsubscribe`.
x-parser-schema-id:
data:
type: object
properties:
statusCode:
type: integer
description: Always `400`.
x-parser-schema-id:
clientRequestId:
type: string
description: Client-generated UUID for correlation
x-parser-schema-id:
error:
type: string
enum:
- invalid_subscriptions
- wrong_product_subscriptions
- market_required
- invalid_market
- legacy_options_market
- missing_expiration
- missing_strike
- invalid_expiration
- invalid_strike
- invalid_type
description: >
`invalid_subscriptions` — `subscriptions` is missing, empty,
not an array, or contains any name that is not a valid
options stream (one bad name rejects the whole request);
`wrong_product_subscriptions` — `subscriptions` contains a
perpetuals stream name; the remaining slugs report an
invalid contract filter (`market`, `expiration`, `strike`,
`type`), with the same meaning as at the handshake
x-parser-schema-id:
required:
- statusCode
- error
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Unsubscribe — Error
description: >
Validation failure response to `unsubscribe`. Note `resultType` is
`unsubscribe` on failure, not `unsubscribed`. The errors are the same
as for `subscribe`.
example: |-
{
"resultType": "unsubscribe",
"data": {
"statusCode": 400,
"clientRequestId": "b21f0f58-8780-4cf2-b3d3-6439fed37304",
"error": "invalid_subscriptions"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribeError
bindings: []
extensions: *ref_0
- &ref_7
id: connectionShutdown
title: Connection shutdown
description: >-
Pushed unprompted when the connection is scheduled to close; reconnect
before the deadline it carries.
type: send
messages:
- &ref_16
id: connectionShutdownNotice
contentType: application/json
payload:
- name: Connection Shutdown
description: >-
Pushed before the connection is closed, carrying the deadline by
which it must be re-established.
type: object
properties:
- name: resultType
type: string
description: Always `connectionShutdown`.
required: true
- name: data
type: object
required: true
properties:
- name: forceCloseInMs
type: integer
description: >-
Milliseconds from this message until the connection is
closed.
required: true
- name: statusCode
type: integer
description: Always `200`.
required: true
- name: ts
type: integer
description: When this notice was sent, in epoch milliseconds.
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `connectionShutdown`.
x-parser-schema-id:
data:
type: object
properties:
forceCloseInMs:
type: integer
description: >-
Milliseconds from this message until the connection is
closed.
x-parser-schema-id:
statusCode:
type: integer
description: Always `200`.
x-parser-schema-id:
ts:
type: integer
description: When this notice was sent, in epoch milliseconds.
x-parser-schema-id:
required:
- forceCloseInMs
- statusCode
- ts
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Connection Shutdown
description: >-
Pushed before the connection is closed, carrying the deadline by which
it must be re-established.
example: |-
{
"resultType": "connectionShutdown",
"data": {
"forceCloseInMs": 60000,
"statusCode": 200,
"ts": 1785258083038
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: connectionShutdownNotice
bindings: []
extensions: *ref_0
sendOperations:
- *ref_1
- *ref_2
- *ref_3
receiveOperations:
- *ref_4
- *ref_5
- *ref_6
- *ref_7
sendMessages:
- *ref_8
- *ref_9
- *ref_10
receiveMessages:
- *ref_11
- *ref_12
- *ref_13
- *ref_14
- *ref_15
- *ref_16
extensions:
- id: x-parser-unique-object-id
value: commonRequests
securitySchemes:
- id: wsAuth
name: Sec-WebSocket-Protocol
type: httpApiKey
description: Supply as `authorization#` during the WebSocket handshake.
in: header
extensions: []
````