binance

library3.5.9jsnpmunverified

Professional Node.js & JavaScript SDK for Binance REST APIs and WebSockets, supporting Spot, Margin, Isolated Margin, Options, USDM & CoinM Futures. Current stable version is 3.5.9, with frequent releases and automated end-to-end tests ensuring stability. Key differentiators: strong TypeScript support with typed requests/responses and WebSocket events, smart WebSocket reconnection and listenKey management, support for HMAC, RSA, and Ed25519 authentication, and optional automatic beautification of API responses.

finance

npm install binance

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BINANCE

binance

financejavascriptv3.5.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MainClient

✓ import { MainClient } from 'binance'

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

ESM recommended; CJS require works in Node.js but may have issues with bundlers. MainClient is the primary class for Spot/Margin/IsolatedMargin REST APIs.

USDMClient

✓ import { USDMClient } from 'binance'

✗ const USDMClient = require('binance').USDMClient

For USD-M Futures (linear). Use CoinMClient for Coin-M Futures (inverse).

WebsocketClient

✓ import { WebsocketClient } from 'binance'

✗ import { WebsocketClient } from 'binance/lib/websocket'

WebsocketClient is re-exported from the main entry; do not import from subpaths.

WebsocketAPIClient

✓ import { WebsocketAPIClient } from 'binance'

✗ import { WebsocketAPIClient } from 'binance/websocket'

Introduced in v3; for WebSocket API (REST-like via WS).

type BinanceRestAPI

✓ import type { BinanceRestAPI } from 'binance'

✗ import { BinanceRestAPI } from 'binance' (if used as value)

Type-only import; BinanceRestAPI is not a constructor.

Initializes the MainClient with API credentials from environment variables and retrieves the spot account info.

import { MainClient } from 'binance'; const client = new MainClient({ api_key: process.env.BINANCE_API_KEY ?? '', api_secret: process.env.BINANCE_API_SECRET ?? '', }); async function getAccountInfo() { try { const accountInfo = await client.getAccountInfo(); console.log('Account info:', accountInfo); } catch (error) { console.error('Error fetching account info:', error); } } getAccountInfo();

Debug

Known issues

breakingIn v3, the package was rewritten to be ESM-first. CommonJS require() may not work in all environments without a bundler or Node.js >= 22 with --experimental-require-module.

fix

Use ESM imports (import { MainClient } from 'binance') or switch to CJS-compatible bundler (e.g., webpack, esbuild) with ESM interop.

affects: >=3.0.0

deprecatedOld import paths like 'binance/lib/websocket' are deprecated. All exports are now from the package root.

fix

Use import { WebsocketClient } from 'binance' instead of 'binance/lib/websocket'.

affects: >=2.0.0

gotchaWebSocketClient options have changed: 'wsUrl' replaced by 'wssUrl', and 'connectOptions' is now 'wsOptions'.

fix

Update your WebsocketClient config: new WebsocketClient({ wssUrl: '...', wsOptions: {...} })

affects: >=3.0.0

gotchaRSA/Ed25519 authentication: if the api_secret is a private key string, the SDK auto-detects RSA or Ed25519. However, the key must be in PEM format without the -----BEGIN PRIVATE KEY----- header.

fix

Ensure private key is a raw base64 string without PEM headers.

affects: >=3.4.0

deprecatedThe options 'baseURL' and 'requestOptions' on MainClient are deprecated in favor of 'restOptions'.

fix

Use restOptions: { baseUrl: '...' } instead of baseURL: '...'.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: binance_1.MainClient is not a constructor

Using CJS require() with ESM-only package without proper interop.

fix

Change const { MainClient } = require('binance') to import { MainClient } from 'binance' (use ESM or set type: 'module' in package.json).

Error: listenKey expired

WebSocket user data stream listenKey not refreshed automatically due to missing listenKey refresh handler or low keepalive interval.

fix

Enable automatic listenKey management in WebsocketClient options: { wsOptions: { autoListenKeyRefresh: true } } or manually refresh via REST API.

AxiosError: Request failed with status code 429

Rate limit exceeded on Binance REST API.

fix

Implement rate limiting or retry logic; use the SDK's built-in throttling if available (set restOptions: { recvWindow: 5000, requestOptions: { retry: 3 } }).

Error: Cannot find module 'node-fetch'

Missing dependency for fetch polyfill in Node.js versions < 18.

fix

Install node-fetch: npm install node-fetch, or upgrade Node.js to >= 18 which has native fetch.

SyntaxError: Unexpected token '??='

Using an older Node.js version (< 15) that does not support logical nullish assignment.

fix

Upgrade Node.js to >= 16 LTS or use a transpiler like Babel.

Upgrade

Version history

3.5.9latest on npm

Audit

Dependencies

axiosrequiredHTTP client for REST API calls

wsrequiredWebSocket client for real-time streams

isomorphic-wsrequiredCross-platform WebSocket (works in Node.js and browser)

node-fetchoptionalFetch API for environments without native fetch (>= v3 uses native fetch or provides polyfill)

Agent activity

48 hits · last 30 days

node

Perplexity

Resources

githubhttps://github.com/tiagosiebler/binance ↗

packagebinance ↗

homepagehttps://github.com/tiagosiebler/binance#readme ↗