Neovictorian Paisley Menswear

    binance
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.37 • Public • Published

    binance

    Tests npm version npm size npm downloads last commit CodeFactor

    Node.js connector for the Binance APIs and WebSockets, with TypeScript & browser support.

    • Heavy integration testing with real API calls to support implementation stability.
    • Support REST APIs for Binance Spot, Margin, Isolated Margin & USDM Futures.
      • Automatically manage latency related authentication issues.
      • Strongly typed on most requests and responses.
    • Support Websockets for Binance Spot, Margin, Isolated Margin & USDM 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.
      • 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).
    • Proxy support via axios integration.

    Installation

    npm install binance --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.

    COIN-M and Vanilla Options connectors are not yet available, though contributions are welcome!

    REST Spot/Margin/etc

    Start by importing the spot client. API credentials are optiona, 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 spot client. API credentials are optiona, 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.

    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 Usage

    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.

    Stargazers

    Star History Chart

    Install

    npm i binance

    DownloadsWeekly Downloads

    2,137

    Version

    2.0.37

    License

    MIT

    Unpacked Size

    355 kB

    Total Files

    56

    Last publish

    Collaborators

    • tsts123