Messages
{
"cmd": "subscribe",
"data": {
"universes": [
"HK_Stock"
],
"channels": [
"ticker"
]
}
}{}{
"cmd": "<string>",
"message": "<string>"
}WebSocket Docs
Hong Kong Full-Market Ticker
Full-market Hong Kong stock ticker subscription; negotiate permessage-deflate during the WebSocket handshake
WSS
/
v1
/
realtime
Plan Access
| Plan | Available |
|---|---|
| Free | ❌ |
| Starter | ❌ |
| Professional | ❌ |
| All A-Shares | ❌ |
| All HK-Shares | ✅ |
| All US-Shares | ❌ |
| Enterprise | ✅ |
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-deflatewhen establishing the connection. - After successful negotiation, the handshake response includes
permessage-deflateinSec-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
Useuniverses to specify one or more market universes. channels must contain ticker.
{
"cmd": "subscribe",
"data": {
"universes": ["HK_Stock"],
"channels": ["ticker"]
}
}
{
"cmd": "subscribe",
"code": 0,
"message": "universe subscription successful",
"data": {
"universes": ["HK_Stock"],
"channels": ["ticker"]
}
}
JavaScript Example
The following Node.js example usesws and explicitly enables permessage-deflate when connecting:
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 500ticker messages:
[
{
"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.
- 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
{
"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. |
Messages
{
"cmd": "subscribe",
"data": {
"universes": [
"HK_Stock"
],
"channels": [
"ticker"
]
}
}{}{
"cmd": "<string>",
"message": "<string>"
}api_key
type:httpApiKey
Subscribe/Unsubscribe to Hong Kong stock Full-Market Ticker
type:object
Subscribe or unsubscribe to ticker updates for all Hong Kong stock symbols; permessage-deflate is required
Hong Kong stock Full-Market Ticker Batch
type:array
Initial snapshot and subsequent ticker updates are sent as arrays of up to 500 messages
WebSocket Error Response
type:object
Subscription or command error returned after the WebSocket connection is established