WebSocket Message Formats

Complete reference for WebSocket message formats, including request/response patterns, data structures, and protocol specifications.

Message Structure

All WebSocket messages follow a consistent JSON structure:

{
  "type": "message_type",
  "data": {
    /* message-specific data */
  },
  "timestamp": "2024-01-15T12:00:00Z",
  "sequence": 12345,
  "requestId": "optional_request_id"
}

Authentication Messages

Authentication Request

{
  "type": "auth",
  "apiKey": "your_api_key",
  "timestamp": 1640995200,
  "signature": "calculated_signature"
}

Authentication Response

{
  "type": "auth_success",
  "message": "Authentication successful",
  "timestamp": 1640995200
}

Authentication Error

{
  "type": "auth_error",
  "error": "invalid_signature",
  "message": "The request signature is invalid",
  "code": 401
}

Subscription Messages

Subscribe to Channel

{
  "type": "subscribe",
  "channel": "ticker",
  "symbol": "BTC/USD",
  "requestId": "sub_001"
}

Subscribe to Multiple Channels

{
  "type": "subscribe",
  "channels": [
    { "channel": "ticker", "symbol": "BTC/USD" },
    { "channel": "orderbook", "symbol": "BTC/USD" },
    { "channel": "trades", "symbol": "BTC/USD" }
  ],
  "requestId": "sub_002"
}

Unsubscribe from Channel

{
  "type": "unsubscribe",
  "channel": "ticker",
  "symbol": "BTC/USD",
  "requestId": "unsub_001"
}

Subscription Confirmation

{
  "type": "subscription.confirmed",
  "channel": "ticker",
  "symbol": "BTC/USD",
  "data": {
    "status": "subscribed",
    "message": "Successfully subscribed to BTC/USD ticker"
  },
  "requestId": "sub_001",
  "timestamp": "2024-01-15T12:00:00Z"
}

Market Data Messages

Ticker Data

{
  "type": "ticker",
  "channel": "ticker",
  "symbol": "BTC/USD",
  "data": {
    "price": 49850.25,
    "bid": 49840.0,
    "ask": 49860.5,
    "bidSize": 0.5,
    "askSize": 0.3,
    "volume24h": 1250.75,
    "change24h": 2.5,
    "changePercent24h": 0.05,
    "high24h": 50200.0,
    "low24h": 48500.0,
    "open24h": 48600.0
  },
  "timestamp": "2024-01-15T12:00:00Z",
  "sequence": 12345
}

Order Book Data

{
  "type": "orderbook",
  "channel": "orderbook",
  "symbol": "BTC/USD",
  "data": {
    "bids": [
      { "price": 49840.0, "quantity": 0.5 },
      { "price": 49835.0, "quantity": 0.3 }
    ],
    "asks": [
      { "price": 49860.5, "quantity": 0.3 },
      { "price": 49865.0, "quantity": 0.4 }
    ],
    "checksum": "abc123def456"
  },
  "timestamp": "2024-01-15T12:00:00Z",
  "sequence": 12346
}

Trade Data

{
  "type": "trade",
  "channel": "trades",
  "symbol": "BTC/USD",
  "data": {
    "tradeId": "trade_123456",
    "price": 49850.25,
    "quantity": 0.1,
    "side": "buy",
    "timestamp": "2024-01-15T12:00:00Z"
  },
  "timestamp": "2024-01-15T12:00:00Z",
  "sequence": 12347
}

Trading Messages

Order Messages

{
  "type": "order",
  "channel": "orders",
  "data": {
    "orderId": "12345678-1234-1234-1234-123456789012",
    "symbol": "BTC/USD",
    "side": "buy",
    "type": "market",
    "quantity": 0.1,
    "status": "filled",
    "filledQuantity": 0.1,
    "averagePrice": 49850.25,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:01Z"
  },
  "timestamp": "2024-01-15T10:30:01Z",
  "sequence": 12348
}

Position Messages

{
  "type": "position",
  "channel": "positions",
  "symbol": "BTC/USD",
  "data": {
    "side": "long",
    "quantity": 0.1,
    "averagePrice": 49850.25,
    "unrealizedPnl": 150.75,
    "unrealizedPnlPercent": 0.3,
    "markPrice": 50000.0,
    "marginUsed": 4985.03,
    "marginRatio": 0.1,
    "updatedAt": "2024-01-15T11:00:00Z"
  },
  "timestamp": "2024-01-15T11:00:00Z",
  "sequence": 12349
}

AI Signal Messages

Signal Data

{
  "type": "signal",
  "channel": "signals",
  "symbol": "BTC/USD",
  "data": {
    "recommendation": "buy",
    "confidence": 87,
    "timeHorizon": "short_term",
    "riskLevel": "medium",
    "reasoning": [
      "Strong bullish momentum detected",
      "High volume confirmation",
      "Positive sentiment from social media"
    ],
    "technicalAnalysis": {
      "rsi": 35.2,
      "macd": "bullish",
      "support": 48500.0,
      "resistance": 50200.0
    },
    "sentimentAnalysis": {
      "socialSentiment": 0.75,
      "newsSentiment": 0.68,
      "fearGreedIndex": 45
    }
  },
  "timestamp": "2024-01-15T12:00:00Z",
  "sequence": 12350
}

System Messages

Heartbeat Messages

{
  "type": "ping",
  "timestamp": "2024-01-15T12:00:00Z"
}

{
  "type": "pong",
  "timestamp": "2024-01-15T12:00:00Z"
}

System Status

{
  "type": "system_status",
  "data": {
    "status": "operational",
    "services": {
      "trading": "operational",
      "api": "operational",
      "websocket": "operational"
    },
    "uptime": 99.9
  },
  "timestamp": "2024-01-15T12:00:00Z"
}

Error Messages

General Error

{
  "type": "error",
  "error": "error_code",
  "message": "Human readable error message",
  "code": 400,
  "timestamp": "2024-01-15T12:00:00Z"
}

Subscription Error

{
  "type": "subscription_error",
  "channel": "ticker",
  "symbol": "INVALID/USD",
  "error": "invalid_symbol",
  "message": "The symbol 'INVALID/USD' is not supported",
  "code": 400,
  "timestamp": "2024-01-15T12:00:00Z"
}

Message Validation

Required Fields

• type: Message type identifier
• timestamp: ISO 8601 timestamp
• sequence: Monotonic sequence number

Optional Fields

• data: Message-specific data payload
• requestId: Request identifier for correlation
• channel: Channel identifier
• symbol: Trading pair symbol

Data Types

• Strings: UTF-8 encoded
• Numbers: IEEE 754 double precision
• Booleans: true/false
• Timestamps: ISO 8601 format
• Arrays: JSON arrays
• Objects: JSON objects

Message Size Limits

• Maximum Message Size: 64KB
• Maximum Array Elements: 1000
• Maximum Object Properties: 100
• Maximum String Length: 32KB

Compression

WebSocket messages support compression:

• Algorithm: Deflate
• Level: 6 (balanced)
• Threshold: 1KB (compress messages > 1KB)

Rate Limiting

• Messages Per Second: 100
• Burst Limit: 200 messages
• Window: 1 second sliding window

---

Need help with error handling? Check out our WebSocket Errors guide.