WebsocketAPIClient Futures Order Methods Reference

The WebsocketAPIClient provides four futures-specific methods that route all requests through KuCoin’s WebSocket API (wsApiFuturesV1) rather than REST. This means lower round-trip latency, persistent connections, and automatic reconnection — with the same ergonomic Promise-based interface you’d expect from a REST client. All futures methods target the futures.* WS API operation namespace and default to the WS_KEY_MAP.wsApiFuturesV1 connection.

Initialization

import { WebsocketAPIClient } from 'kucoin-api';

const client = new WebsocketAPIClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  apiPassphrase: 'your-api-passphrase',
});

Set testnet: true in the constructor options to connect to the KuCoin sandbox/testnet. Do not use a custom wsKey for testnet routing.

The `wsKey` Parameter

Each futures method accepts an optional wsKey: WSAPIWsKey parameter. When omitted, the method uses WS_KEY_MAP.wsApiFuturesV1 — the standard futures WebSocket API endpoint. Supply a custom wsKey only if you want to route over an alternative supported endpoint (for example, a secondary domain).

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

// Explicit wsKey (optional — this is the default for futures methods)
const response = await client.submitFuturesOrder(params, WS_KEY_MAP.wsApiFuturesV1);

Futures Order Methods

`submitFuturesOrder`

Submit a single perpetual futures order.

submitFuturesOrder(
  params: Order,
  wsKey?: WSAPIWsKey,
): Promise<WSAPIResponse<WSAPIOrderResponse>>

Order parameters

clientOid

string

required

Unique client-generated order ID (UUID recommended).

side

'buy' | 'sell'

required

Order side.

symbol

string

required

Futures contract symbol, e.g. 'XBTUSDTM'.

type

'limit' | 'market'

Order type. Defaults to 'limit'.

marginMode

'ISOLATED' | 'CROSS'

Margin mode for the position.

price

string

Required for limit orders.

size

number

Order quantity in lots (integer).

qty

string

Order quantity as a string (alternative to size).

valueQty

string

Order quantity in quote currency value.

leverage

number

Leverage multiplier (e.g. 10 for 10×).

positionSide

'BOTH' | 'LONG' | 'SHORT'

Required when using hedge (two-way) position mode. 'BOTH' for one-way mode.

timeInForce

'GTC' | 'IOC' | 'RPI'

Time-in-force. 'RPI' (Retail Price Improvement) is available for futures as of 2025-01-02.

reduceOnly

boolean

If true, the order can only reduce an existing position.

closeOrder

boolean

If true, closes the position for the given symbol when filled.

forceHold

boolean

If true, forces the order to be held even if the position is being closed.

postOnly

boolean

Ensures the order is added to the book without immediate matching.

hidden

boolean

Hides the order from the order book.

iceberg

boolean

Shows only visibleSize in the order book.

visibleSize

string

Visible quantity for iceberg orders.

stop

'down' | 'up'

Stop trigger direction for stop orders.

stopPriceType

'TP' | 'MP' | 'IP'

Stop price type: Trade Price, Mark Price, or Index Price.

stopPrice

string

Trigger price for stop orders.

stp

'CN' | 'CO' | 'CB'

Self-Trade Prevention strategy.

remark

string

Optional order remark.

WSAPIOrderResponse fields

orderId

string

Server-assigned order ID.

clientOid

string

The client order ID provided in the request.

import { WebsocketAPIClient } from 'kucoin-api';

const client = new WebsocketAPIClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  apiPassphrase: 'your-api-passphrase',
});

const response = await client.submitFuturesOrder({
  clientOid: 'futures-' + Date.now(),
  side: 'buy',
  symbol: 'XBTUSDTM',
  marginMode: 'CROSS',
  type: 'limit',
  price: '50000',
  qty: '0.01',
  leverage: 10,
  positionSide: 'LONG', // required for hedge/two-way mode
});

console.log('Order ID:', response.data.orderId);

`cancelFuturesOrder`

Cancel a single open futures order by server order ID or by client order ID + symbol.

cancelFuturesOrder(
  params: { orderId: string } | { clientOid: string; symbol: string },
  wsKey?: WSAPIWsKey,
): Promise<WSAPIResponse<{ cancelledOrderIds: string[] } | { clientOid: string }>>

Request parameters

orderId

string

Server-assigned order ID. Use this form when you have the server ID.

clientOid

string

Client order ID. Must be paired with symbol.

symbol

string

Futures contract symbol. Required when using clientOid.

Response data

cancelledOrderIds

string[]

Array of cancelled server order IDs. Present when orderId was provided.

clientOid

string

The client order ID. Present when clientOid was provided.

// Cancel using the server-assigned orderId
const cancel = await client.cancelFuturesOrder({
  orderId: '358196976308797441',
});
console.log('Cancelled IDs:', cancel.data.cancelledOrderIds);

`submitMultipleFuturesOrders`

Submit up to the exchange’s batch limit of futures orders in a single WebSocket request.

