Binance Spot API Node.js SDK: 2026 Engineering Guide

Private Binance calls need a correct signature and a timestamp inside recvWindow (SDK default is 5000 ms). There is no separate nonce field. If the clock is off, you get "timestamp for this request is outside of the recvWindow".

Home-grown clients usually fail in the same three places:

• Signature encoding or param order. HMAC, RSA, and Ed25519 each have different rules.
• Clock drift. The SDK can apply an offset (setTimeOffset / setTimeOffsetMs). Time sync is off by default (disableTimeSync: true). Fix the OS clock first.
• Untyped responses. A missing field in a fill report shows up in production, not at compile time.

The binance npm package hides signing and socket bookkeeping. You write trading or AI coding agent logic against typed methods. That is also why order intent chasers and data pipelines can share one client.

What you get:

• One config object for keys, testnet, demo trading, recvWindow, and beautify.
• TypeScript types on requests and responses.
• WebSocket persistence: heartbeats, reconnect, resubscribe, reconnected.

A raw WebSocket API client means you emit a frame, stash the request id, and wait for a matching event. WebsocketAPIClient does that matching for you. You await submitNewSpotOrder(...) the same way you would await client.submitNewOrder(...) on REST.

Ed25519 is the fast path here. The socket can log in once. HMAC and RSA still work, but every command is signed individually. If you care about order latency, generate an Ed25519 key. Check latest SDK releases when Binance ships WS API changes.

import { WebsocketAPIClient } from "binance";

const wsApi = new WebsocketAPIClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  beautify: true,
  // testnet: true,
});

const book = await wsApi.getSpotOrderBook({ symbol: "BTCUSDT" });
console.log(book);

const order = await wsApi.submitNewSpotOrder({
  symbol: "BTCUSDT",
  side: "SELL",
  type: "LIMIT",
  timeInForce: "GTC",
  price: "23416.10000000",
  quantity: "0.00847000",
});
console.log(order);

You can still use the lower-level WebsocketClient.sendWSAPIRequest(wsKey, command, params) if you want the event-driven form. Same connection, more wiring.

Pick the client that matches the product group. Do not point a Spot call at a futures host.

• MainClient: Spot, cross and isolated margin, convert, wallet, staking, sub-accounts, and the rest of api*.binance.com.
• USDMClient: USD-M futures.
• CoinMClient: COIN-M futures.
• PortfolioClient: portfolio margin.

Vanilla Options is not in the SDK yet.

Market maker subdomains (useMMSubdomain: true) are futures only. You need to be in a Binance Futures liquidity-provider program. They are not available on testnet, and they do nothing for Spot or margin. High-volume Spot still uses the normal hosts.

import { MainClient, USDMClient, CoinMClient } from "binance";

const spot = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
});

const usdm = new USDMClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  // useMMSubdomain: true, // futures LP programs only
});

const coinm = new CoinMClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
});

New project? Start with the quickstart tutorial. Import only the clients you need. The same modular split shows up in AI-assisted engineering workflows.

Pass the API key as api_key. Pass the secret as api_secret:

• HMAC: the hex secret string from the Binance UI.
• RSA: PEM including BEGIN RSA PRIVATE KEY or a long BEGIN PRIVATE KEY block.
• Ed25519: a short BEGIN PRIVATE KEY PEM (the SDK treats PEM secrets under about 150 characters as Ed25519).

You do not set a signMethod flag. getSignKeyType() reads the PEM headers and length.

import { MainClient } from "binance";

const rsaClient = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: `-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----`,
  beautifyResponses: true,
});

const edClient = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: `-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----`,
  beautifyResponses: true,
});

await edClient.getAccountInformation();

Keep keys in env vars or a vault. Enable Spot (and margin if you need it). Leave withdrawals off on any bot key.

A quiet TCP drop is worse than a thrown error. The WebsocketClient sends timed heartbeats. On failure it reconnects and emits reconnecting, then reconnected. That event is your cue to refresh exchange state.

Beautify is opt-in, not on by default. Raw frames use one-letter keys (q, p). Set beautify: true and listen on formattedMessage if you want quantity and price. REST has the same idea via beautifyResponses: true. Useful for humans and for agents that map fields by name.

import { WebsocketClient } from "binance";

const wsClient = new WebsocketClient({
  beautify: true,
});

wsClient.on("formattedMessage", (data) => {
  console.log(data);
});

wsClient.on("reconnecting", (data) => {
  console.log("reconnecting", data?.wsKey);
});

wsClient.on("reconnected", (data) => {
  console.log("reconnected", data?.wsKey);
});

wsClient.on("exception", (data) => {
  console.error("ws error", data?.wsKey);
});

wsClient.subscribe(
  ["btcusdt@bookTicker", "btcusdt@depth10@100ms", "btcusdt@depth"],
  "main",
);

One WebsocketClient can subscribe many Spot symbols on the main stream. USD-M public data now has split hosts (usdmPublic, usdmMarket, private). The SDK routes those if you pass the right WS_KEY_MAP key. Convenience helpers like subscribeSpotTrades() still work.

import { WebsocketClient, isWsPartialBookDepthEventFormatted } from "binance";

const wsClient = new WebsocketClient({ beautify: true });

wsClient.on("formattedMessage", (data) => {
  if (isWsPartialBookDepthEventFormatted(data)) {
const [symbol] = data.streamName.split("@");
console.log(symbol, data);
  }
});

