OKX Perpetual Futures API Node.js: A Professional Engineering Guide

OKX routes traffic by registration region. Pick the wrong host and private calls fail auth.

The okx-api market option maps to those hosts:

• Global (default): market: 'GLOBAL' or omit it.

Those values are uppercase. market: 'eea' is not a valid SDK option.

Demo trading is a separate flag, not a market. Do not set market: 'demo'. The client throws if you do. Use demoTrading: true. That adds the x-simulated-trading: 1 header on REST and switches WebSockets to the demo endpoints.

V5 is built around Unified Account. Margin can be shared across perpetuals, spot, and options, depending on the mode. There are four modes, not three:

• Spot mode (acctLv: '1'): spot and options buy-only. No futures, no margin, no swaps.
• Futures mode (acctLv: '2'): single-currency margin. You can trade swaps. Cross margin is per settlement currency.
• Multi-currency margin (acctLv: '3'): all instruments share margin. Assets are valued in USD for collateral.
• Portfolio margin (acctLv: '4'): risk-based margin across the book. Aimed at professional desks.

Read the mode with getAccountConfiguration() before you send a swap order. Spot mode will reject it. This check belongs in startup, not after the first fill fails.

Private REST calls need an API key, secret, and passphrase. The sign string is timestamp + method + requestPath + body, hashed with HMAC-SHA256 and base64-encoded. okx-api builds that for you, including the OK-ACCESS-PASSPHRASE header.

Install the package:

npm install okx-api

It ships TypeScript definitions for V5 requests and responses. A public call is enough to prove the host is reachable before you touch private endpoints.

import { RestClient } from "okx-api";

const client = new RestClient({
  // Global users can omit market. Default is www.okx.com.
  // market: 'EEA', // EEA users (my.okx.com / eea.okx.com)
  // market: 'US',  // US users (app.okx.com / us.okx.com)
});

const ticker = await client.getTicker({ instId: "BTC-USDT-SWAP" });
console.log(ticker);

getTicker is public. No keys required.

Do not hardcode the API key, secret, or passphrase. Load them from the environment or a secret manager. In the OKX dashboard, turn off withdrawal on automation keys and pin them to known IPs. Align internal controls with FINRA Algorithmic Trading Supervision if that applies to your desk.

RestClient takes apiKey, apiSecret, and apiPass. market is optional. Only set it when you are not on Global.

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_PASSPHRASE_COM,
  demoTrading: true,
});

For a walkthrough of these patterns on futures workflows, see the okx-api tutorial.

The SDK signs and sends. It does not throttle. Successful RestClient calls return the unwrapped data array, not the raw Axios response, so you will not see x-ratelimit-remaining on the value you await. Build your own limiter. Hitting the cap can mean a temporary ban. Keep client construction in one module so REST and WebSocket share the same credentials and region.

Use setLeverage from the okx-api RestClient. Pass the swap instId, the leverage as a string, and mgnMode as cross or isolated.

const leverage = await client.setLeverage({
  instId: "BTC-USDT-SWAP",
  lever: "5",
  mgnMode: "cross",
});
console.log(leverage);

Isolated caps loss to that position. Cross shares collateral across the account. Position mode is a second switch:

• long_short_mode (hedge): you can hold long and short on the same swap.
• net_mode (one-way): a sell reduces an existing long.

const posMode = await client.setPositionMode({
  posMode: "net_mode",
});
console.log(posMode);

In hedge mode, orders need posSide: 'long' or posSide: 'short'. In net mode you omit it. Check the response before you send size.

A REST market order on the swap looks like this (from the commented SWAP path in the SDK examples):

const order = await client.submitOrder({
  instId: "BTC-USDT-SWAP",
  tdMode: "cross",
  ordType: "market",
  side: "buy",
  sz: "0.01",
});
console.log(order);

tdMode: 'cash' is spot. Swaps use cross or isolated.

Keep a local picture of the unified account or you will invent ghost positions. Polling is fine for startup. Live trading should follow private WebSocket events.

const config = await client.getAccountConfiguration();
console.log("account level", config[0]?.acctLv, "posMode", config[0]?.posMode);

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

The method is getBalance, not getAccountBalance. acctLv is '1' through '4' as listed above.

Watch margin ratio and equity. If equity cannot cover initial margin, OKX rejects the order. For a higher-level cache of account and position state, see the Siebly AI exchange state framework.

Raw sockets push events. You then have to match request IDs yourself. okx-api wraps that in WebsocketAPIClient. Each call returns a promise that resolves when OKX sends the matching response.

Use the typed helpers (submitNewOrder, cancelOrder, amendOrder, submitMultipleOrders). sendWSAPIRequest lives on WebsocketClient. WebsocketAPIClient already calls it for you.

