binance-api-node

binance-api-node

A complete API wrapper for the Binance API.

Note: This wrapper uses Promises, if they are not supported in your environment, you might want to add a polyfill for them.

For PRs or issues, head over to the source repository.

Installation

yarn add binance-api-node

Getting started

Import the module and create a new client. Passing api keys is optional only if you don't plan on doing authenticated calls. You can create an api key here.

import Binance from 'binance-api-node'

const client = Binance()

// Authenticated client, can make signed calls
const client2 = Binance({
  apiKey: 'xxx',
  apiSecret: 'xxx',
  getTime: xxx // time generator function, optional, defaults to () => Date.now()
})

client.time().then(time => console.log(time))

If you do not have an appropriate babel config, you will need to use the basic commonjs requires.

const Binance = require('binance-api-node').default

Every REST method returns a Promise, making this library async await ready. Following examples will use the await form, which requires some configuration you will have to lookup.

Table of Contents

• Public REST Endpoints
  • ping
  • time
  • exchangeInfo
  • book
  • candles
  • aggTrades
  • trades
  • dailyStats
  • avgPrice
  • prices
  • allBookTickers
• Authenticated REST Endpoints
  • order
  • orderTest
  • getOrder
  • cancelOrder
  • openOrders
  • allOrders
  • accountInfo
  • myTrades
  • tradesHistory
  • depositHistory
  • withdrawHistory
  • withdraw
  • depositAddress
  • tradeFee
• Websockets
  • depth
  • partialDepth
  • ticker
  • allTickers
  • candles
  • aggTrades
  • trades
  • user
• ErrorCodes

Public REST Endpoints

ping

Test connectivity to the API.

console.log(await client.ping())

time

Test connectivity to the Rest API and get the current server time.

console.log(await client.time())

Output

1508478457643

exchangeInfo

Get the current exchange trading rules and symbol information.

console.log(await client.exchangeInfo())

Output

{
  "timezone": "UTC",
  "serverTime": 1508631584636,
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 1200
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 1,
      "limit": 10
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 100000
    }
  ],
  "exchangeFilters": [],
  "symbols": [{
    "symbol": "ETHBTC",
    "status": "TRADING",
    "baseAsset": "ETH",
    "baseAssetPrecision": 8,
    "quoteAsset": "BTC",
    "quotePrecision": 8,
    "orderTypes": ["LIMIT", "MARKET"],
    "icebergAllowed": false,
    "filters": [{
      "filterType": "PRICE_FILTER",
      "minPrice": "0.00000100",
      "maxPrice": "100000.00000000",
      "tickSize": "0.00000100"
    }, {
      "filterType": "LOT_SIZE",
      "minQty": "0.00100000",
      "maxQty": "100000.00000000",
      "stepSize": "0.00100000"
    }, {
      "filterType": "MIN_NOTIONAL",
      "minNotional": "0.00100000"
    }]
  }]
}

book

Get the order book for a symbol.

console.log(await client.book({ symbol: 'ETHBTC' }))

Param	Type	Required	Default
symbol	String	true
limit	Number	false	100

Output

{
  lastUpdateId: 17647759,
  asks:
   [
     { price: '0.05411500', quantity: '5.55000000' },
     { price: '0.05416700', quantity: '11.80100000' }
   ],
  bids:
   [
     { price: '0.05395500', quantity: '2.70000000' },
     { price: '0.05395100', quantity: '11.84100000' }
   ]
}

candles

Retrieves Candlestick for a symbol. Candlesticks are uniquely identified by their open time.

console.log(await client.candles({ symbol: 'ETHBTC' }))

Param	Type	Required	Default	Description
symbol	String	true
interval	String	false	5m	1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
limit	Number	false	500	Max 1000
startTime	Number	false
endTime	Number	false

Output

[{
  openTime: 1508328900000,
  open: '0.05655000',
  high: '0.05656500',
  low: '0.05613200',
  close: '0.05632400',
  volume: '68.88800000',
  closeTime: 1508329199999,
  quoteAssetVolume: '2.29500857',
  trades: 85,
  baseAssetVolume: '40.61900000'
}]

aggTrades

Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.

console.log(await client.aggTrades({ symbol: 'ETHBTC' }))

