KuCoin FuturesClient Order Management Methods Reference

The FuturesClient provides a comprehensive set of order management methods for KuCoin Futures. You can submit market and limit orders, place take-profit/stop-loss (SLTP) orders, batch-cancel by symbol, and query fills or open orders with rich filtering options. All order-placement and cancellation endpoints require authentication via API key, secret, and passphrase.

All order endpoints require a valid apiKey, apiSecret, and apiPassphrase when constructing FuturesClient. Use client.generateNewOrderID() to produce a nanoid-based unique clientOid for each order.

Place Orders

`submitOrder(params)`

Places a new futures order (limit or market) in the trading system.

submitOrder(params: Order): Promise<
  APISuccessResponse<{
    orderId?: string;
    clientOid?: string;
  }>
>

Order interface — all fields

clientOid

string

required

Unique client order ID. Use client.generateNewOrderID() or supply your own UUID (max 32 chars).

side

"buy" | "sell"

required

Order direction.

symbol

string

required

Futures contract symbol, e.g. XBTUSDTM.

type

"limit" | "market"

Order type. Defaults to limit if omitted.

leverage

number

Leverage multiplier, e.g. 5 or 10.

price

string

Limit price (required for limit orders).

size

number

Number of contract lots to trade.

qty

string

Quantity in base currency (alternative to size).

valueQty

string

Quantity in quote currency (alternative to size).

marginMode

"ISOLATED" | "CROSS"

Margin mode. Defaults to ISOLATED.

timeInForce

"GTC" | "IOC" | "RPI"

Time-in-force policy. GTC = Good Till Cancelled (default), IOC = Immediate or Cancel, RPI = Retail Price Improvement (Futures only).

reduceOnly

boolean

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

closeOrder

boolean

If true, closes the entire position. Side/size are determined automatically.

forceHold

boolean

If true, forcibly reserves margin even if the position would be reduced.

stop

"down" | "up"

Stop order trigger direction.

stopPrice

string

Stop trigger price.

stopPriceType

"TP" | "MP" | "IP"

Price type for stop trigger: TP = trade price, MP = mark price, IP = index price.

postOnly

boolean

If true, the order is rejected if it would immediately fill (maker-only).

hidden

boolean

Hidden order (not visible in the order book).

iceberg

boolean

Iceberg order; only visibleSize lots are shown in the book.

visibleSize

string

Visible portion of an iceberg order.

positionSide

"BOTH" | "LONG" | "SHORT"

Position side for hedge mode.

stp

"CN" | "CO" | "CB"

Self-trade prevention policy.

remark

string

Optional order remark (max 100 chars).

orderId

string

Exchange-assigned order ID.

clientOid

string

Client order ID echoed back.

import { FuturesClient } from 'kucoin-api';

const client = new FuturesClient({
  apiKey: 'apiKeyHere',
  apiSecret: 'apiSecretHere',
  apiPassphrase: 'apiPassPhraseHere',
});

// Market long: buy 1 lot of XBTUSDTM at 2x leverage
const result = await client.submitOrder({
  clientOid: client.generateNewOrderID(),
  side: 'buy',
  symbol: 'XBTUSDTM',
  type: 'market',
  size: 1,
  leverage: 2,
});
console.log('Order ID:', result.data.orderId);

`submitNewOrderTest(params)`

Identical to submitOrder but performs a dry-run to validate your request parameters and API signature without placing a live order.

submitNewOrderTest(params: Order): Promise<{
  orderId?: string;
  clientOid?: string;
}>

Accepts the same Order interface as submitOrder. Useful for verifying credential setup before going live.

`submitSLTPOrder(params)`

Places a combined take-profit and stop-loss order. Accepts the SLTPOrder interface, which extends Order with dedicated trigger fields.

submitSLTPOrder(params: SLTPOrder): Promise<
  APISuccessResponse<{
    orderId?: string;
    clientOid?: string;
  }>
>

clientOid

string

required

Unique client order ID.

side

"buy" | "sell"

required

Order direction.

symbol

string

required

Futures contract symbol.

type

"limit" | "market"

required

Order type.

triggerStopUpPrice

string

Take-profit trigger price (triggers when price rises to this level).

triggerStopDownPrice

string

Stop-loss trigger price (triggers when price falls to this level).

stopPriceType

"TP" | "MP" | "IP"

Price type for trigger: trade price, mark price, or index price.

leverage

number

Leverage multiplier.

price

string

Limit price (required for limit type).

size

number

Contract lots.

marginMode

"ISOLATED" | "CROSS"

Margin mode.

const result = await client.submitSLTPOrder({
  clientOid: client.generateNewOrderID(),
  side: 'sell',
  symbol: 'XBTUSDTM',
  type: 'market',
  leverage: 5,
  size: 2,
  triggerStopDownPrice: '60000.00', // stop-loss
  triggerStopUpPrice: '80000.00',   // take-profit
  stopPriceType: 'MP',              // based on mark price
});

`submitMultipleOrders(params)`

Places multiple futures orders in a single API call. Accepts an array of Order objects.

submitMultipleOrders(params: Order[]): Promise<
  APISuccessResponse<SubmitMultipleOrdersFuturesResponse[]>
