README.md

kucoin-futures-node-api

Just a KuCoin Futures API version of https://github.com/escwdev/kucoin-node-api/.

Installation

npm install kucoin-futures-node-api

Alternatively, you can clone/download the repository and import into your project by file path.

Getting Started

To begin using the API wrapper, require it, create a config object that contains your API key, Secret key and Passphrase provided by Kucoin. Create an instantiation of the class then run the custom init() function with your config object as a parameter. If you are only using Public endpoints, the config object only requires the environment key/value pair.

Example code is as follows:

const api = require('./kucoin-futures-node-api')

const config = {
  apiKey: 'xXXXXXXXXXXXXXXXXXXXXxxxxxxxxxxxxxxxxxxxxxXXX',
  secretKey: 'xxxxxxxxXXXXXXXXXXXXXxxXXXXXXXXXXXXXxxxXXX',
  passphrase: 'xxxxxx',
  environment: 'live'
}

const apiLive = new api()
apiLive.init(config)

Using the API Wrapper

Once the API wrapper object is created, you can call any of the associated functions. They will return a Promise which can be utlized with .then/.catch or async/await. Note that the Promise based approach will return directly whereas the async/await approach requires calling the function.

Simple example:

// Promise based approach for getting account information (private & signed)
apiLive.getAccountOverview().then((r) => {
  console.log(r.data)
}).catch((e) => {
  console.log(e))
})

// Async/Await get account info example (private & signed)
async function getAccountOverview() {
  try {
    let r = await apiLive.getAccountOverview()
    console.log(r.data)
  } catch(err) {
    console.log(err)
  } 
}

This approach allows for more complex multi-call asynchronous functionality, especially useful for automated trading.

Market Endpoint (Public)

Public endpoints do not require an API Key, Secret Key or API Passphrase.

/* 
  Get Order Info. of the Contract
  GET /api/v1/contracts
  symbol = string [optional]
*/
apiLive.getContract(symbol)

/* 
  Get Open Contract List
  GET /api/v1/contracts
  symbol = string [optional]
*/
apiLive.getAllContracts()

/*  
  Get Ticker
  GET /api/v1/ticker
  symbol = string
*/
apiLive.getTicker(symbol)

/* 
  Get Full Order Book - Level 2 (aggregated)
  see details at: https://docs.kucoin.com/futures/#get-full-order-book-level-2
  GET /api/v1/level2/snapshot?symbol=<symbol>
  symbol = string
*/
apiLive.getFullOrderBook(symbol)

/* 
  Get Part Order Book (aggregated) 
  GET /api/v1/level2/depth20?symbol=<symbol>
  GET /api/v1/level2/depth100?symbol=<symbol>
  params = {
    amount: integer (20 || 100) 
    symbol: string
  }
*/
apiLive.getPartOrderBook(params)

/* 
  Level 2 Pulling Messages
  see details at: https://docs.kucoin.com/futures/#level-2-pulling-messages
  GET /api/v1/level2/message/query
  params = {
    symbol: string
    start: long
    end	: long
  }
*/
apiLive.pullMessagesLvl2(params)

/* 
  Get Full Order Book (atomic) 
  GET /api/v2/level3/snapshot?symbol=<symbol>
  symbol = string
*/
apiLive.getFullOrderBookAtomic(symbol)

/* 
  Level 3 Pulling Messages
  see details at: https://docs.kucoin.com/futures/#level-3-pulling-messages
  GET /api/v1/level3/snapshot
  params = {
    symbol: string
    start: long
    end	: long
  }
*/
apiLive.pullMessagesLvl3(params)

/* 
  List the last 100 trades for a symbol
  GET /api/v1/trade/history?symbol=<symbol>
  symbol = string
*/
apiLive.getTradeHistories(symbol)

/* 
  Get Interest Rate List
  GET /api/v1/interest/query
  params = {
    symbol = string
    startAt = long (unix time) [optional]
    endAt = long (unix time) [optional]
    reverse = boolean [optional, default: true]
    offset = long [optional]
    forward = boolean [optional, default: true]
    maxCount = int [optional, default: 10]
  }
*/
apiLive.getInterestRate(params)

/* 
  Get Index List
  GET /api/v1/index/query
  params = {
    symbol = string
    startAt = long (unix time) [optional]
    endAt = long (unix time) [optional]
    reverse = boolean [optional, default: true]
    offset = long [optional]
    forward = boolean [optional, default: true]
    maxCount = int [optional, default: 10]
  }
*/
apiLive.getIndexList(params)

/* 
  Get Current Mark Price
  GET /api/v1/mark-price/{symbol}/current
  symbol = string
*/
apiLive.getMarkPrice(symbol)

