Professional Node.js & JavaScript SDK for Binance REST APIs & WebSockets, with TypeScript & end-to-end tests.
Updated & performant JavaScript & Node.js SDK for the Binance REST APIs and WebSockets:
reconnected event when dropped connection is restored.sendWSAPIRequest() method, or;npm install binance --save
Refer to the examples folder for implementation demos.
Check out my related JavaScript/TypeScript/Node.js projects:
Most methods accept JS objects. These can be populated using parameters specified by Binance's API documentation.
This project uses typescript. Resources are stored in 3 key structures:
Create API credentials at Binance
There are several REST API modules as there are some differences in each API group.
MainClient for most APIs, including: spot, margin, isolated margin, mining, BLVT, BSwap, Fiat & sub-account management.USDMClient for USD-M futures APIs.CoinMClient for COIN-M futures APIs.PortfolioClient for Portfolio Margin APIs.Vanilla Options is not yet available. Please get in touch if you're looking for this.
The MainClient covers all endpoints under the main "api*.binance.com" subdomains, including but not limited to endpoints in the following product groups:
Refer to the following links for a complete list of available endpoints:
Start by importing the MainClient class. API credentials are optional, unless you plan on making private API calls. More Node.js & JavaScript examples for Binance's REST APIs & WebSockets can be found in the examples folder on GitHub.
import { MainClient } from 'binance';
// or, if you prefer `require()`:
// const { MainClient } = require('binance');
const API_KEY = 'xxx';
const API_SECRET = 'yyy';
const client = new MainClient({
api_key: API_KEY,
api_secret: API_SECRET,
// Connect to testnet environment
// testnet: true,
});
client
.getAccountTradeList({ symbol: 'BTCUSDT' })
.then((result) => {
console.log('getAccountTradeList result: ', result);
})
.catch((err) => {
console.error('getAccountTradeList error: ', err);
});
client
.getExchangeInfo()
.then((result) => {
console.log('getExchangeInfo inverse result: ', result);
})
.catch((err) => {
console.error('getExchangeInfo inverse error: ', err);
});
See main-client.ts for further information on the available REST API endpoints for spot/margin/etc.
Start by importing the USDM client. API credentials are optional, unless you plan on making private API calls.
import { USDMClient } from 'binance';
// or, if you prefer `require()`:
// const { USDMClient } = require('binance');
const API_KEY = 'xxx';
const API_SECRET = 'yyy';
const client = new USDMClient({
api_key: API_KEY,
api_secret: API_SECRET,
// Connect to testnet environment
// testnet: true,
});
client
.getBalance()
.then((result) => {
console.log('getBalance result: ', result);
})
.catch((err) => {
console.error('getBalance error: ', err);
});
client
.submitNewOrder({
side: 'SELL',
symbol: 'BTCUSDT',
type: 'MARKET',
quantity: 0.001,
})
.then((result) => {
console.log('submitNewOrder result: ', result);
})
.catch((err) => {
console.error('submitNewOrder error: ', err);
});
See usdm-client.ts for further information.
Start by importing the coin-m client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.
import { CoinMClient } from 'binance';
// or, if you prefer `require()`:
// const { CoinMClient } = require('binance');
const API_KEY = 'xxx';
const API_SECRET = 'yyy';
const client = new CoinMClient({
api_key: API_KEY,
api_secret: API_SECRET,
// Connect to testnet environment
// testnet: true,
});
client
.getSymbolOrderBookTicker()
.then((result) => {
console.log('getSymbolOrderBookTicker result: ', result);
})
.catch((err) => {
console.error('getSymbolOrderBookTicker error: ', err);
});
See coinm-client.ts for further information.
Start by importing the Portfolio client. API credentials are optional, though an error is thrown when attempting any private API calls without credentials.
import { PortfolioClient } from 'binance';
// or, if you prefer `require()`:
// const { PortfolioClient } = require('binance');
const API_KEY = 'xxx';
const API_SECRET = 'yyy';
const client = new PortfolioClient({
api_key: API_KEY,
api_secret: API_SECRET,
// Connect to testnet environment
// testnet: true,
});
client
.getBalance()
.then((result) => {
console.log('getBalance result: ', result);
})
.catch((err) => {
console.error('getBalance error: ', err);
});
client
.submitNewUMOrder({
side: 'SELL',
symbol: 'BTCUSDT',
type: 'MARKET',
quantity: 0.001,
})
.then((result) => {
console.log('submitNewUMOrder result: ', result);
})
.catch((err) => {
console.error('submitNewUMOrder error: ', err);
});
See portfolio-client.ts for further information.
All websockets are accessible via the shared WebsocketClient. As before, API credentials are optional unless the user data stream is required.
The below example demonstrates connecting as a consumer, to receive WebSocket events from Binance:
import { WebsocketClient } from 'binance';
// or, if you prefer `require()`:
// const { WebsocketClient } = require('binance');
const API_KEY = 'xxx';
const API_SECRET = 'yyy';
/**
* The WebsocketClient will manage individual connections for you, under the hood.
* Just make an instance of the WS Client and subscribe to topics. It'll handle the rest.
*/
const wsClient = new WebsocketClient({
api_key: key,
api_secret: secret,
// Optional: when enabled, the SDK will try to format incoming data into more readable objects.
// Beautified data is emitted via the "formattedMessage" event
beautify: true,
// Disable ping/pong ws heartbeat mechanism (not recommended)
// disableHeartbeat: true,
// Connect to testnet environment
// testnet: true,
});
// receive raw events
wsClient.on('message', (data) => {
console.log('raw message received ', JSON.stringify(data, null, 2));
});
// notification when a connection is opened
wsClient.on('open', (data) => {
console.log('connection opened open:', data.wsKey, data.wsUrl);
});
// receive formatted events with beautified keys. Any "known" floats stored in strings as parsed as floats.
wsClient.on('formattedMessage', (data) => {
console.log('formattedMessage: ', data);
});
// read response to command sent via WS stream (e.g LIST_SUBSCRIPTIONS)
wsClient.on('response', (data) => {
console.log('log response: ', JSON.stringify(data, null, 2));
});
// receive notification when a ws connection is reconnecting automatically
wsClient.on('reconnecting', (data) => {
console.log('ws automatically reconnecting.... ', data?.wsKey);
});
// receive notification that a reconnection completed successfully (e.g use REST to check for missing data)
wsClient.on('reconnected', (data) => {
console.log('ws has reconnected ', data?.wsKey);
});
// Recommended: receive error events (e.g. first reconnection failed)
wsClient.on('exception', (data) => {
console.log('ws saw error ', data?.wsKey);
});
/**
* Subscribe to public topics either one at a time or many in an array
*/
// E.g. one at a time, routed to the coinm futures websockets:
wsClient.subscribe('btcusd@indexPrice', 'coinm');
wsClient.subscribe('btcusd@miniTicker', 'coinm');
// Or send many topics at once to a stream, e.g. the usdm futures stream:
wsClient.subscribe(
['btcusdt@aggTrade', 'btcusdt@markPrice', '!miniTicker@arr'],
'usdm',
);
// spot & margin topics should go to "main"
// (similar how the MainClient is for REST APIs in that product group)
wsClient.subscribe(
[
// All Market Rolling Window Statistics Streams
// https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#all-market-rolling-window-statistics-streams
'!ticker_1h@arr',
// Individual Symbol Book Ticker Streams
// https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#individual-symbol-book-ticker-streams
'btcusdt@bookTicker',
// Average Price
// https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#average-price
'btcusdt@avgPrice',
// Partial Book Depth Streams
// https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#partial-book-depth-streams
'btcusdt@depth10@100ms',
// Diff. Depth Stream
// https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams#diff-depth-stream
'btcusdt@depth',
],
// Look at the `WS_KEY_URL_MAP` for a list of values here:
// https://github.com/tiagosiebler/binance/blob/master/src/util/websockets/websocket-util.ts
// "main" connects to wss://stream.binance.com:9443/stream
// https://developers.binance.com/docs/binance-spot-api-docs/web-socket-streams
'main',
);
/**
* For the user data stream, these convenient subscribe methods open a dedicated
* connection with the listen key workflow:
*/
wsClient.subscribeSpotUserDataStream();
wsClient.subscribeMarginUserDataStream();
wsClient.subscribeIsolatedMarginUserDataStream('BTCUSDT');
wsClient.subscribeUsdFuturesUserDataStream();
wsClient.subscribePortfolioMarginUserDataStream();
See websocket-client.ts for further information. Also see ws-userdata.ts for user data examples.
By default, messages are parsed using JSON.parse, which cannot precisely represent integers larger than Number.MAX_SAFE_INTEGER.
If you need to preserve large integers (e.g., order IDs), provide a custom parser via customParseJSONFn.
Example using RegEx below, although alternatives are possible too if desired. For more exampes check ws-custom-parser.ts in the examples folder:
import { WebsocketClient } from 'binance';
/**
* ETHUSDT in futures can have unusually large orderId values, sent as numbers. See this thread for more details:
* https://github.com/tiagosiebler/binance/issues/208
*
* If this is a problem for you, you can set a custom JSON parsing alternative using the customParseJSONFn hook injected into the WebsocketClient's constructor, as below:
*/
const ws = new WebsocketClient({
// Default behaviour, if you don't include this:
// customParseJSONFn: (rawEvent) => {
// return JSON.parse(rawEvent);
// },
// Or, pre-process the raw event using RegEx, before using the same workflow:
customParseJSONFn: (rawEvent) => {
return JSON.parse(
rawEvent.replace(/"orderId":\s*(\d+)/g, '"orderId":"$1"'),
);
},
// Or, use a 3rd party library such as json-bigint:
// customParseJSONFn: (rawEvent) => {
// return JSONbig({ storeAsString: true }).parse(rawEvent);
// },
});
ws.on('message', (msg) => {
console.log(msg);
});
// If you prefer native BigInt, beware JSON.stringify will throw on BigInt values.
// Use a custom replacer or JSONbig.stringify if you need to log/serialize:
// const replacer = (_k: string, v: unknown) => typeof v === 'bigint' ? v.toString() : v;
// console.log(JSON.stringify(msg, replacer));
Some of the product groups available on Binance also support sending requests (commands) over an active WebSocket connection. This is called the WebSocket API.
Note: the WebSocket API requires the use of Ed25519 keys. HMAC & RSA keys are not supported by Binance for the WebSocket API (as of Apr 2025).
The WebSocket API is available in the WebsocketClient via the sendWSAPIRequest(wsKey, command, commandParameters) method.
Each call to this method is wrapped in a promise, which you can async await for a response, or handle it in a raw event-driven design.
The WebSocket API is also available in a promise-wrapped REST-like format. Either, as above, await any calls to sendWSAPIRequest(...), or directly use the convenient WebsocketAPIClient. This class is very similar to existing REST API classes (such as the MainClient or USDMClient).
It provides one function per endpoint, feels like a REST API and will automatically route your request via an automatically persisted, authenticated and health-checked WebSocket API connection.
Below is an example showing how easy it is to use the WebSocket API without any concern for the complexity of managing WebSockets.
import { WebsocketAPIClient } from 'binance';
// or, if you prefer `require()`:
// const { WebsocketAPIClient } = require('binance');
/**
* The WS API only works with an Ed25519 API key.
*
* Check the rest-private-ed25519.md in this folder for more guidance
* on preparing this Ed25519 API key.
*/
const publicKey = `-----BEGIN PUBLIC KEY-----
MCexampleQTxwLU9o=
-----END PUBLIC KEY-----
`;
const privateKey = `-----BEGIN PRIVATE KEY-----
MC4CAQAexamplewqj5CzUuTy1
-----END PRIVATE KEY-----
`;
// API Key returned by binance, generated using the publicKey (above) via Binance's website
const apiKey = 'TQpJexamplerobdG';
// Make an instance of the WS API Client
const wsClient = new WebsocketAPIClient({
api_key: apiKey,
api_secret: privateKey,
beautify: true,
// Enforce testnet ws connections, regardless of supplied wsKey
// testnet: true,
});
// Optional, if you see RECV Window errors, you can use this to manage time issues. However, make sure you sync your system clock first!
// https://github.com/tiagosiebler/awesome-crypto-examples/wiki/Timestamp-for-this-request-is-outside-of-the-recvWindow
// wsClient.setTimeOffsetMs(-5000);
// Optional, see above. Can be used to prepare a connection before sending commands
// await wsClient.connectWSAPI(WS_KEY_MAP.mainWSAPI);
// Make WebSocket API calls, very similar to a REST API:
wsClient
.getFuturesAccountBalanceV2({
timestamp: Date.now(),
recvWindow: 5000,
})
.then((result) => {
console.log('getFuturesAccountBalanceV2 result: ', result);
})
.catch((err) => {
console.error('getFuturesAccountBalanceV2 error: ', err);
});
wsClient
.submitNewFuturesOrder('usdm', {
side: 'SELL',
symbol: 'BTCUSDT',
type: 'MARKET',
quantity: 0.001,
timestamp: Date.now(),
// recvWindow: 5000,
})
.then((result) => {
console.log('getFuturesAccountBalanceV2 result: ', result);
})
.catch((err) => {
console.error('getFuturesAccountBalanceV2 error: ', err);
});
Binance provides specialized market maker endpoints for qualified high-frequency trading users who have enrolled in at least one of the Futures Liquidity Provider Programs, including the USDⓈ-M Futures Maker Program, COIN-M Futures Maker Program, and USDⓈ-M Futures Taker Program.
These endpoints provide the same functionality as regular endpoints but with optimized routing for market makers. For more information about eligibility and enrollment, visit: https://www.binance.com/en/support/faq/detail/7df7f3838c3b49e692d175374c3a3283
To use market maker endpoints, simply add the useMMSubdomain: true option when initializing any client (REST API clients, WebSocket clients, or WebSocket API clients):
import { USDMClient, CoinMClient } from 'binance';
// USD-M Futures with MM endpoints
const usdmClient = new USDMClient({
api_key: API_KEY,
api_secret: API_SECRET,
useMMSubdomain: true, // Enable market maker endpoints
});
// COIN-M Futures with MM endpoints
const coinmClient = new CoinMClient({
api_key: API_KEY,
api_secret: API_SECRET,
useMMSubdomain: true, // Enable market maker endpoints
});
import { WebsocketClient, WebsocketAPIClient } from 'binance';
// WebSocket consumer with MM endpoints
const wsClient = new WebsocketClient({
api_key: API_KEY,
api_secret: API_SECRET,
useMMSubdomain: true, // Enable market maker endpoints
});
// WebSocket API client with MM endpoints
const wsApiClient = new WebsocketAPIClient({
api_key: API_KEY,
api_secret: API_SECRET,
useMMSubdomain: true, // Enable market maker endpoints
});
Note: Market maker endpoints are only available for futures products (USD-M and COIN-M). Spot, margin, and other product groups use the regular endpoints regardless of the useMMSubdomain setting. Market maker endpoints are also not available on testnet environments.
Since market maker endpoints are only available for some of the futures endpoints, you may need to use multiple client instances if your algorithm needs to use both regular and MM endpoints.
import { USDMClient } from 'binance';
// MM client for USD-M futures
const futuresMMClient = new USDMClient({
api_key: API_KEY,
api_secret: API_SECRET,
useMMEndpoints: true, // Use MM endpoints for futures
});
// Regular client for USD-M futures
const futuresRegularClient = new USDMClient({
api_key: API_KEY,
api_secret: API_SECRET,
useMMEndpoints: false, // Use regular endpoints for futures
});
Pass a custom logger which supports the log methods trace, info and error, or override methods from the default logger as desired.
import { WebsocketClient, DefaultLogger } from 'binance';
// or, if you prefer `require()`:
// const { WebsocketClient, DefaultLogger } = require('binance');
// Enable all logging on the trace level (disabled by default)
DefaultLogger.trace = (...params) => {
console.trace('trace: ', params);
};
// Pass the updated logger as the 2nd parameter
const ws = new WebsocketClient(
{
api_key: key,
api_secret: secret,
beautify: true,
},
DefaultLogger
);
// Or, create a completely custom logger with the 3 available functions
const customLogger = {
trace: (...params: LogParams): void => {
console.trace(new Date(), params);
},
info: (...params: LogParams): void => {
console.info(new Date(), params);
},
error: (...params: LogParams): void => {
console.error(new Date(), params);
},
}
// Pass the custom logger as the 2nd parameter
const ws = new WebsocketClient(
{
api_key: key,
api_secret: secret,
beautify: true,
},
customLogger
);
This is the "modern" way, allowing the package to be directly imported into frontend projects with full typescript support.
npm install crypto-browserify stream-browserify
tsconfig.json
{
"compilerOptions": {
"paths": {
"crypto": [
"./node_modules/crypto-browserify"
],
"stream": [
"./node_modules/stream-browserify"
]
}
(window as any).global = window;
This is the "old" way of using this package on webpages. This will build a minified js bundle that can be pulled in using a script tag on a website.
Build a bundle using webpack:
npm installnpm buildnpm packThe bundle can be found in dist/. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.
This SDK includes a bundled llms.txt file in the root of the repository. If you're developing with LLMs, use the included llms.txt with your LLM - it will significantly improve the LLMs understanding of how to correctly use this SDK.
This file contains AI optimised structure of all the functions in this package, and their parameters for easier use with any learning models or artificial intelligence.
Have my projects helped you? Share the love, there are many ways you can show your thanks:
0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.
FAQs
Professional Node.js & JavaScript SDK for Binance REST APIs & WebSockets, with TypeScript & end-to-end tests.
The npm package binance receives a total of 2,596 weekly downloads. As such, binance popularity was classified as popular.
We found that binance demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub postponed a new billing model for self-hosted Actions after developer pushback, but moved forward with hosted runner price cuts on January 1.
Research
Destructive malware is rising across open source registries, using delays and kill switches to wipe code, break builds, and disrupt CI/CD.
Security News
Socket CTO Ahmad Nassri shares practical AI coding techniques, tools, and team workflows, plus what still feels noisy and why shipping remains human-led.