> ## 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.

# Upside WebSocket API: Real-Time Data Streaming

> Connect to the Upside WebSocket at wss://dev.upsidemax.xyz/ws for real-time order book, trades, candles, and private account updates.

The Upside WebSocket API delivers real-time push streams for market data and account state without polling. Once you open a connection to `wss://dev.upsidemax.xyz/ws`, the server pushes updates as they occur — typically every block (\~500 ms) for price channels. Private account channels such as order updates and fills are available to any subscriber who provides their account address, and authenticating first is strongly recommended for forward compatibility.

## Connection lifecycle

<Steps>
  <Step title="Open the WebSocket connection">
    Establish a WebSocket connection to `wss://dev.upsidemax.xyz/ws`. No HTTP upgrade headers beyond the standard WebSocket handshake are required.
  </Step>

  <Step title="(Optional) Authenticate">
    Send an `Auth` message to associate the connection with your account. This is required before subscribing to private channels and recommended for all account-level subscriptions. See [Authentication](/websocket/authentication) for details.
  </Step>

  <Step title="Subscribe to channels">
    Send a `subscribe` message for each channel you want to receive. You can subscribe to multiple channels on the same connection. See [Subscription](/websocket/subscription) for the message format.
  </Step>

  <Step title="Receive push messages">
    The server pushes messages to you as events occur. Each message includes a `channel` field that identifies its source so you can route it to the correct handler.
  </Step>

  <Step title="Send Ping every 30 seconds to keep alive">
    Send a standard WebSocket `ping` frame (or the JSON `{"msg": "Ping"}` message) every 30 seconds. The server replies with a `Pong` to keep the connection alive.
  </Step>
</Steps>

## Available channels

The table below summarises every channel available on the WebSocket API. Public channels are accessible without any prior authentication step.

| Channel        | Auth Required | Description                                     |
| -------------- | ------------- | ----------------------------------------------- |
| `l2Book`       | No            | Full order book snapshots pushed every block    |
| `bbo`          | No            | Best bid/ask — bandwidth-efficient top-of-book  |
| `trades`       | No            | Public trade stream for a contract              |
| `candle`       | No            | Real-time OHLCV candles at a chosen interval    |
| `config`       | No            | Contract configuration change notifications     |
| `orderUpdates` | No\*          | Incremental order state changes for an account  |
| `openOrders`   | No\*          | Active orders snapshot plus incremental updates |
| `userFills`    | No\*          | All fills where your account is taker or maker  |

\* Private channels currently accept the account address directly in the subscription parameters without requiring a prior `Auth` message. Authentication is still recommended for future compatibility.

## Reconnection

If the connection drops, the client automatically reconnects after **5 seconds**. On reconnect, your authentication and subscription state are automatically restored — you do not need to manually re-send your `Auth` message or re-subscribe to your channels.

<Note>
  The WebSocket endpoint does not guarantee message ordering across different channels. If you need causal ordering between, for example, `openOrders` and `orderUpdates`, correlate messages using their `ts` timestamps and `bookVersion` / order ID fields.
</Note>

## Channel quick-reference

<CardGroup cols={2}>
  <Card title="l2Book" icon="book-open" href="/websocket/l2-book">
    Full order book snapshots pushed on every block — bids and asks with price, size, and order count.
  </Card>

  <Card title="bbo" icon="arrow-up-arrow-down" href="/websocket/bbo">
    Best bid and best ask only — lower bandwidth than l2Book for top-of-book use cases.
  </Card>

  <Card title="trades" icon="arrow-right-arrow-left" href="/websocket/trades">
    All public trades for a contract as they execute on-chain.
  </Card>

  <Card title="candle" icon="chart-candlestick" href="/websocket/candle">
    Live OHLCV candle updates at any supported interval, with closed-bar events.
  </Card>

  <Card title="orderUpdates" icon="bell" href="/websocket/order-updates">
    Incremental order state changes — placed, filled, cancelled, and TP/SL events.
  </Card>

  <Card title="openOrders" icon="list-check" href="/websocket/open-orders">
    Initial snapshot of all active orders followed by real-time incremental updates.
  </Card>

  <Card title="userFills" icon="receipt" href="/websocket/user-fills">
    Every fill involving your account — whether you were the taker or the maker.
  </Card>

  <Card title="config" icon="gear" href="/websocket/config">
    Lightweight notifications when contract configuration changes — new listings, freezes, or parameter updates.
  </Card>
</CardGroup>