> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Subscription Protocol for Upside API

> Learn how to subscribe and unsubscribe to WebSocket channels on Upside using the method + subscription object protocol introduced in v0.14.

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:

```json theme={null}
{"method": "subscribe", "subscription": {"type": "l2Book", "asset": "1"}}
```

The server responds with a `subscriptionResponse` acknowledgement:

```json theme={null}
{
  "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:

```json theme={null}
{"method": "unsubscribe", "subscription": {"type": "l2Book", "asset": "1"}}
```

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

<Warning>
  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.
</Warning>

## Error messages

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

```json theme={null}
{"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.

<Tip>
  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.
</Tip>

## Quick examples by channel type

<Tabs>
  <Tab title="l2Book">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "l2Book", "asset": "1"}}
    ```
  </Tab>

  <Tab title="bbo">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "bbo", "asset": "1"}}
    ```
  </Tab>

  <Tab title="trades">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "trades", "asset": "1"}}
    ```
  </Tab>

  <Tab title="candle">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "candle", "asset": "1", "interval": "1m"}}
    ```
  </Tab>

  <Tab title="orderUpdates">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "orderUpdates", "user": "0xabc...123"}}
    ```
  </Tab>

  <Tab title="openOrders">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "openOrders", "user": "0xabc...123"}}
    ```
  </Tab>

  <Tab title="userFills">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "userFills", "user": "0xabc...123"}}
    ```
  </Tab>

  <Tab title="config">
    ```json theme={null}
    {"method": "subscribe", "subscription": {"type": "config"}}
    ```
  </Tab>
</Tabs>