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

The Rails WebSocket API provides real-time contracts, quotes, order books, trades, positions, and account state, and is used to place and manage orders — 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. Streams are added after connecting using explicit requests.

#### URL

<pre>
  <code>wss\://ws.sandbox.rails.xyz?market=BTC-19JUN26-62000-C</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="market" required type="string">
  Option contract name. Example value: `BTC-19JUN26-62000-C`. To connect across all contracts, use the value `ALL`.
</ParamField>

#### Request Envelope

All WebSocket requests follow the same top-level structure:

```json theme={null}
{
  "message":"<requestType>",
  "content":{
    "clientRequestId":"<UUID>", // 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

#### Response Envelope

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

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

* `resultType` identifies the type of response or message (e.g., "optionsContracts", "publicOrderBookDelta")
* `data` contains the response or message payload, including a `statusCode` and, where relevant, the `market`

#### Dynamic Subscriptions

The Order Creation Stream (`orders`) is subscribed by default when you connect. All other streams are added after connecting using explicit `subscribe` and `unsubscribe` requests — they cannot be specified in the connection URL. Market-data streams for contracts and quotes are scoped by underlying and expiration date; order book and trades are scoped by contract; account streams are scoped to your account.

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

  <Card title="Unsubscribe" href="/latest/options/websocket-api/unsubscribe">
    Remove streams from your connection
  </Card>
</CardGroup>

#### Supported Streams

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/options/websocket-api/order-creation-stream/overview">
    Create, modify, and cancel orders, with fill and rejection notifications
  </Card>

  <Card title="Contracts Stream" href="/latest/options/websocket-api/contracts-stream">
    Contract definitions with live mark price, IV, and Greeks
  </Card>

  <Card title="Quotes Stream" href="/latest/options/websocket-api/quotes-stream">
    Top-of-book bid/ask with implied volatility per contract
  </Card>

  <Card title="Order Book Stream" href="/latest/options/websocket-api/order-book-stream">
    Full order book snapshots and deltas for a contract
  </Card>

  <Card title="Public Trades Stream" href="/latest/options/websocket-api/public-trades-stream">
    Real-time public trade executions for a contract
  </Card>

  <Card title="Positions Stream" href="/latest/options/websocket-api/positions-stream">
    Open positions with mark price, margin, and PnL
  </Card>

  <Card title="Open Orders Stream" href="/latest/options/websocket-api/open-orders-stream">
    Your open orders and incremental updates
  </Card>

  <Card title="Recent Orders Stream" href="/latest/options/websocket-api/recent-orders-stream">
    Recent order history
  </Card>

  <Card title="Account Summary Stream" href="/latest/options/websocket-api/account-summary-stream">
    Balance, margin used, and PnL
  </Card>

  <Card title="Settlements Stream" href="/latest/options/websocket-api/settlements-stream">
    Settlement results at expiry
  </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/options/websocket-api/ping">
  Connection health monitoring - available even without any subscription
</Card>

#### Deterministic Delivery

Multiple WebSocket connections with identical connection 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