KuCoin Futures API Node.js SDK: 2026 Integration Guide

Public endpoints do not need keys. Private ones do. Futures also means leverage, margin mode, and position state.

Two rate-limit models exist. Do not quote UTA numbers against classic futures REST:

• Classic futures (FuturesClient, api-futures.kucoin.com): VIP0 is 2000/30s on the Futures pool.
• UTA / Pro (UnifiedAPIClient): VIP0 is 300/s on the UTA Trading pool (includes WebSocket manage-order).

Hit 429 and you wait. The SDK will not slow you down.

WebSocket clients need heartbeats, reconnect, and resubscribe. Clock drift kills signed REST. Docs are split across classic futures, spot, and Pro/UTA. A maintained SDK already does the reconnect loop. You should not be writing ping/pong from scratch in 2026.

const { FuturesClient } = require("kucoin-api");

const futuresClient = new FuturesClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});

There is no testnet: true switch. KuCoin's sandbox URLs are dead.

Timestamps come from Date.now() unless you pass customTimestampFn. The SDK does not fetch KuCoin server time on every request. Keep the machine clock in sync. FuturesClient.getServerTime() exists if you want to compare.

Public calls do not need keys:

const client = new FuturesClient();

const ticker = await client.getTicker({ symbol: "XBTUSDTM" });
console.log(ticker);

Least privilege. Disable withdrawals on bot keys. Whitelist IPs. Split market-data keys from execution keys if you can. Put secrets in environment variables, not in git.

The kucoin-api tutorial is the shortest path if you are migrating off raw axios.

This is the futures order path from the SDK's own WS API example. Far-from-market limit price so you do not accidentally fill while testing:

const { WebsocketAPIClient } = require("kucoin-api");

const wsClient = new WebsocketAPIClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});

const futuresOrderResponse = await wsClient.submitFuturesOrder({
  clientOid: "futures-test-" + Date.now(),
  side: "buy",
  symbol: "XBTUSDTM",
  marginMode: "CROSS",
  type: "limit",
  price: "1000",
  qty: "0.01",
  leverage: 10,
  positionSide: "LONG", // needed in hedge / two-way mode
});

console.log("Futures order response:", futuresOrderResponse);

Same client can cancel:

const cancelFuturesResponse = await wsClient.cancelFuturesOrder({
  symbol: "XBTUSDTM",
  orderId: "your-order-id",
});

If you prefer classic REST:

const orderRes = await futuresClient.submitOrder({
  clientOid: futuresClient.generateNewOrderID(),
  side: "buy",
  type: "limit",
  price: "1000",
  symbol: "XBTUSDTM",
  size: 1,
  leverage: 2,
});

Note the field names. REST classic uses size. WebSocket API futures uses qty. Copy from the SDK examples, not from memory.

Private account streams still matter after the ack. Partial fills and position updates come on the user-data WebSocket, not on the order-ack promise.

You do not need to implement ping or exponential backoff. WebsocketClient already:

• sends heartbeats (pingInterval / pongTimeout are configurable)
• reconnects (reconnectTimeout, default 500ms)
• resubscribes after reconnect
• emits reconnect and reconnected so you can log or pause your own logic

const { WebsocketClient } = require("kucoin-api");

const client = new WebsocketClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});

client.on("open", (data) => console.log("open:", data?.wsKey));
client.on("reconnect", (data) => console.log("reconnect:", data));
client.on("reconnected", (data) => console.log("reconnected:", data));
client.on("close", (data) => console.error("close:", data));
client.on("exception", (data) => console.error("exception:", data));

Listen to those events. Do not roll your own reconnect loop on top, or you will fight the SDK. For more reconnect patterns, see Solving WebSocket Reconnection Challenges.

Classic public futures topics (no keys):

const { WebsocketClient } = require("kucoin-api");

const client = new WebsocketClient();

client.on("update", (data) => {
  console.info("data received:", JSON.stringify(data));
});

