The SDK comes from the same maintainers as the binance, bybit-api and okx-api JS SDKs, with over 4.5 million npm downloads across 10+ SDKs. The overview lives in the KuCoin JavaScript SDK docs, and the full walkthrough (Futures test orders, the WebSocket API, reconnect recovery, regional hosts and proxies) is the KuCoin API JavaScript tutorial for Node.js.

What you get

Start with the Classic clients unless you specifically need the newer Unified Account or Pro APIs.

Install and API keys

npm install kucoin-api

Public market data needs no credentials. Private calls, private streams and order commands need three values: KUCOIN_API_KEY, KUCOIN_API_SECRET and KUCOIN_API_PASSPHRASE. The passphrase is the one you chose when creating the key, not your account password.

Use a General-only key while you build account views, and add Spot or Futures permission only when you start testing orders. Nothing here needs Withdrawal permission. Keep keys server-side and out of logs.

A few naming details save time later: Spot symbols look like BTC-USDT, Futures symbols like XBTUSDTM, and a Futures size is a number of contracts rather than an amount of BTC. Successful REST responses come back as { code: '200000', data }.

1. Public REST

import { SpotClient } from 'kucoin-api';

const client = new SpotClient();

async function main() {
  const time = await client.getServerTime();
  console.log('Server time:', time.data);

  const ticker = await client.getTicker({ symbol: 'BTC-USDT' });
  console.log('BTC-USDT ticker:', ticker.data);

  const book = await client.getOrderBookLevel20({ symbol: 'BTC-USDT' });
  console.log('Best bid:', book.data.bids[0], 'best ask:', book.data.asks[0]);

  const candles = await client.getKlines({ symbol: 'BTC-USDT', type: '1hour' });
  console.log('Latest candle:', candles.data[0]);
}

main().catch(console.error);

Prices and sizes are usually strings. Keep them that way when sending values back to KuCoin, and convert deliberately when you calculate.

2. Private REST

The same client takes credentials and signs every request.

import { SpotClient } from 'kucoin-api';

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

async function main() {
  const balances = await client.getBalances({ type: 'trade' });
  console.log('Spot trading balances:', balances.data);

  const openOrders = await client.getHFActiveOrdersPaginated({
    symbol: 'BTC-USDT',
    pageNum: 1,
    pageSize: 20,
  });
  console.log('Open orders:', openOrders.data.items);
}

main().catch(console.error);

The client throws when KuCoin returns a non-success business code. Parsed errors carry the HTTP status, body, headers and request context, with the key, secret and passphrase left out. Methods with HF in the name map to KuCoin's current high-frequency Spot endpoints.

3. Public WebSocket streams

Classic subscriptions take a topic and a wsKey. The SDK fetches the connection token, opens the right connection, keeps it alive and resubscribes after a reconnect.

import { WebsocketClient, WS_KEY_MAP } from 'kucoin-api';

const ws = new WebsocketClient();

ws.on('update', (update) => console.log(update.wsKey, update.topic, update.data));
ws.on('response', (response) => console.log('response', response.type));
ws.on('reconnected', ({ wsKey }) => console.log('reconnected', wsKey));
ws.on('exception', (error) => console.error('ws error', error));

ws.subscribe('/market/ticker:BTC-USDT', WS_KEY_MAP.spotPublicV1);
ws.subscribe('/contractMarket/tickerV2:XBTUSDTM', WS_KEY_MAP.futuresPublicV1);

process.once('SIGINT', () => ws.closeAll());

A welcome response means the connection is ready, and an ack confirms the subscription. Market data arrives through update.

4. Private streams

Spot and Futures private topics use separate connections, so keep the wsKey with every event.

import { WebsocketClient, WS_KEY_MAP } from 'kucoin-api';

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

ws.on('update', (update) => console.log('private', update.wsKey, update.topic));
ws.on('exception', (error) => console.error('ws error', error));

ws.subscribe(['/spotMarket/tradeOrdersV2', '/account/balance'], WS_KEY_MAP.spotPrivateV1);
ws.subscribe(
  ['/contractMarket/tradeOrders:XBTUSDTM', '/contractAccount/wallet'],
  WS_KEY_MAP.futuresPrivateV1,
);

5. A Spot test order

KuCoin's test-order endpoint checks authentication and order fields without touching the matching engine. Read the symbol metadata first so the size meets the minimums.

import { SpotClient } from 'kucoin-api';

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

