Subscribe to Orderbook

Subscribe to real-time orderbook updates for specific trading pairs across multiple exchanges. This is the primary method for receiving live market data through the QuantCite API.

Message Format

Request:

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

Parameters:

type (string, required): Must be “subscribe_aggregated”
symbol (string, required): Trading pair in format “BASE/QUOTE” (e.g., “BTC/USDT”)
exchanges (array, required): List of exchange names to aggregate data from

Request:

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

Parameters:

exchanges (string): Use “all” to subscribe to all available exchanges for the symbol

Response Messages

Successful Subscription

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

Response Fields:

type: Always “aggregated_subscription_response”
symbol: The trading pair you subscribed to
exchanges: Array of exchanges that were successfully subscribed to
requested: Array of exchanges that were requested (for comparison)
success: Boolean indicating if subscription was successful
message: Human-readable success message
subscription_id: Unique identifier for this subscription

Subscription to All Exchanges

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 52 exchanges",
  "subscription_id": "sub_789012"
}

Real-time 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
      }
    ],
    "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
    }
  }
}

Error Responses

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

Authentication Required

{
  "type": "error",
  "error": "authentication_required",
  "message": "You must authenticate before subscribing to data"
}

Supported Symbols

Major Trading Pairs

BTC/USDT - Bitcoin/Tether (most liquid)
ETH/USDT - Ethereum/Tether
BNB/USDT - Binance Coin/Tether
ADA/USDT - Cardano/Tether
SOL/USDT - Solana/Tether
XRP/USDT - Ripple/Tether

Quote Currencies

USDT - Tether (most common)
USD - US Dollar
EUR - Euro
BTC - Bitcoin pairs
ETH - Ethereum pairs

Supported Exchanges

Tier 1 Exchanges (High Volume)

binance - Binance
okx - OKX
bybit - Bybit
kucoin - KuCoin
gate - Gate.io
mexc - MEXC

Tier 2 Exchanges

bitget - Bitget
cryptocom - Crypto.com
huobi - Huobi Global
coinbase - Coinbase Pro
kraken - Kraken

Code Examples

Python Subscription

import asyncio
import websockets
import json

async def subscribe_to_symbol():
    uri = "wss://data.quantcite.com/api/v1/ws"
    
    async with websockets.connect(uri) as websocket:
        # Authenticate first
        auth_msg = {"type": "authenticate", "api_key": "demo_key_123"}
        await websocket.send(json.dumps(auth_msg))
        
        # Wait for auth response
        auth_response = await websocket.recv()
        print("Auth:", json.loads(auth_response))
        
        # Subscribe to BTC/USDT on specific exchanges
        subscribe_msg = {
            "type": "subscribe_aggregated",
            "symbol": "BTC/USDT",
            "exchanges": ["binance", "okx", "bybit"]
        }
        await websocket.send(json.dumps(subscribe_msg))
        
        # Listen for updates
        async for message in websocket:
            data = json.loads(message)
            if data.get("type") == "aggregated_orderbook_update":
                stats = data["data"]["market_stats"]
                print(f"BTC/USDT: {stats['best_bid']} / {stats['best_ask']}")

asyncio.run(subscribe_to_symbol())

JavaScript Subscription

const WebSocket = require('ws');

const ws = new WebSocket('wss://data.quantcite.com/api/v1/ws');

ws.on('open', () => {
    // Authenticate
    const authMsg = {
        type: 'authenticate',
        api_key: 'demo_key_123'
    };
    ws.send(JSON.stringify(authMsg));
});

ws.on('message', (data) => {
    const message = JSON.parse(data.toString());
    
    if (message.type === 'authentication_success') {
        // Subscribe to multiple symbols
        const symbols = ['BTC/USDT', 'ETH/USDT'];
        
        symbols.forEach(symbol => {
            const subscribeMsg = {
                type: 'subscribe_aggregated',
                symbol: symbol,
                exchanges: 'all'
            };
            ws.send(JSON.stringify(subscribeMsg));
        });
    }
    
    if (message.type === 'aggregated_orderbook_update') {
        const { symbol, data: orderbook } = message;
        const stats = orderbook.market_stats;
        console.log(`${symbol}: ${stats.best_bid} / ${stats.best_ask}`);
    }
});

Best Practices

Selective Subscriptions

Subscribe only to symbols you actively need. Each subscription consumes data from your 50GB monthly limit.

Exchange Selection

Choose specific exchanges instead of “all” to reduce data volume and focus on the most liquid markets.

Error Handling

Always handle subscription errors and implement retry logic for failed subscriptions.

Data Management

Monitor your data usage and unsubscribe from unused symbols to conserve your monthly allowance.

Each active subscription continuously streams data and counts toward your 50GB monthly limit. Monitor your usage and unsubscribe from symbols you no longer need.

Getting Started

Public HTTP Endpoints

Unified Transaction APIs

WebSocket Streaming

WebSocket API Reference

Client Examples

Message Format

Response Messages

Successful Subscription

Subscription to All Exchanges

Real-time Updates

Error Responses

Invalid Symbol

Exchange Not Available

Authentication Required

Supported Symbols

Major Trading Pairs

Quote Currencies

Supported Exchanges

Tier 1 Exchanges (High Volume)

Tier 2 Exchanges

Code Examples

Python Subscription

JavaScript Subscription

Best Practices

Selective Subscriptions

Exchange Selection

Error Handling

Data Management

​Message Format

​Subscribe to Specific Exchanges

​Subscribe to All Available Exchanges

​Response Messages

​Successful Subscription

​Subscription to All Exchanges

​Real-time Updates

​Error Responses

​Invalid Symbol

​Exchange Not Available

​Authentication Required

​Supported Symbols

​Major Trading Pairs

​Quote Currencies

​Supported Exchanges

​Tier 1 Exchanges (High Volume)

​Tier 2 Exchanges

​Code Examples

​Python Subscription

​JavaScript Subscription

​Best Practices

Selective Subscriptions

Exchange Selection

Error Handling

Data Management

Message Format

Subscribe to Specific Exchanges

Subscribe to All Available Exchanges

Response Messages

Successful Subscription

Subscription to All Exchanges

Real-time Updates

Error Responses

Invalid Symbol

Exchange Not Available

Authentication Required

Supported Symbols

Major Trading Pairs

Quote Currencies

Supported Exchanges

Tier 1 Exchanges (High Volume)

Tier 2 Exchanges

Code Examples

Python Subscription

JavaScript Subscription

Best Practices