submitMultipleFuturesOrders(
  params: Order[],
  wsKey?: WSAPIWsKey,
): Promise<WSAPIResponse<SubmitMultipleOrdersFuturesResponse[]>>

The params argument is an array of Order objects (same type as submitFuturesOrder). Each entry in the response array corresponds to the order at the same index in the request.

SubmitMultipleOrdersFuturesResponse fields (per order)

orderId

string

Server-assigned order ID.

clientOid

string

Client order ID.

symbol

string

Futures contract symbol.

code

string

Result code for this individual order. '200000' indicates success.

msg

string

Error message if this individual order failed.

const batchResponse = await client.submitMultipleFuturesOrders([
  {
    clientOid: 'batch-1-' + Date.now(),
    side: 'buy',
    symbol: 'XBTUSDTM',
    marginMode: 'CROSS',
    type: 'limit',
    price: '48000',
    qty: '0.01',
    leverage: 10,
    positionSide: 'LONG',
  },
  {
    clientOid: 'batch-2-' + Date.now(),
    side: 'buy',
    symbol: 'XBTUSDTM',
    marginMode: 'CROSS',
    type: 'limit',
    price: '47500',
    qty: '0.01',
    leverage: 10,
    positionSide: 'LONG',
  },
]);

for (const order of batchResponse.data) {
  if (order.code === '200000') {
    console.log('Order placed:', order.orderId);
  } else {
    console.error('Order failed:', order.clientOid, order.msg);
  }
}

Check each individual order’s code and msg in the response array — a partial batch failure (some orders rejected, some accepted) still returns an outer code: '200000'.

`cancelMultipleFuturesOrders`

Cancel multiple open futures orders in a single WebSocket request. Accepts either a list of server order IDs or a list of { symbol, clientOid } pairs.

cancelMultipleFuturesOrders(
  params: BatchCancelOrdersRequest,
  wsKey?: WSAPIWsKey,
): Promise<WSAPIResponse<BatchCancelOrderResult[]>>

BatchCancelOrdersRequest parameters

orderIdsList

string[]

Array of server-assigned order IDs to cancel.

clientOidsList

object[]

Array of { symbol: string; clientOid: string } objects to cancel by client order ID.

BatchCancelOrderResult fields (per order)

orderId

string | null

Server order ID (null if the order could not be found).

clientOid

string | null

Client order ID (null if not applicable).

code

string

Result code for this cancellation. '200000' indicates success.

msg

string

Error message if this individual cancellation failed.

const cancelResult = await client.cancelMultipleFuturesOrders({
  orderIdsList: ['order-id-1', 'order-id-2', 'order-id-3'],
});

for (const result of cancelResult.data) {
  console.log(result.orderId, result.code, result.msg);
}

Common Response Envelope

All methods return a WSAPIResponse<T> wrapper:

WSAPIResponse fields

string

Auto-generated request correlation ID.

string

The WS API operation executed (e.g. 'futures.order').

code

string

'200000' on success; an error code string on failure.

msg

string

Human-readable error message (only present on failure).

data

Method-specific response payload.

inTime

number

Gateway request receipt time (milliseconds).

outTime

number

Gateway response dispatch time (milliseconds).

rateLimit

object

Optional rate-limit metadata: { limit, reset, remaining }.

wsKey

string

The WebSocket key used for this request.

isWSAPIResponse

boolean

Always true for WS API responses.

Method Summary

Method	WS Operation	Request Type	Response Data
`submitFuturesOrder`	`futures.order`	`Order`	`WSAPIOrderResponse`
`cancelFuturesOrder`	`futures.cancel`	`{ orderId }` or `{ clientOid, symbol }`	`{ cancelledOrderIds[] }` or `{ clientOid }`
`submitMultipleFuturesOrders`	`futures.multi_order`	`Order[]`	`SubmitMultipleOrdersFuturesResponse[]`
`cancelMultipleFuturesOrders`	`futures.multi_cancel`	`BatchCancelOrdersRequest`	`BatchCancelOrderResult[]`

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

WebsocketAPIClient Futures Order Methods Reference

Initialization

The `wsKey` Parameter

Futures Order Methods

`submitFuturesOrder`

`cancelFuturesOrder`

`submitMultipleFuturesOrders`

`cancelMultipleFuturesOrders`

Common Response Envelope

Method Summary

Build docs developers (and LLMs) love

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

Documentation Index

​Initialization

​The wsKey Parameter

​Futures Order Methods

​submitFuturesOrder

​cancelFuturesOrder

​submitMultipleFuturesOrders

​cancelMultipleFuturesOrders

​Common Response Envelope

​Method Summary

Build docs developers (and LLMs) love

Initialization

The `wsKey` Parameter

Futures Order Methods

`submitFuturesOrder`

`cancelFuturesOrder`

`submitMultipleFuturesOrders`

`cancelMultipleFuturesOrders`

Common Response Envelope

Method Summary