Param	Type	Required	Default	Description
symbol	String	true
fromId	String	false		ID to get aggregate trades from INCLUSIVE.
startTime	Number	false		Timestamp in ms to get aggregate trades from INCLUSIVE.
endTime	Number	false		Timestamp in ms to get aggregate trades until INCLUSIVE.
limit	Number	false	500	Max 500

Note: If both startTime and endTime are sent, limit should not be sent AND the distance between startTime and endTime must be less than 24 hours.

Note: If frondId, startTime, and endTime are not sent, the most recent aggregate trades will be returned.

Output

[{
  aggId: 2107132,
  price: '0.05390400',
  quantity: '1.31000000',
  firstId: 2215345,
  lastId: 2215345,
  timestamp: 1508478599481,
  isBuyerMaker: true,
  wasBestPrice: true
}]

trades

Get recent trades of a symbol.

console.log(await client.trades({ symbol: 'ETHBTC' }))

Param	Type	Required	Default	Description
symbol	String	true
limit	Number	false	500	Max 500

Output

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true
  }
]

dailyStats

24 hour price change statistics, not providing a symbol will return all tickers and is resource-expensive.

console.log(await client.dailyStats({ symbol: 'ETHBTC' }))

Param	Type	Required
symbol	String	false

Output

{
  symbol: 'ETHBTC',
  priceChange: '-0.00112000',
  priceChangePercent: '-1.751',
  weightedAvgPrice: '0.06324784',
  prevClosePrice: '0.06397400',
  lastPrice: '0.06285500',
  lastQty: '0.63500000',
  bidPrice: '0.06285500',
  bidQty: '0.81900000',
  askPrice: '0.06291900',
  askQty: '2.93800000',
  openPrice: '0.06397500',
  highPrice: '0.06419100',
  lowPrice: '0.06205300',
  volume: '126240.37200000',
  quoteVolume: '7984.43091340',
  openTime: 1521622289427,
  closeTime: 1521708689427,
  firstId: 45409308, // First tradeId
  lastId: 45724293, // Last tradeId
  count: 314986 // Trade count
}

avgPrice

Current average price for a symbol.

console.log(await client.avgPrice({ symbol: 'ETHBTC' }))

Param	Type	Required
symbol	String	true

Output

{
  "mins": 5,
  "price": "9.35751834"
}

prices

Latest price for all symbols.

console.log(await client.prices())

Output

{
  ETHBTC: '0.05392500',
  LTCBTC: '0.01041100',
  ...
}

allBookTickers

Best price/qty on the order book for all symbols.

console.log(await client.allBookTickers())

Output

{
  DASHBTC: {
    symbol: 'DASHBTC',
    bidPrice: '0.04890400',
    bidQty: '0.74100000',
    askPrice: '0.05230000',
    askQty: '0.79900000'
  },
  DASHETH: {
    symbol: 'DASHETH',
    bidPrice: '0.89582000',
    bidQty: '0.63300000',
    askPrice: '1.02328000',
    askQty: '0.99900000'
  }
  ...
}

Authenticated REST Endpoints

Note that for all authenticated endpoints, you can pass an extra parameter useServerTime set to true in order to fetch the server time before making the request.

order

Creates a new order.

console.log(await client.order({
  symbol: 'XLMETH',
  side: 'BUY',
  quantity: 100,
  price: 0.0002,
}))

Param	Type	Required	Default	Description
symbol	String	true
side	String	true		BUY,SELL
type	String	false	LIMIT	LIMIT, MARKET
quantity	Number	true
price	Number	true		Optional for MARKET orders
timeInForce	String	false	GTC	FOK, GTC, IOC
newClientOrderId	String	false		A unique id for the order. Automatically generated if not sent.
stopPrice	Number	false		Used with stop orders
newOrderRespType	String	false	RESULT	Returns more complete info of the order. ACK, RESULT, or FULL
icebergQty	Number	false		Used with iceberg orders
recvWindow	Number	false

Additional mandatory parameters based on type:

Type	Additional mandatory parameters
LIMIT	timeInForce, quantity, price
MARKET	quantity
STOP_LOSS	quantity, stopPrice
STOP_LOSS_LIMIT	timeInForce, quantity, price, stopPrice
TAKE_PROFIT	quantity, stopPrice
TAKE_PROFIT_LIMIT	timeInForce, quantity, price, stopPrice
LIMIT_MAKER	quantity, price