async function main() {
  const { data: symbol } = await client.getSymbol({ symbol: 'BTC-USDT' });
  const { data: ticker } = await client.getTicker({ symbol: 'BTC-USDT' });

  const price = Number(ticker.bestBid);
  const step = Number(symbol.baseIncrement);
  const minSize = Math.max(Number(symbol.baseMinSize), Number(symbol.minFunds) / price);
  const decimals = (symbol.baseIncrement.split('.')[1] || '').length;
  const size = (Math.ceil(minSize / step) * step).toFixed(decimals);

  const result = await client.submitHFOrderTest({
    clientOid: client.generateNewOrderID(),
    symbol: 'BTC-USDT',
    side: 'buy',
    type: 'limit',
    price: ticker.bestBid,
    size,
    timeInForce: 'GTC',
    postOnly: true,
  });
  console.log('Spot order test:', result);
}

main().catch(console.error);

The test endpoint is good for checking credentials, permissions, signing and order fields. It doesn't test matching, fills, cancellation or private order updates; the full tutorial covers those with the WebSocket API.

Where to go next

• KuCoin JavaScript SDK docs for the client overview.
• KuCoin API JavaScript tutorial for Futures test orders, the WebSocket API, reconnect recovery, regional hosts and proxies.
• kucoin-api on GitHub for examples and the endpoint map.

More docs

API reference and usage guides also live on the Siebly docs portal (Hyperliquid, Bybit and Binance pages so far).

Everything below uses classes and methods exported by the package. The full reference lives in the Hyperliquid JavaScript SDK docs.

What you get

• One RestClient for public market data, account information, orders, transfers and more.
• A WebsocketClient with heartbeats, automatic reconnect and resubscribe.
• A WebsocketAPIClient that mirrors the REST methods over Hyperliquid's WebSocket POST protocol.
• TypeScript declarations for requests and responses, with dual ESM and CommonJS builds.
• Testnet support through a single testnet: true option.

Install

The package supports Node.js 22 or newer.

npm install @siebly/hyperliquid-api

TypeScript is optional, but the type declarations make the request shapes much easier to discover in your editor.

Your first public REST call

Public Info methods need no credentials. Start by checking the exchange status, then pull mid prices and an order book:

import { RestClient } from '@siebly/hyperliquid-api';

const client = new RestClient();

async function main() {
  const status = await client.getExchangeStatus();
  console.log('Exchange status:', status);

  // AllMidsResponse is Record<string, string>: coin to mid price
  const mids = await client.getAllMids();
  console.log('Coins with a mid price:', Object.keys(mids).length);
  console.log('BTC mid:', mids['BTC'] ?? 'not listed');

  const book = await client.getOrderBook({
    coin: 'BTC',
    nSigFigs: 5,
  });

  if (book) {
    console.log('Best bid level:', book.levels[0][0]);
  }
}

main().catch((error) => {
  console.error('Request failed:', error);
});

The SDK uses readable get... names rather than Hyperliquid's internal request type names, so getAllMids() maps to the allMids Info request and getOrderBook() to l2Book.

You can also read any public account by address, without a key:

const user = '0x1234567890123456789012345678901234567890';

const perpSummary = await client.getPerpAccountSummary({ user });
const spotBalances = await client.getSpotBalances({ user });

Authenticated client setup

Signed methods take a private key, and that key belongs on a trusted backend only. Read it from an environment variable rather than hard-coding it:

import { RestClient } from '@siebly/hyperliquid-api';

const privateKey = process.env.HYPERLIQUID_PRIVATE_KEY;

if (!privateKey) {
  throw new Error('Set HYPERLIQUID_PRIVATE_KEY before starting.');
}

const client = new RestClient({
  privateKey,
  testnet: true,
});

const balances = await client.getBalances();
console.log('Account:', balances.user);
console.log('Spot:', balances.spot.balances);
console.log('Perpetuals:', balances.perp.assetPositions);

const openOrders = await client.getOpenOrders();
console.log('Open orders:', openOrders.length);

A few notes:

• Use testnet first. testnet: true points the client at Hyperliquid's testnet API, so you can exercise signing and order flows without touching a real account.
• Keep keys server-side. Never put a private key in frontend code, browser storage or a public environment variable. Public REST calls and public subscriptions are browser-safe; signed calls are not.
• Custom signers. If you would rather not hand the SDK a raw key, the constructor also accepts a signer with a portable signTypedData implementation.

Once that works, the client exposes helpers for common order workflows. This places a post-only limit order on testnet:

const order = await client.submitLimitOrder({
  symbol: 'BTC',
  side: 'buy',
  size: '0.001',
  price: '50000',
  timeInForce: 'GTC',
});

if (order.status === 'ok') {
  console.log(order.response.data);
}

Exchange methods return an ExchangeResponse wrapper, so check status === 'ok' before reading response.data. For the full order surface, including submitOrder() with raw Hyperliquid order fields and submitMarketOrder(), see the Hyperliquid API JavaScript tutorial.

Subscribing to WebSocket streams

