@iofate/kucoin-ws

KuCoin WS

Node.js websocket client for KuCoin. Websocket API documentation: https://docs.kucoin.com/#websocket-feed

IOfate

This package is made by the IOfate company and is open source, feel free to use it, share it and contribute!

Table of contents

• Features
• Install
• How to use it
• API
• Contributing

Features

• [x] Price ticks
  • [x] Subscription
  • [x] Unsubscribe
• [x] Candlesticks
  • [x] Subscription
  • [x] Unsubscribe
• [x] Send ping
• [x] Emit errors by sockets
• [x] Auto-reconnect

Install

$ npm install @iofate/kucoin-ws

How to use it

import { KuCoinWs } from '@iofate/kucoin-ws';

const main = async () => {
  const client = new KuCoinWs();
  const symbol = 'BTC/USDT';

  await client.connect();

  client.on(`ticker-${symbol}`, ticker => console.log(ticker));
  client.on('error', error => console.error(error));

  client.subscribeTicker(symbol);
};

main();

API

This package export one class KuCoinWs and extend from Emittery, which allow us to dispatch and listen events. More information about Emittery API here: https://github.com/sindresorhus/emittery#api

General events

There are several events which are emitted in different contexts.

• subscriptions: emitted when a new subscription is made or closed
• socket-not-ready: emitted when the socket is not ready to subscribe (will try to subscribe later)
• reconnect: emitted when a reconnection occurred
• retry-subscription: emitted event when we retry to subscribe
• error: emitted when an error occurred
• reconnect-candle: emitted when a candle socket reconnect. Value emitted: { symbol: string; interval: string; }

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

client.on('subscriptions', subscriptions => console.log('update on subscriptions', subscriptions));
client.on('reconnect', () => console.log('a reconnection occurred'));
client.on('socket-not-ready', msg => console.warn('socket not ready', msg));
client.on('error', error => console.error(error));

kuCoinWs = new KuCoinWs()

Create a new instance of KuCoinWs.

kuCoinWs.connect()

Open KuCoin websockets. Must be called before any subscription!

Returns a promise. Can throw errors

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();

kuCoinWs.subscribeTicker(symbol)

Subscribe to the websocket ticker of the chosen symbol. Once called you'll be able to listen to ticker events for this symbol. connect method must be called before calling this one.

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();
kuCoinWs.subscribeTicker('BTC/USDT');
kuCoinWs.on('ticker-BTC/USDT', ticker => console.log(ticker));

kuCoinWs.subscribeTickers(symbols)

Subscribe to the websocket ticker of a symbol list. Once called you'll be able to listen to ticker events for all of those symbols. connect method must be called before calling this one.

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();
kuCoinWs.subscribeTickers(['BTC/USDT', 'ETH/USDT']);
kuCoinWs.on('ticker-BTC/USDT', ticker => console.log(ticker));
kuCoinWs.on('ticker-ETH/USDT', ticker => console.log(ticker));

kuCoinWs.unsubscribeTicker(symbol)

Unsubscribe from the ticker websocket of the associated symbol. Once called no more events will be dispatched.

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();
kuCoinWs.subscribeTicker('BTC/USDT');
const stopListenFn = kuCoinWs.on('ticker-BTC/USDT', ticker => console.log(ticker));
kuCoinWs.unsubscribeTicker('BTC/USDT');
stopListenFn();

kuCoinWs.unsubscribeTickers(symbols)

Unsubscribe from the ticker websocket for the list of symbols. Once called no more events will be dispatched.

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();
kuCoinWs.subscribeTickers(['BTC/USDT', 'ETH/USDT']);
kuCoinWs.unsubscribeTickers(['BTC/USDT', 'ETH/USDT']);

kuCoinWs.subscribeCandles(symbol, timeFrame)

Subscribe to the websocket candle of the chosen symbol and time frame. Once called you'll be able to listen to candle events for this symbol. connect method must be called before calling this one.

Valid time frame: '1m', '3m', '15m', '30m', '1h', '2h', '4h', '6h', '8h', '12h', '1d', '1w', '1M'

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();
kuCoinWs.subscribeCandles('BTC/USDT', '1d');
kuCoinWs.on('candle-BTC/USDT-1d', candle => console.log(candle));

kuCoinWs.unsubscribeCandles(symbol, timeFrame)

Unsubscribe from the candle websocket of the associated symbol. Once called no more events will be dispatched.

import { KuCoinWs } from '@iofate/kucoin-ws';

const kuCoinWs = new KuCoinWs();

await kuCoinWs.connect();
kuCoinWs.subscribeCandles('BTC/USDT', '1d');
const stopListenFn = kuCoinWs.on('candle-BTC/USDT-1d', candle => console.log(candle));
kuCoinWs.unsubscribeCandles('BTC/USDT', '1d');
stopListenFn();

kuCoinWs.closeConnection()

Close the connection between you and KuCoin. You must unsubscribe from everything before calling this method!

kuCoinWs.isSocketOpen()

Return a boolean which indicate if the socket is open or not.

kuCoinWs.isSocketConnecting()

Return a boolean which indicate if the socket is connecting or not.

kuCoinWs.getSubscriptionNumber()

Return the number of subscriptions.

kuCoinWs.getMapClientSubscriptionNumber()

Return a map which shows how many subscriptions we have for each sockets.

Contributing

Any merge request must follow conventional commits format.