WebSocket Subscriptions

Subscribe to real-time orderbook updates for specific trading pairs across multiple exchanges. Request:

{
  "type": "subscribe_aggregated",
  "symbol": "BTC/USDT",
  "exchanges": ["binance", "okx", "bybit", "kucoin"]
}

Success Response:

{
  "type": "aggregated_subscription_response",
  "symbol": "BTC/USDT",
  "exchanges": ["binance", "okx", "bybit", "kucoin"],
  "requested": ["binance", "okx", "bybit", "kucoin"],
  "success": true,
  "message": "Subscribed to BTC/USDT on 4 exchanges",
  "subscription_id": "sub_123456"
}

Request:

{
  "type": "subscribe_aggregated",
  "symbol": "BTC/USDT",
  "exchanges": "all"
}

Success Response:

{
  "type": "aggregated_subscription_response",
  "symbol": "BTC/USDT",
  "exchanges": ["binance", "okx", "bybit", "kucoin", "gate", "mexc", "bitget", "cryptocom"],
  "requested": "all",
  "success": true,
  "message": "Subscribed to BTC/USDT on 25 exchanges",
  "subscription_id": "sub_789012"
}

Real-time Orderbook Updates

Once subscribed, you’ll receive continuous orderbook updates:

{
  "type": "aggregated_orderbook_update",
  "symbol": "BTC/USDT",
  "timestamp": "2025-08-19T19:45:13.392607",
  "update_number": 1,
  "subscription_id": "sub_123456",
  "data": {
    "bids": [
      {
        "price": 113393.9,
        "amount": 0.0001,
        "exchanges": ["bybit"],
        "exchange_count": 1,
        "value": 11.33939
      },
      {
        "price": 113390.0,
        "amount": 0.0025,
        "exchanges": ["binance", "okx"],
        "exchange_count": 2,
        "value": 283.475
      }
    ],
    "asks": [
      {
        "price": 113400.0,
        "amount": 0.0005,
        "exchanges": ["binance", "okx"],
        "exchange_count": 2,
        "value": 56.7
      },
      {
        "price": 113405.5,
        "amount": 0.0015,
        "exchanges": ["kucoin"],
        "exchange_count": 1,
        "value": 170.1083
      }
    ],
    "market_stats": {
      "best_bid": 113393.9,
      "best_ask": 113400.0,
      "spread": 6.1,
      "spread_percent": 0.0054,
      "mid_price": 113396.95,
      "total_bid_volume": 0.0026,
      "total_ask_volume": 0.002,
      "participating_exchanges": 4
    }
  }
}

Subscription Management

Get Current Orderbook Snapshot

Request the current orderbook state for an active subscription: Request:

{
  "type": "get_aggregated_orderbook",
  "symbol": "BTC/USDT"
}

Response:

{
  "type": "aggregated_orderbook_data",
  "symbol": "BTC/USDT",
  "timestamp": "2025-08-19T19:45:13.392607",
  "data": {
    "bids": [...],
    "asks": [...],
    "market_stats": {
      "best_bid": 113393.9,
      "best_ask": 113400.0,
      "spread": 6.1,
      "spread_percent": 0.0054,
      "mid_price": 113396.95
    }
  }
}

Unsubscribe from Symbol

Stop receiving updates for a specific trading pair: Request:

{
  "type": "unsubscribe_aggregated",
  "symbol": "BTC/USDT"
}

Response:

{
  "type": "unsubscribe_response",
  "symbol": "BTC/USDT",
  "success": true,
  "message": "Successfully unsubscribed from BTC/USDT"
}

Subscription Errors

Invalid Symbol

{
  "type": "subscription_error",
  "error": "invalid_symbol",
  "message": "Symbol BTC/INVALID is not supported",
  "symbol": "BTC/INVALID",
  "suggested_symbols": ["BTC/USDT", "BTC/USD", "BTC/EUR"]
}

Exchange Not Available

{
  "type": "subscription_error",
  "error": "exchange_unavailable",
  "message": "Exchange 'invalid_exchange' is not supported",
  "exchange": "invalid_exchange",
  "supported_exchanges": ["binance", "okx", "bybit", "kucoin"]
}

No Active Subscription

{
  "type": "error",
  "error": "no_subscription",
  "message": "No active subscription found for BTC/USDT",
  "symbol": "BTC/USDT"
}

Data Structure

Orderbook Entry

Each bid/ask entry contains:

