Bybit API Authentication in Node.js: A Secure Implementation Guide (2026)

Signing ensures request integrity and prevents man-in-the-middle attacks by ensuring that the payload hasn't been altered in transit. To generate the X-BAPI-SIGN header, you must concatenate the timestamp, API key, recvWindow, and the request payload into a specific string format. The signature is a hash of this concatenated request string generated using your API secret as the key. If a single byte in the payload changes, the signature will not match, and the server will reject the request with a 10004 error code.

Authentication requirements vary significantly between protocols. REST requests are stateless, meaning you must generate and include a unique signature for every individual private call. This adds latency if your signing logic is inefficient. Conversely, WebSocket authentication occurs once during the initial connection handshake. Once the private stream is authorized, subsequent messages don't require individual signatures. The bybit-api SDK manages these distinct flows automatically. It handles per-request signing for REST and manages the stateful handshake for WebSockets, allowing you to focus on execution logic rather than cryptographic boilerplate.

For V5 private REST calls, build a pre-sign string by concatenating timestamp + api_key + recv_window + payload. For GET requests, the payload is a query string (key=value&key2=value2). For POST requests, it is the raw JSON body. Sign with HMAC-SHA256 and send the digest as a hex string in X-BAPI-SIGN.

import crypto from "crypto";

const apiKey = process.env.BYBIT_API_KEY;
const apiSecret = process.env.BYBIT_API_SECRET;
const recvWindow = 5000;
const timestamp = Date.now();

// POST example
const body = {
  category: "linear",
  symbol: "BTCUSDT",
  side: "Buy",
  orderType: "Market",
  qty: "0.001",
};
const payload = JSON.stringify(body);
const preSign = `${timestamp}${apiKey}${recvWindow}${payload}`;
const sign = crypto
  .createHmac("sha256", apiSecret)
  .update(preSign)
  .digest("hex");

// Include these headers on the request
const headers = {
  "X-BAPI-API-KEY": apiKey,
  "X-BAPI-TIMESTAMP": String(timestamp),
  "X-BAPI-RECV-WINDOW": String(recvWindow),
  "X-BAPI-SIGN": sign,
  "X-BAPI-SIGN-TYPE": "2",
};

Common pitfalls: wrong concatenation order, sending numbers instead of strings for quantities, or including undefined fields in the JSON body.

RSA authentication shifts key custody to you. Generate a private/public key pair locally (2048 or 4096 bit), upload only the public key to Bybit, and keep the private key in your infrastructure. The pre-sign string format is the same as HMAC, but the signature is RSA-SHA256 encoded as base64, not hex.

With the SDK, pass your API key as key and the PEM private key (including the BEGIN PRIVATE KEY header) as secret. The client detects RSA automatically:

import { RestClientV5 } from "bybit-api";

const client = new RestClientV5({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_RSA_PRIVATE_KEY, // PEM string with BEGIN PRIVATE KEY header
  testnet: true,
});

const account = await client.getAccountInfo();

See the Bybit SDK tutorial and the examples/Auth/RSA-sign.ts sample in the repo for a full walkthrough.

For local development and initial testing, use dotenv or cross-env to manage your credentials. Create a.env file to store your API key and secret, but ensure this file is explicitly included in your.gitignore. Accidental exposure of secrets in public repositories is a common cause of system compromise. Always use the Bybit testnet for all initial authentication development. This allows you to verify your signing logic and permission scopes in a safe environment without risking real assets.

• Use environment variables for all sensitive strings.
• Validate the presence of required variables at process startup.
• Never log raw API secrets or full request headers to the console.
• Rotate API keys periodically to minimize long-term exposure risks.

Permissions must be strictly limited to the specific requirements of your workflow. Bybit provides granular control over key capabilities, categorized into Read-Only, Trade, and Account sets. If your application only consumes account balances, use a Read-Only key. For execution-focused systems, enable Trade permissions but leave Account and Transfer permissions disabled. There is a total prohibition on enabling withdrawal permissions for any automated trading system keys. This eliminates the risk of unauthorized asset transfers even in the event of a full system compromise.

Audit your existing keys regularly through the Bybit dashboard to identify and revoke unnecessary permissions. Effective security architecture relies on these safety boundaries to maintain system integrity. For a deeper look at designing resilient systems, review the Siebly.io research on trading system safety boundaries. Utilizing the bybit-api SDK further supports this by providing a clean implementation layer that respects these security constraints while reducing the boilerplate required for authenticated requests.

Bybit V5 requires X-BAPI-TIMESTAMP to stay within your configured recvWindow (default 5000 ms in the SDK). If your server clock drifts, requests fail with error 10002.

You can query /v5/market/time and store the offset between your clock and Bybit's. The bybit-api SDK exposes two options for this:

• enable_time_sync: true runs an initial sync and repeats it on sync_interval_ms (default 1 hour).
• syncTimeBeforePrivateRequests: true re-syncs before each private REST call.