client.subscribe(
  [
"/contractMarket/tickerV2:XBTUSDTM",
"/contractMarket/ticker:XBTUSDTM",
"/contractMarket/level2:XBTUSDTM",
"/contractMarket/level2Depth5:XBTUSDTM",
"/contractMarket/level2Depth50:XBTUSDTM",
  ],
  "futuresPublicV1",
);

Pro/UTA public futures uses futuresPublicProV2 and topic objects (ticker, obu, trade) instead of the old /contractMarket/... strings. See examples/WebSockets/ws-public-futures-pro-v2.ts in the repo if you are on Pro.

Keep ingestion off the execution path. Building Scalable Market Data Ingestion Pipelines covers that split.

KuCoin delisted sandbox (web and API) on 10 July 2023. There is no replacement environment.

Classic futures has a test-order endpoint. Same params as a real order. It does not go to matching:

const testRes = await futuresClient.submitNewOrderTest({
  clientOid: futuresClient.generateNewOrderID(),
  side: "buy",
  type: "limit",
  price: "1000",
  symbol: "XBTUSDTM",
  size: 1,
  leverage: 2,
});

That checks signing and payload shape. It is not paper trading. For live behavior you still need a funded account and tiny size.

If you use coding agents, the Siebly AI Prompt Frameworks give them the endpoint context so they stop inventing params. Still read the SDK types. Agents love mixing size and qty.

Throttle yourself. Classic futures and UTA/Pro limits are not the same number. Start with submitNewOrderTest, then a far-from-market limit, then live. kucoin-api on Siebly.io has the REST and WS clients used above.

Decouple collectors from executors. If the book handler stalls, orders should still cancel. See Algorithmic Trading System Architecture in Node.js.

Migration is: drop homemade signing, pass the three credentials, call FuturesClient / WebsocketAPIClient. Watch siebly.io/releases for endpoint changes.

If you run multiple processes, put rate limiting in one place. Classic futures VIP0 is 2000/30s. UTA trading VIP0 is 300/s. Subaccounts on classic have independent quotas. UTA master/sub share a pool you can split. The SDK will happily 429 if you ignore this.

No. kucoin-node-sdk was archived on 4 March 2025. KuCoin's official successor is kucoin-universal-sdk. If you want the Siebly client used in this article, that is kucoin-api on npm. It is not futures-only. It also has SpotClient, BrokerClient, UnifiedAPIClient, and the shared WebSocket clients.

You pass apiKey, apiSecret, and apiPassphrase. The SDK builds KC-API-SIGN with HMAC-SHA256 over timestamp + method + endpoint + body, sets KC-API-TIMESTAMP from local time, and sends a signed passphrase in KC-API-PASSPHRASE (key version 2). There is no nonce. Wrong clocks still fail. Optional customSignMessageFn can use Node's createHmac if Web Crypto is too slow for you. See examples/auth/fasterHmacSign.ts.

No. That is intentional. Classic futures and UTA/Pro have different pools and VIP tables. Build your own limiter. Watch 429 / 429000. On a distributed setup, one shared limiter beats N containers all guessing.

Yes. WebsocketAPIClient.submitFuturesOrder() (and cancel / batch variants) sends the command on the WebSocket API and returns a promise when KuCoin replies. Market data still uses WebsocketClient.subscribe(...). Those are different connections.

Yes. The package is written in TypeScript. Request and response types live next to FuturesClient, UnifiedAPIClient, and WebsocketAPIClient. JavaScript works the same via require('kucoin-api').

You mostly don't. The SDK heartbeats and reconnects, then resubscribes. Hook reconnect, reconnected, close, and exception so your strategy knows the book might be stale. Tune pingInterval, pongTimeout, and reconnectTimeout if the defaults do not fit. Do not start a second reconnect state machine.

Env vars or a secret manager. No withdrawals on trading keys. IP whitelist. Least privilege. Passphrase is not the login password.

No, because KuCoin does not have one. Sandbox was delisted on 10 July 2023. kucoin-api does not expose a working testnet URL. Use FuturesClient.submitNewOrderTest() to validate a payload without matching. Then use small live orders. There is no paper-trading venue to toggle in the constructor.

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.*