KuCoin FuturesClient Funding Rates & Account Balance

The FuturesClient provides methods for working with funding rates and account financials on KuCoin Futures. You can fetch the current funding rate for any contract, browse historical rates by time window, review your personal funding fee history, check your account balance and sub-account balances, paginate ledger transactions, and initiate or query fund transfers between your main, trade, and futures wallets. Most of these endpoints require authentication.

Funding Rates

`getFundingRate(params)`

Returns the current funding rate for the specified futures contract, including the predicted next-period rate and rate cap/floor bounds.

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

symbol

string

required

The futures contract symbol, e.g. XBTUSDTM.

symbol

string

Funding rate symbol identifier.

granularity

number

Funding interval in milliseconds.

timePoint

number

Current funding rate timestamp (ms).

value

number

Current funding rate as a decimal (e.g. 0.0001 = 0.01%).

predictedValue

number

Predicted funding rate for the next settlement.

fundingRateCap

number

Maximum allowed funding rate.

fundingRateFloor

number

Minimum allowed funding rate.

period

number

Funding rate period in hours.

fundingTime

number

Next funding settlement timestamp (ms).

import { FuturesClient } from 'kucoin-api';

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

const rate = await client.getFundingRate({ symbol: 'XBTUSDTM' });
console.log('Current rate:', rate.data.value);        // e.g. 0.0001
console.log('Predicted rate:', rate.data.predictedValue);
console.log('Next funding:', new Date(rate.data.fundingTime).toISOString());

`getFundingRates(params?)`

Returns public historical funding rates for a contract over a specified time range.

getFundingRates(params: GetFundingRatesRequest): Promise<
  APISuccessResponse<FuturesHistoricFundingRate[]>
>

symbol

string

required

Futures contract symbol.

from

number

required

Start time as Unix timestamp in milliseconds.

number

required

End time as Unix timestamp in milliseconds.

symbol

string

Contract symbol.

timePoint

number

Settlement timestamp (ms).

fundingRate

number

Funding rate at that settlement.

const now = Date.now();
const sevenDaysAgo = now - 7 * 24 * 60 * 60 * 1000;

const history = await client.getFundingRates({
  symbol: 'XBTUSDTM',
  from: sevenDaysAgo,
  to: now,
});

history.data.forEach(h => {
  console.log(new Date(h.timePoint).toISOString(), h.fundingRate);
});

`getFundingHistory(params?)`

Returns your private funding fee history — the actual funding payments debited or credited against your positions.

getFundingHistory(params: GetFundingHistoryRequest): Promise<
  APISuccessResponse<{
    dataList: FuturesAccountFundingRateHistory[];
    hasMore: boolean;
  }>
>

symbol

string

required

Futures contract symbol.

from

number

Start time (Unix ms, optional).

number

End time (Unix ms, optional).

reverse

boolean

Return in reverse chronological order (optional).

offset

number

Pagination offset (optional).

forward

boolean

Paginate forward (optional).

maxCount

number

Maximum records to return (optional).

dataList

FuturesAccountFundingRateHistory[]

Show FuturesAccountFundingRateHistory fields

number

Record ID.

symbol

string

Contract symbol.

timePoint

number

Settlement timestamp (ms).

fundingRate

number

Funding rate at settlement.

markPrice

number

Mark price at settlement.

positionQty

number

Position size at settlement (lots).

positionCost

number

Position value at settlement.

funding

number

Funding payment (positive = received, negative = paid).

settleCurrency

string

Settlement currency.

marginMode

"ISOLATED" | "CROSS"

Margin mode at settlement.

hasMore

boolean

Whether more pages exist.

Account Balance

`getBalance()`

Returns the futures account balance for the specified currency, including equity, margin breakdown, and available balance.

getBalance(params?: { currency?: string }): Promise<
  APISuccessResponse<AccountBalance>
>

currency

string

Filter by settlement currency, e.g. USDT or XBT (optional). Returns the default account currency if omitted.

accountEquity

number

Total account equity = margin balance + unrealised PnL.

unrealisedPNL

number

Total unrealised profit/loss across open positions.

marginBalance

number

Margin balance = position margin + order margin + frozen funds + available balance − unrealised PnL.

positionMargin

number

Margin locked in open positions.

orderMargin

number

Margin locked in open orders.

frozenFunds

number

Funds frozen for pending withdrawals or transfers.

availableBalance

number

Balance available to place new orders.

currency

string

Currency code, e.g. USDT.

riskRatio

number

Cross-margin risk ratio.

maxWithdrawAmount

number

Maximum amount that can be withdrawn.

availableMargin

number

Cross-margin available balance.

import { FuturesClient } from 'kucoin-api';

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

const balance = await client.getBalance({ currency: 'USDT' });
console.log('Account equity:', balance.data.accountEquity);
console.log('Available:', balance.data.availableBalance);
console.log('Unrealised PnL:', balance.data.unrealisedPNL);

`getSubBalances(params?)`

Returns an aggregated balance summary alongside individual sub-account balance details for the futures business line.

getSubBalances(params?: { currency?: string }): Promise<
  APISuccessResponse<{
    summary: AccountSummary;
    accounts: FuturesSubAccount[];
  }>
>

currency

string

Settlement currency filter (optional).

summary

AccountSummary

Show AccountSummary fields

accountEquityTotal

number

Sum of all sub-account equities.

unrealisedPNLTotal

number

Sum of all unrealised PnL.

marginBalanceTotal

number

Sum of margin balances.

positionMarginTotal

number

Sum of position margins.

orderMarginTotal

number

