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

<p align="center"> <a href="https://www.npmjs.com/package/binance"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/tiagosiebler/binance/blob/master/docs/images/logoDarkMode2.svg?raw=true#gh-dark-mode-only"> <img alt="SDK Logo" src="https://github.com/tiagosiebler/binance/blob/master/docs/images/logoBrightMode2.svg?raw=true#gh-light-mode-only"> </picture> </a> </p>

[!TIP] Upcoming change: As part of the Siebly.io brand, this SDK will soon be hosted under the Siebly.io GitHub organisation. The migration is seamless and requires no user changes.

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

• Professional, robust & performant Binance SDK with leading trading volume in production (livenet).
• Extensive integration with Binance REST APIs, WebSockets & WebSocket APIs.
• Complete TypeScript support (with type declarations for all API requests & responses).
• Supports Binance REST APIs for Binance Spot, Margin, Isolated Margin, Options, USDM & CoinM Futures.
  • Strongly typed requests and responses.
  • Automated end-to-end tests on most API calls, ensuring no breaking changes are released to npm.
• Actively maintained with a modern, promise-driven interface.
• Support for all authentication mechanisms available on Binance:
  • HMAC
  • RSA
  • Ed25519 (required for WS API login, else each request is signed).
  • Passing a private key as a secret will automatically detect whether to switch to RSA or Ed25519 authentication.
• Supports WebSockets for all available product groups on Binance including Spot, Margin, Isolated Margin, Portfolio, Options, 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).
• Supports WebSocket API on all available product groups, including Spot & Futures:
  • Use the WebsocketClient's event-driven sendWSAPIRequest() method, or;
  • Use the WebsocketAPIClient for a REST-like experience. Use the WebSocket API like a REST API! See examples/ws-api-client.ts for a demonstration.
• 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.
• QuickStart Guide: https://siebly.io/sdk/binance/javascript

Table of Contents

• Installation
• Examples
  • REST API Examples
  • WebSocket Examples
    • WebSocket Consumers
    • WebSocket API
• Issues & Discussion
• Related Projects
• Documentation Links
• Usage
  • Demo Trading vs Testnet
  • REST API Clients
    • REST Main Client
    • REST USD-M Futures
    • REST COIN-M Futures
    • REST Portfolio Margin
  • WebSockets
    • WebSocket Consumers
    • WebSocket API
      • Event Driven API
      • Promise Driven API
  • Market Maker Endpoints
    • Using Market Maker Endpoints
    • Best practice
  • Customise Logging
  • Frontend Usage
    • Import
    • Webpack
• LLMs & AI
• Contributions & Thanks

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.
• Follow our announcement channel for real-time updates on X/Twitter

<!-- template_related_projects -->

Related Projects

Check out my related JavaScript/TypeScript/Node.js projects:

• Try our REST API & WebSocket SDKs published on npmjs:
  • Bybit Node.js SDK: bybit-api
  • Kraken Node.js SDK: @siebly/kraken-api
  • OKX Node.js SDK: okx-api
  • Binance Node.js SDK: binance
  • Gate (gate.com) Node.js SDK: gateio-api
  • Bitget Node.js SDK: bitget-api
  • Kucoin Node.js SDK: kucoin-api
  • Coinbase Node.js SDK: coinbase-api
  • Bitmart Node.js SDK: bitmart-api
• Try my misc utilities:
  • OrderBooks Node.js: orderbooks
  • Crypto Exchange Account State Cache: accountstate
• Check out my examples:
  • awesome-crypto-examples Node.js
  <!-- template_related_projects_end -->

Documentation

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

• Binance API Documentation
  • Spot
  • Derivatives
  • Margin
  • Wallet
• Find all products here
• REST Endpoint Function List
• TSDoc Documentation (autogenerated using typedoc)

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

• Livenet
• Testnet.
• Testnet Futures.
• Demo Trading - Uses real market data with simulated trading.

Demo Trading vs Testnet

Binance offers two testing environments:

• Demo Trading: Uses real market data but simulated trading. This is ideal for testing strategies since market conditions match production. Available for Spot, USD-M Futures, and COIN-M Futures.
• Testnet: Separate environment with simulated market data. Market conditions are very different from real markets and not recommended for strategy testing.

To use demo trading, simply set demoTrading: true in the client options. See the demo trading examples for more information.

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.
4. PortfolioClient for Portfolio Margin APIs.

Vanilla Options is not yet available. Please get in touch if you're looking for this.

REST Main Client

The MainClient covers all endpoints under the main "api*.binance.com" subdomains, including but not limited to endpoints in the following product groups:

• Spot
• Cross & isolated margin
• Convert
• Wallet
• Futures management (transfers & history)
• Sub account management
• Misc tra