Crypto Exchange API Timestamp Management in Node.js: A Professional Engineering Guide

The timestamp format is venue-specific. Binance and Bybit put a Unix epoch in milliseconds into the signed payload. OKX signs an ISO-8601 value in OK-ACCESS-TIMESTAMP. KuCoin uses KC-API-TIMESTAMP in milliseconds. Coinbase Advanced Trade puts nbf / exp claims into a JWT. Kraken uses an incrementing nonce (the SDK defaults that nonce to Date.now()). HMAC is common, but Binance also accepts RSA and Ed25519, and Coinbase Advanced Trade is JWT, not HMAC.

The binance client adds timestamp and recvWindow for you on private REST calls:

import { MainClient } from "binance";

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

const trades = await client.getAccountTradeList({ symbol: "BTCUSDT" });

The bybit-api client does the same with X-BAPI-TIMESTAMP and X-BAPI-RECV-WINDOW. Credential fields are key and secret, and the window option is recv_window:

import { RestClientV5 } from "bybit-api";

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

const positions = await client.getPositionInfo({
  category: "linear",
  symbol: "BTCUSDT",
});

OKX does not put a millisecond Unix timestamp in the query string. The okx-api REST client stamps OK-ACCESS-TIMESTAMP with new Date().toISOString():

import { RestClient } from "okx-api";

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

const timeMs = await client.getServerTime();

On Binance, recvWindow is the number of milliseconds after timestamp during which the request is still accepted. The SDK default is 5,000 ms. Binance caps it at 60,000 ms. That window absorbs network delay. It also limits how long a captured payload remains usable. A huge window is a security hole. Keep it tight, use least-privilege keys, and leave withdrawals off automation keys.

recvWindow is not universal. Bybit (recv_window), Bitget, BitMart, and Gate support a similar constructor default. okx-api, KuCoin, Kraken, Coinbase, and HTX validate freshness another way. The SDKs sign and send the timestamp. They do not pace your traffic. Rate limits stay your problem, though binance exposes getRateLimitStates() from response headers and bybit-api can parse per-endpoint limits if you set parseAPIRateLimits: true.

Record local time before and after the public time call. A crude offset is serverTime - Date.now(). A better one (what binance and bybit-api do in fetchTimeOffset()) adds half the round-trip:

offset = ceil(serverTime - end + (end - start) / 2)

Half-RTT is worth doing. A 5,000 ms window can hide a sloppy offset, but you still want the signed timestamp close to the exchange clock.

Do not fetch server time before every private call. That extra round-trip slows orders and burns public rate limits. Store the offset in memory and refresh it on a timer.

If you only need a one-shot measurement, most Siebly REST clients already ship getServerTime() and fetchLatencySummary(). The latter prints RTT, estimated one-way latency, and a warning if the gap is over 500 ms:

import { MainClient } from "binance";
import { RestClientV5 } from "bybit-api";
import { RestClient } from "okx-api";
import { RestClientV2 } from "bitget-api";
import { CBAdvancedTradeClient } from "coinbase-api";

const binance = new MainClient();
const bybit = new RestClientV5();
const okx = new RestClient();
const bitget = new RestClientV2();
const coinbase = new CBAdvancedTradeClient({});

const [binanceTime, bybitTime, okxTime, bitgetTime, coinbaseTime] =
  await Promise.all([
binance.getServerTime(),
bybit.getServerTime(),
okx.getServerTime(),
bitget.getServerTime(),
coinbase.getServerTime(),
  ]);

await binance.fetchLatencySummary();

fetchLatencySummary() is a diagnostic helper, not an official exchange endpoint. It logs to stdout. Use it at boot or when -1021 / 10002 start showing up.

A single sync at process start is not enough for a long-running bot. CPU load, VM migration, and container pause/resume all move the local clock. Refresh the offset every 30 to 60 minutes. That matches the Binance / Bybit default interval of 3600000 ms (one hour) when their time-sync option is turned on.

Watch logs for timestamp and recvWindow errors. A spike is a good reason to re-sync immediately, or to fix the host clock with NTP and restart.

These are the public clocks the SDKs actually call:

