1. Introduction#
While there is a strict access frequency control for REST API, we highly recommend that API users utilize Websocket to get the real-time data.The recommended way is to just create a Websocket connection and subscribe to multiple channels.
2. Apply Connect Token#
Before creating a Websocket connection, you need to get the websocket base URL and apply for a Token。The token is valid for only 24 hours, and a single connection is expected to be disconnected after 24 hours.
3. Create connection#
Once the connection has been successfully established, the system will send a welcome message.The connection will only be available once the welcome message has been received
{
"id": "hQvf8jkno",
"type": "welcome"
}
connectId: The connection ID is a unique value taken from the client side. The welcome message ID and the error message ID are both connectId.If you only want to receive private messages of the specified topic, please set privateChannel to true when subscribing.4. Ping#
{
"id": "1545910590801",
"type": "ping"
}
To prevent the TCP link being disconnected from the server, the client side needs to send ping messages every pingInterval time to the server to keep the link alive.After the ping message is sent to the server, the system will return a pong message to the client side.If the server has not received any message from the client for a long time, the connection will be disconnected.{
"id": "1545910590801",
"type": "pong",
"timestamp": 1764215232226553
}
5. Subscribe#
To subscribe to channel messages from a specific server, the client side should send a subscription message to the server.Parameters#
ID: ID is a unique string to mark the request which is same as ID property of ack.
Topic: The topic you want to subscribe to.
PrivateChannel: You can subscribe to some private topics through the privateChannel parameter. This parameter is set to "false" by default. When set to "true", you can only receive content pushes related to the topics you subscribe to.
Response If the response is set to true, the system will return ack messages after the subscription has succeeded.
{
"id": 1545910660739,
"type": "subscribe",
"topic": "/market/ticker:BTC-USDT,ETH-USDT",
"privateChannel": false,
"response": true
}
{
"id": 1545910660739,
"type": "subscribe",
"topic": "/market/ticker:XBTUSDM",
"privateChannel": false,
"response": true
}
If the subscription succeeds, the system will send ack messages to you, when the response is set as true.{
"id": "1545910660739",
"type": "ack"
}
Whenever topic messages are generated, the system will send the corresponding messages to the client side. For details about the message format, please check the definitions of topics.6. UnSubscribe#
Unsubscribe from topics you have subscribed to.Parameters#
ID: ID unique string to mark the request.
Topic: The topic you want to unsubscribe from.
PrivateChannel: You can unsubscribe from some private topics through the privateChannel parameter. Set to "true", you can unsubscribe from related private channel pushes.
Response: If the response is set as true, the system will return the ack messages after the unsubscription succeeds.
{
"id": "1545910840805",
"type": "unsubscribe",
"topic": "/market/ticker:BTC-USDT,ETH-USDT",
"privateChannel": false,
"response": true
}
{
"id": "1545910840805",
"type": "unsubscribe",
"topic": "/market/ticker:XBTUSDM",
"privateChannel": false,
"response": true
}
If the unsubscription succeeds, the system will send ack messages to you, when the response is set as true.{
"id": "1545910840805",
"type": "ack"
}