WebSocket Messages - QuantCite API

Message Types Overview

The QuantCite WebSocket API uses JSON messages for all communication. Each message has a type field that identifies the message category.

Message Categories

Authentication

Session authentication and user verification

Subscriptions

Subscribe to real-time orderbook data

Data Retrieval

Get current snapshots and information

Connection Management

Ping/pong and connection health

Authentication Messages

1. Authenticate

Authenticate your WebSocket session with API key.

Request

{
  "type": "authenticate",
  "api_key": "YOUR_API_KEY"
}

Success Response

{
  "type": "welcome",
  "session_id": "860a5a96-0da4-4154-9d13-a79d07121758",
  "user_id": "cb88461f-421a-4ac8-9722-afe248a40ae6",
  "user_tier": "premium",
  "message": "Authenticated successfully as premium user",
  "authentication": {
    "api_key": "demo_key...",
    "status": "authenticated"
  }
}

Error Response

{
  "type": "error",
  "error": "Authentication failed",
  "code": 4001,
  "message": "Invalid API key provided"
}

Subscription Messages

Subscribe to real-time orderbook updates from multiple exchanges.

Request (Specific Exchanges)

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

Request (All Exchanges)

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

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

Error Response

{
  "type": "subscription_error",
  "error": "invalid_symbol",
  "message": "Symbol BTC/INVALID is not supported",
  "symbol": "BTC/INVALID"
}

3. Unsubscribe from Symbol

Stop receiving orderbook updates for a symbol.

Request

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

Response

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

Real-time Data Messages

4. Orderbook Update

Real-time orderbook updates after subscription.

Update Message

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

Data Retrieval Messages

5. Get Current Orderbook

Get current orderbook snapshot without 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": [
      {
        "price": 113393.9,
        "amount": 0.0001,
        "exchanges": ["bybit"],
        "exchange_count": 1,
        "value": 11.33939
      }
    ],
    "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
    }
  }
}

6. Get Supported Exchanges

Retrieve list of all supported exchanges.

Request

{
  "type": "get_exchanges"
}

Response

{
  "type": "exchanges_data",
  "data": {
    "supported_exchanges": [
      "alpaca", "apex", "ascendex", "bequant", "binance", "binancecoinm",
      "binanceus", "binanceusdm", "bingx", "bitfinex", "bitget", "bithumb",
      "bitmart", "bitmex", "bitopro", "bitrue", "bitstamp", "bittrade",
      "bitvavo", "blockchaincom", "blofin", "bybit", "cex", "coinbase",
      "coinbaseadvanced", "coinbaseexchange", "coinbaseinternational", "coincatch",
      "coincheck", "coinex", "coinone", "cryptocom", "defx", "deribit",
      "derive", "exmo", "gate", "gateio", "gemini", "hashkey", "hitbtc",
      "hollaex", "htx", "huobi", "hyperliquid", "independentreserve", "kraken",
      "krakenfutures", "kucoin", "kucoinfutures", "lbank", "luno", "mexc",
      "modetrade", "myokx", "ndax", "okcoin", "okx", "okxus", "onetrading",
      "oxfun", "p2b", "paradex", "phemex", "poloniex", "probit", "tradeogre",
      "upbit", "vertex", "whitebit", "woo", "woofipro", "xt"
    ],
    "active_exchanges": [
      "binance", "bybit", "kucoin", "gate", "mexc", "bitget", "cryptocom",
      "huobi", "coinbase", "kraken", "okx", "bitfinex", "poloniex", "whitebit",
      "woo", "deribit", "ascendex", "bequant", "binanceus", "bitmex"
    ],
    "total_supported": 70,
    "total_active": 52,
    "exchange_status": {
      "binance": "active",
      "okx": "active",
      "bybit": "active",
      "kraken": "active",
      "coinbase": "active"
    }
  },
  "timestamp": "2025-08-29T21:08:53.451737"
}

7. Get Trading Pairs

Retrieve available trading pairs for exchanges.

Request (All Exchanges)

