# Node.js & JavaScript SDK for Kucoin REST APIs & Websockets

SDK Logo

[![npm version](https://img.shields.io/npm/v/kucoin-api)][1] [![npm size](https://img.shields.io/bundlephobia/min/kucoin-api/latest)][1] [![npm downloads](https://img.shields.io/npm/dt/kucoin-api)][1] [![Build & Test](https://github.com/tiagosiebler/kucoin-api/actions/workflows/e2etest.yml/badge.svg?branch=master)](https://github.com/tiagosiebler/kucoin-api/actions/workflows/e2etest.yml) [![last commit](https://img.shields.io/github/last-commit/tiagosiebler/kucoin-api)][1] [![Telegram](https://img.shields.io/badge/chat-on%20telegram-blue.svg)](https://t.me/nodetraders) [1]: https://www.npmjs.com/package/kucoin-api Updated & performant JavaScript & Node.js SDK for the Kucoin REST APIs and WebSockets: - Complete integration with all Kucoin REST APIs and WebSockets. - TypeScript support (with type declarations for most API requests & responses) - Robust WebSocket integration with configurable connection heartbeats & automatic reconnect then resubscribe workflows. - Browser-friendly HMAC signature mechanism. - Automatically supports both ESM and CJS projects. - Proxy support via axios integration. - Active community support & collaboration in telegram: [Node.js Algo Traders](https://t.me/nodetraders). ## Installation `npm install --save kucoin-api` ## Issues & Discussion - Issues? Check the [issues tab](https://github.com/tiagosiebler/kucoin-api/issues). - Discuss & collaborate with other node devs? Join our [Node.js Algo Traders](https://t.me/nodetraders) engineering community on telegram. - Follow our announcement channel for real-time updates on [X/Twitter](https://x.com/QuantSDKs) ## Related projects Check out my related JavaScript/TypeScript/Node.js projects: - Try my REST API & WebSocket SDKs: - [Bybit-api Node.js SDK](https://www.npmjs.com/package/bybit-api) - [Okx-api Node.js SDK](https://www.npmjs.com/package/okx-api) - [Binance Node.js SDK](https://www.npmjs.com/package/binance) - [Gateio-api Node.js SDK](https://www.npmjs.com/package/gateio-api) - [Bitget-api Node.js SDK](https://www.npmjs.com/package/bitget-api) - [Kucoin-api Node.js SDK](https://www.npmjs.com/package/kucoin-api) - [Coinbase-api Node.js SDK](https://www.npmjs.com/package/coinbase-api) - [Bitmart-api Node.js SDK](https://www.npmjs.com/package/bitmart-api) - Try my misc utilities: - [OrderBooks Node.js](https://www.npmjs.com/package/orderbooks) - [Crypto Exchange Account State Cache](https://www.npmjs.com/package/accountstate) - Check out my examples: - [awesome-crypto-examples Node.js](https://github.com/tiagosiebler/awesome-crypto-examples) ## Documentation Most methods accept JS objects. These can be populated using parameters specified by Kucoin's API documentation. - [Kucoin API Documentation](https://www.kucoin.com/docs-new/introduction) - Node.js Quick Start Guides - [Spot Node.js Kucoin Quick Start Guide](./examples/kucoin-SPOT-examples-nodejs.md) - [Futures Node.js Kucoin Quick Start Guide](./examples/kucoin-FUTURES-examples-nodejs.md) - [Futures Node.js Kucoin Order Placement Guide](./examples/rest-futures-orders-guide.ts) - [REST Endpoint Function List](./docs/endpointFunctionList.md) ## Structure This project uses typescript. Resources are stored in 2 key structures: - [src](./src) - the whole connector written in typescript - [examples](./examples) - some implementation examples & demonstrations. Contributions are welcome! --- # Usage Create API credentials - [Kucoin API Key Management](https://www.kucoin.com/account/api) ### REST API To use any of Kucoin's REST APIs in JavaScript/TypeScript/Node.js, import (or require) the `SpotClient` (for spot and margin APIs) or `FuturesClient` (for futures APIs): ```javascript const { SpotClient, FuturesClient } = require('kucoin-api'); const client = new SpotClient({ apiKey: 'apiKeyHere', apiSecret: 'apiSecretHere', apiPassphrase: 'apiPassPhraseHere', }); try { const spotBuyResult = await client.submitHFOrder({ clientOid: client.generateNewOrderID(), side: 'buy', type: 'market', symbol: 'BTC-USDT', size: '0.00001', }); console.log('spotBuy ', JSON.stringify(spotBuyResult, null, 2)); const spotSellResult = await client.submitHFOrder({ clientOid: client.generateNewOrderID(), side: 'sell', type: 'market', symbol: 'BTC-USDT', size: '0.00001', }); console.log('spotSellResult ', JSON.stringify(spotSellResult, null, 2)); } catch (e) { console.error(`Req error: `, e); } ``` See [SpotClient](./src/SpotClient.ts) and [FuturesClient](./src/FuturesClient.ts) for further information, or the [examples](./examples/) for lots of usage examples. ## WebSockets 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](src/lib/websocket/websocket-util.ts) 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](./examples/) folder on GitHub. Data events are emitted from the WebsocketClient via the `update` event, see example below: ```javascript const { WebsocketClient } = require('kucoin-api'); const client = new WebsocketClient(); 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); } ``` See [WebsocketClient](./src/WebsocketClient.ts) for further information and make sure to check the [examples](./examples/) folder for much more detail, especially [ws-spot-public.ts](./examples/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. ```javascript 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 function trace: (...params) => { if ( [ 'Sending ping', // 'Sending upstream ws message: ', 'Received pong', ].includes(params[0]) ) { return; } console.log('trace', JSON.stringify(params, null, 2)); }, }; const ws = new WebsocketClient( { apiKey: 'apiKeyHere', apiSecret: 'apiSecretHere', apiPassphrase: 'apiPassPhraseHere', }, logger, ); ``` --- ### Contributions & Thanks Have my projects helped you? Share the love, there are many ways you can show your thanks: - Star & share my projects. - Are my projects useful? Sponsor me on Github and support my effort to maintain & improve them: https://github.com/sponsors/tiagosiebler - Have an interesting project? Get in touch & invite me to it. - Or buy me all the coffee: - ETH(ERC20): `0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C` ### Contributions & Pull Requests Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items. ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=tiagosiebler/bybit-api,tiagosiebler/okx-api,tiagosiebler/binance,tiagosiebler/bitget-api,tiagosiebler/bitmart-api,tiagosiebler/gateio-api,tiagosiebler/kucoin-api,tiagosiebler/coinbase-api,tiagosiebler/orderbooks,tiagosiebler/accountstate,tiagosiebler/awesome-crypto-examples&type=Date)](https://star-history.com/#tiagosiebler/bybit-api&tiagosiebler/okx-api&tiagosiebler/binance&tiagosiebler/bitget-api&tiagosiebler/bitmart-api&tiagosiebler/gateio-api&tiagosiebler/kucoin-api&tiagosiebler/coinbase-api&tiagosiebler/orderbooks&tiagosiebler/accountstate&tiagosiebler/awesome-crypto-examples&Date)