Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/IOfate/kucoin-ws

Node.js websocket client for KuCoin
https://github.com/IOfate/kucoin-ws

Last synced: 26 days ago
JSON representation

Node.js websocket client for KuCoin

Host: GitHub
URL: https://github.com/IOfate/kucoin-ws
Owner: IOfate
License: mit
Created: 2021-09-05T06:14:20.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2024-05-02T10:31:35.000Z (about 1 month ago)
Last Synced: 2024-05-02T22:16:24.625Z (about 1 month ago)
Language: TypeScript
Size: 317 KB
Stars: 7
Watchers: 2
Forks: 5
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Lists

awesome-crypto-trading-bots - kucoin-ws - Node.js websocket client for KuCoin. (Market data libraries)
awesome-crypto-trading-bots - kucoin-ws - Node.js websocket client for KuCoin. (Market data libraries)

README

        # KuCoin WS

[![Node.js CI](https://github.com/IOfate/kucoin-ws/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/IOfate/kucoin-ws/actions/workflows/node.js.yml)

[![npm version](https://img.shields.io/npm/v/@iofate/kucoin-ws)](https://www.npmjs.com/package/@iofate/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](#features)

- [Install](#install)

- [How to use it](#how-to-use-it)

- [API](#api)

- [Contributing](#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

```js

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](https://www.npmjs.com/package/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; }`

```js

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**

```js

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.**

```js

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.**

```js

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.

```js

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.

```js

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'`

```js

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.

```js

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](https://conventionalcommits.org/) format.