• LIMIT_MAKER are LIMIT orders that will be rejected if they would immediately match and trade as a taker.
• STOP_LOSS and TAKE_PROFIT will execute a MARKET order when the stopPrice is reached.
• Any LIMIT or LIMIT_MAKER type order can be made an iceberg order by sending an icebergQty.
• Any order with an icebergQty MUST have timeInForce set to GTC.

Output

{
  symbol: 'XLMETH',
  orderId: 1740797,
  clientOrderId: '1XZTVBTGS4K1e',
  transactTime: 1514418413947,
  price: '0.00020000',
  origQty: '100.00000000',
  executedQty: '0.00000000',
  status: 'NEW',
  timeInForce: 'GTC',
  type: 'LIMIT',
  side: 'BUY'
}

orderTest

Test new order creation and signature/recvWindow. Creates and validates a new order but does not send it into the matching engine.

Same API as above, but does not return any output on success.

getOrder

Check an order's status.

console.log(await client.getOrder({
  symbol: 'BNBETH',
  orderId: 50167927,
}))

Param	Type	Required	Description
symbol	String	true
orderId	Number	true	Not required if origClientOrderId is used
origClientOrderId	String	false
recvWindow	Number	false

Output

{
  clientOrderId: 'NkQnNkdBV1RGjUALLhAzNy',
  cummulativeQuoteQty: '0.16961580',
  executedQty: '3.91000000',
  icebergQty: '0.00000000',
  isWorking: true,
  orderId: 50167927,
  origQty: '3.91000000',
  price: '0.04338000',
  side: 'SELL',
  status: 'FILLED',
  stopPrice: '0.00000000',
  symbol: 'BNBETH',
  time: 1547075007821,
  timeInForce: 'GTC',
  type: 'LIMIT',
  updateTime: 1547075016737
}

cancelOrder

Cancels an active order.

console.log(await client.cancelOrder({
  symbol: 'ETHBTC',
  orderId: 1,
}))

Param	Type	Required	Description
symbol	String	true
orderId	Number	true	Not required if origClientOrderId is used
origClientOrderId	String	false
newClientOrderId	String	false	Used to uniquely identify this cancel. Automatically generated by default.
recvWindow	Number	false

Output

{
  symbol: 'ETHBTC',
  origClientOrderId: 'bnAoRHgI18gRD80FJmsfNP',
  orderId: 1,
  clientOrderId: 'RViSsQPTp1v3WmLYpeKT11'
}

openOrders

Get all open orders on a symbol.

console.log(await client.openOrders({
  symbol: 'XLMBTC',
}))

Param	Type	Required
symbol	String	true
recvWindow	Number	false

Output

[{
  symbol: 'XLMBTC',
  orderId: 11271740,
  clientOrderId: 'ekHkROfW98gBN80LTfufQZ',
  price: '0.00001081',
  origQty: '1331.00000000',
  executedQty: '0.00000000',
  status: 'NEW',
  timeInForce: 'GTC',
  type: 'LIMIT',
  side: 'BUY',
  stopPrice: '0.00000000',
  icebergQty: '0.00000000',
  time: 1522682290485,
  isWorking: true
}]

allOrders

Get all account orders on a symbol; active, canceled, or filled.

console.log(await client.allOrders({
  symbol: 'ETHBTC',
}))

Param	Type	Required	Default	Description
symbol	String	true
orderId	Number	false		If set, it will get orders >= that orderId. Otherwise most recent orders are returned.
limit	Number	false	500	Max 500
recvWindow	Number	false

Output

[{
  symbol: 'ENGETH',
  orderId: 191938,
  clientOrderId: '1XZTVBTGS4K1e',
  price: '0.00138000',
  origQty: '1.00000000',
  executedQty: '1.00000000',
  status: 'FILLED',
  timeInForce: 'GTC',
  type: 'LIMIT',
  side: 'SELL',
  stopPrice: '0.00000000',
  icebergQty: '0.00000000',
  time: 1508611114735,
  isWorking: true
}]

accountInfo

Get current account information.

console.log(await client.accountInfo())

Param	Type	Required
recvWindow	Number	false

Output

{
  makerCommission: 10,
  takerCommission: 10,
  buyerCommission: 0,
  sellerCommission: 0,
  canTrade: true,
  canWithdraw: true,
  canDeposit: true,
  balances: [
    { asset: 'BTC', free: '0.00000000', locked: '0.00000000' },
    { asset: 'LTC', free: '0.00000000', locked: '0.00000000' },
  ]
}

