Subscriptions

After connecting, the client chooses what to receive by sending subscribe messages. Subscriptions are dynamic: you can add, change, or drop them at any time over the life of the connection, without reconnecting.

Subscribing

Send a subscribe message naming the channel. Optionally restrict it to specific events with event_ids:

{ "type": "subscribe", "channel": "market", "event_ids": [12345, 12346] }

Omit event_ids (or send an empty array) to receive all updates on that channel that your key is entitled to:

{ "type": "subscribe", "channel": "market" }

The server replies with an acknowledgement echoing the effective filter that is now active:

{
  "type": "subscribe",
  "status": "ok",
  "channel": "market",
  "effective": { "event_ids": [12345, 12346] }
}

A wildcard subscription comes back as "effective": { "event_ids": [] }.

The filter applies to every data message on the channel except event_sync, which goes to all event channel subscribers regardless of event_ids.

Don't assume the ack arrives first

On a busy feed, data messages can arrive before the subscribe acknowledgement. Branch on type rather than assuming the first message after subscribing is the ack.

Subscribable channels

A partner key may subscribe to event and market. These are described in Message Format. Subscribe to one channel per message; send multiple messages to subscribe to several.

Resubscribing replaces, it does not add

warning

A second subscribe on a channel replaces the previous filter for that channel. It does not merge with it. Always send the full set of event_ids you want.

For example, to watch events 12345 then add 99999, the second message must list both:

{ "type": "subscribe", "channel": "market", "event_ids": [12345] }

{ "type": "subscribe", "channel": "market", "event_ids": [12345, 99999] }

Sending { "type": "subscribe", "channel": "market", "event_ids": [99999] } as the second message would drop 12345. Track the desired filter set on the client and always send it in full.

Unsubscribing

Stop one channel:

{ "type": "unsubscribe", "channel": "market" }

{ "type": "unsubscribe", "status": "ok", "channel": "market" }

Stop everything on the connection at once:

{ "type": "unsubscribe_all" }

{ "type": "unsubscribe_all", "status": "ok" }

Inspecting current subscriptions

Ask the server what the connection is currently subscribed to. This is useful for reconciling client state after a reconnect:

{ "type": "subscriptions" }

{
  "type": "subscriptions",
  "data": [
    { "channel": "market", "event_ids": [12345, 12346] },
    { "channel": "event", "event_ids": [] }
  ]
}

This reports current subscription state only. It does not replay any data. See Reconnecting.

Rejected subscriptions

A subscribe that the server cannot honour is rejected with status: "error"; the connection stays open. Fix the request and resend.

reason	Meaning
unknown channel: <name>	The channel is not a recognised, subscribable channel. Only event and market are available to a partner key; any other value — including internal channels — is reported this way. The reply carries no channel field and does not distinguish an internal channel from an unrecognised name.

{ "type": "subscribe", "status": "error", "reason": "unknown channel: bet" }