• binance: getServerTime() hits /api/v3/time (spot) and returns a number (serverTime).
• bybit-api: getServerTime() hits /v5/market/time and returns { result: { timeSecond, timeNano }, time }.
• okx-api: getServerTime() / getSystemTime() hit /api/v5/public/time. You get a number, or { ts: string }[].
• bitget-api: getServerTime() hits /api/v2/public/time or /api/v3/public/time and returns { data: { serverTime: string } }.
• bitmart-api: getSystemTime() hits system/time and returns { data: { server_time } }.
• coinbase-api: getServerTime() hits /api/v3/brokerage/time and returns { iso, epochSeconds, epochMillis }.
• gateio-api: getServerTime() hits /spot/time and returns { server_time }.
• kucoin-api: getServerTime() hits api/v1/timestamp and returns { data: number }.
• @siebly/kraken-api: getServerTime() hits 0/public/Time and returns { unixtime, rfc1123 }.
• @siebly/htx-api: getTimestamp() hits /v1/common/timestamp and returns { data: number }.

Binance futures use /fapi/v1/time and /dapi/v1/time. The client picks the path from the product group.

interface BinanceTime {
  serverTime: number;
}

interface BybitTime {
  retCode: number;
  retMsg: string;
  result: { timeSecond: string; timeNano: string };
  time: number;
}

interface OkxTime {
  ts: string;
}

interface CoinbaseTime {
  iso: string;
  epochSeconds: string;
  epochMillis: string;
}

okx-api already unwraps the array for you: getServerTime() returns Number(response[0].ts). getSystemTime() returns the raw { ts }[]. For a walkthrough of Bybit public market calls, see the Bybit JavaScript tutorial.

Kraken, KuCoin, and HTX have no auto-sync flag. They accept a customTimestampFn so you can inject Date.now() + offset after you measure it:

import { SpotClient } from "kucoin-api";
import { SpotClient as KrakenSpotClient } from "@siebly/kraken-api";
import { SpotClient as HtxSpotClient } from "@siebly/htx-api";

let offsetMs = 0;

const kucoin = new SpotClient({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  apiPassphrase: process.env.API_PASSPHRASE,
  customTimestampFn: () => Date.now() + offsetMs,
});

const summary = await kucoin.fetchLatencySummary();
offsetMs = summary.timeDifference;

const kraken = new KrakenSpotClient({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  customTimestampFn: () => Date.now() + offsetMs,
});

const htx = new HtxSpotClient({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  customTimestampFn: () => Date.now() + offsetMs,
});

Measure the offset against the same venue you are signing for. A KuCoin delta is not a Kraken delta.

On WebSocket API clients, the matching hook is setTimeOffsetMs().

If the time endpoint times out, do not start trading with a zero offset and hope. Back off, retry, then enter a safe state: no orders, alert the operator. A signed request with a known-bad clock is a guaranteed reject.

You do not need a custom sync service for every venue. Use the SDK helpers above. Only Binance and Bybit will apply the offset on REST for you, and only after you opt in.

TCP handshakes and TLS can eat 50 to 200 ms of your window. Most Siebly REST clients take keepAlive: true (and optional keepAliveMsecs) and attach a Node https.Agent. That reuses sockets. It is off by default.

Also watch event-loop lag. If the loop is blocked, the gap between stamping the request and writing it to the socket grows. That is a timestamp bug even when the clock is correct.

import { MainClient } from "binance";

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

Private WebSocket API frames are signed too. Nonces and timestamps have to be correct on every command, not only on REST. Siebly clients that wrap the WebSocket API (WebsocketAPIClient on Binance, Bybit, OKX, Bitget, Gate, KuCoin, Kraken, HTX) return a Promise per command. The SDK stamps and signs the frame.

import { WebsocketAPIClient } from "binance";

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

// If recvWindow errors persist after NTP, apply a measured offset.
// wsClient.setTimeOffsetMs(-500);

const serverTime = await wsClient.getSpotServerTime();
const order = await wsClient.submitNewSpotOrder({
  symbol: "BTCUSDT",
  side: "BUY",
  type: "LIMIT",
  timeInForce: "GTC",
  price: "60000",
  quantity: "0.001",
});

Bybit's awaitable client uses key / secret and submitNewOrder():

import { WebsocketAPIClient } from "bybit-api";

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

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

