Most methods accept JS objects. These can be populated using parameters specified by Kucoin's API documentation, or check the type definition in each class within this repository.
See SpotClient for further information, or the examples for lots of usage examples.
Futures Trading
Use the FuturesClient for futures trading operations. See FuturesClient for complete API coverage.
Broker Operations
Use the BrokerClient for broker and sub-account management operations. See BrokerClient for complete API coverage.
WebSockets
All WebSocket functionality is supported via the unified WebsocketClient. This client handles both spot and futures WebSocket streams with automatic connection management and reconnection.
Key WebSocket features:
Event driven messaging
Smart WebSocket persistence with automatic reconnection
Heartbeat mechanisms to detect disconnections
Automatic resubscription after reconnection
Support for both public and private WebSocket streams
Unified client for spot and futures markets
Public WebSocket Streams
For public market data, API credentials are not required:
All available WebSockets can be used via a shared WebsocketClient. The WebSocket client will automatically open/track/manage connections as needed. Each unique connection (one per server URL) is tracked using a WsKey (each WsKey is a string - see WS_KEY_MAP for a list of supported values).
Any subscribe/unsubscribe events will need to include a WsKey, so the WebSocket client understands which connection the event should be routed to. See examples below or in the examples folder on GitHub.
Data events are emitted from the WebsocketClient via the update event, see example below:
const { WebsocketClient } = require('kucoin-api');
const client = newWebsocketClient();
client.on('open', (data) => {
console.log('open: ', data?.wsKey);
});
// Data received
client.on('update', (data) => {
console.info('data received: ', JSON.stringify(data));
});
// Something happened, attempting to reconenct
client.on('reconnect', (data) => {
console.log('reconnect: ', data);
});
// Reconnect successful
client.on('reconnected', (data) => {
console.log('reconnected: ', data);
});
// Connection closed. If unexpected, expect reconnect -> reconnected.
client.on('close', (data) => {
console.error('close: ', data);
});
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
client.on('response', (data) => {
console.info('response: ', data);
// throw new Error('res?');
});
client.on('exception', (data) => {
console.error('exception: ', {
msg: data.msg,
errno: data.errno,
code: data.code,
syscall: data.syscall,
hostname: data.hostname,
});
});
try {
// Optional: await a connection to be ready before subscribing (this is not necessary)// await client.connect('futuresPublicV1');/**
* Examples for public futures websocket topics (that don't require authentication).
*
* These should all subscribe via the "futuresPublicV1" wsKey. For detailed usage, refer to the ws-spot-public.ts example.
*/
client.subscribe(
[
'/contractMarket/tickerV2:XBTUSDM',
'/contractMarket/ticker:XBTUSDM',
'/contractMarket/level2:XBTUSDM',
'/contractMarket/execution:XBTUSDM',
'/contractMarket/level2Depth5:XBTUSDM',
'/contractMarket/level2Depth50:XBTUSDM',
'/contractMarket/limitCandle:XBTUSDTM_1hour',
'/contract/instrument:XBTUSDM',
'/contract/announcement',
'/contractMarket/snapshot:XBTUSDM',
],
'futuresPublicV1',
);
} catch (e) {
console.error(`Subscribe exception: `, e);
}
Private WebSocket Streams
For private account data streams, API credentials are required. The WebsocketClient will automatically handle authentication when you provide API credentials.
See WebsocketClient for further information and make sure to check the examples folder for much more detail, especially ws-spot-public.ts, which explains a lot of detail.
Customise Logging
Pass a custom logger which supports the log methods trace, info and error, or override methods from the default logger as desired.
const { WebsocketClient, DefaultLogger } = require('kucoin-api');
// E.g. customise logging for only the trace level:const logger = {
// Inherit existing logger methods, using an object spread
...DefaultLogger,
// Define a custom trace function to override only that functiontrace: (...params) => {
if (
[
'Sending ping',
// 'Sending upstream ws message: ','Received pong',
].includes(params[0])
) {
return;
}
console.log('trace', JSON.stringify(params, null, 2));
},
};
const ws = newWebsocketClient(
{
apiKey: 'apiKeyHere',
apiSecret: 'apiSecretHere',
apiPassphrase: 'apiPassPhraseHere',
},
logger,
);
Use with LLMs & AI
This SDK includes a bundled llms.txt file in the root of the repository. If you're developing with LLMs, use the included llms.txt with your LLM - it will significantly improve the LLMs understanding of how to correctly use this SDK.
This file contains AI optimised structure of all the functions in this package, and their parameters for easier use with any learning models or artificial intelligence.
Contributions & Thanks
Have my projects helped you? Share the love, there are many ways you can show your thanks:
Complete & robust Node.js SDK for Kucoin's REST APIs and WebSockets, with TypeScript & strong end to end tests.
The npm package kucoin-api receives a total of 286 weekly downloads. As such, kucoin-api popularity was classified as not popular.
We found that kucoin-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.It has 0 open source maintainers collaborating on the project.
Package last updated on 25 Jul 2025
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Socket CEO Feross Aboukhadijeh and a16z partner Joel de la Garza discuss vibe coding, AI-driven software development, and how the rise of LLMs, despite their risks, still points toward a more secure and innovative future.