>

orderId

string

Exchange-assigned order ID.

clientOid

string

Client order ID.

symbol

string

Symbol the order was placed on.

code

string

Result code; "200000" indicates success.

msg

string

Result message (empty on success).

const results = await client.submitMultipleOrders([
  {
    clientOid: client.generateNewOrderID(),
    side: 'buy',
    symbol: 'XBTUSDTM',
    type: 'limit',
    price: '60000',
    size: 1,
    leverage: 5,
  },
  {
    clientOid: client.generateNewOrderID(),
    side: 'sell',
    symbol: 'XBTUSDTM',
    type: 'limit',
    price: '70000',
    size: 1,
    leverage: 5,
  },
]);

results.data.forEach(r => console.log(r.orderId, r.code));

Cancel Orders

`cancelOrderById(params)`

Cancels an open order (including stop orders) by its exchange-assigned order ID.

cancelOrderById(params: { orderId: string }): Promise<
  APISuccessResponse<{ cancelledOrderIds: string[] }>
>

orderId

string

required

Exchange order ID to cancel.

const result = await client.cancelOrderById({ orderId: '5bd6e9286d99522a52e458de' });
console.log('Cancelled:', result.data.cancelledOrderIds);

`cancelOrderByClientOid(params)`

Cancels an order by client order ID. Requires both clientOid and symbol.

cancelOrderByClientOid(params: {
  clientOid: string;
  symbol: string;
}): Promise<APISuccessResponse<{ clientOid: string }>>

clientOid

string

required

Client order ID to cancel.

symbol

string

required

Symbol the order was placed on.

`cancelAllOrdersV3(params?)`

Cancels all open orders (excluding stop orders) for the specified symbol in one call.

cancelAllOrdersV3(params: { symbol: string }): Promise<
  APISuccessResponse<{ cancelledOrderIds: string[] }>
>

symbol

string

required

Cancel all active orders for this symbol.

`cancelAllStopOrders(params?)`

Cancels all untriggered stop orders. Optionally filter by symbol.

cancelAllStopOrders(params?: { symbol?: string }): Promise<
  APISuccessResponse<{ cancelledOrderIds: string[] }>
>

symbol

string

Limit cancellation to this symbol (optional).

`batchCancelOrders(params)`

Cancels multiple orders simultaneously by providing either a list of order IDs or a list of client OID + symbol pairs.

batchCancelOrders(params: BatchCancelOrdersRequest): Promise<
  APISuccessResponse<BatchCancelOrderResult[]>
>

orderIdsList

string[]

List of exchange order IDs to cancel. Takes precedence over clientOidsList if both are provided.

clientOidsList

{ symbol: string; clientOid: string }[]

List of { symbol, clientOid } pairs to cancel (used when orderIdsList is not provided).

orderId

string | null

Cancelled order ID (or null if not applicable).

clientOid

string | null

Cancelled client OID (or null).

code

string

Result code; "200000" = success.

msg

string

Result message.

Query Orders

`getOrders(params?)`

Returns a paginated list of orders filtered by status, symbol, side, and type.

getOrders(params?: GetOrdersRequest): Promise<APISuccessResponse<FuturesOrders>>

status

"active" | "done"

required

Filter by order status.

symbol

string

Filter by symbol (optional).

side

"buy" | "sell"

required

Filter by order side.

type

"limit" | "market" | "limit_stop" | "market_stop"

required

Filter by order type.

startAt

number

Start time (Unix ms, optional).

endAt

number

End time (Unix ms, optional).

currentPage

number

Page number (optional).

pageSize

number

Results per page (optional).

currentPage

number

Current page number.

pageSize

number

Page size.

totalNum

number

Total matching orders.

totalPage

number

Total pages.

items

FuturesOrder[]

Array of order objects.

`getStopOrders(params?)`

Returns a paginated list of untriggered stop orders.

getStopOrders(params?: GetStopOrdersRequest): Promise<APISuccessResponse<FuturesOrders>>

symbol

string

Filter by symbol (optional).

side

"buy" | "sell"

Filter by side (optional).

type

"limit" | "market"

Filter by type (optional).

startAt

number

Start time (Unix ms, optional).

endAt

number

End time (Unix ms, optional).

currentPage

number

Page number (optional).

pageSize

number

Results per page (optional).

`getRecentOrders()`

Returns up to the last 1000 closed/filled orders from the past 24 hours.

getRecentOrders(params?: { symbol?: string }): Promise<APISuccessResponse<FuturesOrder[]>>

symbol

string

Optionally filter by symbol.

`getOrderByOrderId(params)`

Returns full details for a single order identified by its exchange-assigned order ID.

getOrderByOrderId(params: { orderId: string }): Promise<APISuccessResponse<FuturesOrder>>

orderId

string

required

Exchange order ID.

string

Order ID.

symbol

string

Contract symbol.

type

"market" | "limit"

Order type.

side

"buy" | "sell"

Order side.

price

string

Order price.

size

number

Order size in lots.

status

"open" | "done"

Order status.

filledSize

number

Number of lots filled.

marginMode

