Skip to main content
The Exchange WebSocket API provides real-time market data updates for trading pairs. Connect to receive live order book depth, trades, and ticker information with low latency.

​
Connection endpoint

Connect to the WebSocket server using the following endpoint: 
ws://your-exchange-domain/ws
The actual URL is configured via the WS_STREAM_URL environment variable on the server.

​
Connection process

1

Establish WebSocket connection

Open a WebSocket connection to the endpoint. The server accepts standard WebSocket handshake requests.
const ws = new WebSocket('ws://your-exchange-domain/ws');

ws.onopen = () => {
  console.log('Connected to Exchange WebSocket');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Connection closed');
};
2

Send subscription messages

After connecting, send subscription requests to start receiving market data. See the Subscriptions page for details.
3

Receive real-time updates

The server will push updates to you as they occur. Messages are sent as text frames containing JSON data.

​
Message format

​
Client messages

All messages sent from the client to the server must be JSON objects with the following structure: 
{
  "method": "SUBSCRIBE" | "UNSUBSCRIBE",
  "params": ["stream_name"],
  "id": 1
}
FieldTypeDescription
methodstringThe action to perform: SUBSCRIBE or UNSUBSCRIBE
paramsarrayArray of stream identifiers to subscribe/unsubscribe
idnumberRequest identifier for tracking

​
Server messages

The server sends updates as JSON objects with this structure: 
{
  "stream": "trade.BTC_USDT",
  "data": {
    "e": "trade",
    "s": "BTC_USDT",
    "E": 1727866324128584,
    "T": 1727866324088922,
    "U": 4977146,
    "a": [["1.0003", "0"]],
    "b": []
  }
}
FieldTypeDescription
streamstringThe stream identifier this data belongs to
dataobjectThe actual market data (format varies by stream type)

​
Connection management

​
Closing connections

To gracefully close the connection, send a WebSocket close frame. The server will:
  1. Remove you from all subscriptions
  2. Clean up your user session
  3. Acknowledge the close
ws.close();

​
Error handling

The server handles various error scenarios:
Protocol errors: Invalid WebSocket frames will log a protocol error and close the connection.
Connection errors: Network issues or unexpected disconnections will trigger automatic cleanup of your subscriptions.
Invalid messages: Non-JSON or improperly formatted messages are silently ignored. Ensure your messages match the expected format.

​
Reconnection strategy

If your connection drops, implement a reconnection strategy: 
function connect() {
  const ws = new WebSocket('ws://your-exchange-domain/ws');
  
  ws.onclose = () => {
    console.log('Connection lost. Reconnecting in 5 seconds...');
    setTimeout(connect, 5000);
  };
  
  ws.onopen = () => {
    console.log('Connected');
    // Re-subscribe to your streams
    ws.send(JSON.stringify({
      method: 'SUBSCRIBE',
      params: ['trade.BTC_USDT'],
      id: 1
    }));
  };
  
  return ws;
}

const ws = connect();

​
Architecture notes

The WebSocket server:
  • Uses Redis Pub/Sub for distributing market data updates
  • Maintains user subscriptions in memory for fast routing
  • Automatically unsubscribes from Redis channels when no users are listening
  • Identifies users by their connection address
  • Supports multiple concurrent connections

​
Next steps

Subscriptions

Learn about available data streams and how to subscribe

REST API

Explore the REST API for account management and trading

Build docs developers (and LLMs) love

Get started for freeTalk to us