Subscribe and Unsubscribe

After the client completes the WebSocket connection and login authentication, it can declare the quote types to receive via subscription messages. After a subscription succeeds, the server pushes data by message type when market data changes; when a type of data is no longer needed, an unsubscribe message should be sent promptly to release subscription quota.

INFO

This page describes the client-visible subscription protocol. The server may internally convert symbol codes to internal identifiers and attach session, permission, quota, and other context; these internal fields are not parameters the client needs to pass in.

Request Format

Subscribe and unsubscribe requests are JSON objects sent over the authenticated WebSocket connection.

{
  "id": "req-001",
  "action": "subscribe",
  "quote": ["US.AAPL", "HK.00700"],
  "order_book": ["US.AAPL"],
  "ticker": ["US.AAPL"],
  "kline": [
    {
      "symbol": "US.AAPL",
      "period": "1m",
      "adjust": "none"
    }
  ]
}

Field Description

Field	Type	Required	Description
id	string	Recommended	Client request ID. The server response echoes this field so the client can match the request and the result.
action	string	Yes	Action type. Can be subscribe or unsubscribe.
quote	string[]	No	Subscribe or unsubscribe basic quote. Array elements are symbol codes.
order_book	string[]	No	Subscribe or unsubscribe order book. Array elements are symbol codes.
ticker	string[]	No	Subscribe or unsubscribe ticker. Array elements are symbol codes.
kline	object[]	No	Subscribe or unsubscribe current K-line. Each element consists of symbol, period, and adjust.

A single request can include multiple quote types at the same time. Fields that do not appear are not handled by this request.

action

subscribe

Subscribe to specified symbols and quote types. After the subscription succeeds, subsequent push messages are returned over the same WebSocket connection.

{
  "id": "sub-quote-001",
  "action": "subscribe",
  "quote": ["US.NVDA"],
  "order_book": ["US.NVDA"]
}

unsubscribe

Unsubscribe from specified symbols and quote types. After the unsubscribe succeeds, the server no longer pushes the corresponding data for the current connection.

{
  "id": "unsub-quote-001",
  "action": "unsubscribe",
  "quote": ["US.NVDA"],
  "order_book": ["US.NVDA"]
}

When unsubscribing, pass the types and symbols no longer needed as precisely as possible. For example, to turn off only K-line without affecting basic quote:

{
  "id": "unsub-kline-001",
  "action": "unsubscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    }
  ]
}

Symbol Code Format

Subscription requests use a unified symbol code format:

{market}.{code}

Common examples:

Market	Example	Description
Hong Kong Stock	HK.00700	Hong Kong stock codes usually preserve leading zeros.
US Stock	US.AAPL	US stocks use ticker symbols.
A-Share Connect	SH.600519, SZ.000001	Shanghai and Shenzhen markets are distinguished by exchange prefix.
Beijing Stock Exchange	BJ.830799	Beijing Stock Exchange market.

Different markets, categories, and permission levels may support different quote types. If a subscribed symbol or type is out of permission scope, the server may return a permission- or quota-related error.

K-line Parameters

Each item in the kline array represents a K-line subscription dimension: different periods or different adjustment methods for the same symbol are different subscriptions.

{
  "symbol": "US.AAPL",
  "period": "1m",
  "adjust": "none"
}

Field	Type	Required	Description
symbol	string	Yes	Symbol code, e.g. US.AAPL.
period	string	Yes	K-line period.
adjust	string	No	Adjustment method. Defaults to none when omitted.

Supported Periods

Common periods include:

Period	Description
1m	1 minute
3m	3 minutes
5m	5 minutes
10m	10 minutes
15m	15 minutes
30m	30 minutes
60m	60 minutes
120m	120 minutes
180m	180 minutes
240m	240 minutes
1D	Daily K
1W	Weekly K
1M	Monthly K
1Q	Quarterly K
1Y	Yearly K

Some markets or categories may support extended periods with suffixes, such as pre/post-market or overnight sessions. Availability is subject to the actual permissions and server response.

Adjustment Methods

Value	Description
none	No adjustment.
forward_exclude_dividend	Forward adjusted, excluding cash dividend adjustments.
forward_include_dividend	Forward adjusted, including cash dividend adjustments.
forward	Compatible notation, usually treated as forward_exclude_dividend.

Examples

Subscribe to Basic Quote, Order Book, and Ticker

{
  "id": "sub-realtime-001",
  "action": "subscribe",
  "quote": ["US.NVDA", "US.AAPL"],
  "order_book": ["US.NVDA"],
  "ticker": ["US.NVDA"]
}

After the subscription succeeds, the push types you may receive include:

