Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/kucoin-api/llms.txt

Use this file to discover all available pages before exploring further.

The WebsocketClient is the primary interface for receiving real-time data from KuCoin over WebSocket. It manages connections, authentication, heartbeats, and resubscription automatically — so your application only needs to subscribe to topics and handle incoming events. Two generations of KuCoin WebSocket endpoints are supported: the original V1 APIs and the newer V2 / Pro endpoints, each with distinct WS keys that route connections to the correct server.

​
WebSocket Key Map

Every subscription call requires a wsKey that identifies which connection to use. The full key map is defined in WS_KEY_MAP:
WsKeyDescription
spotPublicV1Public spot market data (V1)
spotPrivateV1Private spot & margin account events (V1)
futuresPublicV1Public futures market data (V1)
futuresPrivateV1Private futures account & position events (V1)
spotPublicProV2Public spot market data — KuCoin Pro (V2)
futuresPublicProV2Public futures market data — KuCoin Pro (V2)
privateProV2Unified private channel for spot + futures (V2)
wsApiSpotV1WebSocket API connection for spot & margin order operations
wsApiFuturesV1WebSocket API connection for futures order operations
The WS_KEY_MAP object is exported from kucoin-api and can be used directly in your code instead of hardcoding strings: import { WS_KEY_MAP } from 'kucoin-api'.

​
V1 vs V2 (Pro) Endpoints

KuCoin maintains two generations of WebSocket APIs. Both are fully supported by this SDK.
The V1 endpoints use dynamic connection URLs fetched via a REST API call before connecting. They are the current stable generation and cover all spot, margin, and futures topics. Each market (spot vs futures) and visibility (public vs private) has its own dedicated connection, identified by one of the four V1 WsKey values.
  • Public spot: spotPublicV1
  • Private spot: spotPrivateV1
  • Public futures: futuresPublicV1
  • Private futures: futuresPrivateV1

​
Events Emitted

The WebsocketClient is an EventEmitter. Register handlers with .on(event, handler) before subscribing to topics.
EventWhen it fires
openA WebSocket connection is established
updateA data message arrives (market data or account event)
reconnectAn unexpected disconnection was detected; reconnect starting
reconnectedConnection has been successfully re-established
closeConnection was closed
responseA reply to a subscribe/unsubscribe/authenticate request
authenticatedA private connection has successfully authenticated
exceptionAn error was received or message parsing failed
import { WebsocketClient } from 'kucoin-api';

const client = new WebsocketClient();

client.on('open', (data) => {
  console.log('open: ', data?.wsKey);
});

client.on('update', (data) => {
  console.info('data received: ', JSON.stringify(data));
});

client.on('reconnect', (data) => {
  console.log('reconnect: ', data);
});

client.on('reconnected', (data) => {
  console.log('reconnected: ', data);
});

client.on('close', (data) => {
  console.error('close: ', data);
});

client.on('response', (data) => {
  console.info('response: ', data);
});

client.on('exception', (data) => {
  console.error('exception: ', {
    msg: data.msg,
    errno: data.errno,
    code: data.code,
    syscall: data.syscall,
    hostname: data.hostname,
  });
});

​
Configuration Options

Pass a WSClientConfigurableOptions object as the first argument to new WebsocketClient(options).
OptionTypeDescription
apiKeystringYour KuCoin API key (required for private streams)
apiSecretstringYour KuCoin API secret (required for private streams)
apiPassphrasestringThe passphrase you set when creating the API key
apiRegion'global' | 'EU' | 'AU'Target API region (default: global)
recvWindownumberRecv window in milliseconds used when signing private WebSocket connections (e.g. 5000 = 5 seconds)
pingIntervalnumberMilliseconds between heartbeat pings
pongTimeoutnumberMilliseconds to wait for a pong before declaring the connection dead
reconnectTimeoutnumberMilliseconds to wait before attempting reconnection
reauthWSAPIOnReconnectbooleanRe-authenticate the WS API connection after reconnect
wsUrlstringOverride the connection URL (advanced use)
customSignMessageFnfunctionCustom HMAC signing function, e.g. using Node’s crypto.createHmac
import { WebsocketClient } from 'kucoin-api';

const client = new WebsocketClient({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  apiPassphrase: 'your_passphrase',
  pingInterval: 20000,
  pongTimeout: 10000,
  reconnectTimeout: 5000,
});

​
Auto-Reconnect and Resubscribe

The WebsocketClient handles network interruptions transparently:
1

Disconnection detected

When a connection drops unexpectedly, the client emits a reconnect event with the affected wsKey.
2

Automatic reconnection

After reconnectTimeout milliseconds the client re-establishes the WebSocket connection, fetching a fresh connection token from the REST API if required (V1).
3

Re-authentication

For private connections, authentication is automatically repeated as part of the connection handshake.
4

Topic resubscription

All previously subscribed topics are re-sent automatically. Your application does not need to re-register subscriptions after a reconnect.
5

Reconnected event

Once all topics are active again, the client emits reconnected. Your update handler will resume receiving events.
You never need to manually resubscribe after a reconnect. The SDK maintains an internal topic cache and replays all subscriptions on every reconnect.

​
Explore Specific Topics

Public Streams

Subscribe to live ticker, order book, trade, kline, and snapshot data without credentials.

Private Streams

Receive real-time order updates, balance changes, and position events for your account.

WebSocket API

Submit and cancel orders over WebSocket for the lowest possible round-trip latency.

Build docs developers (and LLMs) love

Get started for freeTalk to us