"ISOLATED" | "CROSS"

Margin mode.

createdAt

number

Creation timestamp.

`getOrderByClientOrderId(params)`

Returns full details for a single order using its client-assigned order ID.

getOrderByClientOrderId(params: { clientOid: string }): Promise<APISuccessResponse<FuturesOrder>>

clientOid

string

required

Client order ID.

Fills (Trade History)

`getFills(params?)`

Returns a paginated list of your historical trade fills. For low-latency recent fills, prefer getRecentFills().

getFills(params?: AccountFillsRequest): Promise<APISuccessResponse<FuturesFills>>

orderId

string

Filter by order ID (optional).

symbol

string

Filter by symbol (optional).

side

"buy" | "sell"

Filter by side (optional).

type

"limit" | "market" | "limit_stop" | "market_stop"

Filter by order type (optional).

startAt

number

Start time (Unix ms, optional).

endAt

number

End time (Unix ms, optional).

currentPage

number

Page number (optional).

pageSize

number

Results per page (optional).

tradeTypes

string

Trade type filter string (optional).

currentPage

number

Current page.

pageSize

number

Page size.

totalNum

number

Total fill records.

totalPage

number

Total pages.

items

FuturesFill[]

Show FuturesFill fields

tradeId

string

Transaction ID.

orderId

string

Related order ID.

symbol

string

Contract symbol.

side

"buy" | "sell"

Fill side.

price

string

Fill price.

size

number

Fill quantity in lots.

fee

string

Fee paid.

feeCurrency

string

Fee currency.

liquidity

"taker" | "maker"

Liquidity role.

tradeType

string

trade, liquid, adl, or settlement.

tradeTime

number

Execution timestamp (nanoseconds).

marginMode

"ISOLATED" | "CROSS"

Margin mode at time of fill.

`getRecentFills()`

Returns the last 1000 fills from the past 24 hours with low latency.

getRecentFills(params?: { symbol?: string }): Promise<APISuccessResponse<FuturesFill[]>>

symbol

string

Optionally filter by symbol.

Fee Rate

`getTradingPairFee(params?)`

Returns the actual taker and maker fee rates for your account on the specified futures trading pair.

getTradingPairFee(params: { symbol: string }): Promise<
  APISuccessResponse<{
    symbol: string;
    takerFeeRate: string;
    makerFeeRate: string;
  }>
>

symbol

string

required

Futures trading pair symbol.

symbol

string

Trading pair.

takerFeeRate

string

Your taker fee rate as a decimal string, e.g. "0.0006".

makerFeeRate

string

Your maker fee rate as a decimal string, e.g. "0.0002".

const fee = await client.getTradingPairFee({ symbol: 'XBTUSDTM' });
console.log('Taker fee:', fee.data.takerFeeRate); // "0.0006"
console.log('Maker fee:', fee.data.makerFeeRate); // "0.0002"

Sub-account fee rates mirror the master account. The fee rate can vary based on your VIP tier and KCS holdings.

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

KuCoin FuturesClient Order Management Methods Reference

Place Orders

`submitOrder(params)`

`submitNewOrderTest(params)`

`submitSLTPOrder(params)`

`submitMultipleOrders(params)`

Cancel Orders

`cancelOrderById(params)`

`cancelOrderByClientOid(params)`

`cancelAllOrdersV3(params?)`

`cancelAllStopOrders(params?)`

`batchCancelOrders(params)`

Query Orders

`getOrders(params?)`

`getStopOrders(params?)`

`getRecentOrders()`

`getOrderByOrderId(params)`

`getOrderByClientOrderId(params)`

Fills (Trade History)

`getFills(params?)`

`getRecentFills()`

Fee Rate

`getTradingPairFee(params?)`

Build docs developers (and LLMs) love

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

Documentation Index

​Place Orders

​submitOrder(params)

​submitNewOrderTest(params)

​submitSLTPOrder(params)

​submitMultipleOrders(params)

​Cancel Orders

​cancelOrderById(params)

​cancelOrderByClientOid(params)

​cancelAllOrdersV3(params?)

​cancelAllStopOrders(params?)

​batchCancelOrders(params)

​Query Orders

​getOrders(params?)

​getStopOrders(params?)

​getRecentOrders()

​getOrderByOrderId(params)

​getOrderByClientOrderId(params)

​Fills (Trade History)

​getFills(params?)

​getRecentFills()

​Fee Rate

​getTradingPairFee(params?)

Build docs developers (and LLMs) love

Place Orders

`submitOrder(params)`

`submitNewOrderTest(params)`

`submitSLTPOrder(params)`

`submitMultipleOrders(params)`

Cancel Orders

`cancelOrderById(params)`

`cancelOrderByClientOid(params)`

`cancelAllOrdersV3(params?)`

`cancelAllStopOrders(params?)`

`batchCancelOrders(params)`

Query Orders

`getOrders(params?)`

`getStopOrders(params?)`

`getRecentOrders()`

`getOrderByOrderId(params)`

`getOrderByClientOrderId(params)`

Fills (Trade History)

`getFills(params?)`

`getRecentFills()`

Fee Rate

`getTradingPairFee(params?)`