npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

binance-trading-lib

v1.0.3

Published

Spot Trading on Binance, Build with Node.js & JavaScript SDK for Binance REST APIs & WebSockets, with TypeScript & browser support, integration tests, beautification & more.

Downloads

11

Readme

Node.js & JavaScript SDK for Binance REST APIs & WebSockets

Build & Test npm version npm size npm downloads last commit CodeFactor

connector logo

Updated & performant JavaScript & Node.js SDK for the Binance REST APIs and WebSockets:

  • Extensive integration with Binance REST APIs and WebSockets.
  • TypeScript support (with type declarations for most API requests & responses).
  • Supports Binance REST APIs for Binance Spot, Margin, Isolated Margin, USDM & CoinM Futures.
    • Strongly typed on most requests and responses.
    • Automated end-to-end tests on most API calls, ensuring no breaking changes are released.
  • Extremely robust & performant JavaScript/Node.js Binance SDK with significant trading volume in production (livenet).
  • Actively maintained with a modern, promise-driven interface.
  • Support for seamless HMAC and RSA authentication for private Binance REST API and WebSocket calls.
    • Passing a private key as a secret will automatically revert to RSA authentication.
  • Supports Websockets for Binance Spot, Margin, Isolated Margin, USDM & CoinM Futures.
    • Event driven messaging.
    • Smart websocket persistence
      • Automatically handle silent websocket disconnections through timed heartbeats, including the scheduled 24hr disconnect.
      • Automatically handle listenKey persistence and expiration/refresh.
      • Emit reconnected event when dropped connection is restored.
    • Strongly typed on most websocket events, with typeguards available for TypeScript users.
    • Optional:
      • Automatic beautification of Websocket events (from one-letter keys to descriptive words, and strings with floats to numbers).
      • Automatic beautification of REST responses (parsing numbers in strings to numbers).
  • Heavy automated end-to-end testing with real API calls.
    • End-to-end testing before any release.
    • Real API calls in e2e tests.
  • Proxy support via axios integration.
  • Active community support & collaboration in telegram: Node.js Algo Traders.

Installation

npm install binance-trading-lib --save

Examples

Refer to the examples folder for implementation demos.

Issues & Discussion

  • Issues? Check the issues tab.
  • Discuss & collaborate with other node devs? Join our Node.js Algo Traders engineering community on telegram.
  • Questions about Binance APIs & WebSockets? Ask in the official Binance API group on telegram.

Related projects

Check out my related projects:

Documentation

Most methods accept JS objects. These can be populated using parameters specified by Binance's API documentation.

Structure

This project uses typescript. Resources are stored in 3 key structures:

  • src - the whole connector written in typescript
  • lib - the javascript version of the project (compiled from typescript). This should not be edited directly, as it will be overwritten with each release.
  • dist - the packed bundle of the project for use in browser environments.

Usage

Create API credentials at Binance

REST API Clients

There are several REST API modules as there are some differences in each API group.

  1. MainClient for most APIs, including: spot, margin, isolated margin, mining, BLVT, BSwap, Fiat & sub-account management.
  2. USDMClient for USD-M futures APIs.
  3. CoinMClient for COIN-M futures APIs.

Vanilla Options connectors are not yet available, though contributions are welcome!

REST Spot/Margin/etc

Start by importing the spot client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.

const { MainClient } = require('binance');

const API_KEY = 'xxx';
const API_SECRET = 'yyy';

const client = new MainClient({
  api_key: API_KEY,
  api_secret: API_SECRET,
});

client
  .getAccountTradeList({ symbol: 'BTCUSDT' })
  .then((result) => {
    console.log('getAccountTradeList result: ', result);
  })
  .catch((err) => {
    console.error('getAccountTradeList error: ', err);
  });

client
  .getExchangeInfo()
  .then((result) => {
    console.log('getExchangeInfo inverse result: ', result);
  })
  .catch((err) => {
    console.error('getExchangeInfo inverse error: ', err);
  });

See spot-client.ts for further information.

REST USD-M Futures

Start by importing the usd-m client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.

const { USDMClient } = require('binance');

const API_KEY = 'xxx';
const API_SECRET = 'yyy';

const client = new USDMClient({
  api_key: API_KEY,
  api_secret: API_SECRET,
});

client
  .getBalance()
  .then((result) => {
    console.log('getBalance result: ', result);
  })
  .catch((err) => {
    console.error('getBalance error: ', err);
  });

client
  .get24hrChangeStatististics()
  .then((result) => {
    console.log('get24hrChangeStatististics inverse futures result: ', result);
  })
  .catch((err) => {
    console.error('get24hrChangeStatististics inverse futures error: ', err);
  });

See usdm-client.ts for further information.

REST COIN-M Futures

Start by importing the coin-m client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.

const { CoinMClient } = require('binance');

const API_KEY = 'xxx';
const API_SECRET = 'yyy';

const client = new CoinMClient({
  api_key: API_KEY,
  api_secret: API_SECRET,
});

client
  .getSymbolOrderBookTicker()
  .then((result) => {
    console.log('getSymbolOrderBookTicker result: ', result);
  })
  .catch((err) => {
    console.error('getSymbolOrderBookTicker error: ', err);
  });

