Skip to main content

​
Overview

The Roxom WebSocket API provides real-time access to market data and account updates with minimal latency. Perfect for building trading applications, monitoring portfolios, and implementing algorithmic trading strategies.

​
What You Can Access

Authentication required for market data streams:
  • Level 1 Quotes: Best bid/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
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
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:
SymbolDescriptionBase AssetQuote Asset
US500-BTCS&P 500 Index to BitcoinSPYBTC
US100-BTCNasdaq 100 Index to BitcoinQQQBTC
GOLD-BTCGold to BitcoinPAXBTC
OIL-BTCOil to BitcoinUSOBTC

​
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

ChannelDescriptionSymbol RequiredAuthentication
level1Best bid/ask prices and quantitiesYesYes
tradeReal-time trade executionsYesYes
depthOrder book depth (snapshot + deltas)YesYes
tickerReal-time price and market statisticsYesYes
ordersOrder updates for authenticated userNoYes
balanceBalance updates for authenticated userNoYes
positionsPosition updates for authenticated userNoYes
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 critical account changes are never missed.

​
Connection Lifecycle

1

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
  }
});
2

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
};
3

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" }
  ]
}
4

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);
};
5

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

  • 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
  • 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
  • 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
⌘I