WebsocketClient opens connections when they are first needed, deduplicates matching subscriptions, sends heartbeats, and reconnects then resubscribes after a drop. You register listeners once and subscribe to topics separately:

import { WebsocketClient } from '@siebly/hyperliquid-api';

const ws = new WebsocketClient({ testnet: true });

ws.on('message', (event) => {
  if (event.channel === 'l2Book') {
    console.log(event.wsKey, event.data.coin, event.data.levels);
  } else if (event.channel === 'trades') {
    console.log(event.wsKey, event.data);
  }
});

ws.on('response', (event) => {
  console.log('Acknowledgement:', event.wsKey, event.channel, event.data);
});

ws.on('reconnected', ({ wsKey }) => {
  console.log('Reconnected:', wsKey);
});

ws.on('exception', ({ wsKey, event, data }) => {
  console.error('WebSocket exception:', wsKey, event ?? data);
});

const book = {
  type: 'l2Book',
  coin: 'BTC',
  nSigFigs: 5,
} as const;

const trades = { type: 'trades', coin: 'ETH' } as const;

await ws.subscribe([book, trades]);

// Later, when the feeds are no longer needed:
// await ws.unsubscribe([book, trades]);
// ws.closeAll();

subscribe() resolves once the socket is open and the request has been sent. The server's acknowledgement arrives on the response event, and data arrives on message with the upstream envelope intact plus a wsKey.

Coin identifiers such as BTC, @107 or PURR/USDC pass straight through. If you want to resolve a readable alias first, there is a helper:

const coin = await ws.nameToCoin('HYPE/USDC');
await ws.subscribe({ type: 'trades', coin });

Reconnect timing, ping interval and pong deadline are all configurable through the constructor options if the defaults do not suit your deployment.

Request and response over WebSockets

If you want the REST-style methods but over a persistent socket, WebsocketAPIClient provides the same Info and Exchange methods as RestClient:

import { WebsocketAPIClient } from '@siebly/hyperliquid-api';

const client = new WebsocketAPIClient({ testnet: true });
const mids = await client.getAllMids();
console.log(mids);
client.close();

Debugging tips

• Pass a custom logger as the second argument to WebsocketClient to see pings, subscriptions and messages at trace level.
• RestClient accepts Axios-compatible network options as its second argument, which lets you route requests through a local debugging proxy. Avoid logging signed /exchange bodies.
• If Hyperliquid ships a new operation before the SDK has a typed wrapper, submitRawInfoRequest() keeps it usable in the meantime.

Next steps

• Read the Hyperliquid JavaScript SDK docs for the overview and feature list.
• Work through the Hyperliquid API JavaScript tutorial for Node.js, which covers perpetual and Spot orders, account streams, the WebSocket API, testnet and proxies in more depth.
• Follow the Hyperliquid SDK quickstart guide on GitHub for complete end-to-end workflows.
• Check Hyperliquid SDK release notes for recent changes.
• Browse the source and examples in the sieblyio/hyperliquid-api repository, or install from npm.

Questions or bug reports are welcome on the GitHub issues tab.

The fix

Only the port changes. The host and path stay the same, and wss:// uses 443 by default.

wss://ws.okx.com:8443/ws/v5/public     ->  wss://ws.okx.com/ws/v5/public
wss://ws.okx.com:8443/ws/v5/private    ->  wss://ws.okx.com/ws/v5/private
wss://ws.okx.com:8443/ws/v5/business   ->  wss://ws.okx.com/ws/v5/business
wss://wspap.okx.com:8443/ws/v5/public  ->  wss://wspap.okx.com/ws/v5/public   (demo)

The same applies to the EEA and US hosts (wseea.okx.com, wsus.okx.com and their demo versions).

Look for leftovers in config, env vars and deploy scripts:

grep -rn ":8443" .

Check it's really fixed

Getting connected isn't enough. Confirm that subscriptions are acknowledged and that updates keep arriving:

import WebSocket from 'ws';

const ws = new WebSocket('wss://ws.okx.com/ws/v5/public');

ws.on('open', () => {
  ws.send(JSON.stringify({
    op: 'subscribe',
    args: [{ channel: 'tickers', instId: 'BTC-USDT' }],
  }));
  setInterval(() => ws.send('ping'), 25_000);
});

ws.on('message', (raw) => {
  const text = raw.toString();
  if (text === 'pong') return;
  console.log(JSON.parse(text));
});

If you use an SDK

Check which version you have installed and whether it hard-codes a port. The OKX JavaScript SDK (okx-api) connects on the default port and has no :8443 in its endpoints. It also defaults REST to OKX's newer https://openapi.okx.com domain. The OKX JavaScript tutorial covers reconnects and private streams.

Source: OKX port 8443 announcement.