> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/websocket-api/market-data/partial-order-book.md).

# Partial Order Book

Real-time order book snapshots with top levels of bids and asks.

**Channel:** `orderbook`

## Overview

The orderbook channel provides real-time snapshots of the order book showing configurable price levels on both bid and ask sides. Upon subscription, the current order book state is sent immediately. Afterward, updates are sent when the book changes.

## Connection

Connect to the WebSocket endpoint:

```
wss://marketdata.app.hello.trade/ws
```

## Subscription Request

```json
{
  "type": "subscribe",
  "channel": "orderbook",
  "symbols": ["BTC", "ETH"],
  "levels": 10,
  "orderbookInterval": 100
}
```

| Field               | Type      | Required | Description                                                                |
| ------------------- | --------- | -------- | -------------------------------------------------------------------------- |
| `type`              | string    | Yes      | Must be `"subscribe"`                                                      |
| `channel`           | string    | Yes      | Must be `"orderbook"`                                                      |
| `symbols`           | string\[] | Yes      | List of instrument symbols                                                 |
| `levels`            | Number    | No       | Number of levels: `1`, `5`, `10`, `20`, or `100` (default: `10`)           |
| `orderbookInterval` | Number    | No       | Update interval in milliseconds: `100`, `1000`, or `2000` (default: `100`) |
| `decimals`          | Number    | No       | Decimals to group levels by (default: `0`)                                 |

## Unsubscription Request

```json
{
  "type": "unsubscribe",
  "channel": "orderbook",
  "symbols": ["BTC"]
}
```

## Response

```json
{
  "type": "marketData",
  "channel": "orderbook",
  "data": {
    "symbol": "BTC",
    "bids": [
      { "price": "45000.50", "quantity": "1.5", "numberOfOrders": "3" },
      { "price": "45000.00", "quantity": "2.3", "numberOfOrders": "5" },
      { "price": "44999.50", "quantity": "1.8", "numberOfOrders": "2" }
    ],
    "asks": [
      { "price": "45001.00", "quantity": "1.2", "numberOfOrders": "2" },
      { "price": "45001.50", "quantity": "2.1", "numberOfOrders": "4" },
      { "price": "45002.00", "quantity": "1.6", "numberOfOrders": "3" }
    ],
    "timeStamp": 1705596400000
  }
}
```

| Field       | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| `symbol`    | string | Instrument symbol                                             |
| `bids`      | Array  | Bid price levels, sorted by price descending (best bid first) |
| `asks`      | Array  | Ask price levels, sorted by price ascending (best ask first)  |
| `timeStamp` | Number | Unix timestamp (milliseconds) of order book snapshot          |

**Price Level Structure:**

| Field            | Type   | Description                          |
| ---------------- | ------ | ------------------------------------ |
| `price`          | string | Price level                          |
| `quantity`       | string | Total quantity at this price level   |
| `numberOfOrders` | string | Number of orders at this price level |

## Error Response

```json
{
  "type": "error",
  "message": "Invalid subscription request",
  "code": 400
}
```

## Notes

* Configurable depth: 1, 5, 10, 20, or 100 levels per side
* Bids are sorted highest price first
* Asks are sorted lowest price first
* Empty arrays indicate no orders on that side
* Updates are sent only when the order book changes
* Update interval controls snapshot frequency (100ms, 1000ms, or 2000ms)