> ## 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.
#### Allowed Subscription Values
| Subscription Value | Description |
| ------------------ | ----------------------------------------------------------------- |
| `orders` | Order creation and cancellation requests and notifications |
| `trades` | Real-time trade updates for your account |
| `publicTrades` | Real-time trade updates and snapshots for subscribed markets |
| `publicOrderBook` | Real-time order book updates and snapshots for subscribed markets |
#### Subscribe / Unsubscribe Behavior
* Only new (or currently active) subscriptions are added (or removed) — re-subscribing to an already active subscription, or unsubscribing from an inactive one, is a no-op
* Other subscriptions remain unaffected
* Changes apply immediately
* Safe to call repeatedly (idempotent)
* Does not affect other connections
* Does not require reconnecting
#### 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/perps/asyncapi/perps-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=perpetuals&market={market}'
parameters:
- id: market
jsonSchema:
type: string
description: >
A specific market (e.g. `BTC-USDT`) or `ALL`. When `ALL` is used,
`market` must be supplied explicitly in the `content` of every request
that accepts it.
default: BTC-USDT
description: >
A specific market (e.g. `BTC-USDT`) or `ALL`. When `ALL` is used, `market`
must be supplied explicitly in the `content` of every request that accepts
it.
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
description: Connection health check.
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
description: Connection health check.
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. Idempotent.
type: receive
messages:
- &ref_9
id: subscribeRequest
contentType: application/json
payload:
- name: Subscribe
description: Add one or more streams to the current connection.
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:
- orders
- trades
- publicTrades
- publicOrderBook
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:
- orders
- trades
- publicTrades
- publicOrderBook
x-parser-schema-id:
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.
example: |-
{
"message": "subscribe",
"content": {
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"subscriptions": [
"trades",
"publicTrades",
"publicOrderBook"
]
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribeRequest
bindings: []
extensions: *ref_0
- &ref_5
id: subscribed
title: Subscribed
type: send
messages:
- &ref_12
id: subscribedResponse
contentType: application/json
payload:
- name: Subscribed
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
required: true
properties:
- name: item
type: string
required: false
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
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
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
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
clientRequestId:
type: string
description: Client-generated UUID for correlation
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:
required:
- activeSubscriptions
- requestedSubscriptions
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Subscribed
example: |-
{
"resultType": "subscribed",
"data": {
"activeSubscriptions": [
"orders",
"trades",
"publicTrades",
"publicOrderBook"
],
"clientRequestId": "cfff0f58-8780-4cf2-b3d3-6439fed37304",
"requestedSubscriptions": [
"trades",
"publicTrades",
"publicOrderBook"
]
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribedResponse
bindings: []
extensions: *ref_0
- &ref_3
id: unsubscribe
title: Unsubscribe
description: Remove one or more streams from the current connection. Idempotent.
type: receive
messages:
- &ref_10
id: unsubscribeRequest
contentType: application/json
payload:
- name: Unsubscribe
description: Remove one or more streams from the current connection.
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:
- orders
- trades
- publicTrades
- publicOrderBook
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:
- orders
- trades
- publicTrades
- publicOrderBook
x-parser-schema-id:
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.
example: |-
{
"message": "unsubscribe",
"content": {
"clientRequestId": "245867a5-0de9-4542-a9da-724577ab4102",
"subscriptions": [
"trades",
"publicTrades",
"publicOrderBook"
]
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribeRequest
bindings: []
extensions: *ref_0
- &ref_6
id: unsubscribed
title: Unsubscribed
type: send
messages:
- &ref_13
id: unsubscribedResponse
contentType: application/json
payload:
- name: Unsubscribed
type: object
properties:
- name: resultType
type: string
description: Always `unsubscribed`.
required: true
- name: data
type: object
required: true
properties:
- name: activeSubscriptions
type: array
description: Remaining active subscriptions after the operation
required: true
properties:
- name: item
type: string
required: false
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
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
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `unsubscribed`.
x-parser-schema-id:
data:
type: object
properties:
activeSubscriptions:
type: array
description: Remaining active subscriptions after the operation
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
clientRequestId:
type: string
description: Client-generated UUID for correlation
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:
required:
- activeSubscriptions
- requestedUnsubscriptions
x-parser-schema-id:
required:
- resultType
- data
x-parser-schema-id:
title: Unsubscribed
example: |-
{
"resultType": "unsubscribed",
"data": {
"activeSubscriptions": [
"orders"
],
"clientRequestId": "245867a5-0de9-4542-a9da-724577ab4102",
"requestedUnsubscriptions": [
"trades",
"publicTrades",
"publicOrderBook"
]
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribedResponse
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_14
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
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: []
````