FuturesClient: Futures Trading REST API

FuturesClient provides a fully-typed interface to KuCoin’s Futures REST API. It handles every aspect of futures trading — from fetching contract specs and order book data to placing leveraged orders, managing positions, querying funding rates, and transferring funds in and out of the futures account. All requests are routed to the dedicated futures base URL (api-futures.kucoin.com), and private methods are automatically authenticated.

All futures REST requests are sent to https://api-futures.kucoin.com. The SDK handles the base URL selection automatically when you instantiate FuturesClient — you do not need to configure it manually.

Installation

npm install kucoin-api

Initialization

import { FuturesClient } from 'kucoin-api';

const client = new FuturesClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});

Public endpoints (symbols, tickers, order books, klines) work without credentials. Create the client without options or omit the credentials for a public-only instance.

Feature Overview

Market Data

Fetch active contracts, tickers, full/partial order books, public trades, mark prices, premium index, interest rates, and 24 h transaction volume.

Order Management

Submit single orders, batch-place multiple contracts, place SL/TP orders, cancel by ID or client OID, and batch-cancel. Supports both market and limit types.

Position Management

Query open and historical positions, change position/margin mode (isolated vs cross), deposit or withdraw isolated margin, and set risk-limit levels.

Funding Rates

Get the current funding rate, historical funding rates over date ranges, and your private funding fee payment history for each contract.

Account & Balance

Check XBT/USDT account balance, view transaction ledgers, list sub-account balances, query actual trading fees, and transfer funds to/from the futures account.

Stop & SL/TP Orders

Submit stop orders with configurable trigger types, cancel all untriggered stop orders, and use the dedicated SL/TP order endpoint for bracket-style entries.

Understanding Contract Sizes

Before trading, it is important to understand the contract multiplier. Each futures contract represents a fixed number of the underlying asset (the “multiplier”), not one whole coin.

// Fetch the contract spec for XRPUSDTM
const symbolInfo = await client.getSymbol({ symbol: 'XRPUSDTM' });
const multiplier = symbolInfo.data.multiplier; // e.g. 10 (= 10 XRP per lot)

// Calculate position size given funds and leverage
const xrpPrice = 0.5;       // current price in USDT
const leverage = 5;
const fundsUSDT = 100;

const costPerContract = xrpPrice * multiplier; // 0.5 * 10 = 5 USDT
const size = (fundsUSDT * leverage) / costPerContract; // (100 * 5) / 5 = 100 lots
console.log(`Size: ${size} lots`);

Usage Examples

Market Data

// All active contracts
const contracts = await client.getSymbols();

// Single contract details
const contract = await client.getSymbol({ symbol: 'XBTUSDTM' });

// Ticker — last price, best bid/ask
const ticker = await client.getTicker({ symbol: 'XBTUSDTM' });

// Full Level-2 order book snapshot
const fullBook = await client.getFullOrderBookLevel2({ symbol: 'XBTUSDTM' });

// Partial order book — top 20 or top 100 levels
const partialBook = await client.getPartOrderBookLevel2Depth20({ symbol: 'XBTUSDTM' });

// Klines — 60-minute candles for the last 24 hours
const klines = await client.getKlines({
  symbol: 'XBTUSDTM',
  granularity: 60,
  from: Date.now() - 24 * 60 * 60 * 1000,
  to: Date.now(),
});

// Current mark price
const mark = await client.getMarkPrice({ symbol: 'XBTUSDTM' });

Funding Rates

// Current funding rate for a contract
const currentRate = await client.getFundingRate({ symbol: 'XBTUSDM' });

// Historical public funding rates
const history = await client.getFundingRates({
  symbol: 'XBTUSDTM',
  from: '1700310700000',
  to: '1702310700000',
});

// Your private funding fee payments
const myFees = await client.getFundingHistory({ symbol: 'ETHUSDTM' });

Order Placement

import { FuturesClient } from 'kucoin-api';

const client = new FuturesClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});

// Submit a futures buy order for 1 lot of XBTUSDTM with 2x leverage
const orderRes = await client.submitOrder({
  clientOid: client.generateNewOrderID(),
  side: 'buy',
  type: 'market',
  symbol: 'XBTUSDTM',
  size: 1,
  leverage: 2,
});
console.log('orderRes', JSON.stringify(orderRes, null, 2));

Batch Orders

// Place multiple orders in a single request (up to 20)
const orders = [
  {
    clientOid: '5c52e11203aa677f33e491',
    side: 'buy',
    symbol: 'ETHUSDTM',
    type: 'limit',
    price: '2150',
    leverage: 1,
    size: 2,
  },
  {
    clientOid: 'je12019ka012ja013099',
    side: 'buy',
    symbol: 'XBTUSDTM',
    type: 'limit',
    price: '32150',
    leverage: 1,
    size: 2,
  },
];

const batchResult = await client.submitMultipleOrders(orders);

Order Management

// Cancel by order ID or client OID
await client.cancelOrderById({ orderId: 'your-order-id' });
await client.cancelOrderByClientOid({ clientOid: 'your-client-oid' });

// Cancel all orders for a symbol
await client.cancelAllOrdersV3({ symbol: 'XBTUSDTM' });

// Cancel all untriggered stop orders for a symbol
await client.cancelAllStopOrders({ symbol: 'XBTUSDTM' });

// Query open and closed orders
const activeOrders  = await client.getOrders({ status: 'active' });
const closedOrders  = await client.getOrders({ status: 'done' });

