> For the complete documentation index, see [llms.txt](https://en.apis.alltick.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.apis.alltick.co/websocket-api/websocket-interface-api/handicap-quote-subscription.md).

# Order Book (Real-time Tick-by-Tick, Market Depth) Subscription

English / [中文](https://apis.alltick.co/websocket-api/gu-piao-websocket-jie-kou-api/pan-kou-bao-jia-ding-yue)

## Interface Description

This interface supports subscribing to the latest market depth (real-time tick-by-tick, Order Book) data for products, but does not support historical market depth or historical tick data.

**Interface Features:** For each WebSocket connection, sending this request will overwrite the previous subscription by default. For example, if you initially subscribed to products A, B, and C and want to add E, F, and G, you must resend A, B, C, E, F, and G. After successful subscription, data will be pushed.

**Note:**

1、After a successful subscription, avoid frequent requests. Send a heartbeat every 10 seconds; if no heartbeat is received in 30 seconds, the WebSocket will disconnect.

2、Implement automatic reconnection logic to handle network disconnections.

3、Maximum market depth limits for each product:

3.1  Inactive products may have less depth than listed.

3.2 One side of the depth may be empty, such as during limit up or down for stocks.

<table data-full-width="false"><thead><tr><th width="117.265625"></th><th width="210.8359375">FX、Metals、Energy</th><th width="140.328125">Cryptocurrency</th><th width="142.38671875">HK Stocks</th><th width="141.296875">Chinese Stocks</th></tr></thead><tbody><tr><td>Order Book Description</td><td>Maximum 1 gears（Only Price, No Volume）</td><td>Maximum 5 gears</td><td>Maximum 10 gears</td><td>Maximum 5 gears</td></tr></tbody></table>

## Interface Limitations <a href="#interface-limitations" id="interface-limitations"></a>

1. Please be sure to read:[ \[ Websocket Interface Limitations \].](https://en.apis.alltick.co/integration-process/interface-restriction-description/websocket-interface-limitations)
2. Please be sure to read: [\[ Error Code Descriptions \].](https://en.apis.alltick.co/integration-process/interface-restriction-description/error-code-description)

### API Endpoints <a href="#api-endpoints" id="api-endpoints"></a>

**1、Stock Market Data API for US, HK, A-shares, and Index:**

Base Path: `/quote-stock-b-ws-api`&#x20;

Full URL: `wss://quote.alltick.co/quote-stock-b-ws-api`

**2、API for Forex, Precious Metals, Cryptocurrencies, and Commodities:**

Base Path: `/quote-b-ws-api`&#x20;

Full URL: `wss://quote.alltick.co/quote-b-ws-api`

## Request Examples

**1、Request Example for US, HK, A-shares, and Index Data:**

Each time you establish a connection, you must append your authentication token to the URL as follows:

`wss://quote.alltick.co/quote-stock-b-ws-api?token=your_token`

After a successful connection, you can subscribe to specific stock market data as needed. Please refer to the documentation below for detailed calling methods.

**2、Request Example for Forex, Precious Metals, Cryptocurrencies, and Commodities:**

Each time you establish a connection, you must append your authentication token to the URL as follows:

`wss://quote.alltick.co/quote-b-ws-api?token=your_token`

After a successful connection, you can subscribe to specific forex, cryptocurrency, precious metals, and commodities data as needed. Please refer to the documentation below for detailed calling methods.

## Request - Protocol Number：22002

#### Json definition

<table><thead><tr><th width="115.2265625">Field</th><th width="150.30859375">Name</th><th width="78.6796875">Type</th><th width="98.59375">Required</th><th>Description</th></tr></thead><tbody><tr><td>cmd_id</td><td>protocol number</td><td>integer</td><td>Yes</td><td>The protocol number for the order book data request is fixed: 22002</td></tr><tr><td>seq_id</td><td>response id</td><td>integer</td><td>Yes</td><td>Subscription request identifier, which will be returned in the response. (Customizable and can be repeated for each request)</td></tr><tr><td>trace</td><td>traceable id</td><td>string</td><td>Yes</td><td>Traceable ID for request log information (Customizable, and it should not be repeated for each request)</td></tr><tr><td>symbol_list</td><td>Product List</td><td>array</td><td>Yes</td><td>See the symbol definition below for the specific format.</td></tr></tbody></table>

#### Symbol definition

<table><thead><tr><th width="129.5703125">Field</th><th width="124.73828125">Name</th><th width="84.43359375">Type</th><th width="97.16796875">Required</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>Code</td><td>string</td><td>Yes</td><td>For specific content, please refer to the code list ：<a href="https://docs.google.com/spreadsheets/d/1avkeR1heZSj6gXIkDeBt8X3nv4EzJetw4yFuKjSDYtA/edit?gid=495387863#gid=495387863">[Click on the code list]</a><br><mark style="color:$danger;">Note: The case of the code value must be consistent with the code in the product list</mark></td></tr><tr><td>depth_level</td><td>Depth level</td><td>uint32</td><td>No</td><td>If there is no depth_level field, the background will only provide a quote for one layer, and the requested level is greater than the actual quote level, or if there is no depth_level field, the background will provide as many layers as there are actual quotes.</td></tr></tbody></table>

### Data Structure (JSON)

```
{
    "cmd_id":22002,
    "seq_id":123,
    "trace":"3baaa938-f92c-4a74-a228-fd49d5e2f8bc-1678419657806",
    "data":{
        "symbol_list": [
            {
                "code": "BTCUSDT",
                "depth_level": 5
            },
            {
                "code": "ETHUSDT",
                "depth_level": 5
            }
        ]
    }
}
```

## Response-protocol number：22003 <a href="#ying-da-xie-yi-hao-22001" id="ying-da-xie-yi-hao-22001"></a>

### Data Structure (JSON)

```
{
    "ret":200,
    "msg":"ok",
    "cmd_id":22003,
    "seq_id":123,
    "trace":"3baaa938-f92c-4a74-a228-fd49d5e2f8bc-1678419657806",
    "data":{
    }    
}
```

## Push - Protocol Number: 22999

#### Definition of data

<table><thead><tr><th width="130.23828125">Field</th><th width="180.63671875">Name</th><th width="103.8203125">Type</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>Code</td><td>string</td><td>Specific content, refer to the code list：<a href="https://docs.google.com/spreadsheets/d/1avkeR1heZSj6gXIkDeBt8X3nv4EzJetw4yFuKjSDYtA/edit?gid=495387863#gid=495387863">[Click on the code list]</a></td></tr><tr><td>seq</td><td>Quote Number</td><td>integer</td><td></td></tr><tr><td>tick_time</td><td>Quote Timestamp</td><td>integer</td><td>In milliseconds</td></tr><tr><td>bids</td><td>Bid Depth</td><td>array</td><td>See below for bids definition</td></tr><tr><td>asks</td><td>Ask Depth</td><td>array</td><td>See below for asks definition</td></tr></tbody></table>

#### bids definition

<table><thead><tr><th width="141.9921875">Field</th><th width="166.859375">Name</th><th width="142.4609375">Type</th><th>Description</th></tr></thead><tbody><tr><td>price</td><td>Bid Price</td><td>string</td><td></td></tr><tr><td>volume</td><td>Bid Volume</td><td>string</td><td><p>1、Forex, precious metals, and CFD indices do not provide volume.</p><p>2、Stocks and cryptocurrency data provide volume.</p></td></tr></tbody></table>

asks definition

<table><thead><tr><th width="147.1796875">Field</th><th width="163.4765625">Name</th><th width="143.359375">Type</th><th>Description</th></tr></thead><tbody><tr><td>price</td><td>Ask Price</td><td>string</td><td></td></tr><tr><td>volume</td><td>Ask Volume</td><td>string</td><td><p>1、Forex, precious metals, and CFD indices do not provide volume.</p><p>2、Stocks and cryptocurrency data provide volume.</p></td></tr></tbody></table>

### Data Structure (JSON)

```
{
    "cmd_id":22999,
    "data":{
	"code": "HK-1288",
        "seq": 1605509068000001,
        "tick_time": 1605509068,
        "bids": [
            {
                "price": "9.12",
                "volume": "9.12"
            }
        ],
        "asks": [
            {
                "price": "147.12",
                "volume": "147.12"
            }
        ]
    }
}
```

### Official Website

{% hint style="info" %}
Official website: <https://alltick.co/>
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://en.apis.alltick.co/websocket-api/websocket-interface-api/handicap-quote-subscription.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.