import { RestClientV5 } from "bybit-api";

const client = new RestClientV5({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_API_SECRET,
  testnet: true,
  enable_time_sync: true,
  sync_interval_ms: 3600000, // optional, default is 1 hour
});

If you face persistent 10004 errors, walk through this checklist:

• Concatenation order: timestamp + api_key + recv_window + payload (no separators).
• Encoding: HMAC signatures must be hex. RSA signatures must be base64.
• Data types: Quantities and prices should be strings in the JSON body.
• Empty fields: Strip undefined values before signing.
• Key status: Confirm the API key is active and permissions match the endpoint.

For a more reliable integration that eliminates these manual debugging steps, implement the Bybit SDK to handle signing and optional clock sync via enable_time_sync.

npm install bybit-api

Basic HMAC setup with testnet and time sync:

import { RestClientV5 } from "bybit-api";

const client = new RestClientV5({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_API_SECRET,
  testnet: true,
  enable_time_sync: true,
});

// Authenticated private call - signing is handled internally
const positions = await client.getPositionInfo({
  category: "linear",
  symbol: "BTCUSDT",
});

For private WebSocket streams, pass the same key pair. Auth runs once on connect:

import { WebsocketClient } from "bybit-api";

const wsClient = new WebsocketClient({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_API_SECRET,
  testnet: true,
});

wsClient.on("update", (data) => console.log(data));
wsClient.subscribeV5(["position", "order", "wallet"], "linear");

For awaitable order commands over WebSocket, use WebsocketAPIClient:

import { WebsocketAPIClient } from "bybit-api";

const wsApi = new WebsocketAPIClient({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_API_SECRET,
});

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

Setup notes:

• Install via npm install bybit-api or yarn add bybit-api.
• Set testnet: true for testnet, or demoTrading: true for Bybit's demo trading environment.
• Enable enable_time_sync if your server clock is not NTP-synced.
• The SDK sends an x-referer: bybitapinode header on REST requests, which qualifies requests for higher API rate limits than raw HTTP calls.

The bybit-api SDK covers V5 REST and WebSocket APIs with full TypeScript types. It handles per-request REST signing, private stream auth on connect, reconnects, heartbeats, and resubscriptions. The WebsocketAPIClient wraps trade commands (submitNewOrder, amendOrder, cancelOrder) as awaitable promises, which is useful when you want WebSocket execution without building the request/response correlation yourself.

Compared to generic wrappers, exchange-specific SDKs map directly to Bybit's endpoint shapes, error codes, and auth rules. You also get the higher rate limit tier via the built-in referer header. See the Siebly.io SDK documentation for the full API surface.

You generate keys via the API Management section of the Bybit dashboard. Select "Create New Key" and choose between system-generated HMAC or self-generated RSA types. Ensure you copy the secret immediately; it is only displayed once for security. For a step-by-step implementation, refer to the Bybit JavaScript quickstart guide to configure your environment correctly.

HMAC keys use a shared secret provided by the exchange, while RSA keys utilize asymmetric cryptography where you generate a private/public key pair locally. RSA is more secure because your private key never traverses the network. HMAC is generally faster to implement for standard automated workflows and is the default choice for most system-generated keys.

This error (Bybit retCode 10004) means your local signature does not match the server's. In Bybit API authentication nodejs workflows, check the pre-sign string order, make sure HMAC output is hex (not base64), and confirm quantities are strings. Logging the pre-sign string before hashing is the fastest way to find the mismatch.

Secrets must be stored in environment variables or managed via secure infrastructure like AWS Secrets Manager or HashiCorp Vault. Never include secrets in your source code or version control systems. For local Node.js development, use the dotenv package and ensure your.env file is explicitly listed in your.gitignore to prevent accidental exposure.

The bybit-api package provides comprehensive support for the V5 REST and WebSocket APIs. It handles signing for you and includes the referer header that qualifies REST requests for higher rate limits. See the Bybit SDK tutorial for typed examples across public and private endpoints.

Call /v5/market/time, compare the returned timestamp to Date.now(), and apply the offset to every X-BAPI-TIMESTAMP. Or enable enable_time_sync: true in the bybit-api client so the SDK manages the offset for you. If you only need a sync before each private call, use syncTimeBeforePrivateRequests: true instead.

Yes, a single API key and secret pair works for both protocols. While REST requires a unique signature for every private request, the WebSocket API only requires authentication during the initial connection handshake. Once authorized, the stateful connection allows you to send commands such as order placement without re-signing each individual message, significantly reducing execution latency.

Operating without IP whitelisting is a significant security risk for production systems. Whitelisting binds your API key to specific server addresses, preventing unauthorized use from external networks if your credentials are compromised. It's a fundamental safety boundary for any professional trading infrastructure and should be combined with least-privilege permission scoping for maximum protection.