// Recent fills
const fills = await client.getFills({});
const recentFills = await client.getRecentFills({});

Position Management

// Current open position for a symbol
const position = await client.getPosition({ symbol: 'ETHUSDTM' });

// All open positions (optionally filter by currency)
const allPositions = await client.getPositions({ currency: 'USDT' });

// Historical / closed positions
const history = await client.getHistoryPositions({ symbol: 'ETHUSDTM' });

// Switch margin mode (isolated <-> cross)
await client.updateMarginMode({
  symbol: 'XBTUSDTM',
  marginMode: 'ISOLATED',
});

// Deposit additional margin to an isolated position
await client.depositMargin({
  symbol: 'XBTUSDTM',
  bizNo: client.generateNewOrderID(),
  margin: 100,
});

Account & Transfers

// Futures account balance (XBT by default)
const balance = await client.getBalance({ currency: 'USDT' });

// Transaction history
const txHistory = await client.getTransactions({
  type: 'RealisedPNL',
  maxCount: 10,
  currency: 'USDT',
});

// Transfer USDT out of futures to main account
await client.submitTransferOut({
  amount: 50,
  currency: 'USDT',
  recAccountType: 'MAIN',
});

// Transfer into futures from main account
await client.submitTransferIn({
  amount: 50,
  currency: 'USDT',
  payAccountType: 'MAIN',
});

Key Methods Reference

Market Data (Public)

Method	Auth	Description
`getSymbols()`	❌	All active futures contracts
`getSymbol()`	❌	Single contract details
`getTicker()`	❌	Last price, bid/ask for a symbol
`getTickers()`	❌	All tickers in one call
`getFullOrderBookLevel2()`	❌	Complete Level-2 snapshot
`getKlines()`	❌	Candlestick / OHLCV data
`getMarkPrice()`	❌	Current mark price
`getInterestRates()`	❌	Funding interest rate list
`getPremiumIndex()`	❌	Premium index values
`get24HourTransactionVolume()`	❌	24 h total trading volume

Order Management

Method	Auth	Description
`submitOrder()`	✅	Place a single futures order
`submitMultipleOrders()`	✅	Batch-place futures orders
`submitSLTPOrder()`	✅	Bracket order with SL and TP
`cancelOrderById()`	✅	Cancel by order ID
`cancelOrderByClientOid()`	✅	Cancel by client order ID
`batchCancelOrders()`	✅	Cancel multiple orders at once
`cancelAllOrdersV3()`	✅	Cancel all orders (v3)
`cancelAllStopOrders()`	✅	Cancel all stop orders
`getOrders()`	✅	List active or completed orders
`getStopOrders()`	✅	List untriggered stop orders

Position Management

Method	Auth	Description
`getPosition()`	✅	Single symbol position
`getPositions()`	✅	All open positions
`getHistoryPositions()`	✅	Historical closed positions
`getMarginMode()`	✅	Current margin mode for symbol
`updateMarginMode()`	✅	Switch isolated/cross margin
`depositMargin()`	✅	Add margin to isolated position
`withdrawMargin()`	✅	Remove margin from position
`updateRiskLimitLevel()`	✅	Change risk limit tier
`getPositionMode()`	✅	One-way vs hedge mode
`updatePositionMode()`	✅	Switch position mode

Funding Rates

Method	Auth	Description
`getFundingRate()`	✅	Current rate for a symbol
`getFundingRates()`	✅	Historical public rates
`getFundingHistory()`	✅	Private funding fee payments

Account & Transfers

Method	Auth	Description
`getBalance()`	✅	Futures account balance
`getTransactions()`	✅	Account ledger entries
`getSubBalances()`	✅	Sub-account futures balances
`getTradingPairFee()`	✅	Actual trading fee for a symbol
`submitTransferOut()`	✅	Transfer out of futures
`submitTransferIn()`	✅	Transfer into futures
`getTransfers()`	✅	Transfer history

SpotClient

Spot and margin trading, HF orders, deposits, withdrawals, and earn products.

UnifiedAPIClient

KuCoin PRO unified account — trade spot and futures from a single client.

BrokerClient

Broker sub-account creation, API key management, and rebate downloads.

Get Started

REST Clients

WebSockets

Guides

Installation

Initialization

Feature Overview

Market Data

Order Management

Position Management

Funding Rates

Account & Balance

Stop & SL/TP Orders

Understanding Contract Sizes

Usage Examples

Market Data

Funding Rates

Order Placement

Batch Orders

Order Management

Position Management

Account & Transfers

Key Methods Reference

SpotClient

UnifiedAPIClient

BrokerClient

Build docs developers (and LLMs) love

Get Started

REST Clients

WebSockets

Guides

Documentation Index

​Installation

​Initialization

​Feature Overview

Market Data

Order Management

Position Management

Funding Rates

Account & Balance

Stop & SL/TP Orders

​Understanding Contract Sizes

​Usage Examples

​Market Data

​Funding Rates

​Order Placement

​Batch Orders

​Order Management

​Position Management

​Account & Transfers

​Key Methods Reference

​Related Pages

SpotClient

UnifiedAPIClient

BrokerClient

Build docs developers (and LLMs) love

Installation

Initialization

Feature Overview

Understanding Contract Sizes

Usage Examples

Market Data

Funding Rates

Order Placement

Batch Orders

Order Management

Position Management

Account & Transfers

Key Methods Reference

Related Pages