Subscribe

WebSocket clients must send a subscribe message within 10 seconds of connecting or they will be disconnected.

Subscribe

Message Format

interface SubscribeMessage {
  type: "subscribe";
  product_codes?: string[];
  channels?: ChannelSubscription[];
}

interface ChannelSubscription {
  name: string;
  product_codes: string[];
}

Example

{
  "type": "subscribe",
  "product_codes": ["BUSZ22", "BUSO"],
  "channels": [
    {
      "name": "trade",
      "product_codes": ["BUIZ22"]
    },
    {
      "name": "book",
      "product_codes": ["BUIH23"]
    }
  ]
}

This message will subscribe the client to all channels for BUSZ22 as well as all options with a BUS underlying future. See Product Codes for additional details on what strings are allowed in the product_codes field. Additionally, this message will subscribe the client to only trade updates for BUIZ22 and only book updates for BUIH23.

Unsubscribe

Unsubscribe messages have the same structure as subscribe messages, except for the type field is "unsubscribe".

Example

{
  "type": "unsubscribe",
  "product_codes": [
    "BUIH23"
  ],
  "channels": [
    {
      "name": "trade",
      "product_codes": [
        "BUSO"
      ]
    }
  ]
}

This unsubscribe message will unsubscribe the client from all updates to BUIH23 as well as trade updates from BUSO meaning all options with a BUS underlying. Note that even when subscribing to all updates for a product code, it is still possible to unsubscribe from specific channels later.

Disconnect

Clients will receive a disconnect message when they are disconnected for any reason.

Message Format

interface DisconnectMessage {
  type: "disconnect";
  reason: string;
}

Example

{
  "type": "disconnect",
  "reason": "Client requested logout"
}