WebSocket API Client

What is the WebsocketAPIClient?

WebsocketAPIClient is a REST-like wrapper around OKX’s WebSocket API. It exposes each WS API operation as a typed async method that returns a Promise — so you write the same await-based code you use with a REST client, but requests travel over a persistent WebSocket connection. Internally, every method calls WebsocketClient.sendWSAPIRequest() and resolves when the matching response arrives. The client automatically:

Authenticates the connection using your API credentials
Routes order book operations over the private channel
Routes spread trading operations over the business channel
Reconnects and re-authenticates automatically on connection failure

When to use WebsocketAPIClient vs RestClient

	`RestClient`	`WebsocketAPIClient`
Transport	HTTPS	Persistent WebSocket
Round-trip latency	Higher (TCP + TLS handshake per request)	Lower (connection already open)
Order placement	Yes	Yes
Market data & account streams	No	Use `WebsocketClient` instead
Interface style	`async`/`await`	`async`/`await`

Use WebsocketAPIClient when latency on order operations matters. For everything else — market data subscriptions, account streams — use WebsocketClient.

How it works internally

WebsocketAPIClient wraps WebsocketClient and delegates every call to sendWSAPIRequest():

// Internally, submitNewOrder() does:
return this.wsClient.sendWSAPIRequest(
  this.getWSClient().getMarketWsKey('private'),
  'order',
  params,
);

You can call sendWSAPIRequest() directly via wsClient.getWSClient() if you need lower-level access.

Constructor

new WebsocketAPIClient(
  options?: WSClientConfigurableOptions & Partial<WSAPIClientConfigurableOptions>,
  logger?: DefaultLogger,
)

Configuration options

APICredentials[]

One or more API credential objects. Required for all order operations. Each entry has apiKey, apiSecret, and apiPass.

'prod' | 'EEA' | 'US'

default:"'prod'"

The OKX region to connect to:

'prod' — global (www.okx.com)
'EEA' — European Economic Area (my.okx.com)
'US' — United States (app.okx.com)

boolean

default:"false"

Set to true to use OKX’s demo trading environment.

boolean

default:"true"

When true, the client attaches default console.log event listeners for connection events (open, reconnect, reconnected, authenticated, exception). Set to false and attach your own listeners via wsClient.getWSClient().on(...) if you want custom handling.

number

How often (in milliseconds) to send a ping to keep the connection alive.

number

Delay in milliseconds before attempting to respawn a dropped connection.

Basic setup

Install the package

npm install okx-api

yarn add okx-api

Create the client

import { WebsocketAPIClient } from 'okx-api';
// CommonJS: const { WebsocketAPIClient } = require('okx-api');

const wsClient = new WebsocketAPIClient({
  accounts: [
    {
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET,
      apiPass: process.env.API_PASSPHRASE,
    },
  ],
  // For EEA users: market: 'EEA'
  // For US users:  market: 'US'
});

Place your first order

try {
  const res = await wsClient.submitNewOrder({
    instId: 'BTC-USDT',
    tdMode: 'cash',
    side: 'buy',
    ordType: 'market',
    sz: '100',
  });
  console.log('Order result:', res);
} catch (e) {
  console.error('Order failed:', e);
}

The WebSocket connection is established lazily on the first request. To avoid the cold-start delay on your first order, call await wsClient.connectWSAPI() at startup.

Custom event listeners

By default the client logs connection events to the console. To use your own handlers, set attachEventListeners: false and listen on the embedded WebsocketClient:

const wsClient = new WebsocketAPIClient(
  { accounts: [...], attachEventListeners: false },
);

wsClient.getWSClient()
  .on('open', ({ wsKey }) => console.log('Connected', wsKey))
  .on('reconnected', ({ wsKey }) => console.log('Reconnected', wsKey))
  .on('authenticated', ({ wsKey }) => console.log('Authenticated', wsKey))
  .on('exception', (data) => console.error('WS error', data));

Get Started

REST Client

WebSocket Client

Guides

WebSocket API Client

What is the WebsocketAPIClient?

When to use WebsocketAPIClient vs RestClient

How it works internally

Constructor

Configuration options

Basic setup

Custom event listeners

Explore the available operations

Order management

Spread orders

​What is the WebsocketAPIClient?

​When to use WebsocketAPIClient vs RestClient

​How it works internally

​Constructor

​Configuration options

​Basic setup

​Custom event listeners

​Explore the available operations

Order management

Spread orders

What is the WebsocketAPIClient?

When to use WebsocketAPIClient vs RestClient

How it works internally

Constructor

Configuration options

Basic setup

Custom event listeners

Explore the available operations