Introduction

Important Notice:

The Automatic Load Balancing has been launched to further enhance the stability and latency performance of API services. The system dynamically balances traffic and allocates resources based on the real‑time load of each instance, enabling customers to enjoy more stable connection quality and improved latency experience.

During subsequent load switching, some WebSocket connections may be actively disconnected by the server. Such load switching is expected to occur a maximum of one to two times per week, and normal service can be restored by re‑establishing the connection.

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. Create connection

For push of public data

For push of private data

For websocket trade

TIP

The connection will only be available once the welcome message has been received. There's a recommanded interval in ms for ping message that should be send to server for keepalive.

// Websocket Public Channel
{"sessionId":"81f56400-e7e3-4f2b-b0f6-5e649f48c302","message":"welcome","pingInterval":18000}
// Websocket Private Channel
{"sessionId":"f39d99cb-8aef-41c0-b859-97753b9101e2","message":"welcome","pingInterval":18000,"pingTimeout":10000}
// Websocket Trade
{"pingTimeout":10000,"sessionId":"cbb32567-489d-4102-a35e-9dcd61dc0919","pingInterval":18000,"data":"welcome"}

sessionId: The sessionId is a unique ID that is to identify a connection, which is useful for troubleshooting for kucoin developing team.
pingInterval: The recommended interval in ms for the client to send ping message to server to keep alive the connection.
pingTimeout: The estimated interval in ms for the client to receive pong messgae from server.

3. Generate signature

TIP

For push of public market data, skip step 3 and step 4.

Use API-Secret to encrypt the prehash string {timestamp+POST/api/websocket/users/verify} with sha256 HMAC to get kc-api-sign

4. Send authentication message

Header	Required	Description
op	Yes	Set 'auth'
kc-api-key	Yes	Your API key, provided as a string.
kc-api-sign	Yes	The Base64-encoded signature generated for the request.
kc-api-timestamp	Yes	The timestamp of the request in milliseconds.
kc-api-passphrase	Yes	The passphrase specified when the API key was created.
kc-api-partner	No	Only applicable in websocket trade connections and only for broker users.
kc-api-partner-sign	No	Only applicable in websocket trade connections and only for broker users.
enable_ns	No	Only applicable in websocket trade connections. Default (not set): inTime/outTime are in milliseconds; set enable_ns=true to return nanoseconds (Colo UTA users: default nanoseconds, no enable_ns=true required).

Code Examples

Python

PHP

5. Ping

{
  "id": "1545910590801",    // No special restriction
  "op": "ping",
  "timestamp": your_timestamp // optional
}

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 by the server. Also if client cannot receive pong message from server for a while (such as 3 second) the connection should be cansidered as broken and a new connection is recommended to be initialized.

The connection will be dropped if the ping frequency is exceeded once per second.

{
  "id": "1545910590801",    // No special restriction
  "op": "pong",
  "timestamp": server_timestamp
}

To receive market push or private push from server, the client side should send a subscription message to the server.

Parameters

id: An optional unique string used to identify the request. If id is provided in the subscription request, the server will return the same id in the acknowledgment message. If id is not provided, the acknowledgment message will not include id. The id constraints are as follows:

Channel Type	Allowed Characters	Length Limit
Pro WS Public Channel	Only `A-Z`, `a-z`, `0-9`, `_`, `.`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `-` are supported	Maximum 40 characters
Pro WS Private Channel	No special restriction	No special restriction

action: subscribe

channel: The channel to subscribe to.

symbol: The symbol for this channel.

tradeType: SPOT or FUTURES

//Spot Demo
{
  "id": "1545910660739",
  "action": "subscribe",
  "channel": "ticker",
  "symbol": "BTC-USDT",
  "tradeType": "SPOT"
}

//Future Demo
{
  "id": "1545910660739",
  "action": "subscribe",
  "channel": "trade",
  "symbol": "ETHUSDTM",
  "tradeType": "FUTURES"
}

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

{
  "id": "1545910660739",
  "result": "true"
}

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.

7. UnSubscribe (Public/Private channels)

Unsubscribe from channels you have subscribed to.

Parameters

Channel Type	Allowed Characters	Length Limit
WS Public Channel	Only `A-Z`, `a-z`, `0-9`, `_`, `.`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `-` are supported	Maximum 40 characters
WS Private Channel	No special restriction	No special restriction

action: Fixed as unsubscribe.

channel: The channel to unsubscribe from.

symbol: The symbol for this channel.

tradeType: SPOT or FUTURES.

//Spot Unsubscribe Topic
{
  "id": "1545910840805",
  "action": "unsubscribe",
  "channel": "ticker",
  "symbol": "BTC-USDT",
  "tradeType": "SPOT"
}

//Futures Unsubscribe Topic
{
  "id": "1545910840805",
  "action": "unsubscribe",
  "channel": "trade",
  "symbol": "ETHUSDTM",
  "tradeType": "FUTURES"

}

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

{
  "id": "1545910840805",
  "result": "true"
}

1. Introduction#

2. Create connection#

3. Generate signature#

4. Send authentication message#

Code Examples#

5. Ping#

6. Subscribe (Public/Private channels)#

Parameters#

7. UnSubscribe (Public/Private channels)#

Parameters#

1. Introduction

2. Create connection

3. Generate signature

4. Send authentication message

Code Examples

5. Ping

6. Subscribe (Public/Private channels)

Parameters

7. UnSubscribe (Public/Private channels)

Parameters