> ## 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.

# Overview

> Real-time market data, order updates, and execution events for Rails Perpetuals.

export const url_0 = "wss://ws.sandbox.rails.xyz?product=perpetuals&market=BTC-USDT&subscriptions=orders,trades,publicTrades,publicOrderBook&sessionId=d785d51c-054e-4e33-9738-92d04ede9fab"

The Rails WebSocket API provides real-time market data, order updates, and execution events with the guarantees required by professional trading systems.

It is designed to remain predictable, secure, and low-latency even during periods of extreme market activity.

The API adopts a subscription model that gives you control over which real-time streams your connection receives.
Subscriptions can be specified either at connection time via query parameters or dynamically modified after connecting using explicit requests.

#### URL

<pre>
  <code>
    {url_0}
  </code>
</pre>

***

#### Authorizations

See [Get Access Token](/latest/get-access-token) on how to retrieve the token. Set `Sec-WebSocket-Protocol` during the handshake or on `connect()`.

<ParamField header="Sec-WebSocket-Protocol" required type="string">
  Example value (authorization token):

  ```
  authorization#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdGFnaW5nLmZ1bmdpYmxlLnh5eiIsInN1YiI6ImQxM2I1MzBmLWFmNzMtNDBmOS04ZjhlLWVkNzk1OTU3YTU3ZiIsImF1ZCI6WyJzdGFnaW5nLWFwcC5mdW5naWJsZS54eXoiXSwiZXhwIjoxNzAzMzA1NzQwLCJpYXQiOjE3MDMzMDM5NDB9.vsHe4G_yEkRfz8XNoTKcX83udA-LUysWD4q80wfCC8k
  ```
</ParamField>

#### Query Parameters

<ParamField query="product" required type="string">
  Always `perpetuals` for this API.
</ParamField>

<ParamField query="market" required type="string">
  Market name. Example value: `BTC-USDT`. To get all supported markets, call [/api/v1/markets](/latest/perps/rest-api/get-supported-markets) endpoint. To subscribe to all markets, use the value `ALL`.
</ParamField>

<ParamField query="subscriptions" type="string">
  Comma-separated list of subscription types. Supported subscription types: `orders`, `trades`, `publicTrades`, `publicOrderBook`. Defaults to `orders` if omitted.
</ParamField>

<ParamField query="sessionId" type="string">
  UUID identifying a session. Enables [WebSocket Session](/latest/websocket-session) on the [Order Creation Stream](/latest/perps/websocket-api/order-creation-stream) (subscription type `orders`). Omit to opt out.
</ParamField>

#### Recommended: Per-Market Connections

While the WebSocket API supports connecting with `market=ALL` for convenience, we strongly recommend establishing separate connections per market (e.g., `market=BTC-USDT`) whenever possible.

**Why?**

Using `market=ALL` means a single WebSocket connection is responsible for all market data and events. If that connection experiences issues (e.g., network instability, client-side bugs, or resource exhaustion), it can disrupt data for *all* markets at once. In contrast, per-market connections isolate risk: a problem with one market's connection will not impact others.

**Best Practice:**

* Use `market=BTC-USDT`, `market=ETH-USDT`, etc., in your connection URLs to create one connection per market you care about.
* Reserve `market=ALL` for development, quick testing, or when you are certain your client can robustly handle all markets in a single connection.

This approach ensures greater reliability and fault isolation for production trading systems.

#### Request Envelope

All WebSocket requests follow the same top-level structure:

```json theme={null}
{
  "message":"<requestType>",
  "content":{
    "clientRequestId":"<UUID>", // optional
    "market":"BTC-USDT", // optional
      ...
  }
}
```

* `message` defines the request type
* `content` contains request-specific parameters (can be omitted if no parameters)
* An optional `clientRequestId` field is supported for correlation, and must be a UUID, unique per request
* An optional `market` field is required when connecting with `market=ALL`

Reusing a `clientRequestId` on `createOrder`, `modifyOrder`, `cancelOrder`, or `updateMargin` within 60 seconds returns a `409` — the original request stands and is not executed a second time.

```json theme={null}
{
  "resultType": "createOrder",
  "data": {
    "statusCode": 409,
    "clientRequestId": "2f6635e5-bdab-4fbc-8e2e-21252d2219dc",
    "error": "duplicate clientRequestId, request already accepted"
  }
}
```

`resultType` echoes the `message` of the request that was rejected.

#### Response Envelope

All WebSocket responses and stream messages follow a consistent top-level structure:

```json theme={null}
{
  "resultType": "<responseType>",
  "market": "BTC-USDT", // optional
  "data": {
    // response-specific fields...
  }
}
```

* `resultType` identifies the type of response or message (e.g., "subscribed", "publicOrderBookDelta")
* An optional `market` field indicates the market associated with the response or message
* `data` contains the response or message payload

#### Dynamic Subscriptions

You can modify subscriptions dynamically after connecting using explicit `subscribe` and `unsubscribe` requests, documented alongside `ping` on the Common Requests page.

<CardGroup cols={1}>
  <Card title="Common Requests" href="/latest/perps/websocket-api/common-requests">
    Ping, subscribe, unsubscribe, and the connection shutdown notice - available even without any subscription
  </Card>
</CardGroup>

#### Supported Streams

There are four streams you can subscribe to. Check out their respective documentation for details on the data they provide and any supported requests.

<CardGroup cols={2}>
  <Card title="Order Creation Stream" href="/latest/perps/websocket-api/order-creation-stream">
    Order creation and cancellation requests and notifications
  </Card>

  <Card title="Account Trades Stream" href="/latest/perps/websocket-api/account-trades-stream">
    Real-time trade updates for your account
  </Card>

  <Card title="Public Trades Stream" href="/latest/perps/websocket-api/public-trades-stream">
    Real-time trade updates and snapshots for subscribed markets
  </Card>

  <Card title="Order Book Stream" href="/latest/perps/websocket-api/order-book-stream">
    Real-time order book updates and snapshots for subscribed markets
  </Card>
</CardGroup>

#### Deterministic Delivery

Multiple WebSocket connections with identical market and subscription parameters receive the same sequence of events with no per-connection filtering or divergence.

This enables:

* Multiple parallel connections for redundancy
* Hot standby consumers for failover
* Independent processes handling the same events
* Focused connections for specific stream subsets