FuturesClient Position & Margin Management Reference

The FuturesClient provides full position and margin lifecycle management for KuCoin Futures. You can retrieve live position data, switch between isolated and cross margin modes (individually or in batch), adjust cross-margin leverage, manually add or remove isolated margin, query and update risk limit levels, and control whether the account operates in one-way or hedge mode. All methods in this section require authentication.

Query Positions

`getPosition(params)`

Returns position details for a single symbol using the v1 endpoint.

getPosition is deprecated. Prefer getPositionV2 for new integrations.

getPosition(params: { symbol: string }): Promise<APISuccessResponse<FuturesPosition>>

symbol

string

required

The futures contract symbol, e.g. XBTUSDTM.

string

Position ID.

symbol

string

Contract symbol.

marginMode

"CROSS" | "ISOLATED"

Current margin mode for this position.

currentQty

number

Position size in lots (negative = short).

avgEntryPrice

number

Average entry price.

markPrice

number

Current mark price.

unrealisedPnl

number

Unrealised profit/loss.

unrealisedPnlPcnt

number

Unrealised PnL as a fraction.

unrealisedRoePcnt

number

Return on equity percentage.

realisedPnl

number

Accumulated realised PnL.

liquidationPrice

number

Estimated liquidation price.

bankruptPrice

number

Bankruptcy price.

leverage

number

Current leverage.

isOpen

boolean

Whether the position is currently open.

positionSide

string

Position side; BOTH for one-way mode.

settleCurrency

string

Settlement currency.

import { FuturesClient } from 'kucoin-api';

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

const position = await client.getPosition({ symbol: 'XBTUSDTM' });
console.log('Qty:', position.data.currentQty);
console.log('Entry price:', position.data.avgEntryPrice);
console.log('Unrealised PnL:', position.data.unrealisedPnl);

`getPositionV2(params)`

Returns position details for a single symbol using the v2 endpoint (recommended).

getPositionV2(params: { symbol: string }): Promise<APISuccessResponse<FuturesPosition>>

symbol

string

required

The futures contract symbol.

Returns the same FuturesPosition shape as getPosition. See response fields above.

`getPositions(params?)`

Returns a list of all currently open positions, optionally filtered by settlement currency.

getPositions(params?: { currency?: string }): Promise<APISuccessResponse<FuturesPosition[]>>

currency

string

Filter positions by settlement currency, e.g. USDT (optional).

const positions = await client.getPositions({ currency: 'USDT' });
positions.data.forEach(p => {
  console.log(`${p.symbol}: qty=${p.currentQty}, pnl=${p.unrealisedPnl}`);
});

`getHistoryPositions(params?)`

Returns paginated historical (closed) position records.

getHistoryPositions(params?: {
  symbol?: string;
  from?: number;
  to?: number;
  limit?: number;
  pageId?: number;
}): Promise<APISuccessResponse<FuturesClosedPositions>>

symbol

string

Filter by contract symbol (optional).

from

number

Start time (Unix ms, optional).

number

End time (Unix ms, optional).

limit

number

Maximum records per page (optional).

pageId

number

Page cursor for pagination (optional).

currentPage

number

Current page.

pageSize

number

Page size.

totalNum

number

Total closed position records.

totalPage

number

Total pages.

items

FuturesClosedPosition[]

Show FuturesClosedPosition fields

closeId

string

Close record ID.

symbol

string

Contract symbol.

pnl

string

Net PnL at close.

tradeFee

string

Trade fees paid.

fundingFee

string

Funding fees paid during the position’s lifetime.

openPrice

string

Average entry price.

closePrice

string

Average close price.

openTime

number

Position open timestamp.

closeTime

number

Position close timestamp.

leverage

string

Leverage used.

marginMode

"CROSS" | "ISOLATED"

Margin mode.

Margin Mode

`getMarginMode(params)`

Returns the current margin mode (ISOLATED or CROSS) for the specified symbol.

getMarginMode(params: { symbol: string }): Promise<
  APISuccessResponse<{
    symbol: string;
    marginMode: 'ISOLATED' | 'CROSS';
  }>
>

symbol

string

required

Futures contract symbol.

`updateMarginMode(params)`

Switches the margin mode for a specified symbol between ISOLATED and CROSS.

updateMarginMode(params: {
  symbol: string;
  marginMode: 'ISOLATED' | 'CROSS';
}): Promise<
  APISuccessResponse<{
    symbol: string;
    marginMode: 'ISOLATED' | 'CROSS';
  }>
>

symbol

string

required

Futures contract symbol.

marginMode

"ISOLATED" | "CROSS"

required

Target margin mode.

import { FuturesClient } from 'kucoin-api';

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

const result = await client.updateMarginMode({
  symbol: 'XBTUSDTM',
  marginMode: 'CROSS',
});
console.log('New mode:', result.data.marginMode); // "CROSS"

