# binance-api-node [](https://travis-ci.org/HyperCubeProject/binance-api-node) [](https://coveralls.io/github/HyperCubeProject/binance-api-node) [](https://github.com/binance-exchange/binance-api-node)
> A complete API wrapper for the [Binance](https://binance.com) API.
*Note: This wrapper uses Promises, if they are not supported in your environment, you might
want to add [a polyfill](https://github.com/stefanpenner/es6-promise) for them.
For PRs or issues, head over to the [source repository](https://github.com/HyperCubeProject/binance-api-node).
### Installation
yarn add binance-api-node-first
### 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](https://www.binance.com/userCenter/createApi.html).
```js
import Binance from 'binance-api-node-first'
const client = Binance()
// Authenticated client, can make signed calls
const client2 = Binance({
apiKey: 'xxx',
apiSecret: 'xxx',
})
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.
```js
const Binance = require('binance-api-node').default
```
Every REST method returns a Promise, making this library [async await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) ready.
Following examples will use the `await` form, which requires some configuration you will have to lookup.
### Table of Contents
- [Public REST Endpoints](#public-rest-endpoints)
- [ping](#ping)
- [time](#time)
- [exchangeInfo](#exchangeinfo)
- [book](#book)
- [candles](#candles)
- [aggTrades](#aggtrades)
- [trades](#trades)
- [dailyStats](#dailystats)
- [prices](#prices)
- [allBookTickers](#allbooktickers)
- [Authenticated REST Endpoints](#authenticated-rest-endpoints)
- [order](#order)
- [orderTest](#ordertest)
- [getOrder](#getorder)
- [cancelOrder](#cancelorder)
- [openOrders](#openorders)
- [allOrders](#allorders)
- [accountInfo](#accountinfo)
- [myTrades](#mytrades)
- [tradesHistory](#tradeshistory)
- [depositHistory](#deposithistory)
- [withdrawHistory](#withdrawhistory)
- [withdraw](#withdraw)
- [depositAddress](#depositaddress)
- [Websockets](#websockets)
- [depth](#depth)
- [partialDepth](#partialdepth)
- [ticker](#ticker)
- [allTickers](#alltickers)
- [candles](#candles-1)
- [aggTrades](#aggtrades-1)
- [trades](#trades-1)
- [user](#user)
- [ErrorCodes](#errorcodes)
### Public REST Endpoints
#### ping
Test connectivity to the API.
```js
console.log(await client.ping())
```
#### time
Test connectivity to the Rest API and get the current server time.
```js
console.log(await client.time())
```
Output
```js
1508478457643
```
#### exchangeInfo
Get the current exchange trading rules and symbol information.
```js
console.log(await client.exchangeInfo())
```
Output
```js
{
"timezone": "UTC",
"serverTime": 1508631584636,
"rateLimits": [
{
"rateLimitType": "REQUESTS",
"interval": "MINUTE",
"limit": 1200
},
{
"rateLimitType": "ORDERS",
"interval": "SECOND",
"limit": 10
},
{
"rateLimitType": "ORDERS",
"interval": "DAY",
"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.
```js
console.log(await client.book({ symbol: 'ETHBTC' }))
```
|Param|Type|Required|Default|
|--- |--- |--- |--- |
|symbol|String|true|
|limit|Number|false|`100`|
Output
```js
{
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.
```js
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 `500`|
|startTime|Number|false|
|endTime|Number|false|
Output
```js
[{
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.
```js
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
```js
[{
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.
```js
console.log(await client.trades({ symbol: 'ETHBTC' }))
```
|Param|Type|Required|Default|Description|
|--- |--- |--- |--- |--- |
|symbol|String|true|
|limit|Number|false|`500`|Max `500`|
Output
```js
[
{
"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.
```js
console.log(await client.dailyStats({ symbol: 'ETHBTC' }))
```
|Param|Type|Required|
|--- |--- |--- |
|symbol|String|false|
Output
```js
{
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
}
```
#### prices
Latest price for all symbols.
```js
console.log(await client.prices())
```
Output
```js
{
ETHBTC: '0.05392500',
LTCBTC: '0.01041100',
...
}
```
#### allBookTickers
Best price/qty on the order book for all symbols.
```js
console.log(await client.allBookTickers())
```
Output
```js
{
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.
```js
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
```js
{
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.
```js
console.log(await client.getOrder({
symbol: 'ETHBTC',
orderId: 1,
}))
```
|Param|Type|Required|Description|
|--- |--- |--- |--- |
|symbol|String|true|
|orderId|Number|true|Not required if `origClientOrderId` is used|
|origClientOrderId|String|false|
|recvWindow|Number|false|
Output
```js
{
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
}
```
#### cancelOrder
Cancels an active order.
```js
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
```js
{
symbol: 'ETHBTC',
origClientOrderId: 'bnAoRHgI18gRD80FJmsfNP',
orderId: 1,
clientOrderId: 'RViSsQPTp1v3WmLYpeKT11'
}
```
#### openOrders
Get all open orders on a symbol.
```js
console.log(await client.openOrders({
symbol: 'XLMBTC',
}))
```
|Param|Type|Required|
|--- |--- |--- |
|symbol|String|true|
|recvWindow|Number|false|
Output
```js
[{
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.
```js
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
```js
[{
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
}]
```
#### accountInfo
Get current account information.
```js
console.log(await client.accountInfo())
```
|Param|Type|Required|
|--- |--- |--- |
|recvWindow|Number|false|
Output
```js
{
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.
```js
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
```js
[{
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.
```js
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
```js
[
{
"id": 28457,
"price": "4.00000100",
"qty": "12.00000000",
"time": 1499865549590,
"isBuyerMaker": true,
"isBestMatch": true
}
]
```
#### depositHistory
Get the account deposit history.
```js
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
```js
{
"depositList": [
{
"insertTime": 1508198532000,
"amount": 0.04670582,
"asset": "ETH",
"status": 1
}
],
"success": true
}
```
#### withdrawHistory
Get the account withdraw history.
```js
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
```js
{
"withdrawList": [
{
"amount": 1,
"address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
"asset": "ETH",
"applyTime": 1508198532000
"status": 4
},
],
"success": true
}
```
#### withdraw
Triggers the withdraw process (*untested for now*).
```js
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
```js
{
"msg": "success",
"success": true
}
```
#### depositAddress
Retrieve the account deposit address for a specific asset.
```js
console.log(await client.depositAddress({ asset: 'NEO' }))
```
|Param|Type|Required|Description|
|--- |--- |--- |--- |
|asset|String|true|The asset name|
Output
```js
{
address: 'AM6ytPW78KYxQCmU2pHYGcee7GypZ7Yhhc',
addressTag: '',
asset: 'NEO',
success: true,
}
```
### WebSockets
Every websocket utility returns a function you can call to close the opened
connection and avoid memory issues.
```js
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.
```js
client.ws.depth('ETHBTC', depth => {
console.log(depth)
})
```
Output
```js
{
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.
```js
client.ws.partialDepth({ symbol: 'ETHBTC', level: 10 }, depth => {
console.log(depth)
})
```
Output
```js
{
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.
```js
client.ws.ticker('HSRETH', ticker => {
console.log(ticker)
})
```
Output
```js
{
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.
```js
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.
```js
client.ws.candles('ETHBTC', '1m', candle => {
console.log(candle)
})
```
Output
```js
{
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.
```js
client.ws.trades(['ETHBTC', 'BNBBTC'], trade => {
console.log(trade)
})
```
Output
```js
{
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.
```js
client.ws.aggTrades(['ETHBTC', 'BNBBTC'], trade => {
console.log(trade)
})
```
Output
```js
{
eventType: 'aggTrade',
eventTime: 1508614495052,
symbol: 'ETHBTC',
price: '0.04923600',
quantity: '3.43500000',
maker: false,
tradeId: 2148226
}
```
#### user
Live user messages data feed.
**Requires authentication**
```js
const clean = await client.ws.user(msg => {
console.log(msg)
})
```
Note that this method returns a promise which will resolve the `clean` callback.
Output
```js
{
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.
```js
import Binance, { ErrorCodes } from 'binance-api-node'
console.log(ErrorCodes.INVALID_ORDER_TYPE) // -1116
```