For more on event-driven layouts, see the algorithmic trading system architecture guide. To pull the clients into a production service, start with the Siebly SDK catalog.

Binance REST clients default disableTimeSync: true. Set it to false to fetch /api/v3/time (or the futures equivalent), store the offset, and refresh it on syncIntervalMs (default one hour). The SDK comments mark this as not the first recommendation. Sync the host clock first.

import { MainClient } from "binance";

const client = new MainClient({
  api_key: process.env.API_KEY_COM,
  api_secret: process.env.API_SECRET_COM,
  disableTimeSync: false,
  syncIntervalMs: 3600000,
  recvWindow: 5000,
});

console.log("offset ms", client.getTimeOffset());

Bybit REST clients default enable_time_sync: false. Turn it on if you want /v5/market/time polled on an interval. syncTimeBeforePrivateRequests re-measures before every private call. Leave that off unless you are debugging a consistently lagged host. One slow time request can stall order placement.

import { RestClientV5 } from "bybit-api";

const client = new RestClientV5({
  key: process.env.API_KEY_COM,
  secret: process.env.API_SECRET_COM,
  enable_time_sync: true,
  sync_interval_ms: 3600000,
  recv_window: 5000,
});

Every WebSocket API client in the catalog supports setTimeOffsetMs(). That is the portable knob when REST auto-sync is missing, including bitget-api, gateio-api, okx-api, and @siebly/kraken-api. Full package list: Siebly SDK overview.

The TypeScript request and response types are strict enough that an agent can emit valid calls without guessing field names. That helps with timestamp-aware code too: recvWindow vs recv_window, api_key vs key, getServerTime() vs getTimestamp(). Use the Siebly AI prompt frameworks if you want that context bundled. The same clients cover kucoin-api and coinbase-api without a separate signing stack.

On Binance this is -1021. The signed timestamp differs from server time by more than recvWindow. Usual causes: drifted host clock, blocked event loop, or a long RTT. Fix NTP, then measure with fetchLatencySummary(). Bybit's equivalent is retCode 10002. See Bybit for the v5 client.

Sync the OS with NTP. Then, if needed, fetch server time and store serverTime - Date.now(). On binance, set disableTimeSync: false. On bybit-api, set enable_time_sync: true. Both refresh on a one-hour timer by default. You can also call getServerTime() yourself and pass an offset into setTimeOffsetMs() or customTimestampFn.

Yes, and you should. NTP is the baseline. It is not always enough. Exchange clocks are not a public NTP pool, and a container may not be allowed to step its clock. Use the exchange time endpoint as the source of truth for the offset you apply to signatures. AWS and GCP hosts under CPU steal still produce intermittent -1021 / 10002 if you only trust NTP.

5,000 ms is the SDK default on Binance, Bybit, Bitget, BitMart, and Gate. 5,000 to 10,000 ms is the usual production range. Binance allows up to 60,000 ms. Do not use the max unless you understand the replay cost. Same-region hosts can run 2,000 ms. OKX, KuCoin, Kraken, Coinbase, and HTX do not take recvWindow on REST.

Not by default, and not on every package. binance applies an offset when disableTimeSync is false. bybit-api applies one when enable_time_sync is true. Both re-sync on syncIntervalMs / sync_interval_ms (default one hour). OKX REST uses new Date().toISOString() with no offset. Kraken, KuCoin, and HTX take customTimestampFn. WebSocket API clients take setTimeOffsetMs(). Rate-limit throttling is still your code.

To block replay and to drop stale commands. A millisecond timestamp (or an ISO timestamp, or a JWT exp) lets the venue prove the request is recent. It also helps order sequence under load. The signature covers that timestamp, so changing it after the fact invalidates the request.

Latency burns recvWindow. If RTT is larger than the window, a correct local timestamp still expires in flight. That is why people colocate in AWS Tokyo for Binance. keepAlive: true removes handshake cost on later REST calls. Cheap serialization helps. A blocked event loop does not.

Use a stored offset. Fetching time before every private call adds a mandatory round-trip and consumes public rate limits. Fetch once at startup, refresh every 30 to 60 minutes, and re-sync if timestamp errors spike. Binance and Bybit already do that hourly timer when you opt in.