WebsocketAPIClient

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
)

object

Accepts all WSClientConfigurableOptions fields (credentials, market, demo trading, etc.) plus the additional options below.

DefaultLogger

Optional custom logger.

Additional options (`WSAPIClientConfigurableOptions`)

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

Method	WS connection	OKX operation
`submitNewOrder()`	private	`order`
`submitMultipleOrders()`	private	`batch-orders`
`cancelOrder()`	private	`cancel-order`
`cancelMultipleOrders()`	private	`batch-cancel-orders`
`amendOrder()`	private	`amend-order`
`amendMultipleOrders()`	private	`batch-amend-orders`
`massCancelOrders()`	private	`mass-cancel`
`submitSpreadOrder()`	business	`sprd-order`
`amendSpreadOrder()`	business	`sprd-amend-order`
`cancelSpreadOrder()`	business	`sprd-cancel-order`
`massCancelSpreadOrders()`	business	`sprd-mass-cancel`

Classes

Endpoint Index

Overview

Constructor

Additional options (`WSAPIClientConfigurableOptions`)

Utility methods

`getWSClient()`

`connectWSAPI()`

`setTimeOffsetMs(offsetMs)`

Order management methods

`submitNewOrder(params)`

`submitMultipleOrders(params)`

`cancelOrder(params)`

`cancelMultipleOrders(params)`

`amendOrder(params)`

`amendMultipleOrders(params)`

`massCancelOrders(params)`

Spread order methods

`submitSpreadOrder(params)`

`amendSpreadOrder(params)`

`cancelSpreadOrder(params)`

`massCancelSpreadOrders(params)`

Method summary

​Overview

​Constructor

​Additional options (WSAPIClientConfigurableOptions)

​Utility methods

​getWSClient()

​connectWSAPI()

​setTimeOffsetMs(offsetMs)

​Order management methods

​submitNewOrder(params)

​submitMultipleOrders(params)

​cancelOrder(params)

​cancelMultipleOrders(params)

​amendOrder(params)

​amendMultipleOrders(params)

​massCancelOrders(params)

​Spread order methods

​submitSpreadOrder(params)

​amendSpreadOrder(params)

​cancelSpreadOrder(params)

​massCancelSpreadOrders(params)

​Method summary

Overview

Constructor

Additional options (`WSAPIClientConfigurableOptions`)

Utility methods

`getWSClient()`

`connectWSAPI()`

`setTimeOffsetMs(offsetMs)`

Order management methods

`submitNewOrder(params)`

`submitMultipleOrders(params)`

`cancelOrder(params)`

`cancelMultipleOrders(params)`

`amendOrder(params)`

`amendMultipleOrders(params)`

`massCancelOrders(params)`

Spread order methods

`submitSpreadOrder(params)`

`amendSpreadOrder(params)`

`cancelSpreadOrder(params)`

`massCancelSpreadOrders(params)`

Method summary