> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantcite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Messages

> Complete reference for all WebSocket message types and responses

## 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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    Session authentication and user verification
  </Card>

  <Card title="Subscriptions" icon="wifi">
    Subscribe to real-time orderbook data
  </Card>

  <Card title="Data Retrieval" icon="database">
    Get current snapshots and information
  </Card>

  <Card title="Connection Management" icon="handshake">
    Ping/pong and connection health
  </Card>
</CardGroup>

## Authentication Messages

### 1. Authenticate

Authenticate your WebSocket session with API key.

#### Request

```json theme={null}
{
  "type": "authenticate",
  "api_key": "YOUR_API_KEY"
}
```

#### Success Response

```json theme={null}
{
  "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

```json theme={null}
{
  "type": "error",
  "error": "Authentication failed",
  "code": 4001,
  "message": "Invalid API key provided"
}
```

## Subscription Messages

### 2. Subscribe to Aggregated Orderbook

Subscribe to real-time orderbook updates from multiple exchanges.

#### Request (Specific Exchanges)

```json theme={null}
{
  "type": "subscribe_aggregated",
  "symbol": "BTC/USDT",
  "exchanges": ["binance", "okx", "bybit", "kucoin"]
}
```

#### Request (All Exchanges)

```json theme={null}
{
  "type": "subscribe_aggregated",
  "symbol": "BTC/USDT",
  "exchanges": "all"
}
```

#### Success Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "type": "unsubscribe_aggregated",
  "symbol": "BTC/USDT"
}
```

#### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "type": "get_aggregated_orderbook",
  "symbol": "BTC/USDT"
}
```

#### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "type": "get_exchanges"
}
```

#### Response

```json theme={null}
{
  "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)

```json theme={null}
{
  "type": "get_pairs"
}
```

#### Request (Specific Exchange)

```json theme={null}
{
  "type": "get_pairs",
  "exchange": "binance"
}
```

#### Response (All Exchanges)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "type": "ping"
}
```

#### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<Steps>
  <Step title="Connect and Authenticate">
    ```json theme={null}
    // Send after connection
    {
      "type": "authenticate",
      "api_key": "demo_key_123"
    }

    // Receive welcome message
    {
      "type": "welcome",
      "user_tier": "premium",
      "message": "Authenticated successfully"
    }
    ```
  </Step>

  <Step title="Subscribe to Data">
    ```json theme={null}
    // 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"
    }
    ```
  </Step>

  <Step title="Receive Updates">
    ```json theme={null}
    // Continuous orderbook updates
    {
      "type": "aggregated_orderbook_update",
      "symbol": "BTC/USDT",
      "data": {
        "bids": [...],
        "asks": [...],
        "market_stats": {...}
      }
    }
    ```
  </Step>
</Steps>

### Error Handling Flow

<Steps>
  <Step title="Invalid Request">
    ```json theme={null}
    // Send invalid symbol
    {
      "type": "subscribe_aggregated",
      "symbol": "INVALID/PAIR"
    }

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

  <Step title="Handle Rate Limits">
    ```json theme={null}
    // Rate limit exceeded
    {
      "type": "error",
      "error": "rate_limit_exceeded",
      "retry_after": 60
    }
    ```
  </Step>
</Steps>

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