> ## 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
> Requests available on every connection: ping, subscribe, and unsubscribe.
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
## 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_7
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
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_10
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_8
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
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_11
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_9
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
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_12
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
sendOperations:
- *ref_1
- *ref_2
- *ref_3
receiveOperations:
- *ref_4
- *ref_5
- *ref_6
sendMessages:
- *ref_7
- *ref_8
- *ref_9
receiveMessages:
- *ref_10
- *ref_11
- *ref_12
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: []
````