{
  "type": "get_pairs"
}

Request (Specific Exchange)

{
  "type": "get_pairs",
  "exchange": "binance"
}

Response (All Exchanges)

{
  "type": "pairs_data",
  "data": {
    "exchanges": {
      "binance": ["BTC/USDT", "ETH/USDT", "BNB/USDT", "ADA/USDT", "SOL/USDT"],
      "bybit": ["BTC/USDT", "ETH/USDT", "SOL/USDT", "DOGE/USDT", "DOT/USDT"],
      "kucoin": ["BTC/USDT", "ETH/USDT", "KCS/USDT", "DOT/USDT", "ADA/USDT"],
      "okx": ["BTC/USDT", "ETH/USDT", "OKB/USDT", "SOL/USDT", "DOT/USDT"],
      "gate": ["BTC/USDT", "ETH/USDT", "GT/USDT", "ADA/USDT", "DOT/USDT"],
      "mexc": ["BTC/USDT", "ETH/USDT", "MX/USDT", "SOL/USDT", "ADA/USDT"],
      "coinbase": ["BTC/USD", "ETH/USD", "ADA/USD", "SOL/USD", "DOT/USD"],
      "kraken": ["BTC/USD", "ETH/USD", "ADA/USD", "DOT/USD", "SOL/USD"]
    },
    "total_exchanges": 52,
    "total_pairs": 50000,
    "common_pairs": ["BTC/USDT", "ETH/USDT", "BNB/USDT", "ADA/USDT", "SOL/USDT", "DOT/USDT"]
  },
  "timestamp": "2025-08-29T21:08:53.451737"
}

Response (Specific Exchange)

{
  "type": "pairs_data",
  "data": {
    "exchange": "binance",
    "pairs": [
      "BTC/USDT", "ETH/USDT", "BNB/USDT", "ADA/USDT", "SOL/USDT",
      "DOGE/USDT", "XRP/USDT", "DOT/USDT", "AVAX/USDT", "LINK/USDT",
      "LTC/USDT", "BCH/USDT", "ETC/USDT", "XLM/USDT", "ICP/USDT"
    ],
    "total_pairs": 3826,
    "categories": {
      "major": ["BTC/USDT", "ETH/USDT", "BNB/USDT"],
      "altcoins": ["ADA/USDT", "SOL/USDT", "DOT/USDT", "AVAX/USDT", "LINK/USDT"],
      "meme": ["DOGE/USDT", "SHIB/USDT", "PEPE/USDT"],
      "defi": ["AAVE/USDT", "UNI/USDT", "COMP/USDT"],
      "layer1": ["SOL/USDT", "ADA/USDT", "DOT/USDT", "AVAX/USDT", "ICP/USDT"]
    }
  },
  "timestamp": "2025-08-29T21:08:53.451737"
}

Connection Management

8. Ping/Pong

Health check and connection maintenance.

Request

{
  "type": "ping"
}

Response

{
  "type": "pong",
  "timestamp": "2025-08-19T20:45:13.392607",
  "server_time": "2025-08-19T20:45:13.392607",
  "latency_ms": 2.5
}

Error Messages

Rate Limit Exceeded

{
  "type": "error",
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait before sending more messages.",
  "retry_after": 60,
  "current_limit": 600,
  "window": "per_minute"
}

Invalid Symbol

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

Exchange Not Available

{
  "type": "error",
  "error": "exchange_unavailable",
  "message": "Exchange 'invalid_exchange' is not supported",
  "exchange": "invalid_exchange",
  "supported_exchanges": ["binance", "okx", "bybit", "kucoin", "gate", "mexc", "coinbase", "kraken", "huobi", "bitfinex"]
}

Data Limit Exceeded

{
  "type": "error",
  "error": "data_limit_exceeded",
  "message": "Monthly data limit of 50GB exceeded",
  "data_usage": {
    "used_gb": 51.2,
    "limit_gb": 50.0
  },
  "action_required": "Wait for monthly reset or contact support"
}

Usage Notifications

