Account State Management for Crypto APIs: Node.js Guide

Binance spot is the example people still get wrong. The old user-data listen key for spot is deprecated. The SDK opens spot user data through the WebSocket API, and it will resubscribe after a reconnect unless you turn that off. Futures still use a listen key, and the SDK creates it and keeps it alive. You do not PUT a listen key on a timer yourself.

import { WebsocketAPIClient, WS_KEY_MAP } from "binance";

const wsClient = new WebsocketAPIClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  beautify: true,
  // resubscribeUserDataStreamAfterReconnect defaults to true
});

const response = await wsClient.subscribeUserDataStream(WS_KEY_MAP.mainWSAPI);

USD-M futures user data is still the listen-key connection, handled inside subscribeUsdFuturesUserDataStream():

import { WebsocketClient } from "binance";

const wsClient = new WebsocketClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  beautify: true,
});

wsClient.subscribeUsdFuturesUserDataStream();

The reconnected handler in the Binance user-data example is the right place to re-read balances, positions, and open orders. The socket coming back does not mean you saw every event from the gap.

Do not feed raw responses into one shared interface. A Bybit wallet balance and a Kraken balance are different objects, different field names, different units.

Bybit V5, from OrderStatusV5 in bybit-api:

Created, New, Rejected, PartiallyFilled, PartiallyFilledCanceled, Filled, Cancelled, Untriggered, Triggered, Deactivated, Active

Binance spot OrderStatus:

NEW, PARTIALLY_FILLED, FILLED, CANCELED, PENDING_CANCEL, REJECTED, EXPIRED

OKX order state on the private order payloads includes live, partially_filled, filled, and canceled. There is no shared Created then New pipeline. Created and New are Bybit values, and Bybit also has states that never pass through both.

Keep the exchange payload, and map the few fields your engine needs (orderId, status, filled qty, free balance) into your own type. The SDK types already describe the raw payload. They do not normalize it across venues.

Treat the private order or execution event as the update, and use REST when you need to repair the book. The SDK emits the exchange message. Your reducer applies it.

A Bybit private subscription from the V5 example:

import { WebsocketClient } from "bybit-api";

const wsClient = new WebsocketClient({
  key: process.env.API_KEY_COM,
  secret: process.env.API_SECRET_COM,
});

// Private V5 topics share one private endpoint. Category is ignored here.
wsClient.subscribeV5(["order", "wallet", "position", "execution"], "linear");

wsClient.on("update", (data) => {
  // apply to your local orders / wallet / positions
});

wsClient.on("reconnected", () => {
  // REST snapshot again. Events from the gap are gone.
});

The client pings, reconnects, and resubscribes. You still reconcile.

• binance: api_key, api_secret. HMAC-SHA256, RSA, or Ed25519. Ed25519 can log in once on the WebSocket API. HMAC and RSA sign each WS API command.
• bybit-api: key, secret. HMAC-SHA256, or RSA.
• okx-api: apiKey, apiSecret, apiPass. HMAC-SHA256. The passphrase is required.
• bitget-api: apiKey, apiSecret, apiPass. HMAC-SHA256 or RSA. Passphrase required. V3 WebSocket API needs UTA keys.
• kucoin-api: apiKey, apiSecret, apiPassphrase. HMAC-SHA256. Passphrase is not the account password.
• bitmart-api: apiKey, apiSecret, apiMemo. HMAC-SHA256. Memo is required.
• @siebly/htx-api: apiKey, apiSecret. HMAC-SHA256.
• gateio-api: apiKey, apiSecret. HMAC-SHA512.
• @siebly/kraken-api: apiKey, apiSecret. SHA-256 of the payload, then HMAC-SHA512. The secret is the base64 private key from Kraken.
• coinbase-api: apiKey, apiSecret (CDP key name and private key). JWT. ECDSA (BEGIN EC PRIVATE KEY) or Ed25519. The client detects which.

OKX private sockets need the passphrase on every account you subscribe with. Miss it and the socket never authenticates, which looks a lot like "no fills".

