WebSocket Overview

Overview

The Roxom WebSocket API provides real-time access to market data and account updates with minimal latency. Use it to build trading applications, monitor portfolios, and implement algorithmic trading strategies.

What you can access

Market Data Streams

Authentication required for market data streams:

Level 1 Quotes: Best bid and ask prices and quantities
Trade Executions: Real-time trade data with volume statistics
Order Book Depth: Complete order book with multiple price levels
Ticker Data: Real-time price and market statistics including funding rates and open interest

Private Account Data

Authentication required for private account streams:

Order Updates: Real-time order status changes and fills
Balance Changes: Account balance updates from trades and transfers
Position Updates: Position changes and PnL updates

Connection URLs

wss://ws.roxom.com/ws

wss://ws.roxom.io/ws

Use the sandbox environment for testing and development. Production credentials will not work with sandbox endpoints.

Supported trading pairs

Current supported symbols for market data streams:

Symbol	Description	Base Asset	Quote Asset
`US500-BTC`	S&P 500 Index to Bitcoin	SPY	BTC
`GOLD-BTC`	Gold to Bitcoin	PAX	BTC
`USDT-BTC`	Tether to Bitcoin	USDT	BTC
`OIL-BTC`	WTI Crude Oil to Bitcoin	OIL	BTC

Message format

All WebSocket messages use JSON format with a consistent structure:

Client to server messages

{
  "op": "subscribe|unsubscribe",
  "args": [
    {
      "channel": "channelName",
      "symbol": "tradingPair"
    }
  ]
}

Server to client messages

{
  "topic": "channel.symbol",
  "type": "snapshot|delta",
  "createdTime": 1640995200000000000,
  "data": {
    // Channel-specific data
  }
}

Supported channels

Channel	Description	Symbol Required	Authentication
`level1`	Best bid and ask prices and quantities	Yes	Yes
`trade`	Real-time trade executions	Yes	Yes
`depth`	Order book depth (snapshot + deltas)	Yes	Yes
`ticker`	Real-time price and market statistics	Yes	Yes
`orders`	Order updates for authenticated user	No	Yes
`balance`	Balance updates for authenticated user	No	Yes
`positions`	Position updates for authenticated user	No	Yes

Account Event Broadcasting: Account-related events (orders, positions, balance) are automatically sent to all authenticated connections for your account, regardless of individual subscriptions. This ensures you never miss critical account changes.

Connection lifecycle

Establish Authenticated Connection

All WebSocket connections require authentication using API key headers during the connection handshake.

// Generate RSA signature for the payload 'GET:/ws'
const signature = generateRSASignature(privateKey, 'GET:/ws');

const ws = new WebSocket('wss://ws.roxom.com/ws', [], {
  headers: {
    'X-API-Key': 'your_api_key',
    'X-API-Signature': signature
  }
});

Handle Connection Events

Implement proper event handlers for connection management.

ws.onopen = () => {
  console.log('✅ WebSocket connected and authenticated');
};

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

ws.onclose = (event) => {
  console.log('🔌 WebSocket closed:', event.code, event.reason);
  // Implement reconnection logic
};

Subscribe to Channels

Send subscription messages for the data streams you need.

{
  "op": "subscribe",
  "args": [
    { "channel": "level1", "symbol": "US500-BTC" },
    { "channel": "depth", "symbol": "GOLD-BTC" },
    { "channel": "orders" }
  ]
}

Handle Messages

Process incoming real-time data and maintain connection status.

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

Maintain Connection

Implement ping/pong and reconnection logic for reliability.

Send ping frames every 30 seconds to keep the connection alive.

Key features

Low Latency

Sub-millisecond message delivery for time-sensitive trading applications

Multiple Streams

Subscribe to multiple symbols and channels simultaneously

Reliable Delivery

Built-in heartbeat and reconnection mechanisms

Efficient Updates

Delta updates minimize bandwidth usage for order book streams

Best practices

Connection Management

Single Connection: Use one connection per application when possible
Reconnection Logic: Implement exponential backoff for reconnections
Heartbeat Monitoring: Send ping frames every 30 seconds
Resource Cleanup: Properly close connections when shutting down

Subscription Management

Selective Subscriptions: Only subscribe to data you actually need
Unsubscribe Unused: Remove subscriptions you no longer need
Batch Operations: Subscribe to multiple channels in single message
Symbol Validation: Verify symbol names before subscribing

Error Handling

Graceful Degradation: Handle connection drops gracefully
Error Parsing: Always validate JSON before parsing
Retry Logic: Implement smart retry mechanisms
Logging: Log connection events for debugging

Getting started

Connection Setup

Learn how to establish and maintain WebSocket connections

Market Data Streams

Subscribe to real-time market data feeds

Account Updates

Receive real-time account and order updates

Authentication

Set up API authentication for private streams

​Overview

​What you can access

​Connection URLs

​Supported trading pairs

​Message format

​Client to server messages

​Server to client messages

​Supported channels

​Connection lifecycle

​Key features

Low Latency

Multiple Streams

Reliable Delivery

Efficient Updates

​Best practices

​Getting started

Connection Setup

Market Data Streams

Account Updates

Authentication

Overview

What you can access

Connection URLs

Supported trading pairs

Message format

Client to server messages

Server to client messages

Supported channels

Connection lifecycle

Key features

Best practices

Getting started