myTrades

Get trades for the current authenticated account and symbol.

console.log(await client.myTrades({
  symbol: 'ETHBTC',
}))

Param	Type	Required	Default	Description
symbol	String	true
limit	Number	false	500	Max 500
fromId	Number	false		TradeId to fetch from. Default gets most recent trades.
recvWindow	Number	false

Output

[{
  id: 9960,
  orderId: 191939,
  price: '0.00138000',
  qty: '10.00000000',
  commission: '0.00001380',
  commissionAsset: 'ETH',
  time: 1508611114735,
  isBuyer: false,
  isMaker: false,
  isBestMatch: true
}]

tradesHistory

Lookup symbol trades history.

console.log(await client.tradesHistory({ symbol: 'ETHBTC' }))

Param	Type	Required	Default	Description
symbol	String	true
limit	Number	false	500	Max 500
fromId	Number	false	null	TradeId to fetch from. Default gets most recent trades.

Output

[
  {
    "id": 28457,
      "price": "4.00000100",
      "qty": "12.00000000",
      "time": 1499865549590,
      "isBuyerMaker": true,
      "isBestMatch": true
  }
]

depositHistory

Get the account deposit history.

console.log(await client.depositHistory())

Param	Type	Required	Description
asset	String	false
status	Number	false	0 (0: pending, 1: success)
startTime	Number	false
endTime	Number	false
recvWindow	Number	false

Output

{
  "depositList": [
    {
      "insertTime": 1508198532000,
      "amount": 0.04670582,
      "asset": "ETH",
      "status": 1
    }
  ],
  "success": true
}

withdrawHistory

Get the account withdraw history.

console.log(await client.withdrawHistory())

Param	Type	Required	Description
asset	String	false
status	Number	false	0 (0: Email Sent, 1: Cancelled 2: Awaiting Approval, 3: Rejected, 4: Processing, 5: Failure, 6: Completed)
startTime	Number	false
endTime	Number	false
recvWindow	Number	false

Output

{
  "withdrawList": [
    {
      "amount": 1,
      "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
      "asset": "ETH",
      "applyTime": 1508198532000,
      "status": 4
    },
  ],
  "success": true
}

withdraw

Triggers the withdraw process (untested for now).

console.log(await client.withdraw({
  asset: 'ETH',
  address: '0xfa97c22a03d8522988c709c24283c0918a59c795',
  amount: 100,
}))

Param	Type	Required	Description
asset	String	true
address	String	true
amount	Number	true
name	String	false	Description of the address
recvWindow	Number	false

Output

{
  "msg": "success",
  "success": true
}

depositAddress

Retrieve the account deposit address for a specific asset.

console.log(await client.depositAddress({ asset: 'NEO' }))

Param	Type	Required	Description
asset	String	true	The asset name

Output

{
  address: 'AM6ytPW78KYxQCmU2pHYGcee7GypZ7Yhhc',
  addressTag: '',
  asset: 'NEO',
  success: true,
}

tradeFee

Retrieve the account trade Fee per asset.

console.log(await client.tradeFee())

Output

[{
  symbol: 'BTC',
  maker: 0.0001,
  taker: 0.0001,
},
{
  symbol: 'LTC',
  maker: 0.0001,
  taker: 0.0001,
}
...]

WebSockets

Every websocket utility returns a function you can call to close the opened connection and avoid memory issues.

const clean = client.ws.depth('ETHBTC', depth => {
  console.log(depth)
})

// After you're done
clean()

depth

Live depth market data feed. The first parameter can either be a single symbol string or an array of symbols.

client.ws.depth('ETHBTC', depth => {
  console.log(depth)
})

Output

{
  eventType: 'depthUpdate',
  eventTime: 1508612956950,
  symbol: 'ETHBTC',
  firstUpdateId: 18331140,
  finalUpdateId: 18331145,
  bidDepth: [
    { price: '0.04896500', quantity: '0.00000000' },
    { price: '0.04891100', quantity: '15.00000000' },
    { price: '0.04891000', quantity: '0.00000000' } ],
  askDepth: [
    { price: '0.04910600', quantity: '0.00000000' },
    { price: '0.04910700', quantity: '11.24900000' }
  ]
}

