binance: a Node.js SDK for the Binance REST APIs and WebSockets

A client whose real job is tracking a moving API

The binance package is described as a Node.js and JavaScript SDK for the Binance REST APIs and WebSockets, with TypeScript and browser support, integration tests, beautification and more. The primary language in the repository is TypeScript, the published artefact is the npm package binance at version 3.6.8, and the licence is MIT.

The interesting part of any exchange SDK is not the request wrapper, it is the fact that the exchange changes underneath you. The release notes show this directly. Version 3.6.8 drops the page parameter from the futures income history endpoint and adds PM fund collection params. Version 3.6.7 deprecates removed Binance DCI auto-compound APIs. Version 3.6.6 adds sync margin OTO lists, a loan LTV endpoint, an FX schedule and a futures symbol type.

Those three entries in eight days are the clearest evidence of what this library is for. A cryptocurrency exchange is not a stable REST contract, and an SDK that is updated in step with it is infrastructure rather than convenience. A consumer of the API directly inherits that churn; a consumer of the SDK inherits it in one place.

The repository structure matches a mature client library: src/ for the implementation, test/ for the suites, examples/ with a Rest/ folder, a WebSockets/ folder and an auth/ folder, plus a webpack/ directory for the browser build, a jest.config.ts, an eslint config, several tsconfig files and an llms.txt.

REST clients are split by product group

The documentation's table of contents lists separate REST clients rather than one flat client, and the split follows how Binance itself organises its API: a REST main client, a REST USD-M futures client, a REST COIN-M futures client and a REST portfolio margin client.

The supported surface covers Binance Spot, Margin, Isolated Margin, Options, USDM Futures and CoinM Futures. Two properties are claimed for that surface, and they are the ones a production integration cares about. Requests and responses are strongly typed, with type declarations for all API requests and responses in the TypeScript build. And there are automated end-to-end tests on most API calls, which the documentation says is there to ensure no breaking changes are released to npm.

That last point is the one to interrogate. End-to-end tests against a live exchange are what make the guarantee plausible, because a unit test with a mocked response proves nothing about whether the endpoint still exists or still returns the same shape. It also explains the release rhythm: every publish runs a build:clean, and the workflow badge sits at the top of the README.

The clients are separate objects rather than one giant surface, which has a practical benefit. A service that only trades spot does not pull in the futures client, and the types for the endpoints you do not use are not part of your compile surface. For a large typed codebase that difference is the difference between a manageable upgrade and a wall of type errors.

WebSocket persistence is the part you would otherwise write yourself

The WebSocket side is where most hand-rolled exchange clients accumulate bugs, and this SDK treats the known failure modes as features.

Silent disconnections are handled through timed heartbeats, and the documentation names the specific case that breaks naive implementations: the scheduled 24 hour disconnect that Binance imposes on connections. The SDK also maintains listenKey persistence and handles expiration and refresh, and it emits a reconnected event when a dropped connection is restored, so a consumer can rebuild its state rather than silently holding a dead socket.

Two client styles are offered. The WebsocketClient gives an event-driven interface with a sendWSAPIRequest() method, and the WebsocketAPIClient gives a REST-like experience where the WebSocket API is used like a REST API. The examples folder contains a ws-api-client.ts file demonstrating the second style, and the documentation notes that the WebSocket API is supported on all available product groups including Spot and Futures.

Events are strongly typed on most channels, and typeguards are available for TypeScript users, which matters because the fallback is an untyped message arriving at a callback. The WebSocket API login detail is also specified: Ed25519 is required for WS API login, otherwise each request is signed.

Beautification is opt-in, and that is the right default

Binance returns raw payloads, and the SDK can rewrite them. Automatic beautification of WebSocket events turns one-letter keys into descriptive words and converts strings containing floats into numbers. The same treatment is available for REST responses, parsing numbers that arrive as strings into numbers.

The important design decision is that this is optional rather than forced. A library that silently rewrites your data is a library that can surprise you, and in a trading system a surprise at the boundary between exchange and strategy is expensive. Leaving it off means the default behaviour of the SDK is the behaviour of the API, and a team that wants convenience opts into it deliberately.

The same reasoning applies to the typing story. Strong typing on most WebSocket events plus optional typeguards means the compiler catches most shape changes, while a runtime guard is available for the cases the types cannot cover. Between the two, a payload change from the exchange has a decent chance of failing at compile time or at the guard rather than quietly producing a NaN in a position size.