const symbols = ["BTCUSDT", "ETHUSDT"];
const topics = symbols.map(
  (symbol) => `${symbol.toLowerCase()}@depth20@1000ms`,
);
wsClient.subscribe(topics, "main");

Push typed events into a queue or bus so other services never touch the socket layer. For a fuller ingest layout, see the Siebly historical and live data pipeline guide.

REST and the WebSocket API share the same order fields. TypeScript will reject a Spot order missing symbol or type before it hits the wire. After a submit, trust the user-data stream for fills, partials, and cancels, not only the HTTP or WS API ack. That is how local exchange state stays honest.

import { MainClient } from "binance";

const client = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  beautifyResponses: true,
});

const buyOrderRequest = {
  symbol: "BTCUSDT",
  quantity: 0.001,
  side: "BUY",
  type: "MARKET",
  newOrderRespType: "FULL",
};

await client.testNewOrder(buyOrderRequest);
const result = await client.submitNewOrder(buyOrderRequest);
console.log(result);

Walk through the Binance Node.js tutorial if you want the full order-lifecycle setup.

The package includes an llms.txt in the repo root. Point an agent at that file plus the Siebly AI prompt framework and the Binance exchange state reference. Agents write fewer broken calls when methods and types are consistent.

Log REST calls and WebSocket events. Keep a central throttle. Use recvWindow on purpose and keep the host clock in NTP. For layout ideas, see the algorithmic trading system architecture guide.

Two sandboxes exist. Do not mix them up:

• Demo trading (demoTrading: true): real market data, simulated balances. This is what you want for strategy tests.
• Testnet (testnet: true): a separate venue with fake books. Fine for wiring checks. Poor for strategy work.

import { MainClient } from "binance";

const demo = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  beautifyResponses: true,
  demoTrading: true,
});

const account = await demo.getAccountInformation();
const order = await demo.submitNewOrder({
  side: "BUY",
  symbol: "BTCUSDT",
  type: "MARKET",
  quantity: 0.001,
});

You can still pass a custom baseUrl if you need a proxy host. You do not need to hardcode the testnet URL. The flag is enough.

No. It does not sleep, queue, or retry on HTTP 429. It does record the x-mbx-used-weight headers it sees. After any REST call you can read client.getRateLimitStates(). Combine that with getExchangeInfo().rateLimits and your own limiter.

Binance tears down sockets around the 24 hour mark. The SDK heartbeats, reconnects, and emits reconnected. For Spot user data, subscribeUserDataStream is re-issued after reconnect unless you set resubscribeUserDataStreamAfterReconnect: false. Use reconnected to re-check open orders and balances.

Yes. MainClient covers Spot and margin. USDMClient and CoinMClient cover the two futures product groups. PortfolioClient covers portfolio margin. Method names stay close across clients so a multi-market process does not need a second mental model.

Ed25519 signs faster than RSA. On the WebSocket API it is the only key type that supports session login. HMAC and RSA must sign every WS API command. Pass the Ed25519 PEM as api_secret. The SDK detects it from the BEGIN PRIVATE KEY header and key length.

Yes, for public data. The Binance package documents frontend import (and a webpack bundle in dist/). Sister SDKs do the same. Do not put API secrets in browser code, VITE_*, or REACT_APP_*. Signed REST, private sockets, and order placement stay on a backend. Browser support is not a reason to ship keys to the client.

Spot user data should use subscribeUserDataStream(WS_KEY_MAP.mainWSAPI). The listenKey workflow is deprecated on Spot. For futures, margin, isolated margin, and portfolio, the SDK still creates a listenKey and sends keep-alive every 50 minutes. If Binance sends listenKeyExpired, it fetches a new key and respawns the stream.

Yes. Set testnet: true on the REST or WebSocket client. For anything that should look like production books, prefer demoTrading: true instead. Demo trading uses live market data with simulated fills. Testnet data does not.

Put the PEM string (including the BEGIN/END lines) in api_secret. The SDK signs REST and WebSocket API calls. You do not build the query string or the signature buffer yourself.

const client = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.RSA_PRIVATE_KEY_PEM,
  beautifyResponses: true,
});

await client.getBalances();

Disclaimer

*Technical and legal disclaimer: Siebly.io provides software development tools, SDKs, documentation, and educational engineering content for crypto exchange API integrations. This content is for software engineering education only and is not financial, investment, legal, tax, accounting, compliance, or trading advice.

Nothing in this article is a recommendation, invitation, or inducement to buy, sell, hold, trade, long, short, or allocate to any cryptoasset, exchange product, strategy, bot, or automated workflow. Examples, code patterns, simulations, backtests, and architecture diagrams are illustrative only and must not be treated as trading signals, investment recommendations, or evidence of future performance.

Cryptoasset markets are high risk and volatile. If you choose to build or operate exchange-connected software, you are responsible for your own legal, regulatory, tax, security, exchange-account, API-key, and risk-management obligations. Use public data, testnet, demo, dry-run, or paper-trading workflows before any live execution. Keep API keys server-side, use least-privilege permissions, and never enable withdrawals for automation keys unless you fully understand and accept the risks.

Siebly.io is not an exchange, custodian, investment adviser, trading-signal provider, or managed trading service. Official exchange documentation remains the source of truth for exchange-specific rules, API behavior, and terms of use. Use of Siebly.io content and software is also subject to the Siebly.io terms and conditions.*