Skip to content

MohamedLamineAllal/binance-client

BranchesTags

Repository files navigation

binance-client

🥎🥎🥎🥎🥎 ❌❌❌ ❌❌❌ ❌❌❌ ❌❌❌ ❌❌❌ ❌❌❌ 🥎🥎🥎🥎🥎

  • This package is no more being maintained. Deprecated. ❗

🥎🥎🥎🥎🥎 ❌❌❌ ❌❌❌ ❌❌❌ ❌❌❌ ❌❌❌ ❌❌❌ 🥎🥎🥎🥎🥎

NOTICE: Proxy support was Added (check the last section in the doc)

NOTICE: BINANCE FUTURES support

(User stream for Binance futures is fully supported ! Doc updated to reflect it! Go all bellow!)

Binance futures typescript supported

The doc for Binance (spot, margin,) wasn't updated! Neither futures is well documented! If you go for this package check the code source and the official doc! Still we are updating and adding more reference from time to time!

To note the Binance futures official doc is way nice

https://binance-docs.github.io/apidocs/futures/en/

The same order as the official doc was followed for the function implementation

The Doc here is just a big mess! We don't have time for it now! It will be updated at a later time! (If any one want to contribute! And match things between the code source and the official doc! And update the different sections! Special for normal Binance! Just a little updates are required! We will accept and review all PR! The library is just getting more complete and richer! With options that are not supported anywhere else! A good doc will make it helpful for a lot! And we want to make it so!)

For the future we will take full support and development responsibility for the package so it will be helpful to other people! As our work is based on it! We will keep it sharp at all times

No may be this is just the wrong destination! the package is well usable and all good! And getting better and better! But there is no support! And all the doc is a mess

NOTICE: The Doc is out of date! Make sure to verify the outcomes! Or check the Declaration type file here! Or the code source itself! (Use CTRL + F To be productive)!

NOTICE: if you use this library and just to save some hassle if it happen! In case you update! Then the code break! Immediately go check the package version! We may have add breaking changes updates! We are using semantic versioning! But still we made some partial breaking changes! Which we completed on the same version! We shouldn't have done that! But to move fast we did that! If anything check the version! Things will get more robust by the time that is coming!

