Skip to main content

​
Overview

WebsocketAPIClient is a minimal, promise-driven wrapper around WebsocketClient. It lets you submit, cancel, and amend orders over WebSocket using async/await, without managing the underlying connection lifecycle yourself. Each method sends a request over the appropriate private or business WebSocket connection and returns a promise that resolves when the matching response arrives from OKX.
WebsocketAPIClient uses WebsocketClient internally. You can access the underlying client at any time via wsApiClient.getWSClient() to subscribe to channels, listen to events, or call sendWSAPIRequest() directly.
import { WebsocketAPIClient } from 'okx-api';

const client = new WebsocketAPIClient({
  accounts: [
    {
      apiKey: 'YOUR_API_KEY',
      apiSecret: 'YOUR_API_SECRET',
      apiPass: 'YOUR_API_PASSPHRASE',
    },
  ],
});

// Place an order
const result = await client.submitNewOrder({
  instId: 'BTC-USDT',
  tdMode: 'cash',
  side: 'buy',
  ordType: 'market',
  sz: '0.01',
});

​
Constructor

new WebsocketAPIClient(
  options?: WSClientConfigurableOptions & Partial<WSAPIClientConfigurableOptions>,
  logger?: DefaultLogger
)
​
options
object
Accepts all WSClientConfigurableOptions fields (credentials, market, demo trading, etc.) plus the additional options below.
​
logger
DefaultLogger
Optional custom logger.

​
Additional options (WSAPIClientConfigurableOptions)

​
attachEventListeners
boolean
default:"true"
When true, the client automatically attaches default event listeners that log connection lifecycle events (open, reconnect, reconnected, authenticated, exception) to the console.Set to false if you want to handle all events yourself via getWSClient().on(...).

​
Utility methods

​
getWSClient()

getWSClient(): WebsocketClient
Returns the underlying WebsocketClient instance. Use this to subscribe to channels, listen to raw events, or call sendWSAPIRequest() directly.

​
connectWSAPI()

connectWSAPI(): Promise<unknown[]>
Pre-warms both the private and business WebSocket connections and authenticates them. Call this before your first order request to reduce initial latency.

​
setTimeOffsetMs(offsetMs)

setTimeOffsetMs(offsetMs: number): void
Manually set the time offset (ms) between the local clock and OKX servers. Delegates to the underlying WebsocketClient.

​
Order management methods

All order methods require authentication. Credentials must be provided in the constructor options.

​
submitNewOrder(params)

submitNewOrder(
  params: WSAPIPlaceOrderRequestV5
): Promise<WSAPIResponse<[OrderResult], 'order'>>
Place a single new order via the WebSocket API.
​
params
WSAPIPlaceOrderRequestV5
required
Order parameters. Key fields include:
  • instId (string, required) — Instrument ID, e.g. 'BTC-USDT'.
  • tdMode (string, required) — Trade mode: 'cash', 'cross', or 'isolated'.
  • side (string, required) — 'buy' or 'sell'.
  • ordType (string, required) — Order type: 'market', 'limit', 'post_only', 'fok', 'ioc', etc.
  • sz (string, required) — Order size.
  • px (string) — Price. Required for limit orders.
  • ccy (string) — Margin currency. Required for cross-margin on non-USDT pairs.
  • clOrdId (string) — Client-assigned order ID.
  • tag (string) — Order tag.
OKX docs: WS place order

​
submitMultipleOrders(params)

submitMultipleOrders(
  params: WSAPIPlaceOrderRequestV5[]
): Promise<WSAPIResponse<OrderResult[], 'batch-orders'>>
Place multiple orders in a single batch request.
​
params
WSAPIPlaceOrderRequestV5[]
required
Array of order parameter objects. Each entry follows the same shape as submitNewOrder().
OKX docs: WS place multiple orders

​
cancelOrder(params)

cancelOrder(
  params: OrderIdRequest
): Promise<WSAPIResponse<[WSAPICancelOrderResultV5], 'cancel-order'>>
Cancel a single open order.
​
params
OrderIdRequest
required
  • instId (string, required) — Instrument ID.
  • ordId (string) — OKX order ID. Either ordId or clOrdId is required.
  • clOrdId (string) — Client order ID.
OKX docs: WS cancel order

​
cancelMultipleOrders(params)

cancelMultipleOrders(
  params: OrderIdRequest[]
): Promise<WSAPIResponse<WSAPICancelOrderResultV5[], 'batch-cancel-orders'>>
Cancel multiple open orders in a single batch request.
​
params
OrderIdRequest[]
required
Array of order ID objects. Each entry follows the same shape as cancelOrder().
OKX docs: WS cancel multiple orders

​
amendOrder(params)