import { WebsocketClient } from "okx-api";

const wsClient = new WebsocketClient({
  accounts: [
{
apiKey: process.env.API_KEY_COM!,
apiSecret: process.env.API_SECRET_COM!,
apiPass: process.env.API_PASSPHRASE_COM!,
},
  ],
});

wsClient.subscribe([
  { channel: "account" },
  { channel: "positions", instType: "ANY" },
  { channel: "orders", instType: "ANY" },
]);

Read keys from the environment. Do not put them in the repo. The examples in each package already do this with process.env.

WebsocketAPIClient sends a command on the WebSocket API and resolves when the matching response arrives. That response means the exchange accepted or rejected the command. It is not a fill. Fills still arrive on the private stream.

Bybit:

import { WebsocketAPIClient } from "bybit-api";

const wsClient = new WebsocketAPIClient({
  key: process.env.API_KEY_COM,
  secret: process.env.API_SECRET_COM,
  // testnet: true,
  // demoTrading does not support the Bybit WS API (events only, as of the Jan 2025 note in the SDK)
});

const response = await wsClient.submitNewOrder({
  category: "linear",
  symbol: "BTCUSDT",
  orderType: "Limit",
  qty: "0.001",
  side: "Buy",
  price: "50000",
});

OKX (passphrase again):

import { WebsocketAPIClient } from "okx-api";

const wsClient = new WebsocketAPIClient({
  accounts: [
{
apiKey: process.env.API_KEY_COM || "",
apiSecret: process.env.API_SECRET_COM || "",
apiPass: process.env.API_PASSPHRASE_COM || "",
},
  ],
});

const res = await wsClient.submitNewOrder({
  instId: "BTC-USDT",
  tdMode: "cash",
  side: "buy",
  ordType: "market",
  sz: "100",
});

Kraken spot. The SDK fetches the private WS token for you. Do not pass token yourself:

import { WebsocketAPIClient } from "@siebly/kraken-api";

const client = new WebsocketAPIClient({
  apiKey: process.env.API_SPOT_KEY,
  apiSecret: process.env.API_SPOT_SECRET,
});

const addOrderResponse = await client.submitSpotOrder({
  order_type: "limit",
  side: "buy",
  limit_price: 26500.4,
  order_qty: 1.2,
  symbol: "BTC/USD",
});

Gate.io spot:

import { WebsocketAPIClient } from "gateio-api";

