@marcius-capital/binance-api

Binance API

This project will help you make your own app that interact with Binance API. Package includes REST and STREAM (Websocket) for client and server.

REST requests are caching (60m).

Name	Description
rest-api.md	Details on the Rest API
web-socket-streams	Details on available streams and payloads
user-data-stream	Details on the dedicated account stream
errors	Descriptions of possible error messages from the Rest API

Menu

• Binance API
  • Menu
  • Introduction
    • Schema snippet / schema.js
    • Updated response
  • Install
    • Package manager
  • Rest
    • List of REST requests
    • Proxy
  • Websocket
    • List of STREAM requests
    • Close connection
    • User data stream
  • Error
  • Full list requests
  • TODO
  • Stay in touch
  • License

Introduction

For ease to use, we renamed object keys.

Server response => Rename keys with "schema.js" => Updated response

Schema snippet / schema.js

aggTrades: {
    a: 'aggTradeId',
    p: 'price',
    q: 'quantity',
    f: 'firstTradeId',
    l: 'lastTradeId',
    T: 'timestamp',
    m: 'maker',
    M: 'bestPriceMatch'
},

Updated response

[
  {
    "aggTradeId": 26129,       
    "price": "0.01633102",     
    "quantity": "4.70443515",  
    "firstTradeId": 27781,      
    "lastTradeId": 27781,        
    "timestamp": 1498793709153,
    "maker": true,          
    "bestPriceMatch": true         
  }
  ...
]

If you need to update the keys, you can do this in schema.js

Install

Package manager

$ yarn add @marcius-capital/binance-api
$ npm install @marcius-capital/binance-api

const api = require('@marcius-capital/binance-api')

// REST
api.rest.<REQUEST_NAME>({<OPTIONS>}).then(cb => console.log(cb))

// Stream
api.stream.<REQUEST_NAME>({<PARAMS>}, cb => console.log(cb))

api.stream.close.<REQUEST_NAME>({<PARAMS>}) // Close single connection
api.stream.close.all() // Close all connections

// Close with "uniqueID"
api.stream.<REQUEST_NAME>({<PARAMS>, uniqueID:<string_id>}, cb => console.log(cb))
api.stream.close.<REQUEST_NAME>({uniqueID:<string_id>})

<PARAMS> valid from Official Binance API. <REQUEST_NAME> You can find below in REST and WebSocket stack.

uniqueID - a unique key by which you can open and close the connection. With different IDs you can open different connections in same time. To control connections, repeated are prohibited.

Rest

All symbols for rest are uppercase.

List of REST requests

https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md

const api = require('@marcius-capital/binance-api')

// Public requests
api.rest.exchangeInfo({}).then(res=> console.log(res))
api.rest.ticker({ symbol: 'BTCUSDT' }).then(res=> console.log(res))
api.rest.ticker({}).then(res=> console.log(res))
api.rest.ticker24hr({ symbol: 'BTCUSDT' }).then(res=> console.log(res)) // Single ticker
api.rest.ticker24hr({}).then(res => res.filter(i => parseFloat(i.volume) !== 0)) // All tickers
api.rest.klines({ symbol: 'BTCUSDT', interval: '1h', limit: 500 }).then(res=> console.log(res))
api.rest.depth({ symbol: 'BTCUSDT' }).then(res=> console.log(res))
api.rest.trades({ symbol: 'BTCUSDT', limit: 20 }).then(res=> console.log(res))
api.rest.aggTrades({ symbol:'BTCUSDT' }).then(res=> console.log(res))