Field	Type	Description
`price`	number	Order price level
`amount`	number	Total amount at this price
`exchanges`	array	List of exchanges contributing
`exchange_count`	number	Number of exchanges
`value`	number	Price × Amount

Market Statistics

Real-time market statistics included with each update:

Field	Type	Description
`best_bid`	number	Highest bid price
`best_ask`	number	Lowest ask price
`spread`	number	Bid-ask spread
`spread_percent`	number	Spread as percentage
`mid_price`	number	(best_bid + best_ask) / 2
`total_bid_volume`	number	Total bid volume
`total_ask_volume`	number	Total ask volume
`participating_exchanges`	number	Active exchanges count

Best Practices

Subscription Management

Subscribe only to needed symbols
Unsubscribe from unused pairs
Monitor subscription count
Handle subscription errors gracefully

Data Processing

Process updates efficiently
Implement proper buffering
Handle high-frequency updates
Monitor memory usage

Code Examples

Python Subscription Manager

import asyncio
import websockets
import json

class SubscriptionManager:
    def __init__(self, api_key):
        self.api_key = api_key
        self.websocket = None
        self.subscriptions = set()
    
    async def subscribe(self, symbol, exchanges="all"):
        if not self.websocket:
            await self.connect()
        
        subscribe_msg = {
            "type": "subscribe_aggregated",
            "symbol": symbol,
            "exchanges": exchanges
        }
        
        await self.websocket.send(json.dumps(subscribe_msg))
        self.subscriptions.add(symbol)
        print(f"Subscribed to {symbol}")
    
    async def unsubscribe(self, symbol):
        if symbol not in self.subscriptions:
            print(f"Not subscribed to {symbol}")
            return
        
        unsubscribe_msg = {
            "type": "unsubscribe_aggregated",
            "symbol": symbol
        }
        
        await self.websocket.send(json.dumps(unsubscribe_msg))
        self.subscriptions.remove(symbol)
        print(f"Unsubscribed from {symbol}")

JavaScript Subscription Handler

class SubscriptionHandler {
    constructor(websocket) {
        this.ws = websocket;
        this.subscriptions = new Set();
    }
    
    subscribe(symbol, exchanges = 'all') {
        const subscribeMsg = {
            type: 'subscribe_aggregated',
            symbol: symbol,
            exchanges: exchanges
        };
        
        this.ws.send(JSON.stringify(subscribeMsg));
        this.subscriptions.add(symbol);
        console.log(`Subscribed to ${symbol}`);
    }
    
    unsubscribe(symbol) {
        if (!this.subscriptions.has(symbol)) {
            console.log(`Not subscribed to ${symbol}`);
            return;
        }
        
        const unsubscribeMsg = {
            type: 'unsubscribe_aggregated',
            symbol: symbol
        };
        
        this.ws.send(JSON.stringify(unsubscribeMsg));
        this.subscriptions.delete(symbol);
        console.log(`Unsubscribed from ${symbol}`);
    }
}

Each subscription consumes data from your 50GB monthly limit. Monitor your usage and unsubscribe from unused symbols to conserve data.

Getting Started

Public HTTP Endpoints

Unified Transaction APIs

WebSocket Streaming

WebSocket API Reference

Client Examples

Real-time Orderbook Updates

Subscription Management

Get Current Orderbook Snapshot

Unsubscribe from Symbol

Subscription Errors

Invalid Symbol

Exchange Not Available

No Active Subscription

Data Structure

Orderbook Entry

Market Statistics

Best Practices

Subscription Management

Data Processing

Code Examples

Python Subscription Manager

JavaScript Subscription Handler

​Subscribe to Aggregated Orderbook

​Subscribe to Specific Exchanges

​Subscribe to All Available Exchanges

​Real-time Orderbook Updates

​Subscription Management

​Get Current Orderbook Snapshot

​Unsubscribe from Symbol

​Subscription Errors

​Invalid Symbol

​Exchange Not Available

​No Active Subscription

​Data Structure

​Orderbook Entry

​Market Statistics

​Best Practices

Subscription Management

Data Processing

​Code Examples

​Python Subscription Manager

​JavaScript Subscription Handler

Subscribe to Aggregated Orderbook

Subscribe to Specific Exchanges

Subscribe to All Available Exchanges

Real-time Orderbook Updates

Subscription Management

Get Current Orderbook Snapshot

Unsubscribe from Symbol

Subscription Errors

Invalid Symbol

Exchange Not Available

No Active Subscription

Data Structure

Orderbook Entry

Market Statistics

Best Practices

Code Examples

Python Subscription Manager

JavaScript Subscription Handler