Subscription

Every channel on the UpsideMAX WebSocket follows the same subscribe/unsubscribe protocol. You send a JSON message with a method field set to "subscribe" or "unsubscribe", and a subscription object that specifies the channel type and any required parameters. The server acknowledges each request and begins (or stops) pushing messages on that channel.

Subscribing to a channel

Send the following JSON frame to start receiving messages on a channel:

{"method": "subscribe", "subscription": {"type": "l2Book", "asset": "1"}}

The server responds with a subscriptionResponse acknowledgement:

{
  "channel": "subscriptionResponse",
  "data": {
    "method": "subscribe",
    "subscription": {"type": "l2Book", "asset": "1"}
  }
}

The data field mirrors your original request so you can match acknowledgements to subscriptions in async code.

Unsubscribing from a channel

Send the same subscription object with "method": "unsubscribe" to stop receiving messages:

{"method": "unsubscribe", "subscription": {"type": "l2Book", "asset": "1"}}

The server sends a matching subscriptionResponse with "method": "unsubscribe" to confirm.

The older {"msg": "Subscribe", "channels": [...]} array format is no longer accepted. All clients must use the method + subscription object format shown above.

Error messages

If a subscription request is invalid, the server responds on the error channel:

{"channel": "error", "data": {"code": "BAD_SUBSCRIPTION", "message": "missing/invalid params for type=bbo", "subscription": {"type": "bbo"}}}

data.subscription echoes the subscription object of the refused request, mirroring the subscriptionResponse acknowledgement, so you can tell which of several concurrent subscriptions was refused.

Code	Meaning
`BAD_SUBSCRIPTION`	`subscription.type` is missing, or a required parameter for that type is missing or invalid — for example `asset` sent as a number instead of a string. An optional parameter with an invalid form is also rejected (for example an `l2Book` `group` that is not an integer), as is an `l2Book` `group` that is not configured for the contract
`UNKNOWN_TYPE`	The parameters are present but cannot be resolved to a valid channel — for example a `user` that is not `0x` followed by 40 hex characters. `message` reads `Could not resolve subscription to a valid channel: <channel>`

All subscription types and parameters

The table below lists every channel type and its parameters. No channel requires an authentication step.

type	Parameters
`l2Book`	`asset`, `group` (optional)
`bbo`	`asset`
`trades`	`asset`
`candle`	`asset`, `interval`
`ticker`	`asset`
`allMarkets`	(none)
`orderUpdates`	`user` (account address)
`openOrders`	`user` (account address)
`userFills`	`user` (account address)
`userAccount`	`user` (account address), `marketDeployerId`
`config`	(none)

Parameter formats:

asset — the contract ID as a string, for example "1". Read contract IDs from configs.
user — the account address in lowercase, 0x followed by 40 hex characters. The address must belong to a registered account; otherwise the server returns an error frame.
group — optional for l2Book: a price-grouping level from the contract’s digitMerge list in configs. See L2 Book.

You can hold multiple active subscriptions on a single WebSocket connection. There is no hard limit on the number of simultaneous subscriptions, but subscribing to many high-frequency channels (e.g., l2Book for many assets) on one connection may increase message processing latency on the client side.

Quick examples by channel type

{"method": "subscribe", "subscription": {"type": "l2Book", "asset": "1"}}

{"method": "subscribe", "subscription": {"type": "bbo", "asset": "1"}}

{"method": "subscribe", "subscription": {"type": "trades", "asset": "1"}}

{"method": "subscribe", "subscription": {"type": "ticker", "asset": "1"}}

{"method": "subscribe", "subscription": {"type": "allMarkets"}}

{"method": "subscribe", "subscription": {"type": "candle", "asset": "1", "interval": "1m"}}

{"method": "subscribe", "subscription": {"type": "orderUpdates", "user": "0xabc...123"}}

{"method": "subscribe", "subscription": {"type": "openOrders", "user": "0xabc...123"}}

{"method": "subscribe", "subscription": {"type": "userFills", "user": "0xabc...123"}}

{"method": "subscribe", "subscription": {"type": "config"}}

Overview

Market Channels

Account Channels

Subscribing to a channel

Unsubscribing from a channel

Error messages

All subscription types and parameters

Quick examples by channel type

​Subscribing to a channel

​Unsubscribing from a channel

​Error messages

​All subscription types and parameters

​Quick examples by channel type

Subscribing to a channel

Unsubscribing from a channel

Error messages

All subscription types and parameters

Quick examples by channel type