WebSocket Subscription Protocol for Upside API

Every channel on the Upside 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 was deprecated in v0.14 and 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 required parameter: asset"}}

Code	Meaning
`BAD_SUBSCRIPTION`	One or more required subscription parameters are missing or have an invalid value
`NOT_AUTHENTICATED`	The requested channel requires an authenticated connection — send `Auth` first

All subscription types and parameters

The table below lists every channel type, its required parameters, and whether authentication is needed.

type	Parameters	Auth?
`l2Book`	`asset`	No
`bbo`	`asset`	No
`trades`	`asset`	No
`candle`	`asset`, `interval`	No
`orderUpdates`	`user` (account address)	No*
`openOrders`	`user` (account address)	No*
`userFills`	`user` (account address)	No*
`config`	(none)	No

* Private channels accept the account address in the user field without requiring a prior Auth message today. Authenticating first is recommended for forward compatibility.

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": "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

WebSocket Subscription Protocol for Upside API

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