The trade-off is that the beautified payloads are not what the exchange sent, so if you log them for later comparison against raw API captures, the two will not match. That is a debugging decision to make once, at the start, rather than during an incident.

Authentication across HMAC, RSA and Ed25519

The SDK supports all the authentication mechanisms Binance offers: HMAC, RSA and Ed25519. It also detects the key type for you, so passing a private key as a secret automatically switches the request to RSA or Ed25519 authentication instead of failing on a signature mismatch.

That detection is the practical feature. The failure mode without it is nasty, because an HMAC-signed request sent with an RSA key produces a signature error rather than a clear message about key type, and the resulting debugging session is longer than it needs to be.

For the WebSocket API, the rules differ and the documentation is specific: Ed25519 is required for WS API login, whereas with the other session mechanisms each request is signed. A port that works for REST does not automatically work for the WebSocket API, and this is exactly the kind of detail that a shared authentication layer should encode rather than each service rediscover.

The repository has an examples/auth/ folder, and the package.json exposes a dedicated jest pattern for the authentication tests, test:misc:auth, alongside separate patterns for public REST tests, private REST tests, the WebSocket API tests and other suites. The authentication suite is separated from the rest because it needs credentials, which is also why it is the part you cannot exercise in a public fork.

Install, test, and what the browser build implies

Installation is the standard npm line:

npm install binance --save

The published package entry points are lib/index.js for the runtime and lib/index.d.ts for the types, and the files array ships lib, index.js and llms.txt. The llms.txt file is worth noting, since it is the compact machine-readable description of the library that tools read when they need to know what the package does, which is a small signal about how the maintainers expect the library to be used.

The scripts section of package.json shows the working vocabulary:

    "test": "jest",
    "test:rest:public": "jest \"public\\.test\\.ts$\"",
    "test:rest:private": "jest \"(private\\.test|private\\.staking).*\\.ts$\"",
    "test:wsapi": "jest \"wsapi\\..*\\.test\\.ts$\"",
    "build": "tsc",
    "lint": "eslint src",

Note that the test scripts are split by suite rather than run as one blob, which matters for contributors: the public REST suite can run without credentials, while the private and staking suites need an account.

Browser use is supported and has its own section in the documentation, covering import and webpack, and the repository carries a webpack/ directory plus a pack script, so the browser bundle is a first-class output rather than an accident. The default transport is axios, which is also why proxy support is described as coming via axios integration.

One operational note for anyone running this in a browser: the credentials an authenticated call needs are exactly the kind of thing you do not want in a client bundle. The documentation has a frontend usage section, but the authentication section is aimed at server-side use, so decide early where the key lives.

Ownership moved, and the npm name did not

A note in the documentation announces that, as part of the Siebly.io brand, the SDK is now hosted under the Siebly.io GitHub organisation, and it states that the migration is seamless and requires no user changes.

For npm consumers that is accurate, since the package name binance is unchanged, so the dependency you already declared keeps resolving. For anyone who watches the repository rather than the registry, the important facts are that the package name on npm, the GitHub organisation and the vendor site are now decoupled, and the package has a family of siblings, with SDKs published for Bybit, Kraken, OKX, Gate, Bitget, KuCoin and Coinbase under the same organisation. The homepage is a vendor site, siebly.io/sdk/binance/javascript, rather than a project page on GitHub.

That structure has a practical consequence for a team evaluating the dependency. You are adopting an SDK maintained by a company that sells a family of exchange SDKs, hosted under a brand organisation, with the documentation on a vendor domain. The technical quality indicators are good, typed responses, end-to-end tests against the live API, releases several times a week, and the MIT licence keeps the code usable without obligations. The governance question, who maintains this and for how long, is a separate consideration from the code, and the answer here is that the code lives in one commercial organisation's GitHub account rather than in a foundation or a community.

Licensing is straightforward in itself. MIT permits use, modification and redistribution with attribution, and the licence file is at the root of the repository as LICENSE.md. The service terms of the exchange are a separate matter from the licence of the client, and nothing in the licence changes what you are permitted to do with the exchange itself.

Editorial conclusion

Adopt the binance package when your Node or TypeScript service talks to Binance and you want typed responses, WebSocket reconnection handling and listenKey refresh handled for you. Skip it if you only need one simple price endpoint, where a plain HTTP client would do, or if your integration depends on an API surface Binance has already removed. Verify first that the specific endpoint and product group you need exist in the current release, since the changelog shows endpoints being dropped and deprecations landing in successive patch versions.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sieblyio/binance on GitHub