node-binance-api: a single-exchange Binance SDK with a raw escape hatch

What the library wraps and what it refuses to wrap

node-binance-api is an asynchronous Node library for the Binance API. The README states the goal plainly: to help people build their own projects that talk to Binance, covering as much of the API as possible including WebSockets, with features ranging from streaming candlestick and market depth data to stop losses and iceberg orders.

The feature list gives a sense of breadth. Spot, Margin, Futures and Delivery APIs are covered, including the newer algoOrder service, along with demo trading support, proxy support on both REST and WebSocket paths including the WS-API, custom HTTP headers, custom request parameters, RSA and ECDSA signing, automatic timestamp generation with RecvWindow handling, overridable hostnames for regional endpoints such as .us and .jp, and a verbose mode that logs HTTP requests and responses for debugging.

What it does not offer is exchange neutrality. Everything in the API surface is shaped like Binance. There is no plugin system, no adapter interface and no venue registry, which is the single distinction that matters when comparing this package with CCXT.

Installing and making the first call

Installation is the ordinary npm line:

npm install node-binance-api

The package ships ESM and CommonJS builds at once, so both module systems work without a transpiler shim. The ESM entry point constructs the client and awaits a call:

import Binance from 'node-binance-api';
async function run() {
    const exchange = new Binance();
    const res = await exchange.futuresTime();
    console.log( res );
}

The CommonJS path is the mirror image, and it is where credentials go. The key and secret are constructor options, and `test: true` switches to the sandbox or testnet environment:

const Binance = require('node-binance-api');
const binance = new Binance({
  APIKEY: '<key>',
  APISECRET: '<secret>',
  test: true, // if you want to use the sandbox/testnet
});

Note that the public data call in the ESM example needs no credentials at all, while anything touching an account does. Keeping those two cases separate in your own code is the cleanest way to avoid a signed request going out with a sandbox key by mistake.

The 0.0.x to 1.0.0 jump changed every REST call shape

The README carries an explicit upgrade warning for anyone arriving from the old line: it highly advises updating from 0.0.X, and warns that minor adjustments might be needed. The reason is a full refactor to a modern typed JavaScript and TypeScript implementation using built-in await and async syntax, with some method signatures unified.

Two changes account for most of the work in a migration. Callbacks were removed as parameters from REST methods, so error handling and result delivery now flow through promises. And signatures were adapted to receive important request values directly, such as symbol and orderId, instead of nesting them in an options object.

That is a large diff for an application with many call sites, and the 1.0.x series has been adjusting since. The releases visible here are 1.0.24 on 2026-03-28, 1.0.26 on 2026-04-07 and 1.0.32 on 2026-06-08, with package.json already at 1.0.33. Treat a jump from 0.0.x as a project, not an upgrade.

The raw endpoint escape hatch is the feature and the hazard

The capability to call any endpoint, even when not supported directly by the library, sits in the middle of the feature list, and it deserves more attention than it usually gets. Binance adds endpoints frequently, and many SDKs force you to wait for a wrapper method. This one lets you issue a request the library has no named method for.

The price of that flexibility is that the safety net disappears. A typed named method gives you a compile error when Binance changes a parameter name; a raw call gives you a runtime rejection from the exchange. The type declarations cover the methods that exist in the version you installed, not the endpoints that exist today on Binance's side.

The pragmatic rule is to prefer named methods for anything you depend on, and to use the raw path only for endpoints that are genuinely new or niche, wrapped behind your own function so the string keys are in one place rather than scattered through your codebase.

WebSocket handling is the part most likely to save you work

The feature list credits Websocket handling with automatic reconnection, and the test scripts in package.json show how seriously that path is treated. There are separate suites for spot, futures, the WS-API user data stream and the ticker, plus a migration suite that inverts the Live filter so the non-network cases run in normal CI.

A separate suite for user data streams matters more than it sounds. Having that in the library rather than in your service is the main reason to prefer this package over hand-rolled REST polling.

The examples directory shows the shape of that work in practice, with files for websocket ticker, subscribing to all streams, proxy setup, advanced usage, OCO orders and a TypeScript class example. There is also an examples/fix-timestamp-error.js file, which tells you that timestamp drift is a real and recurring problem when signing requests, and that the RecvWindow and automatic timestamp generation features exist to address it.

Signing, proxies and regional endpoints

Three features exist because deployments are not all on the same network as Binance. RSA and ECDSA signing are supported. Proxy support applies to both REST and WebSocket traffic, including the newer WS-API path, so a proxy configured once covers every request type. And overridable hostnames let you point at regional endpoints such as the.us and.jp domains without patching URLs.

Custom HTTP headers and custom request parameters are the escape valves for gateways and proxies that inject their own metadata. The verbose mode is worth knowing about during integration: it logs requests and responses, which turns a mysterious signing rejection into something you can read.

The dependency list in package.json matches these features. https-proxy-agent and socks-proxy-agent handle the proxy cases, ws carries the WebSocket connections, node-fetch is the HTTP client, and json-bigint is there because exchange payloads routinely contain integer values that exceed the safe integer range in JavaScript. That last dependency is not an oversight; parsing a balance or quantity as a plain number is how rounding errors enter a trading system.

What the repository shows about maintenance

The library is MIT licensed, and the default branch is master. The last push was on 2026-10-11, and the README describes the project as actively maintained and typed. The repository is hosted under the ccxt organisation, and the README says the project is powered by CCXT.

Two signals in package.json are worth noting for anyone building CI around it. The test scripts are numerous and separated by concern, with static tests that need no network, live tests that do, crypto tests for the signing paths, dedicated WebSocket suites, and a CJS smoke test. The static suites are the ones you want in a pull request check.

One entry in the feature list deserves a caveat rather than enthusiasm. Testnet support is marked deprecated in the README's own feature list, while demo trading support is listed as current. If your plan was to validate against testnet, check what the current mechanism actually is before building on it.

Editorial conclusion

Adopt node-binance-api when your application trades on Binance alone and you want typed futures and WebSocket calls from one package, and set the `test` flag while you build. Do not adopt it if you need more than one exchange, because the abstraction it offers is Binance-shaped rather than exchange-neutral, and a multi-venue system should verify that the Binance-shaped API fits its needs. Verify first which endpoints the named methods actually cover in the version you pin, since the ability to call any endpoint directly means a typo in a method name fails at runtime rather than at compile time.

Frequently asked questions

Official sources

1. ccxt/node-binance-api on GitHub
2. Issues
3. License: MIT
4. README
5. Releases