Data Limit Warning

{
  "type": "data_limit_warning",
  "message": "Data streaming limit exceeded",
  "data_usage": {
    "used_gb": 52.3,
    "limit_gb": 50.0,
    "exceeded_by_gb": 2.3,
    "usage_percentage": 104.6
  },
  "action_required": "Contact support to increase your data limit",
  "timestamp": "2025-01-30T10:30:00Z"
}

Rate Limit Warning

{
  "type": "rate_limit_warning",
  "message": "Approaching rate limit",
  "current_rate": 580,
  "limit": 600,
  "window": "per_minute",
  "reset_time": "2025-01-30T10:31:00Z"
}

Message Flow Examples

Basic Subscription Flow

Connect and Authenticate

// Send after connection
{
  "type": "authenticate",
  "api_key": "demo_key_123"
}

// Receive welcome message
{
  "type": "welcome",
  "user_tier": "premium",
  "message": "Authenticated successfully"
}

Subscribe to Data

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

// Receive subscription confirmation
{
  "type": "aggregated_subscription_response",
  "symbol": "BTC/USDT",
  "success": true,
  "subscription_id": "sub_123456"
}

Receive Updates

// Continuous orderbook updates
{
  "type": "aggregated_orderbook_update",
  "symbol": "BTC/USDT",
  "data": {
    "bids": [...],
    "asks": [...],
    "market_stats": {...}
  }
}

Error Handling Flow

Invalid Request

// Send invalid symbol
{
  "type": "subscribe_aggregated",
  "symbol": "INVALID/PAIR"
}

// Receive error response
{
  "type": "error",
  "error": "invalid_symbol",
  "message": "Symbol INVALID/PAIR is not supported"
}

Handle Rate Limits

// Rate limit exceeded
{
  "type": "error",
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

Always implement proper error handling in your WebSocket clients to handle network issues, rate limits, and invalid requests gracefully.

​Message Types Overview

​Message Categories

Authentication

Subscriptions

Data Retrieval

Connection Management

​Authentication Messages

​1. Authenticate

​Request

​Success Response

​Error Response

​Subscription Messages

​2. Subscribe to Aggregated Orderbook

​Request (Specific Exchanges)

​Request (All Exchanges)

​Success Response

​Error Response

​3. Unsubscribe from Symbol

​Request

​Response

​Real-time Data Messages

​4. Orderbook Update

​Update Message

​Data Retrieval Messages

​5. Get Current Orderbook

​Request

​Response

​6. Get Supported Exchanges

​Request

​Response

​7. Get Trading Pairs

​Request (All Exchanges)

​Request (Specific Exchange)

​Response (All Exchanges)

​Response (Specific Exchange)

​Connection Management

​8. Ping/Pong

​Request

​Response

​Error Messages

​Rate Limit Exceeded

​Invalid Symbol

​Exchange Not Available

​Data Limit Exceeded

​Usage Notifications

​Data Limit Warning

​Rate Limit Warning

​Message Flow Examples

​Basic Subscription Flow

​Error Handling Flow

Message Types Overview

Message Categories

Authentication Messages

1. Authenticate

Request

Success Response

Error Response

Subscription Messages

2. Subscribe to Aggregated Orderbook

Request (Specific Exchanges)

Request (All Exchanges)

Success Response

Error Response

3. Unsubscribe from Symbol

Request

Response

Real-time Data Messages

4. Orderbook Update

Update Message

Data Retrieval Messages

5. Get Current Orderbook

Request

Response

6. Get Supported Exchanges

Request

Response

7. Get Trading Pairs

Request (All Exchanges)

Request (Specific Exchange)

Response (All Exchanges)

Response (Specific Exchange)

Connection Management

8. Ping/Pong

Request

Response

Error Messages

Rate Limit Exceeded

Invalid Symbol

Exchange Not Available

Data Limit Exceeded

Usage Notifications

Data Limit Warning

Rate Limit Warning

Message Flow Examples

Basic Subscription Flow

Error Handling Flow