Sum of order margins.

frozenFundsTotal

number

Sum of frozen funds.

availableBalanceTotal

number

Sum of available balances.

currency

string

Currency code.

accounts

FuturesSubAccount[]

List of per-sub-account balance records.

Transactions & Transfers

`getTransactions(params?)`

Returns paginated ledger records for the futures account — realised PnL, deposits, withdrawals, and fund transfers.

getTransactions(params: GetTransactionsRequest): Promise<
  APISuccessResponse<{
    hasMore: boolean;
    dataList: FuturesAccountTransaction[];
  }>
>

startAt

number

Start time (Unix ms, optional).

endAt

number

End time (Unix ms, optional).

type

"RealisedPNL" | "Deposit" | "Withdrawal" | "Transferin" | "TransferOut"

Filter by transaction type (optional).

offset

number

Pagination offset (optional).

maxCount

number

Maximum records per page (optional).

currency

string

Filter by currency (optional).

forward

boolean

Paginate forward (optional).

hasMore

boolean

Whether more pages are available.

dataList

FuturesAccountTransaction[]

Show FuturesAccountTransaction fields

time

number

Event timestamp (ms).

type

string

Transaction type (e.g. RealisedPNL, Deposit).

amount

number

Transaction amount.

fee

number | null

Fees charged (null for non-fee events).

accountEquity

number

Account equity at the time of this event.

status

"Completed" | "Pending"

Processing status.

remark

string

Related contract symbol or description.

offset

number

Ledger offset for pagination.

currency

string

Currency of the transaction.

`getTransfers(params?)`

Returns historical records of fund transfers in and out of the futures account.

getTransfers is deprecated. Use the universal transfer methods on SpotClient for new integrations.

getTransfers(params?: {
  currency?: string;
  type?: 'MAIN' | 'TRADE' | 'MARGIN' | 'ISOLATED';
  tag?: string[];
  startAt?: number;
  endAt?: number;
  currentPage?: number;
  pageSize?: number;
}): Promise<APISuccessResponse<any>>

currency

string

Filter by currency (optional).

type

"MAIN" | "TRADE" | "MARGIN" | "ISOLATED"

Filter by account 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).

`submitTransferIn(params)`

Transfers funds into the futures account from your main or trade wallet.

submitTransferIn is deprecated. Use the universal transfer endpoint on SpotClient for new integrations.

submitTransferIn(params: {
  currency: string;
  amount: number;
  payAccountType: 'MAIN' | 'TRADE';
}): Promise<APISuccessResponse<any>>

currency

string

required

Currency to transfer (e.g. USDT).

amount

number

required

Amount to transfer in.

payAccountType

"MAIN" | "TRADE"

required

Source account type.

`submitTransferOut(params)`

Transfers funds out of the futures account to your main or trade wallet.

submitTransferOut is deprecated. Use the universal transfer endpoint on SpotClient for new integrations.

submitTransferOut(params: {
  currency: string;
  amount: number;
  recAccountType: 'MAIN' | 'TRADE';
}): Promise<APISuccessResponse<any>>

currency

string

required

Currency to transfer (e.g. USDT).

amount

number

required

Amount to transfer out.

recAccountType

"MAIN" | "TRADE"

required

Destination account type.

Open Order Statistics

`getOpenOrderStatistics(params)`

Returns the total count and aggregate notional value of all open orders for the specified futures contract.

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

symbol

string

required

Futures contract symbol.

openOrderBuySize

number

Total number of open buy (long) order lots.

openOrderSellSize

number

Total number of open sell (short) order lots.

openOrderBuyCost

string

Aggregate notional value of all open buy orders.

openOrderSellCost

string

Aggregate notional value of all open sell orders.

settleCurrency

string

Settlement currency for the contract.

const stats = await client.getOpenOrderStatistics({ symbol: 'XBTUSDTM' });
console.log('Open buy lots:', stats.data.openOrderBuySize);
console.log('Open sell lots:', stats.data.openOrderSellSize);
console.log('Buy cost:', stats.data.openOrderBuyCost);

Use getOpenOrderStatistics alongside getPosition to assess your full market exposure — open orders commit margin just like live positions.

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

KuCoin FuturesClient Funding Rates & Account Balance

Funding Rates

`getFundingRate(params)`

`getFundingRates(params?)`

`getFundingHistory(params?)`

Account Balance

`getBalance()`

`getSubBalances(params?)`

Transactions & Transfers

`getTransactions(params?)`

`getTransfers(params?)`

`submitTransferIn(params)`

`submitTransferOut(params)`

Open Order Statistics

`getOpenOrderStatistics(params)`

Build docs developers (and LLMs) love

SpotClient

FuturesClient

WebsocketAPIClient

UnifiedAPIClient

Documentation Index

​Funding Rates

​getFundingRate(params)

​getFundingRates(params?)

​getFundingHistory(params?)

​Account Balance

​getBalance()

​getSubBalances(params?)

​Transactions & Transfers

​getTransactions(params?)

​getTransfers(params?)

​submitTransferIn(params)

​submitTransferOut(params)

​Open Order Statistics

​getOpenOrderStatistics(params)

Build docs developers (and LLMs) love

Funding Rates

`getFundingRate(params)`

`getFundingRates(params?)`

`getFundingHistory(params?)`

Account Balance

`getBalance()`

`getSubBalances(params?)`

Transactions & Transfers

`getTransactions(params?)`

`getTransfers(params?)`

`submitTransferIn(params)`

`submitTransferOut(params)`

Open Order Statistics

`getOpenOrderStatistics(params)`