amendOrder(
  params: WSAPIAmendOrderRequestV5
): Promise<WSAPIResponse<[OrderResult], 'amend-order'>>
Amend a single open order (price and/or quantity).
​
params
WSAPIAmendOrderRequestV5
required
  • instId (string, required) — Instrument ID.
  • ordId (string) — OKX order ID. Either ordId or clOrdId is required.
  • clOrdId (string) — Client order ID.
  • newSz (string) — New order size.
  • newPx (string) — New order price.
  • reqId (string) — Client-assigned request ID, echoed back in the response.
OKX docs: WS amend order

​
amendMultipleOrders(params)

amendMultipleOrders(
  params: WSAPIAmendOrderRequestV5[]
): Promise<WSAPIResponse<[OrderResult], 'batch-amend-orders'>>
Amend multiple open orders in a single batch request.
​
params
WSAPIAmendOrderRequestV5[]
required
Array of amendment objects. Each entry follows the same shape as amendOrder().
OKX docs: WS amend multiple orders

​
massCancelOrders(params)

massCancelOrders(
  params: WSAPIMassCancelOrdersRequestV5
): Promise<WSAPIResponse<[{ result: boolean }], 'mass-cancel'>>
Cancel all pending orders for a given instrument family in a single operation. Used by market makers for rapid risk-off.
​
params
WSAPIMassCancelOrdersRequestV5
required
  • instType (string, required) — Instrument type, e.g. 'OPTION'.
  • instFamily (string, required) — Instrument family, e.g. 'BTC-USD'.
OKX docs: WS mass cancel order

​
Spread order methods

Spread order methods route through the business WebSocket connection.

​
submitSpreadOrder(params)

submitSpreadOrder(
  params: WSAPIPlaceSpreadOrderRequestV5
): Promise<WSAPIResponse<[WSAPISpreadPlaceOrderResultV5], 'sprd-order'>>
Place a new spread order via WebSocket.
​
params
WSAPIPlaceSpreadOrderRequestV5
required
  • sprdId (string, required) — Spread instrument ID.
  • side (string, required) — 'buy' or 'sell'.
  • ordType (string, required) — Order type: 'limit', 'market', 'post_only', 'ioc', etc.
  • sz (string, required) — Order size (number of contracts).
  • px (string) — Price. Required for limit orders.
  • clOrdId (string) — Client-assigned order ID.
  • tag (string) — Order tag.
OKX docs: WS spread place order

​
amendSpreadOrder(params)

amendSpreadOrder(
  params: WSAPIAmendSpreadOrderRequestV5
): Promise<WSAPIResponse<[WSAPISpreadAmendOrderResultV5], 'sprd-amend-order'>>
Amend an open spread order.
​
params
WSAPIAmendSpreadOrderRequestV5
required
  • ordId (string) — OKX order ID. Either ordId or clOrdId is required.
  • clOrdId (string) — Client order ID.
  • newSz (string) — New order size.
  • newPx (string) — New order price.
  • reqId (string) — Client-assigned request ID, echoed back in the response.
OKX docs: WS spread amend order

​
cancelSpreadOrder(params)

cancelSpreadOrder(
  params: WSAPICancelSpreadOrderRequestV5
): Promise<WSAPIResponse<[WSAPISpreadCancelOrderResultV5], 'sprd-cancel-order'>>
Cancel a single open spread order.
​
params
WSAPICancelSpreadOrderRequestV5
required
  • ordId (string) — OKX order ID. Either ordId or clOrdId is required.
  • clOrdId (string) — Client order ID.
OKX docs: WS spread cancel order

​
massCancelSpreadOrders(params)

massCancelSpreadOrders(
  params: WSAPISpreadMassCancelOrdersRequestV5
): Promise<WSAPIResponse<[{ result: boolean }], 'sprd-mass-cancel'>>
Cancel all open spread orders for a given spread instrument.
​
params
WSAPISpreadMassCancelOrdersRequestV5
required
  • sprdId (string, optional) — Spread instrument ID to target. Omit to cancel all open spread orders.
OKX docs: WS spread cancel all orders

​
Method summary

MethodWS connectionOKX operation
submitNewOrder()privateorder
submitMultipleOrders()privatebatch-orders
cancelOrder()privatecancel-order
cancelMultipleOrders()privatebatch-cancel-orders
amendOrder()privateamend-order
amendMultipleOrders()privatebatch-amend-orders
massCancelOrders()privatemass-cancel
submitSpreadOrder()businesssprd-order
amendSpreadOrder()businesssprd-amend-order
cancelSpreadOrder()businesssprd-cancel-order
massCancelSpreadOrders()businesssprd-mass-cancel

Build docs developers (and LLMs) love

Get started for freeTalk to us