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, which will expire in 24 hours but 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',
);

Once the connection has been successfully established, the system will send a welcome message.

::: tip
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"
}

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.

//Spot Demo
{
  "id": 1545910660739, //The ID should be a unique value
  "type": "subscribe",
  "topic": "/market/ticker:BTC-USDT,ETH-USDT", //Topic needs to be subscribed. Some topics support subscribing to information on multiple trading pairs by separating them with a comma (“,”).
  "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 a unique value
  "type": "subscribe",
  "topic": "/market/ticker:XBTUSDM", //Subscribed topic. Some topics support subscribing to information on multiple trading pairs by separating them with a comma (“,”).
  "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"
}

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.

//Spot Unsubscribe Topic
{
  "id": "1545910840805", //The ID should be a unique value
  "type": "unsubscribe",
  "topic": "/market/ticker:BTC-USDT,ETH-USDT", //Topic needs to be unsubscribed. Some topics support unsubscribing from information on multiple trading pairs by separating them with a comma (“,”).
  "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 unsubscribing from information on multiple trading pairs by separating them with a comma (“,”).
  "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"
}