kucoin-api 0.0.2 → 1.0.0

package/README.md

@@ -1,61 +1,277 @@
+# Node.js & JavaScript SDK for Kucoin REST APIs, WebSockets & WebSocket API
+
 <p align="center">
-  <img
-    src="https://user-images.githubusercontent.com/30309816/31295829-c8d25310-ab2b-11e7-8885-fb335d0c3baf.png"
-    width="125px;">
+  <a href="https://www.npmjs.com/package/kucoin-api">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/tiagosiebler/kucoin-api/blob/master/docs/images/logoDarkMode2.svg?raw=true#gh-dark-mode-only">
+      <img alt="SDK Logo" src="https://github.com/tiagosiebler/kucoin-api/blob/master/docs/images/logoBrightMode2.svg?raw=true#gh-light-mode-only">
+    </picture>
+  </a>
 </p>
 
-<h1 align="center">KuCoin API Client</h1>
+[![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)
 
-<p align="center">
-  A Node.js client for the [KuCoin](https://www.kucoin.com/) API.
-</p>
+[1]: https://www.npmjs.com/package/kucoin-api
 
-## Overview
+Updated & performant JavaScript & Node.js SDK for the Kucoin REST APIs and WebSockets:
 
-### What does it currently do
+- 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).
 
-The [KuCoin API documentation](http://docs.kucoinapidocs.apiary.io/) is not too bad, though some holes and inconsistencies. This Node.js client attempts to make up for some of those. 25 of the 29 endpoints are supported, the missing ones are mainly relating to Kline data.
+## Installation
 
-### Get help or give help
+`npm install --save kucoin-api`
 
-- Open a new [issue](https://github.com/Satoshinaire/kucoin-api/issues/new) if you encounter a problem.
-- Or ping **@satoshinaire** on **Twitter**.
-- Pull requests welcome.
+## Issues & Discussion
 
-## Getting started
+- 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.
 
-### Installation
+<!-- template_related_projects -->
 
+## 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)
+  - [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)
+  <!-- template_related_projects_end -->
+
+## 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/beginners/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)
+<!-- - [TSDoc Documentation (autogenerated using typedoc)](https://tsdocs.dev/docs/kucoin-api) -->
+
+## 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.submitOrder({
+    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.submitOrder({
+    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);
+}
 ```
-npm install --save kucoin-api
-```
 
-### Usage
+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);
+}
 ```
-'use strict'
-
-require('dotenv').config()
-const Kucoin = require('kucoin-api')
-
-let kc = new Kucoin(process.env.KUCOIN_API_KEY, process.env.KUCOIN_API_SECRET)
-
-kc.getBalance({
-    symbol: 'GAS'
-  })
-  .then((result) => {
-    console.log(result)
-  })
-  .catch((err) => {
-    console.log(err)
-  })
+
+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,
+);
 ```
 
-## License
+---
+
+<!-- template_contributions -->
+
+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` <!-- metamask -->
+
+<!---
+old ones:
+  - BTC: `1C6GWZL1XW3jrjpPTS863XtZiXL1aTK7Jk`
+  - BTC(SegWit): `bc1ql64wr9z3khp2gy7dqlmqw7cp6h0lcusz0zjtls`
+  - ETH(ERC20): `0xe0bbbc805e0e83341fadc210d6202f4022e50992`
+  - USDT(TRC20): `TA18VUywcNEM9ahh3TTWF3sFpt9rkLnnQa
+-->
+<!-- template_contributions_end -->
+
+### Contributions & Pull Requests
+
+Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.
+
+<!-- template_star_history -->
 
-- Open-source [MIT](https://github.com/Satoshinaire/kucoin-api/blob/master/LICENSE).
-- Main author is [@satoshinaire](https://github.com/satoshinaire).
+## Star History
 
-## Donations
+[![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/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/orderbooks&tiagosiebler/accountstate&tiagosiebler/awesome-crypto-examples&Date)
 
-NEO / GAS accepted at __AWcAwoXK6gbMUTojHMHEx8FgEfaVK9Hz5s__
+<!-- template_star_history_end -->

package/dist/cjs/FuturesClient.d.ts

@@ -0,0 +1,246 @@
+import { AxiosRequestConfig } from 'axios';
+import { BaseRestClient } from './lib/BaseRestClient.js';
+import { RestClientOptions, RestClientType } from './lib/requestUtils.js';
+import { AccountFillsRequest, CreateSubAPIRequest, DeleteSubAPIRequest, GetFundingHistoryRequest, GetFundingRatesRequest, GetInterestRatesRequest, GetKlinesRequest, GetOrdersRequest, GetStopOrdersRequest, GetSubAPIsRequest, GetTransactionsRequest, GetTransfersRequest, MaxOpenSizeRequest, Order, SubmitTransfer, UpdateSubAPIRequest } from './types/request/futures.types.js';
+import { AccountBalance, AccountSummary, AddMargin, CreateSubAccountAPI, FullOrderBookDetail, FuturesAccountFundingRateHistory, FuturesAccountTransaction, FuturesActiveOrder, FuturesClosedPositions, FuturesCurrentFundingRate, FuturesFill, FuturesFills, FuturesHistoricFundingRate, FuturesKline, FuturesMarkPrice, FuturesOrder, FuturesOrders, FuturesPosition, FuturesRiskLimit, FuturesSymbolInfo, FuturesTransferRecords, IndexListItem, InterestRateItem, MarketTradeDetail, MaxOpenSize, PremiumIndexItem, SubAccountAPI, SubBalance, SubmitMultipleOrdersFuturesResponse, TickerDetail, TransferDetail, UpdateSubAccountAPI } from './types/response/futures.types.js';
+import { APISuccessResponse } from './types/response/shared.types.js';
+import { WsConnectionInfo } from './types/response/ws.js';
+/**
+ *
+ */
+export declare class FuturesClient extends BaseRestClient {
+    constructor(restClientOptions?: RestClientOptions, requestOptions?: AxiosRequestConfig);
+    getClientType(): RestClientType;
+    /**
+     *
+     * Misc Utility Methods
+     *
+     */
+    generateNewOrderID(): string;
+    getServerTime(): Promise<any>;
+    getServiceStatus(): Promise<any>;
+    /**
+     * REST - ACCOUNT  - BASIC INFO
+     * Get Account Ledgers - Futures
+     */
+    getTransactions(params: GetTransactionsRequest): Promise<APISuccessResponse<{
+        hasMore: boolean;
+        dataList: FuturesAccountTransaction[];
+    }>>;
+    /**
+     * REST - ACCOUNT  - SUBACCOUNT API
+     */
+    getSubAPIs(params: GetSubAPIsRequest): Promise<APISuccessResponse<SubAccountAPI[]>>;
+    createSubAPI(params: CreateSubAPIRequest): Promise<APISuccessResponse<CreateSubAccountAPI>>;
+    updateSubAPI(params: UpdateSubAPIRequest): Promise<APISuccessResponse<UpdateSubAccountAPI>>;
+    deleteSubAPI(params: DeleteSubAPIRequest): Promise<APISuccessResponse<{
+        subName: string;
+        apiKey: string;
+    }>>;
+    /**
+     * REST - FUNDING - FUNDING OVERVIEW
+     */
+    getBalance(params?: {
+        currency?: string;
+    }): Promise<APISuccessResponse<AccountBalance>>;
+    getSubBalances(params?: {
+        currency?: string;
+    }): Promise<APISuccessResponse<{
+        summary: AccountSummary;
+        accounts: SubBalance[];
+    }>>;
+    /**
+     * REST - FUNDING - TRANSFER
+     */
+    submitTransferOut(params: SubmitTransfer): Promise<Promise<APISuccessResponse<TransferDetail>>>;
+    submitTransferIn(params: SubmitTransfer): Promise<any>;
+    getTransfers(params: GetTransfersRequest): Promise<APISuccessResponse<FuturesTransferRecords>>;
+    /**
+     * REST - FUNDING - TRADE FEE
+     */
+    getTradingPairFee(params: {
+        symbols: string;
+    }): Promise<APISuccessResponse<{
+        symbol: string;
+        takerFeeRate: string;
+        makerFeeRate: string;
+    }>>;
+    /**
+     *
+     * REST - FUTURES TRADING - Market Data
+     *
+     */
+    getSymbols(): Promise<APISuccessResponse<FuturesSymbolInfo[]>>;
+    getSymbol(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FuturesSymbolInfo>>;
+    getTicker(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<TickerDetail>>;
+    getTickers(): Promise<APISuccessResponse<TickerDetail[]>>;
+    getFullOrderBookLevel2(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FullOrderBookDetail>>;
+    getPartOrderBookLevel2Depth20(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FullOrderBookDetail>>;
+    getPartOrderBookLevel2Depth100(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FullOrderBookDetail>>;
+    getMarketTrades(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<MarketTradeDetail>>;
+    getKlines(params: GetKlinesRequest): Promise<APISuccessResponse<FuturesKline[]>>;
+    getInterestRates(params: GetInterestRatesRequest): Promise<APISuccessResponse<{
+        dataList: InterestRateItem[];
+        hasMore: boolean;
+    }>>;
+    getIndex(params: GetInterestRatesRequest): Promise<APISuccessResponse<{
+        dataList: IndexListItem[];
+        hasMore: boolean;
+    }>>;
+    getMarkPrice(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FuturesMarkPrice>>;
+    getPremiumIndex(params: GetInterestRatesRequest): Promise<APISuccessResponse<{
+        dataList: PremiumIndexItem[];
+        hasMore: boolean;
+    }>>;
+    get24HourTransactionVolume(): Promise<APISuccessResponse<{
+        turnoverOf24h: number;
+    }>>;
+    /**
+     *
+     * REST - FUTURES TRADING - Orders
+     *
+     */
+    submitOrder(params: Order): Promise<APISuccessResponse<{
+        orderId: string;
+    }>>;
+    submitNewOrderTest(): Promise<any>;
+    cancelOrderById(params: {
+        orderId: string;
+    }): Promise<APISuccessResponse<{
+        cancelledOrderIds: string[];
+    }>>;
+    cancelOrderByClientOid(params: {
+        clientOid: string;
+    }): Promise<APISuccessResponse<{
+        clientOid: string;
+    }>>;
+    submitMultipleOrders(params: Order[]): Promise<APISuccessResponse<SubmitMultipleOrdersFuturesResponse[]>>;
+    cancelAllOrders(params?: {
+        symbol?: string;
+    }): Promise<APISuccessResponse<{
+        cancelledOrderIds: string[];
+    }>>;
+    cancelAllStopOrders(params?: {
+        symbol?: string;
+    }): Promise<APISuccessResponse<{
+        cancelledOrderIds: string[];
+    }>>;
+    getOrders(params?: GetOrdersRequest): Promise<APISuccessResponse<FuturesOrders>>;
+    getStopOrders(params?: GetStopOrdersRequest): Promise<APISuccessResponse<FuturesOrders>>;
+    getRecentOrders(params?: {
+        symbol?: string;
+    }): Promise<APISuccessResponse<FuturesOrder[]>>;
+    getOrderByOrderId(params: {
+        orderId: string;
+    }): Promise<APISuccessResponse<FuturesOrder>>;
+    getOrderByClientOrderId(params: {
+        clientOid: string;
+    }): Promise<APISuccessResponse<FuturesOrder>>;
+    /**
+     *
+     * REST - FUTURES TRADING - Fills
+     *
+     */
+    /**
+     * Get a list of recent fills.
+     *
+     * If you need to get your recent trade history with low latency, please query endpoint Get List of Orders Completed in 24h.
+     * The requested data is not real-time.
+     */
+    getFills(params?: AccountFillsRequest): Promise<APISuccessResponse<FuturesFills>>;
+    /**
+     * Get a list of recent 1000 fills in the last 24 hours.
+     *
+     * If you need to get your recent traded order history with low latency, you may query this endpoint.
+     */
+    getRecentFills(params?: {
+        symbol?: string;
+    }): Promise<APISuccessResponse<FuturesFill[]>>;
+    getOpenOrderStatistics(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FuturesActiveOrder>>;
+    /**
+     *
+     * REST - FUTURES TRADING - Positions
+     *
+     */
+    getMaxOpenSize(params: MaxOpenSizeRequest): Promise<APISuccessResponse<MaxOpenSize>>;
+    getPosition(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FuturesPosition>>;
+    getPositions(params?: {
+        currency?: string;
+    }): Promise<APISuccessResponse<FuturesPosition[]>>;
+    getHistoryPositions(params?: {
+        symbol?: string;
+        from?: number;
+        to?: number;
+        limit?: number;
+        pageId?: number;
+    }): Promise<APISuccessResponse<FuturesClosedPositions>>;
+    updateAutoDepositStatus(params: {
+        symbol: string;
+        status: boolean;
+    }): Promise<APISuccessResponse<boolean>>;
+    getMaxWithdrawMargin(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<number>>;
+    withdrawMargin(params: {
+        symbol: string;
+        withdrawAmount: string;
+    }): Promise<APISuccessResponse<{
+        sybmol: string;
+        withdrawAmount: number;
+    }>>;
+    depositMargin(params: {
+        symbol: string;
+        margin: number;
+        bizNo: string;
+    }): Promise<APISuccessResponse<AddMargin>>;
+    /**
+     *
+     * REST - FUTURES TRADING - Risk limit
+     *
+     */
+    getRiskLimitLevel(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FuturesRiskLimit[]>>;
+    updateRiskLimitLevel(params: {
+        symbol: string;
+        level: number;
+    }): Promise<any>;
+    /**
+     *
+     * REST - FUTURES TRADING - Funding fees
+     *
+     */
+    getFundingRate(params: {
+        symbol: string;
+    }): Promise<APISuccessResponse<FuturesCurrentFundingRate>>;
+    getFundingRates(params: GetFundingRatesRequest): Promise<APISuccessResponse<FuturesHistoricFundingRate[]>>;
+    getFundingHistory(params: GetFundingHistoryRequest): Promise<APISuccessResponse<{
+        dataList: FuturesAccountFundingRateHistory[];
+        hasMore: boolean;
+    }>>;
+    /**
+     *
+     * WebSockets
+     *
+     */
+    getPublicWSConnectionToken(): Promise<APISuccessResponse<WsConnectionInfo>>;
+    getPrivateWSConnectionToken(): Promise<APISuccessResponse<WsConnectionInfo>>;
+}