`batchSwitchMarginMode(params)`

Switches the margin mode for multiple symbols at once.

batchSwitchMarginMode(params: {
  marginMode: 'ISOLATED' | 'CROSS';
  symbols: string[];
}): Promise<APISuccessResponse<BatchMarginModeUpdateResponse>>

marginMode

"ISOLATED" | "CROSS"

required

Target margin mode for all listed symbols.

symbols

string[]

required

Array of futures contract symbols to update.

marginMode

object

Map of { symbol: marginMode } for each successfully updated symbol.

errors

array

Array of error objects for any symbols that failed, each with code, msg, and symbol.

Position Mode

`getPositionMode()`

Returns the current position mode for the account: one-way (0) or hedge (1).

getPositionMode(): Promise<APISuccessResponse<GetPositionModeResponse>>

positionMode

0 | 1

0 = one-way mode (single BOTH-side position per symbol). 1 = hedge mode (separate LONG and SHORT positions).

`updatePositionMode(params)`

Switches the account-wide position mode between one-way and hedge mode.

updatePositionMode(params: { positionMode: '0' | '1' }): Promise<
  APISuccessResponse<{ positionMode: '0' | '1' }>
>

positionMode

"0" | "1"

required

"0" = one-way mode. "1" = hedge mode.

Switching position mode affects all futures trading pairs. Ensure all positions and open orders are closed before switching.

Open Size

`getMaxOpenSize(params)`

Returns the maximum number of contracts that can be opened at the given price and leverage.

getMaxOpenSize(params: MaxOpenSizeRequest): Promise<APISuccessResponse<MaxOpenSize>>

symbol

string

required

Futures contract symbol.

price

string

required

Order price as a string.

leverage

number

required

Intended leverage multiplier.

symbol

string

Contract symbol.

maxBuyOpenSize

number

Maximum lots available for a long position.

maxSellOpenSize

number

Maximum lots available for a short position.

Isolated Margin Operations

`getMaxWithdrawMargin(params)`

Returns the maximum amount of margin that can be manually withdrawn from the current isolated margin position.

getMaxWithdrawMargin(params: { symbol: string }): Promise<APISuccessResponse<string>>

symbol

string

required

Futures contract symbol.

Returns a string representing the maximum withdrawable margin amount.

`depositMargin(params)`

Manually adds isolated margin to the specified position.

depositMargin(params: {
  symbol: string;
  margin: number;
  bizNo: string;
}): Promise<APISuccessResponse<AddMargin>>

symbol

string

required

Futures contract symbol.

margin

number

required

Amount of margin to add (in settlement currency).

bizNo

string

required

Unique business number for idempotency (client-generated).

string

Position ID.

symbol

string

Contract symbol.

posMargin

number

Updated total position margin.

posCross

number

Amount of manually added margin.

realLeverage

number

Actual leverage after deposit.

liquidationPrice

number

Updated liquidation price.

`withdrawMargin(params)`

Manually removes isolated margin from the specified position.

withdrawMargin(params: {
  symbol: string;
  withdrawAmount: string;
}): Promise<APISuccessResponse<string>>

symbol

string

required

Futures contract symbol.

withdrawAmount

string

required

Amount of margin to remove as a string.

Returns the withdrawn amount as a string on success.

Cross Margin Leverage

`getCrossMarginLeverage(params)`

Returns the current cross-margin leverage multiple for the specified symbol.

getCrossMarginLeverage(params: { symbol: string }): Promise<
  APISuccessResponse<{
    symbol: string;
    leverage: string;
  }>
>

symbol

string

required

Futures contract symbol.

`changeCrossMarginLeverage(params)`

Updates the cross-margin leverage multiple for the specified symbol.

changeCrossMarginLeverage(params: {
  symbol: string;
  leverage: string;
}): Promise<
  APISuccessResponse<{
    symbol: string;
    leverage: string;
  }>
>

symbol

string

required

Futures contract symbol.

leverage

string

required

New leverage value as a string, e.g. "10".

const result = await client.changeCrossMarginLeverage({
  symbol: 'XBTUSDTM',
  leverage: '10',
});
console.log('Updated leverage:', result.data.leverage);

Risk Limits

`getRiskLimitLevel(params)`

Returns the isolated margin risk limit levels available for the specified contract. Each level defines margin rates and maximum leverage.

getRiskLimitLevel(params: { symbol: string }): Promise<
  APISuccessResponse<FuturesRiskLimit[]>
>

symbol

string

required

Futures contract symbol.

symbol

string

Contract symbol.

level

number

Risk limit level index.

maxRiskLimit

number

Maximum position value for this level.

minRiskLimit

number

Minimum position value for this level.

maxLeverage

number