/* 
  Get Premium Index
  GET /api/v1/index/query
  params = {
    symbol = string
    startAt = long (unix time) [optional]
    endAt = long (unix time) [optional]
    reverse = boolean [optional, default: true]
    offset = long [optional]
    forward = boolean [optional, default: true]
    maxCount = int [optional, default: 10]
  }
*/
apiLive.getPremiumIndex(params)

/* 
  Get Current Funding Rate
  GET /api/v1/funding-rate/{symbol}/current
  symbol = string
*/
apiLive.getFundingRate(symbol)

/* 
  Server Time
  GET /api/v1/timestamp
*/
apiLive.getServerTime() 

/* 
  Get Klines
  GET /api/v1/kline/query
  params = {
    symbol: string [Required]
    granularity: int [Required] - Granularity (minute)
    startAt: long (unix time) [Optional]
    endAt: long (unix time) [Optional]
  }
*/
apiLive.getKlines(params) 

User Endpoints (Private)

/* 
  Get Account Overview
  GET /api/v1/account-overview
  params = {
    currency: string [optional, default: XBT]
  }
*/
apiLive.getAccountOverview(params)

/* 
  Get Transaction History, see: https://docs.kucoin.com/futures/#get-transaction-history
  GET /api/v1/transaction-history
  params = {
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
    type: string [optional]
    offset: long [optional]
    maxCount: long [optional, default: 50]
    currency: string [optional]
    forward: boolean [optional, default: True]
  }
*/
apiLive.getTransactionHist(params)

/* 
  Get Deposit Address
  GET /api/v1/deposit-address?currency=<currency>
  params = {
    currency: string
  }
*/
apiLive.getDepositAddress(params)

/* 
  Get Deposit List
  GET /api/v1/deposit-list
  params = {
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
    status: string [optional]
    currency: string [optional]
  }
*/
apiLive.getDepositList(params)

/* 
  Get Withdrawal Quotas
  GET /api/v1/withdrawals/quotas
  params = {
    currency: string
  }
*/
apiLive.getWithdrawalQuotas(params)

/* 
  Withdraw Funds
  POST /api/v1/withdrawals
  params = {
    currency: string
    address: string
    amount: number
    isInner: boolean [optional]
    remark: string [optional]
    chain: string [optional, default: ERC20]
    memo: string [optional]
  }
*/
apiLive.applyForWithdrawal(params)

/*  
  Get Withdrawals List
  GET /api/v1/withdrawal-list
  params = {
    status: string [optional]
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
    currency: string [optional]
  }
*/
apiLive.getWithdrawalsList(params)

/* 
  Cancel Withdrawal
  DELETE /api/v1/withdrawals/<withdrawalId>
  params = {
    withdrawalId: string
  }
*/
apiLive.cancelWithdrawal(params)

/* 
  Transfer Funds
  POST /api/v2/transfer-out
  params = {
    bizNo: string
    amount: number
    currency: string
  }
*/
apiLive.transferFunds(params)

/*  
  Get Transfer List
  GET /api/v1/transfer-list
  params = {
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
    status: string [optional]
    currency: string
  }
*/
apiLive.getTransferList(params)

/* 
  Cancel Withdrawal
  DELETE /api/v1/cancel/transfer-out
  params = {
    applyId: string
  }
*/
apiLive.cancelWithdrawal(params)

Trade Endpoints (Private)

/* 
  Place a new order
  POST /api/v1/orders
  Details for market order vs. limit order and params see https://docs.kucoin.com/futures/#place-a-new-order
  General params
  params = {
    clientOid: string - Unique order id created by users to identify their orders
    side: string ['buy' || 'sell]
    symbol: string - a valid contract code. e.g. XBTUSDM
    type: string [optional] - Either limit or market
    leverage: string - Leverage of the order
    remark: string [optional] - remark for the order, length cannot exceed 100 utf8 characters
    stop: string [optional] - Either down or up. Requires stopPrice and stopPriceType to be defined
    stopPriceType: string [optional] - Either TP, IP or MP, Need to be defined if stop is specified.
    stopPrice: string [optional] - Need to be defined if stop is specified.
    reduceOnly: boolean [optional, default: false] - A mark to reduce the position size only
    closeOrder: boolean [optional, default: false] - A mark to close the position
    forceHold: boolean [optional, default: false] -  A mark to forcely hold the funds for an order
    
    LIMIT ORDER PARAMETERS
    price: string - Limit price
    size: Integer - Order size
    timeInForce: string [optional, default is GTC] - GTC, IOC. read: https://docs.kucoin.com/futures/#time-in-force
    postOnly: boolean [optional] - Post only flag, invalid when timeInForce is IOC
    hidden: boolean [optional] - Orders not displaying in order book
    iceberg: boolean [optional]
    visibleSize: Integer [optional]

    MARKET ORDER PARAMETERS
    size: Integer [optional] - amount of contract to buy or sell
  }
*/
apiLive.placeOrder(params)

