Subscribe

All WebSocket requests and responses contain an array with two elements. The first element is the header object, and the second element is the payload, following the explicit-header design outlined here.

Subscriptions allow you to receive asynchronous notifications about specific channels.

Add Subscription Requests

The request type informs the system that the client wishes to subscribe to data feed channels. The client will begin receiving asynchronous notification messages about a particular channel until they cancel their subscription using the cancel_subscriptions request.

If any named channel name is invalid or the client does not have permission to access it (e.g., a private account fill feeds), none of the subscriptions will be added.

[
  {
    "msg_type": "add_subscriptions",
    "id": 1002,
    "version": 1
  },
  {
    "channels": ["<data-feed-name-1>","<data-feed-name-2>", ...]
  }
]

Add Subscription Responses

The request only subscribes to channels if all proposed channels are valid and authorized.

[
  {
    "msg_type": "add_subscriptions_response",
    "id": 1002,
    "version": 1
  },
  {
    "subscriptions_added": true,
    "channel_status": [["<data-feed-name-1>", "no_error"],["<data-feed-name-2>", "no_error"], ...]
  }
]

Response Body

• subscriptions_added: Boolean indicating the outcome of the subscription attempt.
  • true if all channel subscriptions were successfully added.
  • false if any channel could not be subscribed due to errors; this does not necessarily imply that the channel was unsubscribed, as it might have been already subscribed.
• channel_status: An array of results for each channel attempted. This field helps identify why subscriptions_added might be false. Each entry in the array contains:
  • Channel Name: The name of the channel.
  • Status Indicator: Describes the subscription result.
    • no_error: No issues with the channel.
    • channel_already_subscribed: The channel was already subscribed (not considered an error).
    • channel_not_found: The channel does not exist.
    • access_denied: Subscription denied due to lack of authentication on this connection.

Cancel Subscription Requests

The request type informs the system that the client wishes to unsubscribe to data feed channels. The client will stop receiving asynchronous notification messages about the specified channels.

[
  {
    "msg_type": "cancel_subscriptions",
    "id": 1002,
    "version": 1
  },
  {
    "channels": ["<data-feed-name-1>","<data-feed-name-2>", ...]
  }
]

Cancel Subscription Responses

The request is accepted even if not every channel subscription could be canceled.

[
  {
    "msg_type": "cancel_subscriptions_response",
    "id": 1002,
    "version": 1
  },
  {
    "cancel_count": 1,
    "channel_status": [["<data-feed-name-1>", "no_error"],["<data-feed-name-2>", "no_error"], ...]
  }
]

Response Body

• cancel_count: The number of channel subscriptions cancelled.
• channel_status: An array of results for each channel cancel attempted. Each entry in the array contains:
  • Channel Name: The name of the channel.
  • Status Indicator: Describes the subscription result.
    • no_error: The channel subscription is canceled.
    • channel_not_subscribed: The channel was not subscribed.
    • channel_not_found: The channel does not exist.

Notifications

The msg_type field will describe what data feed the notification is related to. The client must first explicitly subscribe to WebSocket notifications using the add_subscriptions request type.

[
  {
    "msg_type": "<data-feed-name>",
    "id": 1002,
    "version": 1
  },
  <body-of-notification JSON object>
]