--- title: "Crypto Exchange API Timestamp Management in Node.js" description: "Master crypto exchange API timestamp management in Node.js. Fix clock drift and auth failures by syncing server time and managing recvWindow with Siebly SDKs." canonical: "https://siebly.io/blog/crypto-exchange-api-timestamp-management-in-nodejs-a-professional-engineering-guide" --- # Crypto Exchange API Timestamp Management in Node.js: A Professional Engineering Guide Master crypto exchange API timestamp management in Node.js. Fix clock drift and auth failures by syncing server time and managing recvWindow with Siebly SDKs. ## Technical Disclaimer These articles are software engineering references for exchange API integrations. They are not financial, investment, legal, tax, compliance, or trading advice. Use public data, demo, testnet, or paper workflows first. Keep API credentials out of frontend code and disable withdrawal permissions for automation keys. ## Overview {#overview} Why does a cryptographically perfect request fail the moment it hits an exchange gateway? For engineers building high-frequency integrations, few issues are as persistent or as disruptive as clock drift. When your local system time deviates from the exchange server time by even a few seconds, authentication fails. Timestamp handling in a Node.js exchange client is more than an NTP checkbox. You need a clear picture of how each venue validates time, what `recvWindow` actually means, and which SDK options exist. You've likely seen a containerized Node.js 24 process lose sync and start rejecting orders on Binance or Coinbase. The usual cause is a drifted host clock, not a bad signature. This guide walks through that failure mode and shows how Siebly SDKs such as [binance](/sdk/binance/javascript), [bybit-api](/sdk/bybit/javascript), and [okx-api](/sdk/okx/javascript) attach timestamps, expose server-time helpers, and (on a couple of venues) optionally apply an offset. By the end, you should know what the libraries already do, what they do not do, and where you still have to sync the machine clock. ## Key Takeaways {#key-takeaways} - Clock drift between the host and the exchange server is a common reason signed requests fail, especially in containers that inherit a bad host clock. - Fetch the exchange's own time endpoint, measure the delta against `Date.now()`, and apply that offset if you cannot trust the local clock. - `recvWindow` is a Binance-style validity window (default 5,000 ms, max 60,000 ms on Binance). Bybit, Bitget, BitMart, and Gate have similar knobs. OKX, KuCoin, Kraken, Coinbase, and HTX do not use `recvWindow` on REST. - Automatic periodic time sync is not a catalog-wide constructor flag. It exists on [binance](/sdk/binance/javascript) (`disableTimeSync: false`) and [bybit-api](/sdk/bybit/javascript) (`enable_time_sync: true`). Both default to off. Other SDKs expose `getServerTime()`, `fetchLatencySummary()`, `customTimestampFn`, and `setTimeOffsetMs()`. - Response shapes differ. Binance returns `{ serverTime }`. Bybit v5 wraps `{ timeSecond, timeNano }` in `result` and also sends a top-level `time`. OKX returns `{ ts }` inside a data array. Map those shapes before you store an offset. ## Identifying Timestamp Synchronization Issues in Node.js {#identifying-timestamp-synchronization-issues-in-nodejs} Exchanges like Binance and Bybit require a fresh timestamp on every signed request. If that value is too far from the exchange clock, the request is rejected. That check is the main defense against replay attacks: an intercepted payload should not still be valid minutes later. Clock drift of a few hundred milliseconds is enough to blow a tight window. On Binance the failure is error `-1021` (`Timestamp for this request is outside of the recvWindow`). On Bybit it is typically `retCode` `10002` with a timestamp-window message. NTP is the usual OS-level fix, and it is still the first thing you should do. It is often not enough in containers or serverless runtimes. Containers share the host kernel clock. If that host is loaded, paused, or badly configured, your Node process inherits the drift. ### The Anatomy of a Signed Request {#the-anatomy-of-a-signed-request} 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](/sdk/binance/javascript) client adds `timestamp` and `recvWindow` for you on private REST calls: ```ts title="Imported example" 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](/sdk/bybit/javascript) 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`: ```ts title="Imported example" 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](/sdk/okx/javascript) REST client stamps `OK-ACCESS-TIMESTAMP` with `new Date().toISOString()`: ```ts title="Imported example" 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(); ``` ### Security Boundaries and Replay Attacks {#security-boundaries-and-replay-attacks} 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](/sdk/okx/javascript), 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`. ## Calculating Server Time Offsets for Request Signing {#calculating-server-time-offsets-for-request-signing} The practical fix is an offset, not a forced rewrite of the OS clock from inside Node. Fetch server time, subtract local time, store the delta, then use `Date.now() + offset` for later signatures. That is the same formula the Binance and Bybit REST clients use when time sync is enabled. Do not call `/v3/public/time` on Bybit. The current public clock is `/v5/market/time`. Binance spot is `/api/v3/time`. OKX is `/api/v5/public/time`, not `/api/v5/public/system-time`. ### The Server Offset Algorithm {#the-server-offset-algorithm} Record local time before and after the public time call. A crude offset is `serverTime - Date.now()`. A better one (what [binance](/sdk/binance/javascript) and [bybit-api](/sdk/bybit/javascript) 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: ```ts title="Imported example" 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. ### Handling Clock Drift Over Time {#handling-clock-drift-over-time} 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. ## Implementing Automatic Clock Synchronization in TypeScript {#implementing-automatic-clock-synchronization-in-typescript} Do not place orders before you know the clock is sane. If you roll your own offset, make init awaitable. If you use the SDK helpers, call `fetchLatencySummary()` (or `getServerTime()`) during startup and fail closed if it cannot complete. The annoying part is the response shape. You cannot read `serverTime` off every venue. ### Mapping Exchange-Specific Time Endpoints {#mapping-exchange-specific-time-endpoints} These are the public clocks the SDKs actually call: - [binance](/sdk/binance/javascript): `getServerTime()` hits `/api/v3/time` (spot) and returns a `number` (`serverTime`). - [bybit-api](/sdk/bybit/javascript): `getServerTime()` hits `/v5/market/time` and returns `{ result: { timeSecond, timeNano }, time }`. - [okx-api](/sdk/okx/javascript): `getServerTime()` / `getSystemTime()` hit `/api/v5/public/time`. You get a `number`, or `{ ts: string }[]`. - [bitget-api](/sdk/bitget/javascript): `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](/sdk/coinbase/javascript): `getServerTime()` hits `/api/v3/brokerage/time` and returns `{ iso, epochSeconds, epochMillis }`. - [gateio-api](/sdk/gate/javascript): `getServerTime()` hits `/spot/time` and returns `{ server_time }`. - [kucoin-api](/sdk/kucoin/javascript): `getServerTime()` hits `api/v1/timestamp` and returns `{ data: number }`. - [@siebly/kraken-api](/sdk/kraken/javascript): `getServerTime()` hits `0/public/Time` and returns `{ unixtime, rfc1123 }`. - [@siebly/htx-api](/sdk/htx/javascript): `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. ```ts title="Imported example" 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](/sdk/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: ```ts title="Imported example" 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()`. ### Error Handling and Retries {#error-handling-and-retries} 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. ## Optimizing the recvWindow for High-Latency Environments {#optimizing-the-recvwindow-for-high-latency-environments} On Binance, `recvWindow` is how many milliseconds after `timestamp` the gateway will still accept the request. Default 5,000 ms, max 60,000 ms. A larger window hides latency and drift. It also widens the replay window and means you may be acting on stale data. Tune it to where the process runs. A Node process in AWS Tokyo (`ap-northeast-1`) talking to Binance's Tokyo gateways should see much lower RTT than one in `us-east-1`. If RTT is consistently under 20 ms, a 2,000 ms window is reasonable. BitMart documents the same range (`(0, 60000]`, default 5,000 ms) and lets you set it globally or per call: ```ts title="Imported example" import { RestClient } from "bitmart-api"; const client = new RestClient({ apiKey: process.env.API_KEY, apiSecret: process.env.API_SECRET, apiMemo: process.env.API_MEMO, recvWindow: 10000, }); await client.getAccountBalancesV1({ recvWindow: 5000 }); ``` Bybit's constructor field is `recv_window`, not `recvWindow`. Bitget and Gate use `recvWindow` and default it to 5,000 ms. ### Network Topology and Jitter {#network-topology-and-jitter} 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. ```ts title="Imported example" 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, }); ``` ### Managing Awaitable WebSocket Timestamps {#managing-awaitable-websocket-timestamps} 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. ```ts title="Imported example" 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()`: ```ts title="Imported example" 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](/blog/algorithmic-trading-system-architecture-in-nodejs-a-2026-engineering-guide). To pull the clients into a production service, [start with the Siebly SDK catalog](/). ## Leveraging Siebly SDKs for Automated Timestamp Management {#leveraging-siebly-sdks-for-automated-timestamp-management} Manual HMAC and ISO-timestamp plumbing is busywork. The Siebly Node clients sign private REST and WebSocket API calls for you. That is the real win: you pass credentials, you call `submitOrder()`, the library attaches the timestamp your venue expects. They do not magically keep a drifted VM in sync across every exchange. There is no `enableServerTimeSync` option. Time sync is opt-in, named differently per package, and absent on most REST clients. They also do not throttle you. [binance](/sdk/binance/javascript) can report `getRateLimitStates()`. [bybit-api](/sdk/bybit/javascript) can attach parsed limits with `parseAPIRateLimits: true`. Pacing, retries, and backoff are still yours. ### Opt-in time sync (Binance and Bybit only) {#opt-in-time-sync-binance-and-bybit-only} 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. ```ts title="Imported example" 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. ```ts title="Imported example" 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](/sdk/bitget/javascript), [gateio-api](/sdk/gate/javascript), [okx-api](/sdk/okx/javascript), and [@siebly/kraken-api](/sdk/kraken/javascript). Full package list: [Siebly SDK overview](/sdk). ### Building Reliable Systems with AI Coding Agents {#building-reliable-systems-with-ai-coding-agents} 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](/ai) if you want that context bundled. The same clients cover [kucoin-api](/sdk/kucoin/javascript) and [coinbase-api](/sdk/coinbase/javascript) without a separate signing stack. ## Building Resilient Execution Layers for Systematic Trading {#building-resilient-execution-layers-for-systematic-trading} Do not treat `Date.now()` as the exchange clock. Measure the delta, apply it where the SDK lets you, and keep `recvWindow` (when the venue has one) tight enough that a replay is useless. In containers, NTP on the host still comes first. The SDK offset is a second line of defense. [Explore Siebly SDKs](/sdk) for typed REST and WebSocket API clients on the major venues. They sign requests, expose server time, and on Binance and Bybit can apply a periodic offset if you turn that on. The rest of production reliability (clocks, rate limits, kill switches) stays in your process. ## Frequently Asked Questions {#frequently-asked-questions} ### What is the "timestamp outside of recvWindow" error in Node.js? {#what-is-the-timestamp-outside-of-recvwindow-error-in-node-js} 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](/sdk/bybit/javascript) for the v5 client. ### How do I synchronize my computer clock with Binance or Bybit servers? {#how-do-i-synchronize-my-computer-clock-with-binance-or-bybit-servers} Sync the OS with NTP. Then, if needed, fetch server time and store `serverTime - Date.now()`. On [binance](/sdk/binance/javascript), 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`. ### Can I use NTP to solve crypto exchange API timestamp issues? {#can-i-use-ntp-to-solve-crypto-exchange-api-timestamp-issues} 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. ### What is a safe recvWindow value for a production trading bot? {#what-is-a-safe-recvwindow-value-for-a-production-trading-bot} 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. ### Does the Siebly SDK handle clock drift automatically? {#does-the-siebly-sdk-handle-clock-drift-automatically} 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. ### Why do exchanges require a timestamp for every private API request? {#why-do-exchanges-require-a-timestamp-for-every-private-api-request} 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. ### How does network latency affect my request signing and timestamps? {#how-does-network-latency-affect-my-request-signing-and-timestamps} 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. ### Is it better to use a local offset or fetch server time for every request? {#is-it-better-to-use-a-local-offset-or-fetch-server-time-for-every-request} 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. ## Related articles - [Exchange API Timestamp Synchronization for Node.js Trading Systems](/blog/exchange-api-timestamp-synchronization-for-nodejs-trading-systems) - [Unified Crypto Exchange API in Node.js: A Professional Engineering Roundup for 2026](/blog/unified-crypto-exchange-api-in-nodejs-a-professional-engineering-roundup-for-2026) - [Crypto Exchange SDK: JS, TS, & Node.js Engineering Guide](/blog/crypto-exchange-sdk-js-ts-nodejs-engineering-guide) ## Related Siebly Resources - [Binance JavaScript SDK](/sdk/binance/javascript) - [Bybit JavaScript SDK](/sdk/bybit/javascript) - [OKX JavaScript SDK](/sdk/okx/javascript) - [Siebly SDK directory](/sdk) - [Siebly AI Prompt Framework & Skills](/ai)