Skip to main content
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

wss://ws.sandbox.rails.xyz?market=BTC-19JUN26-62000-C

​
Authorizations

See Get Access Token on how to retrieve the token. Set Sec-WebSocket-Protocol during the handshake or on connect().
​
Sec-WebSocket-Protocol
string
required
Example value (authorization token):
authorization#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdGFnaW5nLmZ1bmdpYmxlLnh5eiIsInN1YiI6ImQxM2I1MzBmLWFmNzMtNDBmOS04ZjhlLWVkNzk1OTU3YTU3ZiIsImF1ZCI6WyJzdGFnaW5nLWFwcC5mdW5naWJsZS54eXoiXSwiZXhwIjoxNzAzMzA1NzQwLCJpYXQiOjE3MDMzMDM5NDB9.vsHe4G_yEkRfz8XNoTKcX83udA-LUysWD4q80wfCC8k

​
Query Parameters

​
market
string
required
Option contract name. Example value: BTC-19JUN26-62000-C. To connect across all contracts, use the value ALL.

​
Request Envelope

All WebSocket requests follow the same top-level structure: 
{
  "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: 
{
  "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.

Subscribe

Add streams to your connection

Unsubscribe

Remove streams from your connection

​
Supported Streams

Check out their respective documentation for details on the data they provide and any supported requests.

Order Creation Stream

Create, modify, and cancel orders, with fill and rejection notifications

Contracts Stream

Contract definitions with live mark price, IV, and Greeks

Quotes Stream

Top-of-book bid/ask with implied volatility per contract

Order Book Stream

Full order book snapshots and deltas for a contract

Public Trades Stream

Real-time public trade executions for a contract

Positions Stream

Open positions with mark price, margin, and PnL

Open Orders Stream

Your open orders and incremental updates

Recent Orders Stream

Recent order history

Account Summary Stream

Balance, margin used, and PnL

Settlements Stream

Settlement results at expiry

​
Common Requests

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

Ping

Connection health monitoring - available even without any subscription

​
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