• QUOTE: basic quote.
• ORDER_BOOK: order book.
• TICKER: ticker.
• BROKER_QUEUE: broker queue. This type is usually derived from the order book capability of some Hong Kong Stock categories and does not require a separate broker_queue field in the request.
• MARKET_STATE: market state. This type is market-level state information and may be pushed by the server based on the connection, market, and permissions; it is not passed in as a regular symbol subscription field.

Subscribe to K-line

{
  "id": "sub-kline-001",
  "action": "subscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    },
    {
      "symbol": "US.NVDA",
      "period": "1D",
      "adjust": "forward_exclude_dividend"
    }
  ]
}

After the subscription succeeds, the server pushes KLINE messages by K-line dimension. The push data includes period, adjust, and kl_list. For the field structure, see Data Format.

Switch K-line Period

When switching periods, unsubscribe from the old period first, then subscribe to the new period to avoid holding multiple unneeded K-line subscriptions at the same time.

{
  "id": "unsub-kline-1m-001",
  "action": "unsubscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    }
  ]
}

{
  "id": "sub-kline-5m-001",
  "action": "subscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "5m",
      "adjust": "none"
    }
  ]
}

Unsubscribe from All Common Types

{
  "id": "unsub-all-001",
  "action": "unsubscribe",
  "quote": ["US.NVDA"],
  "order_book": ["US.NVDA"],
  "ticker": ["US.NVDA"],
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    },
    {
      "symbol": "US.NVDA",
      "period": "1D",
      "adjust": "forward_exclude_dividend"
    }
  ]
}

Response Format

Subscribe and unsubscribe requests usually return a response message indicating whether the request was accepted. The response echoes the id from the request.

{
  "id": "sub-realtime-001",
  "code": 0,
  "message": ""
}

Field	Type	Description
id	string	Corresponds to the id in the request.
code	number	Result code. 0 indicates success; non-0 indicates failure.
message	string	Error description. May be empty on success.

Common failure reasons include:

• WebSocket login authentication not completed or the session has expired.
• action is not subscribe or unsubscribe.
• K-line period is unsupported or malformed.
• Symbol code is malformed, not subscribable, or the market does not support the type.
• Insufficient quote permissions.
• Subscription count exceeds the account or permission-level quota.
• Server temporarily unavailable or an internal dependency error.

For error troubleshooting, see Error Codes and Rate Limit and Quota.

Behavior Notes

Subscription Idempotency

The client can treat duplicate subscriptions for the same symbol and type as idempotent operations. To reduce invalid requests and quota consumption, it is still recommended that the client maintain local subscription state and only send subscribe or unsubscribe when the state changes.

Multi-type Subscription

The same symbol can be subscribed to quote, order_book, ticker, and multiple kline dimensions at the same time. The server distinguishes the returned content by the push message type. The client should not assume that different types of messages arrive in a fixed order when parsing pushes.

Reconnection

After a WebSocket disconnect, do not assume the original subscriptions are automatically restored. The client should recover in the following order:

1. Re-establish the WebSocket connection.
2. Complete login authentication again.
3. Re-send subscription requests based on the locally saved subscription list.
4. If necessary, use the REST real-time quote API to backfill the latest state during the disconnect.

Unsubscribe and Quota Release

When leaving a page, switching symbols, or closing data types no longer needed, actively unsubscribe. Subscription quota is usually managed by account, permission level, and subscription dimension; subscriptions on multiple connections of the same account may also jointly affect the available quota. The actual quota is subject to the account permissions and server response.

Derivative Push Types

Client request fields only need to cover the subscribable types: quote, order_book, ticker, kline. The following push types are returned at the server's discretion based on the subscribed capabilities, market, and permissions:

Push Type	Description
BROKER_QUEUE	Broker queue, mainly related to the order book capability of some Hong Kong Stock categories. The client does not need to pass in a broker_queue subscription field.
MARKET_STATE	Market state, representing market-level trading status. The client should identify it by type and handle it compatibly.

Best Practices

• Set a unique id for each subscription request and record the request state locally for timeout retries and troubleshooting.
• Maintain subscription lists per page or business module; subscribe on entry and unsubscribe on exit.
• It is recommended to re-send subscription requests every 5 minutes to keep the subscription state in sync with the server.
• When switching K-line period or adjustment method, unsubscribe from the old dimension first, then subscribe to the new dimension.
• Parse server pushes leniently: ignore unknown fields and apply business defaults for omitted fields.
• Do not retry indefinitely on non-0 responses; for insufficient permissions, quota exceeded, or parameter errors, correct the request or prompt the user first.
• Re-authenticate and re-subscribe after reconnecting; do not rely on the subscription state of the old connection.