const client = new WebsocketAPIClient({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

const newOrder = await client.submitNewSpotOrder({
  text: "t-my-custom-id",
  currency_pair: "BTC_USDT",
  type: "limit",
  account: "spot",
  side: "buy",
  amount: "1",
  price: "10000",
});

Bitget V3 UTA:

import { WebsocketAPIClient } from "bitget-api";

const wsClient = new WebsocketAPIClient({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
});

const res = await wsClient.submitNewOrder("spot", {
  orderType: "limit",
  price: "100",
  qty: "0.1",
  side: "buy",
  symbol: "BTCUSDT",
  timeInForce: "gtc",
});

Coinbase and BitMart stop at subscribe. Coinbase Advanced Trade user data:

import { WebsocketClient } from "coinbase-api";

const client = new WebsocketClient({
  apiKey: process.env.API_KEY_NAME,
  apiSecret: process.env.API_PRIVATE_KEY,
});

client.subscribe("user", "advTradeUserData");
client.on("update", (data) => {
  // user channel payloads
});

The Coinbase example subscribes to futures_balance_summary on advTradeUserData the same way. Authentication is the CDP private key, not an HMAC secret.

BitMart spot private:

import { WebsocketClient } from "bitmart-api";

const client = new WebsocketClient({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  apiMemo: process.env.API_MEMO,
});

client.subscribe("spot/user/order:BTC_USDT", "spot");
// client.subscribe('spot/user/balance:BALANCE_UPDATE', 'spot');

Bybit unified wallet:

import { RestClientV5 } from "bybit-api";

const rest = new RestClientV5({
  key: process.env.API_KEY_COM,
  secret: process.env.API_SECRET_COM,
});

const wallet = await rest.getWalletBalance({ accountType: "UNIFIED" });

Binance spot balances (free is what you can still spend):

import { MainClient } from "binance";

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

const balances = await client.getBalances();
const usdt = balances.find((row) => row.coin === "USDT");

OKX trading balance is getBalance, not getBalances. getBalances is the funding account.

import { RestClient } from "okx-api";

const rest = new RestClient({
  apiKey: process.env.API_KEY_COM!,
  apiSecret: process.env.API_SECRET_COM!,
  apiPass: process.env.API_PASSPHRASE_COM!,
});

const balance = await rest.getBalance();
const positions = await rest.getPositions({ instType: "SWAP" });

Kraken spot:

import { SpotClient } from "@siebly/kraken-api";

const client = new SpotClient({
  apiKey: process.env.API_SPOT_KEY,
  apiSecret: process.env.API_SPOT_SECRET,
});

const balances = await client.getAccountBalance();
const extended = await client.getExtendedBalance();

getExtendedBalance is the one that includes held amounts. Available is balance plus credit, minus credit used, minus hold_trade.

Turn these on only for the client you are testing. They are not a global SDK mode.

• binance: testnet: true or demoTrading: true. Demo uses live market data with a simulated account. Testnet is a separate market. They are not the same flag.
• bybit-api: testnet: true. demoTrading: true is for consuming events. The WS API client does not support demo trading.
• okx-api: demoTrading: true on both RestClient and WebsocketClient.
• bitget-api: demoTrading: true.
• gateio-api: useTestnet: true.
• bitmart-api: demoTrading: true for V2 futures only. Spot stays on production.
• @siebly/kraken-api: testnet: true on the derivatives client. Spot does not have this. Kraken calls the derivatives environment "demo".
• coinbase-api: useSandbox: true on the International client. That flag is not an Advanced Trade paper venue.
• kucoin-api and @siebly/htx-api: no testnet or demo switch in the client.

These SDKs do not queue, delay, or retry for rate limits. That includes REST and the WebSocket API. If you burst getWalletBalance on a timer plus order commands, you will get 429s or the venue's equivalent. Back off yourself. The library will not do it quietly in the background, which is what you want if you care about latency.

Listen for reconnected, then REST-read balances, open orders, and positions. The clients reconnect and resubscribe on their own. They do not store the events from the gap, so there is nothing to replay unless you buffered it yourself. The Binance user-data example calls this out in the reconnected handler.

No. No client in this set throttles or queues to stay under exchange weight. Some responses include rate-limit numbers (Binance and Bybit). You have to read them and slow down.

Subscribe and buffer first, then fetch REST, then drop buffered events older than that snapshot and apply the newer ones. If the venue does not give you a sequence you trust, refetch REST.

Environment variables or a secret manager. A monitor key should be read-only. An execution key should be allowed to trade and not allowed to withdraw.

A WebsocketAPIClient call that returns a promise for the command response. submitNewOrder on Bybit and OKX, submitSpotOrder on Kraken, submitNewSpotOrder on Gate.io, and submitNewOrder on Bitget V3 work this way. The promise resolves on accept or reject. Fills are a later private-stream event. Coinbase and BitMart do not offer this client.

Store the raw message, and map status into your own enum. Bybit Filled, Binance FILLED, and OKX filled are the same idea and not the same string. bybit-api and okx-api will not do that mapping for you.

Where the exchange and the client support it, yes. See the demo and testnet list above. KuCoin and HTX are not on that list. Bybit demo trading does not support the WebSocket API. BitMart demo is V2 futures only. Kraken testnet is derivatives only.

Each package is typed to that venue's REST and private WebSocket, including the odd parts: OKX and Bitget passphrases, BitMart memo, Kraken's WS token, Binance Ed25519 login, Gate.io SHA-512. A general library can still place an order. It will not match these private stream topics and WebsocketAPIClient methods one for one.