> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tickdb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Hong Kong Full-Market Ticker
> Full-market Hong Kong stock ticker subscription; negotiate permessage-deflate during the WebSocket handshake
## Plan Access
| Plan | Available |
| - | :-: |
| Free | ❌ |
| Starter | ❌ |
| Professional | ❌ |
| All A-Shares | ❌ |
| All HK-Shares | ✅ |
| All US-Shares | ❌ |
| Enterprise | ✅ |
A subscription to HK\_Stock first sends a batched market snapshot, then continuously pushes changed tickers.
## Enable WebSocket Compression
A full-market subscription must successfully negotiate `permessage-deflate` during the WebSocket handshake. This is different from the `gzip`, `br`, and `zstd` compression used by REST endpoints and cannot be enabled through `Accept-Encoding` or a subscription message.
* The client must enable `permessage-deflate` when establishing the connection.
* After successful negotiation, the handshake response includes `permessage-deflate` in `Sec-WebSocket-Extensions`.
* If compression is not negotiated, a full-market subscription returns error code `2008`. Enable compression and reconnect.
* Browsers normally negotiate WebSocket compression automatically. Server-side clients should explicitly enable it and verify the negotiated extension.
## Subscription Message
Use `universes` to specify one or more market universes. `channels` must contain `ticker`.
```json theme={null}
{
"cmd": "subscribe",
"data": {
"universes": ["HK_Stock"],
"channels": ["ticker"]
}
}
```
Successful subscription response:
```json theme={null}
{
"cmd": "subscribe",
"code": 0,
"message": "universe subscription successful",
"data": {
"universes": ["HK_Stock"],
"channels": ["ticker"]
}
}
```
## JavaScript Example
The following Node.js example uses `ws` and explicitly enables `permessage-deflate` when connecting:
```javascript theme={null}
const WebSocket = require("ws");
const market = "HK_Stock";
const ws = new WebSocket(
`wss://api.tickdb.ai/v1/realtime?api_key=${process.env.TICKDB_API_KEY}`,
{ perMessageDeflate: true },
);
ws.on("upgrade", (response) => {
const extensions = response.headers["sec-websocket-extensions"] || "";
if (!extensions.includes("permessage-deflate")) {
ws.close();
throw new Error("permessage-deflate was not negotiated");
}
});
ws.on("open", () => {
ws.send(JSON.stringify({
cmd: "subscribe",
data: {
universes: [market],
channels: ["ticker"],
},
}));
});
ws.on("message", (raw) => {
const message = JSON.parse(raw.toString());
if (Array.isArray(message)) {
// Full snapshot or incremental update; each array contains at most 500 ticker messages
for (const item of message) {
console.log(item.data.symbol, item.data.last_price);
}
return;
}
// Connection response, subscription result, error, or pong
console.log(message);
});
ws.on("error", console.error);
```
## Push Format
Full-market data is pushed in JSON arrays of at most 500 `ticker` messages:
```json theme={null}
[
{
"cmd": "ticker",
"data": {
"symbol": "700",
"name": "Tencent Holdings",
"type": "stock",
"last_price": "543",
"timestamp": 1773292807000
}
}
]
```
* The first subscription delivers the current full snapshot, which may be split across multiple arrays.
* After the initial snapshot, only changed tickers are pushed, using the same array format.
* Quote fields follow the corresponding REST endpoint: [HK-stock full-market quotes](../rest/api_ticker_hk_stock).
* After a full-market subscription is activated for a market, existing per-symbol stock subscriptions for that market are canceled on the same connection to avoid duplicate messages.
## Unsubscribe
```json theme={null}
{
"cmd": "unsubscribe",
"data": {
"universes": ["HK_Stock"],
"channels": ["ticker"]
}
}
```
## Common Errors
| Code | Description |
| - | - |
| `2001` | Invalid `universes` or `channels` format. |
| `2002` | Unsupported universe or channel. |
| `2008` | The connection did not negotiate `permessage-deflate`; enable compression and reconnect. |
| `4005` | The current API key does not have permission for the requested full-market subscription. |
| `5003` | The requested full-market subscription is temporarily unavailable. |
## AsyncAPI
````yaml asyncapi.en.json ticker_hk_stock
id: ticker_hk_stock
title: Ticker_hk_stock
description: >-
Full-market Hong Kong stock ticker subscription; negotiate permessage-deflate
during the WebSocket handshake
servers:
- id: production
protocol: wss
host: api.tickdb.ai
bindings: []
variables: []
address: /v1/realtime
parameters: []
bindings: []
operations:
- &ref_2
id: sendTickerHkStockSubscription
title: Send ticker hk stock subscription
type: receive
messages:
- &ref_4
id: subscribeRequest
contentType: application/json
payload:
- name: Subscribe/Unsubscribe to Hong Kong stock Full-Market Ticker
description: >-
Subscribe or unsubscribe to ticker updates for all Hong Kong stock
symbols; permessage-deflate is required
type: object
properties:
- name: cmd
type: string
description: Command type (subscribe or unsubscribe)
enumValues:
- subscribe
- unsubscribe
required: true
- name: data
type: object
required: true
properties:
- name: universes
type: array
description: Full-market universe to subscribe or unsubscribe
required: true
properties:
- name: item
type: string
enumValues:
- HK_Stock
required: false
- name: channels
type: array
description: Ticker channel for full-market updates
required: true
properties:
- name: item
type: string
enumValues:
- ticker
required: false
headers: []
jsonPayloadSchema:
type: object
additionalProperties: false
properties:
cmd:
type: string
enum:
- subscribe
- unsubscribe
default: subscribe
description: Command type (subscribe or unsubscribe)
x-parser-schema-id:
data:
type: object
additionalProperties: false
properties:
universes:
type: array
minItems: 1
maxItems: 1
items:
type: string
enum:
- HK_Stock
x-parser-schema-id:
default:
- HK_Stock
description: Full-market universe to subscribe or unsubscribe
x-parser-schema-id:
channels:
type: array
minItems: 1
maxItems: 1
items:
type: string
enum:
- ticker
x-parser-schema-id:
default:
- ticker
description: Ticker channel for full-market updates
x-parser-schema-id:
required:
- universes
- channels
x-parser-schema-id:
required:
- cmd
- data
x-parser-schema-id:
title: Subscribe/Unsubscribe to Hong Kong stock Full-Market Ticker
description: >-
Subscribe or unsubscribe to ticker updates for all Hong Kong stock
symbols; permessage-deflate is required
example: |-
{
"cmd": "subscribe",
"data": {
"universes": [
"HK_Stock"
],
"channels": [
"ticker"
]
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribeRequest
bindings: []
extensions: &ref_1
- id: x-parser-unique-object-id
value: ticker_hk_stock
- &ref_3
id: receiveTickerHkStockBatch
title: Receive ticker hk stock batch
type: send
messages:
- &ref_5
id: tickerBatch
contentType: application/json
payload:
- type: array
maxItems: 500
items: &ref_0
type: object
additionalProperties: false
properties:
cmd:
type: string
const: ticker
description: Message type
x-parser-schema-id:
data:
type: object
additionalProperties: false
properties:
symbol:
type: string
example: AAPL.US
description: Trading symbol
x-parser-schema-id:
name:
type: string
description: Product name, when available
x-parser-schema-id:
type:
type: string
enum:
- stock
- indices
- crypto
- forex
- futures
description: Symbol type
x-parser-schema-id:
category:
type: string
description: Product category, when available
x-parser-schema-id:
last_price:
type: string
example: '150.25'
description: Latest price
x-parser-schema-id:
open:
type: string
description: Opening price, when available
x-parser-schema-id:
prev_close:
type: string
description: Previous close or reference price, when available
x-parser-schema-id:
bid_price:
type: string
description: Best bid, when available
x-parser-schema-id:
ask_price:
type: string
description: Best ask, when available
x-parser-schema-id:
spread:
type: string
description: Bid-ask spread for forex or metals, when available
x-parser-schema-id:
volume_24h:
type: string
description: >-
Trading volume; rolling 24 hours for crypto, usually
current day or session for stocks and futures
x-parser-schema-id:
quote_volume_24h:
type: string
description: >-
Turnover over the same window as volume_24h, when
available
x-parser-schema-id:
high_24h:
type: string
description: High price over the same window as volume_24h
x-parser-schema-id:
low_24h:
type: string
description: Low price over the same window as volume_24h
x-parser-schema-id:
price_change_24h:
type: string
description: >-
Price change over the same statistics window, when
available
x-parser-schema-id:
price_change_percent_24h:
type: string
description: Price change percentage, when available
x-parser-schema-id:
trade_session:
type: string
enum:
- pre_market
- post_market
- overnight
description: US stock extended trading session, when applicable
x-parser-schema-id:
quote_volume:
type: string
description: >-
Turnover in the current extended trading session, when
available
x-parser-schema-id:
pre_market_quote:
type: object
description: Pre-market quote, when available
x-parser-schema-id:
post_market_quote:
type: object
description: Post-market quote, when available
x-parser-schema-id:
overnight_quote:
type: object
description: Overnight quote, when available
x-parser-schema-id:
timestamp:
type: integer
example: 1703123456789
description: Unix timestamp in milliseconds
x-parser-schema-id:
required:
- symbol
- last_price
- timestamp
x-parser-schema-id:
required:
- cmd
- data
x-parser-schema-id:
x-parser-schema-id:
name: Hong Kong stock Full-Market Ticker Batch
description: >-
Initial snapshot and subsequent ticker updates are sent as arrays
of up to 500 messages
headers: []
jsonPayloadSchema:
type: array
maxItems: 500
items: *ref_0
x-parser-schema-id:
title: Hong Kong stock Full-Market Ticker Batch
description: >-
Initial snapshot and subsequent ticker updates are sent as arrays of
up to 500 messages
example: '{}'
bindings: []
extensions:
- id: x-parser-unique-object-id
value: tickerBatch
- &ref_6
id: errorResponse
contentType: application/json
payload:
- name: WebSocket Error Response
description: >-
Subscription or command error returned after the WebSocket
connection is established
type: object
properties:
- name: cmd
type: string
description: Command that caused the error
required: true
- name: code
type: oneOf
description: >-
Error code; clients should normalize it to a string before
comparison
required: true
- name: message
type: string
description: Human-readable error message
required: true
- name: data
type: oneOf
description: Optional error context
required: false
headers: []
jsonPayloadSchema:
type: object
additionalProperties: false
properties:
cmd:
type: string
description: Command that caused the error
x-parser-schema-id:
code:
description: >-
Error code; clients should normalize it to a string before
comparison
oneOf:
- type: integer
x-parser-schema-id:
- type: string
x-parser-schema-id:
x-parser-schema-id:
message:
type: string
description: Human-readable error message
x-parser-schema-id:
data:
description: Optional error context
oneOf:
- type: 'null'
x-parser-schema-id:
- type: object
additionalProperties: true
x-parser-schema-id:
- type: array
items:
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
required:
- cmd
- code
- message
x-parser-schema-id:
title: WebSocket Error Response
description: >-
Subscription or command error returned after the WebSocket connection
is established
example: |-
{
"cmd": "",
"message": ""
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: errorResponse
bindings: []
extensions: *ref_1
sendOperations:
- *ref_2
receiveOperations:
- *ref_3
sendMessages:
- *ref_4
receiveMessages:
- *ref_5
- *ref_6
extensions:
- id: x-parser-unique-object-id
value: ticker_hk_stock
securitySchemes:
- id: apiKey
name: api_key
type: httpApiKey
in: query
extensions: []
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.