/* 
  Cancel an order (including a stop order)
  DELETE /api/v1/orders/<order-id>
  params = {
    id: order-id
  }
*/
apiLive.cancelOrder(params)

/* 
  Cancel all open orders (excluding stop orders)
  DELETE /api/v1/orders
  params = {
    symbol: string [optional]
  }
*/
apiLive.cancelAllOrders(params)

/* 
  Cancel all untriggered stop orders
  DELETE /api/v1/stopOrders
  params = {
    symbol: string [optional] - Cancel all untriggered stop orders for a specific contract only
  }
*/
apiLive.cancelAllStopOrders(params)

/* 
  List your current orders
  GET /api/v1/orders
  params = {
    status: string [optional, default: done, alt: active]
    symbol: string [optional]
    side: string [optional, 'buy' || 'sell]
    type: string [optional, limit || market || limit_stop || market_stop]
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
  }
*/
apiLive.getOrders(params) 

/* 
  Get the un-triggered stop orders list.
  GET /api/v1/stopOrders
  params = {
    symbol: string [optional]
    side: string [optional, 'buy' || 'sell]
    type: string [optional, limit || market]
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
  }
*/
apiLive.getStopOrders(params)

/* 
  Get a list of recent 1000 orders in the last 24 hours.
  GET /api/v1/recentDoneOrders
*/
apiLive.getRecentOrders()

/* 
  Get a single order by order id (including a stop order)
  GET /api/v1/orders/<order-id>?clientOid=<client-order-id>
  params = {
    oid: order-id,
    cid: client-order-id [optional] - oid (order-id) must be undefined
  }
*/
apiLive.getOrderById(params)

/* 
  List Fills
  GET /api/v1/fills
  params: {
    orderId: string [optional]
    symbol: string [optional]
    side: string [optional, 'buy' || 'sell]
    type: string [optional, limit || market || limit_stop || market_stop]
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
  }
*/
apiLive.listFills(params)

/* 
  List Your Recent Fills: max 1000 fills in the last 24 hours, all symbols
  GET /api/v1/recentFills
*/
apiLive.recentFills()

/* 
  Active Order Value Calculation
  GET /api/v1/openOrderStatistics
  params: {
    symbol: string
  }
*/
apiLive.getOpenOrderStatistics(params)

/* 
  Get the position details of a specified position.
  GET /api/v1/position
  params: {
    symbol: string
  } 
*/
apiLive.getPosition(params)

/* 
  Get all the positions
  GET /api/v1/positions
*/
apiLive.getAllPositions()

/* 
  Enable/Disable of Auto-Deposit Margin
  POST /api/v1/position/margin/auto-deposit-status
  params = {
    symbol: string - Symbol of the contract
    status: boolean - Status
  }
*/
apiLive.changeAutoDeposit(params)

/* 
  Add Margin Manually
  POST /api/v1/position/margin/deposit-margin
  params = {
    symbol: string - Ticker symbol of the contract
    margin: number - Margin amount (min. margin amount≥0.00001667XBT）
    bizNo: string - A unique ID generated by the user
  }
*/
apiLive.addMargin(params)

/* 
  Get V1 Historical Orders List
  GET /api/v1/funding-history
  params: {
    symbol: string
    startAt: long (unix time) [optional]
    endAt: long (unix time) [optional]
    reverse: boolean [optional, default: true]
    offset: long [optional]
    forward: boolean [optional, default: true]
    maxCount: int [optional, default: 10]
  }
*/
apiLive.getFundingHistory(params)

Websockets

The websocket component of the API wrapper is utilized by initializing websockets based on topics that match Kucoin endpoints. These include:

• 'ticker'
• 'tickerv2'
• 'orderbook'
• 'execution'
• 'fullMatch'
• 'depth5'
• 'depth50'
• 'market'
• 'announcement'
• 'snapshot'
• 'ordersMarket' (private)
• 'orders' (private)
• 'advancedOrders' (private)
• 'balances' (private)
• 'position' (private)

To initialize a websocket, provide the paramaters and an event handler. A simple example is as follows:

// Parameters 
params = {
  topic: enum (see above)
  symbols: array (ignored if not required by the endpoint, single array element if single, multiple if desired)
}

// Public streaming websocket for the orderbook of the provide symbol(s)
apiLive.initSocket({topic: "orderbook", symbols: ['KCS-BTC']}, (msg) => {
  let data = JSON.parse(msg)
  console.log(data)
})

// Private streaming websocket for account balances
apiLive.initSocket({topic: "balances"}, (msg) => {
  let data = JSON.parse(msg)
  console.log(data)
})

The event handler can be programmed to manipulate/store the returned websocket stream data as desired.