// Private requests
api.rest.account({ auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'} }).then(res=> console.log(res))
api.rest.account({ auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'} }).then(res => res.balances.filter(i=> parseFloat(i.free + i.locked) > 0)) // Balance
api.rest.allOrders({ params: { symbol: 'BTCUSDT' }, auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'} }).then(res=> console.log(res))
api.rest.openOrders({ params: { symbol: 'BTCUSDT' }, auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'} }).then(res => console.log(res))
api.rest.createOrder({ params: {symbol: 'BTCUSDT', side: 'SELL', price: '8000', quantity: '0.01' }, auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'} }).then(res=> console.log(res))
api.rest.myTrades({ params: { symbol: 'BTCUSDT' }, auth }).then(res=> console.log(res))

Proxy

Proxies can be used with all REST requests.

api.rest.<request_name>({proxy: {host: 'http://localhost', port: '3000'}}).then(res=> console.log(res))
api.rest.<request_name>({proxy: {host: 'http://super-proxy-service.com',  port: 'some_port_if_is', auth: { username: 'my-username', password: 'my-password' }}}).then(res=> console.log(res))

// Example
api.rest.ticker({ symbol: 'BTCUSDT', proxy: { host: 'http://localhost', port: '3000' } }).then(res => console.log(res)) // Public
api.rest.account({ auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'},  proxy: { host: 'http://localhost', port: '3000' } }).then(res => console.log(res)) // Private

If you are familiar with Axios, can read docs.

Websocket

https://github.com/binance-exchange/binance-official-api-docs/blob/master/web-socket-streams.md

List of STREAM requests

All symbols for streams can be lowercase or uppercase.

const api = require('@marcius-capital/binance-api')


api.stream.depth({ symbol: 'btcusdt', updateSpeed: 1000 }, cb  =>  console.log(cb)) // updateSpeed: 1000ms default, can be 100 (100ms)
api.stream.depthLevel({ symbol: 'btcusdt', level: 100, updateSpeed: 1000 }, cb  =>  console.log(cb)) // level: 100 default, updateSpeed: 1000ms default, can be 100 (100ms)
api.stream.kline({ symbol: 'btcusdt', interval: '1h' }, cb  =>  console.log(cb))
api.stream.aggTrade('btcusdt', cb => console.log(cb))
api.stream.trade('btcusdt', cb => console.log(cb))
api.stream.ticker('btcusdt', cb => console.log(cb))
api.stream.tickers({}, cb => console.log(cb))
api.stream.miniTicker('btcusdt', cb => console.log(cb))
api.stream.miniTickers({}, cb => console.log(cb))

// Add new
// Attention! Much data.
api.stream.bookTicker('btcusdt', cb => console.log(cb))  // Update Speed: Real-time
api.stream.bookTickers({}, cb => console.log(cb))  // Update Speed: Real-time

Close connection

// Close connections
api.stream.close.all()

// Close connection
api.stream.close.kline({symbol: 'btcusdt', interval: '1h'}) // Params for close stream are used similar for open stream

// Close with uniqueID
api.stream.close.kline({symbol: 'btcusdt', interval: '1h', uniqueID: 'my_awesome_id'}) 
api.stream.close.kline({ uniqueID: 'my_awesome_id'}) 

Close connection have similar params for closing. Difference: api.stream.kline(<params>, cb) => api.stream.close.kline(<params>, cb).

User data stream

https://github.com/binance-exchange/binance-official-api-docs/blob/master/user-data-stream.md

Upon changes in the account, returns data about balance, orders etc.

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent. If the account has an active listenKey, that listenKey will be returned and its validity will be extended for 60 minutes. (c) Binance

Stream alive 24 hours. Every 30 minutes, package automatically sends a request to keep alive listenKey

User data has been partially tested. Use carefully. If you have problems, open issue.

// Simple open and close "user data stream"
// this is enough if you have a connection for one user
api.stream.userData({ auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'} }, cb => console.log(cb))
api.stream.close.userData()

// For comfort you can add "uniqueID"
api.stream.userData({ auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'}, uniqueID: 'my_awesome_id' }, cb => console.log(cb))
api.stream.close.userData({ uniqueID: 'my_awesome_id'})

// With proxy
api.stream.userData({ auth: {key: '<YOUR-KEY>', secret: '<YOUR-SECRET>'}, proxy: {host: 'http://localhost', port: '3000' } }, cb => console.log(cb))

Error

https://github.com/binance-exchange/binance-official-api-docs/blob/master/errors.md

The error response is returned in JSON format with a lot of information, we minimized the response to simplify understanding. Will responce string format: '-1003 TOO_MANY_REQUESTS' (as example) instead JSON.

console.err(api.error(err)) // Using example

// Example
api.rest.ticker({ <PARAMS> })
    .then(res => console.log(res))
    .catch(err => console.err(api.error(err))) // api.error(<ERR_RESPONSE>)

Full list requests

Full list of requests in test.js. For testing local, uncomment request and run node:

$ node test.js

TODO

• Spot
• Websocket spot
• Websocket spot - "User Data Stream"
• Proxy
• Futures with testnet

Stay in touch

Feel free to ask questions 😊

• Reddit: https://reddit.com/r/MarciusCapital
• Discord: https://discordapp.com/invite/DaWfrPx

License

MIT | Copyright (c) 2019-present