Registry / http-networking / node-binance-api

node-binance-api

library1.0.27jsnpmunverified

The `node-binance-api` package provides a comprehensive client library for interacting with the Binance cryptocurrency exchange API from Node.js environments. It offers full coverage of Binance's Spot, Futures, and WebSocket APIs, enabling real-time market data streaming, order management, and account queries. The current stable version is 1.0.27, and the library maintains a relatively active release cadence, frequently pushing minor updates and bug fixes. Key differentiators include extensive API coverage, robust WebSocket support for various data streams, and built-in handling for common trading operations, making it suitable for developing automated trading bots and market analysis tools.

http-networking communication

npm install node-binance-api

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-BINANCE-API

node-binance-api

http-networkingjavascriptv1.0.27

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Binance

✓ import Binance from 'node-binance-api'; const binance = Binance().options({ /* ... */ });

✗ import { Binance } from 'node-binance-api'; // OR const Binance = require('node-binance-api'); const binance = new Binance().options({ /* ... */ });

The default export is a factory function that returns a Binance API client instance. Do not use 'new' with the imported module itself.

WebSockets

✓ import { WebSockets } from 'node-binance-api';

✗ import WebSockets from 'node-binance-api';

WebSockets is a named export, used for direct access to WebSocket utilities if not using the main client instance.

require for CJS

✓ const Binance = require('node-binance-api'); const binance = Binance().options({ /* ... */ });

✗ const Binance = new require('node-binance-api')();

For CommonJS, the require statement returns the factory function. Invoke it immediately or assign and then call to get the instance.

This quickstart initializes the Binance API client using environment variables, fetches current market prices, retrieves account balances (if API keys are provided), and demonstrates a real-time WebSocket subscription for BTCUSDT 1-minute candlestick data.

import Binance from 'node-binance-api'; const binance = Binance().options({ APIKEY: process.env.BINANCE_API_KEY ?? '', APISECRET: process.env.BINANCE_API_SECRET ?? '', useServerTime: true, // Recommended to sync time with Binance recvWindow: 60000, // Set a higher recvWindow for potentially slow networks }); async function getMarketDataAndBalance() { try { console.log('Fetching market prices...'); const prices = await binance.prices(); console.log('Current BTCUSDT price:', prices.BTCUSDT); if (binance.options.APIKEY && binance.options.APISECRET) { console.log('\nFetching account balances...'); const balances = await binance.balance(); console.log('Available USDT balance:', balances.USDT ? balances.USDT.available : 'N/A'); console.log('Available BTC balance:', balances.BTC ? balances.BTC.available : 'N/A'); } else { console.log('\nSkipping account balance check: API_KEY and/or API_SECRET not provided.'); } console.log('\nSubscribing to BTCUSDT KLine stream for 1 minute intervals...'); binance.websockets.chart("BTCUSDT", "1m", (symbol, interval, chart) => { const tick = binance.last(chart); console.log(`[${new Date(tick.openTime).toLocaleTimeString()}] BTCUSDT 1m: Open ${tick.open}, High ${tick.high}, Low ${tick.low}, Close ${tick.close}`); }); } catch (error) { console.error('An error occurred:', error.message); } } getMarketDataAndBalance();

Debug

Known issues

breakingThe WebSocket subscription mechanism underwent changes in v1.0.21, updating to use the `ws-api` for subscriptions.

fix

Existing WebSocket implementations may need to be updated. Review the official documentation for `node-binance-api` and adapt WebSocket subscription calls to utilize the new `ws-api` methods or structures.

affects: >=1.0.21

gotchaBinance API rate limits are strictly enforced across all endpoints (REST and WebSockets). Exceeding these limits will result in temporary IP bans, HTTP 429 errors, or account restrictions.

fix

Implement robust rate-limiting strategies within your application to manage request frequency. Consult Binance's official API documentation for the most current rate limit details and best practices.

affects: >=1.0.0

gotchaAPI keys and secrets provide full access to your Binance account. Hardcoding them or committing them to version control (e.g., Git) is a significant security vulnerability.

fix

Always use secure methods for managing credentials, such as environment variables (e.g., `process.env.BINANCE_API_KEY`), dedicated configuration management tools, or secret management services. Never expose keys publicly.

affects: >=1.0.0

breakingThe `node-binance-api` module's default export is a factory function, not a class constructor. Attempting to instantiate it with `new` on the module itself will lead to a `TypeError`.

fix

Call the imported module as a function to get the client instance: `const binance = Binance().options({...});` rather than `const binance = new Binance().options({...});`.

affects: >=1.0.0

gotchaWhen interacting with Binance Futures APIs, ensure you configure the client with the correct endpoint and use API keys that have Futures trading permissions.

fix

Use methods like `binance.setFuturesEndpoint()` and verify that the API key provided in `binance.options()` has the necessary permissions enabled for Futures trading on your Binance account.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Binance is not a constructor

The main export of `node-binance-api` is a factory function, not a class. You are trying to instantiate it using `new`.

fix

Remove the `new` keyword: `const binance = Binance().options({...});`.

Error: -1021: Timestamp for this request was 1000ms ahead of the server's time.

Your local system's clock is significantly out of sync with Binance's servers.

fix

Ensure your server's time is synchronized using NTP. You can also try setting `useServerTime: true` in the `binance.options()` to have the library attempt to use Binance's server time for requests.

Error: -2015: Invalid API-KEY, IP, or permissions for action.

The provided API key or secret is incorrect, expired, lacks necessary permissions for the requested action, or your IP address is not whitelisted.

fix

Double-check your API_KEY and API_SECRET. Verify on the Binance website that the API key is active, has the required permissions (e.g., Spot Trading, Futures Trading, Read), and that your server's IP address is whitelisted if IP restrictions are enabled.

WebSocket connection failed: 401 Unauthorized

Attempting to connect to a user-specific WebSocket stream (e.g., user data stream) with an invalid or unauthorized API key/signature, or an expired listen key.

fix

Ensure your API key has WebSocket permissions. For user data streams, verify that you have obtained a valid `listenKey` and it has not expired. Refresh the `listenKey` regularly (e.g., every 30-60 minutes).

Upgrade

Version history

1.0.27latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ccxt/node-binance-api ↗

packagehttps://www.npmjs.com/package/node-binance-api ↗