Maximum allowed leverage at this level.

initialMargin

number

Initial margin rate.

maintainMargin

number

Maintenance margin rate.

`updateRiskLimitLevel(params)`

Adjusts the isolated margin risk limit level for the specified symbol. Changing levels may cancel open orders.

updateRiskLimitLevel(params: {
  symbol: string;
  level: number;
}): Promise<boolean>

symbol

string

required

Futures contract symbol.

level

number

required

Target risk limit level number.

Returns true on successful submission.

Cross Margin Requirements & Risk

`getCrossMarginRequirement(params)`

Queries the cross-margin initial and maintenance margin requirements for a given position value.

getCrossMarginRequirement(params: {
  symbol: string;
  positionValue: string;
  leverage?: string;
}): Promise<APISuccessResponse<CrossMarginRequirement>>

symbol

string

required

Futures contract symbol.

positionValue

string

required

Hypothetical position value in quote currency.

leverage

string

Leverage to apply (optional).

symbol

string

Contract symbol.

imr

string

Initial margin rate.

mmr

string

Maintenance margin rate.

size

number

Computed position size in lots.

positionValue

string

Input position value.

price

string

Reference price used for calculation.

`getCrossMarginRiskLimit(params)`

Batch-fetches cross-margin risk limit data for a symbol across different margin and leverage combinations. Unlike isolated margin, cross-margin risk limits form a smooth curve rather than fixed tiers.

getCrossMarginRiskLimit(params: {
  symbol: string;
  totalMargin?: string;
  leverage?: number;
}): Promise<APISuccessResponse<CrossMarginRiskLimit[]>>

symbol

string

required

Futures contract symbol.

totalMargin

string

Total margin to evaluate against (optional).

leverage

number

Leverage to evaluate (optional).

symbol

string

Contract symbol.

maxOpenSize

number

Maximum open position size.

maxOpenValue

string

Maximum open position value.

totalMargin

string

Total margin used in the calculation.

leverage

string

Leverage used.

mmr

string

Maintenance margin rate.

imr

string

Initial margin rate.

currency

string

Settlement currency.

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

FuturesClient Position & Margin Management Reference

Query Positions

`getPosition(params)`

`getPositionV2(params)`

`getPositions(params?)`

`getHistoryPositions(params?)`

Margin Mode

`getMarginMode(params)`

`updateMarginMode(params)`

`batchSwitchMarginMode(params)`

Position Mode

`getPositionMode()`

`updatePositionMode(params)`

Open Size

`getMaxOpenSize(params)`

Isolated Margin Operations

`getMaxWithdrawMargin(params)`

`depositMargin(params)`

`withdrawMargin(params)`

Cross Margin Leverage

`getCrossMarginLeverage(params)`

`changeCrossMarginLeverage(params)`

Risk Limits

`getRiskLimitLevel(params)`

`updateRiskLimitLevel(params)`

Cross Margin Requirements & Risk

`getCrossMarginRequirement(params)`

`getCrossMarginRiskLimit(params)`

Build docs developers (and LLMs) love

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

Documentation Index

​Query Positions

​getPosition(params)

​getPositionV2(params)

​getPositions(params?)

​getHistoryPositions(params?)

​Margin Mode

​getMarginMode(params)

​updateMarginMode(params)

​batchSwitchMarginMode(params)

​Position Mode

​getPositionMode()

​updatePositionMode(params)

​Open Size

​getMaxOpenSize(params)

​Isolated Margin Operations

​getMaxWithdrawMargin(params)

​depositMargin(params)

​withdrawMargin(params)

​Cross Margin Leverage

​getCrossMarginLeverage(params)

​changeCrossMarginLeverage(params)

​Risk Limits

​getRiskLimitLevel(params)

​updateRiskLimitLevel(params)

​Cross Margin Requirements & Risk

​getCrossMarginRequirement(params)

​getCrossMarginRiskLimit(params)

Build docs developers (and LLMs) love

Query Positions

`getPosition(params)`

`getPositionV2(params)`

`getPositions(params?)`

`getHistoryPositions(params?)`

Margin Mode

`getMarginMode(params)`

`updateMarginMode(params)`

`batchSwitchMarginMode(params)`

Position Mode

`getPositionMode()`

`updatePositionMode(params)`

Open Size

`getMaxOpenSize(params)`

Isolated Margin Operations

`getMaxWithdrawMargin(params)`

`depositMargin(params)`

`withdrawMargin(params)`

Cross Margin Leverage

`getCrossMarginLeverage(params)`

`changeCrossMarginLeverage(params)`

Risk Limits

`getRiskLimitLevel(params)`

`updateRiskLimitLevel(params)`

Cross Margin Requirements & Risk

`getCrossMarginRequirement(params)`

`getCrossMarginRiskLimit(params)`