partialDepth

Top levels bids and asks, pushed every second. Valid levels are 5, 10, or 20. Accepts an array of objects for multiple depths.

client.ws.partialDepth({ symbol: 'ETHBTC', level: 10 }, depth => {
  console.log(depth)
})

Output

{
  symbol: 'ETHBTC',
  level: 10,
  bids: [
    { price: '0.04896500', quantity: '0.00000000' },
    { price: '0.04891100', quantity: '15.00000000' },
    { price: '0.04891000', quantity: '0.00000000' }
  ],
  asks: [
    { price: '0.04910600', quantity: '0.00000000' },
    { price: '0.04910700', quantity: '11.24900000' }
  ]
}

ticker

24hr Ticker statistics for a symbol pushed every second. Accepts an array of symbols.

client.ws.ticker('HSRETH', ticker => {
  console.log(ticker)
})

Output

{
  eventType: '24hrTicker',
  eventTime: 1514670820924,
  symbol: 'HSRETH',
  priceChange: '-0.00409700',
  priceChangePercent: '-11.307',
  weightedAvg: '0.03394946',
  prevDayClose: '0.03623500',
  curDayClose: '0.03213800',
  closeTradeQuantity: '7.02000000',
  bestBid: '0.03204200',
  bestBidQnt: '78.00000000',
  bestAsk: '0.03239800',
  bestAskQnt: '7.00000000',
  open: '0.03623500',
  high: '0.03659900',
  low: '0.03126000',
  volume: '100605.15000000',
  volumeQuote: '3415.49097353',
  openTime: 1514584420922,
  closeTime: 1514670820922,
  firstTradeId: 344803,
  lastTradeId: 351380,
  totalTrades: 6578
}

allTickers

Retrieves all the tickers.

client.ws.allTickers(tickers => {
  console.log(tickers)
})

candles

Live candle data feed for a given interval. You can pass either a symbol string or a symbol array.

client.ws.candles('ETHBTC', '1m', candle => {
  console.log(candle)
})

Output

{
  eventType: 'kline',
  eventTime: 1508613366276,
  symbol: 'ETHBTC',
  open: '0.04898000',
  high: '0.04902700',
  low: '0.04898000',
  close: '0.04901900',
  volume: '37.89600000',
  trades: 30,
  interval: '5m',
  isFinal: false,
  quoteVolume: '1.85728874',
  buyVolume: '21.79900000',
  quoteBuyVolume: '1.06838790'
}

trades

Live trade data feed. Pass either a single symbol string or an array of symbols. The trade streams push raw trade information; each trade has a unique buyer and seller.

client.ws.trades(['ETHBTC', 'BNBBTC'], trade => {
  console.log(trade)
})

Output

{
  eventType: 'trade',
  eventTime: 1508614495052,
  symbol: 'ETHBTC',
  price: '0.04923600',
  quantity: '3.43500000',
  maker: false,
  tradeId: 2148226
}

aggTrades

Live trade data feed. Pass either a single symbol string or an array of symbols. The aggregate trade streams push trade information that is aggregated for a single taker order.

client.ws.aggTrades(['ETHBTC', 'BNBBTC'], trade => {
  console.log(trade)
})

Output

{
  eventType: 'aggTrade',
  eventTime: 1508614495052,
  symbol: 'ETHBTC',
  price: '0.04923600',
  quantity: '3.43500000',
  maker: false,
  tradeId: 2148226
}

user

Live user messages data feed.

Requires authentication

const clean = await client.ws.user(msg => {
  console.log(msg)
})

Live user messages data feed on margin wallet.

Requires authentication

const clean = await client.ws.marginUser(msg => {
  console.log(msg)
})

Note that this methods returns a promise which will resolve the clean callback.

Output

{
  eventType: 'account',
  eventTime: 1508614885818,
  balances: {
    '123': { available: '0.00000000', locked: '0.00000000' },
    '456': { available: '0.00000000', locked: '0.00000000' },
    BTC: { available: '0.00000000', locked: '0.00000000' },
  }
}

ErrorCodes

An utility error code map is also being exported by the package in order for you to make readable conditionals upon specific errors that could occur while using the API.

import Binance, { ErrorCodes } from 'binance-api-node'

console.log(ErrorCodes.INVALID_ORDER_TYPE) // -1116