Introduction

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.
::: tip
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 apply for a Token, The Token will expires in 24 hours, but it will remain valid if there is no disconnection. It is recommended to change the token every 24 hours.

It should be noted that:

• if you subscribe to spot/margin data, you need to obtain tokens through the spot base URL;
  Get Public Token - Spot/Margin
  Get Private Token - Spot/Margin

• if you subscribe to futures data, you need to obtain tokens through the futures base URL, which cannot be mixed.
  Get Public Token - Futures
  Get Private Token - Futures

3. Create connection

var socket = new WebSocket(
  'wss://ws-api-spot.kucoin.com?token=xxx&connectId=xxxxx',
);

When the connection is successfully established, the system will send a welcome message.

::: tip
Only when the welcome message is received will the connection be available
:::

{
  "id": "hQvf8jkno",
  "type": "welcome"
}

connectId: the connection id, a unique value taken from the client side. Both the id of the welcome message and the id of the error message are 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 by the server, the client side needs to send ping messages every pingInterval time to the server to keep alive the link.

After the ping message is sent to the server, the system would 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"
}

5. Subscribe

To subscribe channel messages from a certain server, the client side should send subscription message to the server.

Parameters

• ID: ID is 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 as true, the system will return the ack messages after the subscription succeed.

//Spot Demo
{
  "id": 1545910660739, //The id should be an unique value
  "type": "subscribe",
  "topic": "/market/ticker:BTC-USDT,ETH-USDT", //Topic needs to be subscribed. Some topics support to divisional subscribe the informations of multiple trading pairs through ",".
  "privateChannel": false, //Adopted the private channel or not. Set as false by default.
  "response": true //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
}

//Future Demo
{
  "id": 1545910660739, //The id should be an unique value
  "type": "subscribe",
  "topic": "/market/ticker:XBTUSDM", //Subscribed topic. Some topics support to divisional subscribe the informations of multiple trading pairs through ",".
  "privateChannel": false, //Adopted the private channel or not. Set as false by default.
  "response": true //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
}

If the subscription succeeds, the system will send ack messages to you, when the response is set as true.

{
  "id": "1545910660739",
  "type": "ack"
}

While there are topic messages 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.
• PrivateChannel: You can unsubscribe from some private topics through the privateChannel parameter. Set to "true", you can unsubscribe related private channel push.
• Response: If the response is set as true, the system would return the ack messages after the unsubscription succeed.

//Spot Unsubscribe Topic
{
  "id": "1545910840805", //The id should be an unique value
  "type": "unsubscribe",
  "topic": "/market/ticker:BTC-USDT,ETH-USDT", //Topic needs to be unsubscribed. Some topics support to divisional unsubscribe the informations of multiple trading pairs through ",".
  "privateChannel": false,
  "response": true //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
}

//Futures Unsubscribe Topic
{
  "id": "1545910840805", //The id should be an unique value
  "type": "unsubscribe",
  "topic": "/market/ticker:XBTUSDM", //Topic needs to be unsubscribed. Some topics support to divisional unsubscribe the informations of multiple trading pairs through ",".
  "privateChannel": false,
  "response": true //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
}

If the unsubscription succeeds, the system will send ack messages to you, when the response is set as true.

{
  "id": "1545910840805",
  "type": "ack"
}