import { WebsocketAPIClient } from "okx-api";

const wsApi = new WebsocketAPIClient({
  demoTrading: true,
  accounts: [
{
apiKey: process.env.API_KEY_COM,
apiSecret: process.env.API_SECRET_COM,
apiPass: process.env.API_PASSPHRASE_COM,
},
  ],
});

const result = await wsApi.submitNewOrder({
  instId: "BTC-USDT-SWAP",
  tdMode: "cross",
  side: "buy",
  ordType: "market",
  sz: "0.01",
});
console.log(result);

Credentials go in accounts, not as top-level apiKey on WebsocketAPIClient. You can call connectWSAPI() early if you want the socket warm before the first order. Otherwise the client opens it on demand.

The SDK already heartbeats the socket, tears down a dead connection, reconnects, re-auths, and resubscribes. You do not need to send manual pings on top of that. Hook the client events so your process knows when the link bounced.

Private fills and balances come from WebsocketClient (the stream client), not from WebsocketAPIClient (the order-entry client). Subscribe to account and position channels:

import { WebsocketClient } from "okx-api";

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

ws.on("update", (data) => {
  console.log("ws update", JSON.stringify(data));
});
ws.on("reconnect", ({ wsKey }) => {
  console.log("reconnecting", wsKey);
});
ws.on("reconnected", (data) => {
  console.log("reconnected", data?.wsKey);
});
ws.on("exception", (data) => {
  console.error("ws exception", data);
});

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

That is the same pattern as the SDK demo-trading example. For reconnect architecture notes, see the Siebly guide on WebSocket reconnection. Full client docs: OKX Node.js SDK documentation.

WebSocket order entry shares OKX trading rate limits with REST. The SDK will not queue or delay those calls for you.

okx-api does not rate-limit. A token bucket or priority queue in your process should wrap both RestClient and WebsocketAPIClient.

Limits differ by endpoint. Place, cancel, and amend are commonly 60 requests per 2 seconds per instrument. Balance and position reads are tighter (often 10 per 2 seconds). Public unauthenticated limits are per IP. Private limits are per user. WS and REST trading share the same bucket.

Do not expect x-ratelimit-remaining on the object RestClient returns. Successful calls unwrap to data only. If you need exchange-side usage for orders, call getAccountRateLimit().

Do not ship new execution to live first. Demo trading mirrors V5 with virtual funds.

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

That flag is what attaches x-simulated-trading: 1. There is no market: 'demo'. Use it to exercise partial fills, rejects, and reconnects. For how to split these pieces in a Node.js desk, see Siebly.io algorithmic trading architecture.

Keep withdrawal off on bot keys. Log every request and response you care about for post-trade review. Combined with the OKX Node.js SDK, that is a workable production baseline.

You handle them. okx-api does not throttle. RestClient also does not return rate-limit headers on success, because it returns the unwrapped data payload. Put a token bucket in front of RestClient and WebsocketAPIClient. Order place/cancel/amend is often 60 per 2 seconds. Reads such as balance are often 10 per 2 seconds. getAccountRateLimit() reports order-entry usage from the exchange.

REST is request-response over HTTP. Use it for leverage, position mode, account config, and snapshots. The WebSocket API keeps a socket open for place, amend, and cancel. WebsocketAPIClient makes those operations look like REST (await submitNewOrder(...)) without the handshake cost. Market data and account pushes use WebsocketClient subscriptions.

Yes. The package is TypeScript-first. Request and response types cover V5, including instId, mgnMode, tdMode, and leverage fields. JavaScript works too via require('okx-api').

Environment variables or a secret manager. RestClient reads apiPass at runtime. Websocket clients take the same value inside accounts[].apiPass. Disable withdrawals on those keys and restrict by IP.

Yes. Set demoTrading: true on RestClient, WebsocketClient, and WebsocketAPIClient. That is the supported path. market: 'demo' throws. Demo REST requests get x-simulated-trading: 1 automatically. Demo keys are separate from live keys in the OKX UI.

Let the SDK do it. It heartbeats, reconnects, re-authenticates, and resubscribes. Listen for reconnect, reconnected, and exception so your app can pause orders while the socket is down. Do not add a second ping loop on the same connection.

Call setLeverage with instId (for example BTC-USDT-SWAP), lever as a string, and mgnMode of cross or isolated. Leverage is per instrument, not account-wide. In hedge mode you may also pass posSide. Confirm the response, then place the order.

Lower latency on place, amend, and cancel. You keep async/await, but the call rides an already-open socket. Use RestClient for account setup. Use WebsocketClient to subscribe to fills and positions. Use WebsocketAPIClient when the hot path is order entry.

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