Including cleaning that big mess README and doc! That make people go away! GO AWAY! UNLESS you see real VALUE hhhhh! (And of course i'm awesome hhhhhh! Humor can be magic)

DOC

A complete API wrapper for the Binance API.

this project support typescript too.

Installation

npm install binance-client --save

or yarn add binance-client

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

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-client').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

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', qty: '5.55000000' },
     { price: '0.05416700', qty: '11.80100000' }
   ],
  bids:
   [
     { price: '0.05395500', qty: '2.70000000' },
     { price: '0.05395100', qty: '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',
  qty: '1.31000000',
  firstId: 2215345,
  lastId: 2215345,
  time: 1508478599481,
  isBuyerMaker: true,
  isBestMatch: 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/quantity 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',
  qty: 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",
    "quantity": "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 an object that contain the closeStream function you can call it to close the opened connection or connections and avoid memory issues.

And too a ws that refer to websocket or a list of websockets objects! That you can use to listen to the websocket cycle events! Sometimes you may need that! And we exposed the object! We needed that in our work!

Return object signature

export interface StreamReturnObj {
  closeStream: ReconnectingWebSocketHandler,
  ws: WebSocket | WebSocket[]
}

You can check the WebSocket object api!

https://developer.mozilla.org/en-US/docs/Web/API/WebSocket

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

// After you're done
closeStream()

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', qty: '0.00000000' },
    { price: '0.04891100', qty: '15.00000000' },
    { price: '0.04891000', qty: '0.00000000' } ],
  askDepth: [
    { price: '0.04910600', qty: '0.00000000' },
    { price: '0.04910700', qty: '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', qty: '0.00000000' },
    { price: '0.04891100', qty: '15.00000000' },
    { price: '0.04891000', qty: '0.00000000' }
  ],
  asks: [
    { price: '0.04910600', qty: '0.00000000' },
    { price: '0.04910700', qty: '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',
  closeTradeqty: '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(['BTCUSDT', 'ETHBTC'], trade => {
  console.log(trade)
})
Output 
......
{
  eventType: 'trade',
  eventTime: 1570196993155,
  symbol: 'ETHBTC',
  tradeId: 145470107,
  price: '0.02142700',
  qty: '0.06300000',
  buyerOrderId: 498249081,
  sellerOrderId: 498249078,
  tradeTime: 1570196993151,
  isBuyerMaker: false,
  isBestMatch: true
}
{
  eventType: 'trade',
  eventTime: 1570196993376,
  symbol: 'BTCUSDT',
  tradeId: 186166622,
  price: '8138.30000000',
  qty: '0.01722700',
  buyerOrderId: 684614964,
  sellerOrderId: 684614991,
  tradeTime: 1570196993372,
  isBuyerMaker: true,
  isBestMatch: true
}
.....

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(['BTCUSDT', 'ETHBTC'], trade => {
  console.log(trade)
})
Output 
.....
{
  eventType: 'aggTrade',
  eventTime: 1570197286258,
  symbol: 'ETHBTC',
  aggId: 132178432,
  price: '0.02144000',
  qty: '0.42500000',
  firstTradeId: 145470333,
  lastTradeId: 145470333,
  tradeTime: 1570197286254,
  isBuyerMaker: true,
  isBestMatch: true
}
{
  eventType: 'aggTrade',
  eventTime: 1570197286697,
  symbol: 'BTCUSDT',
  aggId: 168291934,
  price: '8160.04000000',
  qty: '0.40000000',
  firstTradeId: 186167448,
  lastTradeId: 186167448,
  tradeTime: 1570197286693,
  isBuyerMaker: true,
  isBestMatch: true
}
....

user

Live user messages data feed.

Requires authentication

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

Note that this method 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-client'

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

Binance futures

Futures Websocket

Normal streams

We gonna update that section later! But here a quick signature representation! You can check it here (Declaration type file)! For more details (Use CTRL + F)

export interface FuturesWebSocket {
  depth: (payload: { symbol: string, speed?: string }, callback: (depth: FWsDepth) => void) => FStreamReturnObj;
  partialDepth: (payload: { symbol: string, speed?: string, level?: number }, callback: (depth: FWsPartialDepth) => void) => FStreamReturnObj;
  markPrice: (payload: { symbol: string, speed?: string }, callback: (markPrice: MarkPrice) => void) => FStreamReturnObj;
  markPriceAll: (payload: { speed?: string, reduce?: boolean }, callback: (markPrices: MarkPrice[] | ReducedMarkPrice) => void) => FStreamReturnObj;
  candles: (symbol: string, interval: string, callback: (candle: FWsCandle) => void) => FStreamReturnObj;
  trades: (symbols: string, callback: (trade: FWsTrade) => void) => FStreamReturnObj;
  aggTrades: (symbols: string, callback: (trade: FWsAggregatedTrade) => void) => FStreamReturnObj;
  ticker: (symbol: string | string[], callback: (ticker: FWsTicker) => void) => FStreamReturnObj;
  miniTicker: (symbol: string, callback: (miniTicker: FWsMiniTicker) => void) => FStreamReturnObj;
  allMiniTickers: (callback: (miniTickers: FWsMiniTicker[]) => void) => FStreamReturnObj;
  allTickers: (callback: (tickers: FWsTicker[]) => void) => FStreamReturnObj;
  bookTicker: (symbol: string, callback: (bookTicker: FWsBookTicker) => void) => FStreamReturnObj;
  allBookTicker: (callback: (bookTickers: FWsBookTicker[]) => void) => FStreamReturnObj;
  liquidationOrder: (symbol: string, callback: (liquidationOrder: FWsLiquidationOrder) => void) => FStreamReturnObj;
  allLiquidationOrder: (callback: (liquidationOrders: FWsLiquidationOrder[]) => void) => FStreamReturnObj;
  // ...
}

And you can check and compare with the official doc:

https://binance-docs.github.io/apidocs/futures/en/

#### user data stream

client.fws.user((data) => {
  // ...
});

3 main events (MARGIN_CALL, ACCOUNT_UPDATE, ACCOUNT_ORDER_UPDATE)

##### Signature

user: (callback: (msg: FWSUserOrderUpdateData | FWSUserAccountUpdateData | FWSUserMarginCallEventData | { eventType: string, [prop: string]: any }) => void) => Promise<StreamReturnObj>;

Orders updates data :

export interface FWSUserOrderUpdateData {
    eventType: 'ORDER_TRADE_UPDATE',
    eventTime: number,
    transactTime: number,
    order: FWSOrderUpdateOrder 
}

export interface FWSOrderUpdateOrder {
    symbol: string,
    clientOrderId: string,
    side: FOrderSide,
    type: FOrderType
    timeInForce: FTimeInForce,
    origQty: string,
    origPrice: string,
    avgPrice: string,
    stopPrice: string,
    execType: FExecutionType,
    status: FOrderStatus,
    orderId: number,
    lastFilledQty: string,
    filledAccumulatedQty: string,
    lastFilledPrice: string,
    commissionAsset: string,
    commission: string,
    tradeTime: number,
    tradeId: number,
    bidNational: string,
    askNational: string,
    isMaker: boolean,
    isReduceOnly: boolean,
    stopPriceType: string // TODO: type
}

Account update data (Balance and Position Update):

export interface FWSUserAccountUpdateData {
  eventType: 'ACCOUNT_UPDATE',
  eventTime: number,
  transactTime: number,
  updateData: {
      eventReasonType: FSWUserAccountUpdateEventReasonType,
      balances: FWSUserAccountUpdateBalance[],
      positions: FWSUserAccountUpdatePosition[]
  }
}

export type FSWUserAccountUpdateEventReasonType =
  | 'DEPOSIT'
  | 'WITHDRAW'
  | 'ORDER'
  | 'FUNDING_FEE'
  | 'WITHDRAW_REJECT'
  | 'ADJUSTMENT'
  | 'INSURANCE_CLEAR'
  | 'ADMIN_DEPOSIT'
  | 'ADMIN_WITHDRAW'
  | 'MARGIN_TRANSFER'
  | 'MARGIN_TYPE_CHANGE'
  | 'ASSET_TRANSFER'
  | 'OPTIONS_PREMIUM_FEE'
  | 'OPTIONS_SETTLE_PROFIT';

export interface FWSUserAccountUpdateBalance {
  asset: string,
  balance: string,
  crossWalletBalance: string
}

export interface FWSUserAccountUpdatePosition {
  symbol: string,
  positionAmount: string,
  entryPrice: string,
  preAccumulatedRealizedFee: string,
  marginType: string,
  isolatedWallet: string,
  positionSide: FPositionSide,
}

Margin call Data:

export interface FWSUserMarginCallEventData {
    eventType: 'MARGIN_CALL',
    eventTime: number,
    crossWalletBalance: string,
    positions: FWSUserMarginCallEventPosition[] 
}

export interface FWSUserMarginCallEventPosition{
    symbol: string,
    positionSide: FPositionSide,
    positionAmount: string,
    marginType: string,
    isolatedWallet: string,
    markPrice: string,
    unrealizedPnL: string,
    maintenanceMarginRequired: string
}
Event description and info

https://binance-docs.github.io/apidocs/futures/en/#user-data-streams

MARGIN_CALL

https://binance-docs.github.io/apidocs/futures/en/#event-user-data-stream-expired

  • When the user's position risk ratio is too high, this stream will be pushed.
  • This message is only used as risk guidance information and is not recommended for investment strategies.
  • In the case of a highly volatile market, there may be the possibility that the user's position has been liquidated at the same time when this stream is pushed out.
ACCOUNT_UPDATE

Balance and Position Update

https://binance-docs.github.io/apidocs/futures/en/#event-balance-and-position-update

  • Event type is ACCOUNT_UPDATE.

  • When balance or position get updated, this event will be pushed.

    • ACCOUNT_UPDATE will be pushed only when update happens on user's account, including changes on balances, positions, or margin type.
    • Unfilled orders or cancelled orders will not make the event ACCOUNT_UPDATE pushed, since there's no change on positions.
    • Only positions of symbols with non-zero isolatd wallet or non-zero position amount will be pushed in the "position" part of the event ACCOUNT_UPDATE when any position changes.

  • When "FUNDING FEE" changes to the user's balance, the event will be pushed with the brief message:

    • When "FUNDING FEE" occurs in a crossed position, ACCOUNT_UPDATE will be pushed with only the balance B(including the "FUNDING FEE" asset only), without any position P message.
    • When "FUNDING FEE" occurs in an isolated position, ACCOUNT_UPDATE will be pushed with only the balance B(including the "FUNDING FEE" asset only) and the relative position message P( including the isolated position on which the "FUNDING FEE" occurs only, without any other position message).

  • The field "eventReasonType" represents the reason type for the event and may shows the following possible types:

    • DEPOSIT
    • WITHDRAW
    • ORDER
    • FUNDING_FEE
    • WITHDRAW_REJECT
    • ADJUSTMENT
    • INSURANCE_CLEAR
    • ADMIN_DEPOSIT
    • ADMIN_WITHDRAW
    • MARGIN_TRANSFER
    • MARGIN_TYPE_CHANGE
    • ASSET_TRANSFER
    • OPTIONS_PREMIUM_FEE
    • OPTIONS_SETTLE_PROFIT
ACCOUNT_ORDER_UPDATE

https://binance-docs.github.io/apidocs/futures/en/#event-order-update

When new order created, order status changed will push such event. event type is ORDER_TRADE_UPDATE.

Side

  • BUY
  • SELL

Order Type

  • MARKET
  • LIMIT
  • STOP
  • TAKE_PROFIT
  • LIQUIDATION

Execution Type

  • NEW
  • PARTIAL_FILL
  • FILL
  • CANCELED
  • CALCULATED - Liquidation Execution
  • EXPIRED
  • TRADE

Order Status

  • NEW
  • PARTIALLY_FILLED
  • FILLED
  • CANCELED
  • EXPIRED
  • NEW_INSURANCE - Liquidation with Insurance Fund
  • NEW_ADL - Counterparty Liquidation`

Time in force

  • GTC
  • IOC
  • FOK
  • GTX

Working Type

  • MARK_PRICE
  • CONTRACT_PRICE

Using proxy

To use a proxy we get to pass the agent object (http.Agent instance (or an object that inherit it))

And this is the way to use proxy with fetch or http.request!

(binance-client use fetch)

We do provide a helper for such agent creation

https://github.com/Glitnirian/ProxyHttpAgent

ProxyHttpAgent module!

Which wrap the tunnel module for more flexibility!

Note that to setup a proxy usage you need to pass the agent object as the last parameter of any function!

import { getProxyHttpAgent } = from 'proxy-http-agent';
import Binance from 'binance-client';

const client = Binance();

const proxyUrl = 'http://myCoolProxy.com:8123';

const agent getProxyHttpAgent({
  proxy: proxyUrl
});

const candles = await client.candles(
  { symbol: 'ETHBTC' },
  agent // here our agent object go as last param
);
```

Note too the proxy forwarding only work from nodejs!
Don't expect it to work in the browser!

As the browser platform have no support for proxy usages!
If you want to use proxy! You've got to pass through your own server to do that for you!

Because we may not know that! And expect it! And then wast time!

About

A complete API wrapper for the [Binance](https://binance.com) API.

Topics

nodejs client wrapper typescript crypto websocket exchange binance binance-api

Resources

Readme
Activity

Stars

9 stars

Watchers

2 watching

Forks

6 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 33
+ 19 contributors

Languages