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.
Public WebSocket streams deliver real-time market data without requiring any API credentials. Instantiate WebsocketClient with no arguments (or without apiKey/apiSecret) and the SDK will automatically open the appropriate public connection the first time you call subscribe(). All incoming market data events are emitted on the update event.
Installing and Importing
import { WebsocketClient, WS_KEY_MAP, WsTopicRequest } from 'kucoin-api';
The WsTopicRequest Type
Topics can be passed to subscribe() as plain strings or as structured WsTopicRequest objects when you need to include extra parameters.
// Plain string — simplest form
client.subscribe('/market/ticker:BTC-USDT', 'spotPublicV1');
// Structured object — merge extra parameters into the subscribe request
const subRequest: WsTopicRequest = {
topic: '/market/ticker:BTC-USDT',
payload: {
response: false,
},
};
client.subscribe(subRequest, 'spotPublicV1');
Every field inside payload is merged directly into the raw subscribe message sent to KuCoin. Refer to the KuCoin WebSocket documentation for which parameters each topic accepts.
Spot Public V1 Streams
Use the spotPublicV1 WsKey for all public spot and margin market data topics.
Create the client
Instantiate WebsocketClient with no credentials for public data.import { WebsocketClient, WsTopicRequest } from 'kucoin-api';
const client = new WebsocketClient();
Register event handlers
Attach your handlers before calling subscribe().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,
});
});
Subscribe to topics
Pass one topic, an array of topics, or an array of WsTopicRequest objects.// Single topic as a string
client.subscribe('/market/ticker:BTC-USDT,ETH-USDT', 'spotPublicV1');
// Array of string topics
client.subscribe(
['/market/ticker:BTC-USDT,ETH-USDT', '/market/snapshot:KCS-BTC'],
'spotPublicV1',
);
// Structured object with payload
const subRequest: WsTopicRequest = {
topic: '/market/ticker:BTC-USDT',
payload: {
id: 123456,
response: false,
},
};
client.subscribe(subRequest, 'spotPublicV1');
All Spot V1 Topics
The following topics are all valid for the spotPublicV1 WsKey:
client.subscribe(
[
'/market/ticker:BTC-USDT,ETH-USDT', // Real-time best bid/ask & last price
'/market/ticker:all', // All symbols ticker
'/market/snapshot:KCS-BTC', // Market snapshot for a symbol
'/market/snapshot:BTC', // Snapshot for all pairs in a market
'/spotMarket/level1:BTC-USDT,ETH-USDT', // Level-1 best bid/ask
'/market/level2:BTC-USDT,ETH-USDT', // Full order book updates (level 2)
'/spotMarket/level2Depth5:BTC-USDT,ETH-USDT', // Top 5 levels order book
'/spotMarket/level2Depth50:BTC-USDT,ETH-USDT', // Top 50 levels order book
'/market/candles:BTC-USDT_1hour', // Kline/candlestick data
'/market/match:BTC-USDT,ETH-USDT', // Real-time trade executions
],
'spotPublicV1',
);
Futures Public V1 Streams
Use the futuresPublicV1 WsKey for public futures contract market data.
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,
});
});
client.subscribe(
[
'/contractMarket/tickerV2:XBTUSDM', // Ticker V2
'/contractMarket/ticker:XBTUSDM', // Ticker V1
'/contractMarket/level2:XBTUSDM', // Full order book updates
'/contractMarket/execution:XBTUSDM', // Real-time trade executions
'/contractMarket/level2Depth5:XBTUSDM', // Top 5 levels
'/contractMarket/level2Depth50:XBTUSDM', // Top 50 levels
'/contractMarket/limitCandle:XBTUSDTM_1hour', // Kline data
'/contract/instrument:XBTUSDM', // Funding rate & mark price
'/contract/announcement', // Contract announcements
'/contractMarket/snapshot:XBTUSDM', // Contract snapshot
],
'futuresPublicV1',
);
Pro V2 Public Streams
The V2 (Pro) endpoints use a different message format. Topics are identified by a short channel name and additional parameters (such as tradeType, symbol, interval) are passed inside payload.
Spot Pro V2
Futures Pro V2
Use the spotPublicProV2 WsKey. Set tradeType: 'SPOT' in all payloads.import { WebsocketClient, WS_KEY_MAP, WsTopicRequest } from 'kucoin-api';
const client = new WebsocketClient();
// Register handlers (same as V1 examples above)
client.on('open', (data) => console.log('open: ', data?.wsKey));
client.on('update', (data) => console.info('data received: ', JSON.stringify(data)));
client.on('exception', (data) => {
console.error('exception: ', {
msg: data.msg,
errno: data.errno,
code: data.code,
syscall: data.syscall,
hostname: data.hostname,
});
});
// Structured kline subscription
const klineRequest: WsTopicRequest = {
topic: 'kline',
payload: {
tradeType: 'SPOT',
symbol: 'BTC-USDT',
interval: '1min',
},
};
client.subscribe(klineRequest, WS_KEY_MAP.spotPublicProV2);
// Multiple topics in one call
client.subscribe(
[
{
topic: 'ticker',
payload: { tradeType: 'SPOT', symbol: 'BTC-USDT' },
},
{
topic: 'ticker',
payload: { tradeType: 'SPOT', symbols: ['ETH-USDT', 'XRP-USDT'] },
},
{
topic: 'obu',
payload: {
tradeType: 'SPOT',
symbol: 'BTC-USDT',
depth: '5', // '1' / '5' / '50' / 'increment'
rpiFilter: 0, // 0: NoneRPI orders only (default)
},
},
{
topic: 'trade',
payload: { tradeType: 'SPOT', symbol: 'BTC-USDT' },
},
],
WS_KEY_MAP.spotPublicProV2,
);
Use the futuresPublicProV2 WsKey. Set tradeType: 'FUTURES' in all payloads.import { WebsocketClient, WS_KEY_MAP, WsTopicRequest } 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('exception', (data) => {
console.error('exception: ', {
msg: data.msg,
errno: data.errno,
code: data.code,
syscall: data.syscall,
hostname: data.hostname,
});
});
const klineRequest: WsTopicRequest = {
topic: 'kline',
payload: {
tradeType: 'FUTURES',
symbol: 'XBTUSDTM',
interval: '1min',
},
};
client.subscribe(klineRequest, WS_KEY_MAP.futuresPublicProV2);
client.subscribe(
[
{
topic: 'ticker',
payload: { tradeType: 'FUTURES', symbol: 'XBTUSDTM' },
},
{
topic: 'ticker',
payload: { tradeType: 'FUTURES', symbols: ['ETHUSDTM', 'XRPUSDTM'] },
},
{
topic: 'obu',
payload: {
tradeType: 'FUTURES',
symbol: 'XBTUSDTM',
depth: '5',
rpiFilter: 0,
},
},
{
topic: 'trade',
payload: { tradeType: 'FUTURES', symbol: 'XBTUSDTM' },
},
],
WS_KEY_MAP.futuresPublicProV2,
);
With the V2 Pro endpoints, the tradeType in your payload must match the WsKey you pass to subscribe(). Use tradeType: 'SPOT' with spotPublicProV2 and tradeType: 'FUTURES' with futuresPublicProV2.
Unsubscribing from Topics
Call unsubscribe() with the same topic string (or WsTopicRequest) and WsKey you used to subscribe. The SDK sends an unsubscribe request and removes the topic from its internal cache, so it won’t be resubscribed after a reconnect.
// Unsubscribe from a single topic
client.unsubscribe('/market/ticker:BTC-USDT,ETH-USDT', 'spotPublicV1');
// Unsubscribe from multiple topics at once
client.unsubscribe(
['/market/level2:BTC-USDT,ETH-USDT', '/market/candles:BTC-USDT_1hour'],
'spotPublicV1',
);
