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

export const url_0 = "wss://ws.trade.rails.xyz?market=BTC-USDT&subscriptions=orders,trades,publicTrades,publicOrderBook"

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/rest-api/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="market" required type="string">
  Market name. Example value: `BTC-USDT`. To get all supported markets, call [/api/v1/markets](/latest/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>

#### 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
* An optional `market` field is required when connecting with `market=ALL`

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

<CardGroup cols={2}>
  <Card title="Subscribe" href="/latest/websocket-api/subscribe">
    Add streams to your connection
  </Card>

  <Card title="Unsubscribe" href="/latest/websocket-api/unsubscribe">
    Remove streams from your connection
  </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={3}>
  <Card title="Order Creation Stream" href="/latest/websocket-api/order-creation-stream">
    Order creation and cancellation requests and notifications
  </Card>

  <Card title="Trade Stream" href="/latest/websocket-api/transaction-stream">
    Real-time trade updates for your account
  </Card>

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

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

#### Common Requests

The `ping` request is available regardless of your current subscriptions and can be used to monitor connection health.

<Card title="Ping" href="/latest/websocket-api/ping">
  Connection health monitoring - available even without any subscription
</Card>

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