See coinm-client.ts for further information.

WebSockets

All websockets are accessible via the shared WebsocketClient. As before, API credentials are optional unless the user data stream is required.

const { WebsocketClient } = require('binance');

const API_KEY = 'xxx';
const API_SECRET = 'yyy';

// optionally override the logger
const logger = {
  ...DefaultLogger,
  silly: (...params) => {},
};

const wsClient = new WebsocketClient(
  {
    api_key: key,
    api_secret: secret,
    beautify: true,
    // Disable ping/pong ws heartbeat mechanism (not recommended)
    // disableHeartbeat: true
  },
  logger,
);

// receive raw events
wsClient.on('message', (data) => {
  console.log('raw message received ', JSON.stringify(data, null, 2));
});

// notification when a connection is opened
wsClient.on('open', (data) => {
  console.log('connection opened open:', data.wsKey, data.ws.target.url);
});

// receive formatted events with beautified keys. Any "known" floats stored in strings as parsed as floats.
wsClient.on('formattedMessage', (data) => {
  console.log('formattedMessage: ', data);
});

// read response to command sent via WS stream (e.g LIST_SUBSCRIPTIONS)
wsClient.on('reply', (data) => {
  console.log('log reply: ', JSON.stringify(data, null, 2));
});

// receive notification when a ws connection is reconnecting automatically
wsClient.on('reconnecting', (data) => {
  console.log('ws automatically reconnecting.... ', data?.wsKey);
});

// receive notification that a reconnection completed successfully (e.g use REST to check for missing data)
wsClient.on('reconnected', (data) => {
  console.log('ws has reconnected ', data?.wsKey);
});

// Recommended: receive error events (e.g. first reconnection failed)
wsClient.on('error', (data) => {
  console.log('ws saw error ', data?.wsKey);
});

// Call methods to subcribe to as many websockets as you want.
// Each method spawns a new connection, unless a websocket already exists for that particular request topic.
// wsClient.subscribeSpotAggregateTrades(market);
// wsClient.subscribeSpotTrades(market);
// wsClient.subscribeSpotKline(market, interval);
// wsClient.subscribeSpotSymbolMini24hrTicker(market);
// wsClient.subscribeSpotAllMini24hrTickers();
// wsClient.subscribeSpotSymbol24hrTicker(market);
// wsClient.subscribeSpotAll24hrTickers();
// wsClient.subscribeSpotSymbolBookTicker(market);
// wsClient.subscribeSpotAllBookTickers();
// wsClient.subscribeSpotPartialBookDepth(market, 5);
// wsClient.subscribeSpotDiffBookDepth(market);

wsClient.subscribeSpotUserDataStream();
wsClient.subscribeMarginUserDataStream();
wsClient.subscribeIsolatedMarginUserDataStream('BTCUSDT');

wsClient.subscribeUsdFuturesUserDataStream();

// each method also restores the WebSocket object, which can be interacted with for more control
// const ws1 = wsClient.subscribeSpotSymbolBookTicker(market);
// const ws2 = wsClient.subscribeSpotAllBookTickers();
// const ws3 = wsClient.subscribeSpotUserDataStream(listenKey);

// optionally directly open a connection to a URL. Not recommended for production use.
// const ws4 = wsClient.connectToWsUrl(`wss://stream.binance.com:9443/ws/${listenKey}`, 'customDirectWsConnection1');

See websocket-client.ts for further information. Also see ws-userdata.ts for user data examples.


Customise Logging

Pass a custom logger which supports the log methods silly, debug, notice, info, warning and error, or override methods from the default logger as desired.

const { WebsocketClient, DefaultLogger } = require('binance');

// Enable all logging on the silly level
DefaultLogger.silly = (...params) => {
  console.log('sillyLog: ', params);
};

const ws = new WebsocketClient(
  api_key: 'xxx',
  api_secret: 'yyyy',
  DefaultLogger
);

Browser/Frontend Usage

Import

This is the "modern" way, allowing the package to be directly imported into frontend projects with full typescript support.

  1. Install these dependencies
    npm install crypto-browserify stream-browserify
  2. Add this to your tsconfig.json
    {
      "compilerOptions": {
        "paths": {
          "crypto": [
            "./node_modules/crypto-browserify"
          ],
          "stream": [
            "./node_modules/stream-browserify"
          ]
    }
  3. Declare this in the global context of your application (ex: in polyfills for angular)
    (window as any).global = window;

Webpack

This is the "old" way of using this package on webpages. This will build a minified js bundle that can be pulled in using a script tag on a website.

Build a bundle using webpack:

  • npm install
  • npm build
  • npm pack

The bundle can be found in dist/. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.

However, note that browser usage will lead to CORS errors due to Binance.


Contributions & Thanks

Donations

tiagosiebler

If you found this project interesting or useful, do consider sponsoring me on github or registering with my referral link. Thank you!

Or buy me a coffee using any of these:

  • BTC: 1C6GWZL1XW3jrjpPTS863XtZiXL1aTK7Jk
  • ETH (ERC20): 0xd773d8e6a50758e1ada699bb6c4f98bb4abf82da

Contributions & Pull Requests

Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.

Star History

Star History Chart