> ## 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.
# Order Book Stream
> Real-time order book updates and snapshots for a specific market.
This stream is available on the `publicOrderBook` subscription. It provides real-time order book updates for a specified market via `publicOrderBookDelta` push messages, plus on-demand full snapshots via `emitPublicOrderBook`.
For `publicOrderBookDelta` messages, `quantity` is the absolute size at that price level. A `quantity` of `0` means the level should be removed from your local book.
#### Snapshot vs. Delta
The `emitPublicOrderBook` request returns a full order book snapshot via `publicOrderBook`. Use it for:
* Bootstrapping order book state when first subscribing to the stream
* Recovering after temporary data loss or connection issues
* Synchronizing local book models with the current market state
* Getting the complete order book picture before processing delta updates
## AsyncAPI
````yaml latest/perps/asyncapi/perps-ws.yaml publicOrderBookStream
id: publicOrderBookStream
title: Order Book Stream
description: >
Available on the `publicOrderBook` subscription. Real-time order book deltas
and on-demand full snapshots for a specific market.
servers:
- id: sandbox
protocol: wss
host: ws.sandbox.rails.xyz
bindings: []
variables: []
address: '?product=perpetuals&market={market}&subscriptions=publicOrderBook'
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_2
id: emitPublicOrderBook
title: Emit public order book
description: >
Request a full order book snapshot. Useful for bootstrapping and
resynchronizing local book state before processing delta updates.
type: receive
messages:
- &ref_5
id: emitPublicOrderBookRequest
contentType: application/json
payload:
- name: Emit Public Order Book
type: object
properties:
- name: message
type: string
description: Always `emitPublicOrderBook`.
required: true
- name: content
type: object
required: false
properties:
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: market
type: string
description: >-
Market name, only required when connecting with
`market=ALL`
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
message:
type: string
description: Always `emitPublicOrderBook`.
x-parser-schema-id:
content:
type: object
properties:
clientRequestId:
type: string
format: uuid
description: Client-generated UUID for correlation
x-parser-schema-id:
market:
type: string
description: Market name, only required when connecting with `market=ALL`
x-parser-schema-id:
x-parser-schema-id:
required:
- message
x-parser-schema-id:
title: Emit Public Order Book
example: |-
{
"message": "emitPublicOrderBook",
"content": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a",
"market": "ETH-USDT"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: emitPublicOrderBookRequest
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: publicOrderBookStream
- &ref_3
id: publicOrderBookSnapshot
title: Public order book snapshot
description: Response to `emitPublicOrderBook`.
type: send
messages:
- &ref_6
id: publicOrderBookResponse
contentType: application/json
payload:
- name: Order Book Snapshot
description: Response to `emitPublicOrderBook`.
type: object
properties:
- name: resultType
type: string
description: Always `publicOrderBook`.
required: true
- name: market
type: string
description: Market name
required: true
- name: data
type: object
required: true
properties:
- name: clientRequestId
type: string
description: Client-generated UUID for correlation
required: false
- name: orders
type: array
description: Full order book entries
required: true
properties:
- name: orderType
type: string
description: Order side
enumValues:
- buy
- sell
required: true
- name: price
type: string
description: Price level
required: true
- name: quantity
type: string
description: >-
Size at the price level; `0` in a delta removes the
level
required: true
- name: statusCode
type: integer
description: Always `200`.
required: true
- name: ts
type: integer
description: Snapshot timestamp in milliseconds since epoch
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `publicOrderBook`.
x-parser-schema-id:
market:
type: string
description: Market name
x-parser-schema-id:
data:
type: object
properties:
clientRequestId:
type: string
description: Client-generated UUID for correlation
x-parser-schema-id:
orders:
type: array
description: Full order book entries
items: &ref_1
type: object
properties:
orderType:
type: string
enum:
- buy
- sell
description: Order side
x-parser-schema-id:
price:
type: string
description: Price level
x-parser-schema-id:
quantity:
type: string
description: >-
Size at the price level; `0` in a delta removes the
level
x-parser-schema-id:
required:
- orderType
- price
- quantity
x-parser-schema-id: OrderBookLevel
x-parser-schema-id:
statusCode:
type: integer
description: Always `200`.
x-parser-schema-id:
ts:
type: integer
description: Snapshot timestamp in milliseconds since epoch
x-parser-schema-id:
required:
- orders
- statusCode
- ts
x-parser-schema-id:
required:
- resultType
- market
- data
x-parser-schema-id:
title: Order Book Snapshot
description: Response to `emitPublicOrderBook`.
example: |-
{
"resultType": "publicOrderBook",
"market": "ETH-USDT",
"data": {
"clientRequestId": "4cc68b60-ed2d-42aa-a21e-cb5486f8fd1a",
"orders": [
{
"orderType": "buy",
"price": "3181.39",
"quantity": "38.98"
},
{
"orderType": "sell",
"price": "3181.41",
"quantity": "38.92"
}
],
"statusCode": 200,
"ts": 1772576154169
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: publicOrderBookResponse
bindings: []
extensions: *ref_0
- &ref_4
id: publicOrderBookUpdate
title: Public order book update
description: Pushed whenever the order book changes for the subscribed market.
type: send
messages:
- &ref_7
id: publicOrderBookDelta
contentType: application/json
payload:
- name: Order Book Delta
type: object
properties:
- name: resultType
type: string
description: Always `publicOrderBookDelta`.
required: true
- name: market
type: string
description: Market name
required: true
- name: data
type: object
required: true
properties:
- name: orders
type: array
description: Incremental order book changes
required: true
properties:
- name: orderType
type: string
description: Order side
enumValues:
- buy
- sell
required: true
- name: price
type: string
description: Price level
required: true
- name: quantity
type: string
description: >-
Size at the price level; `0` in a delta removes the
level
required: true
- name: statusCode
type: integer
description: Always `200`.
required: true
- name: ts
type: integer
description: Update timestamp in milliseconds since epoch
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
resultType:
type: string
description: Always `publicOrderBookDelta`.
x-parser-schema-id:
market:
type: string
description: Market name
x-parser-schema-id:
data:
type: object
properties:
orders:
type: array
description: Incremental order book changes
items: *ref_1
x-parser-schema-id:
statusCode:
type: integer
description: Always `200`.
x-parser-schema-id:
ts:
type: integer
description: Update timestamp in milliseconds since epoch
x-parser-schema-id:
required:
- orders
- statusCode
- ts
x-parser-schema-id:
required:
- resultType
- market
- data
x-parser-schema-id:
title: Order Book Delta
example: |-
{
"resultType": "publicOrderBookDelta",
"market": "ETH-USDT",
"data": {
"orders": [
{
"orderType": "sell",
"price": "3181.41",
"quantity": "38.92"
},
{
"orderType": "buy",
"price": "3181.39",
"quantity": "38.98"
}
],
"statusCode": 200,
"ts": 1772576154169
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: publicOrderBookDelta
bindings: []
extensions: *ref_0
sendOperations:
- *ref_2
receiveOperations:
- *ref_3
- *ref_4
sendMessages:
- *ref_5
receiveMessages:
- *ref_6
- *ref_7
extensions:
- id: x-parser-unique-object-id
value: publicOrderBookStream
securitySchemes:
- id: wsAuth
name: Sec-WebSocket-Protocol
type: httpApiKey
description: |
Supply as `authorization#` during the WebSocket handshake.
in: header
extensions: []
````