Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/kucoin-api/llms.txt

Use this file to discover all available pages before exploring further.

UnifiedAPIClient is the REST client for KuCoin’s Unified Trading Account (UTA), also known as KuCoin PRO. The Unified Account collapses the separate Spot, Futures, and Margin balances into a single account view, and exposes a unified set of API endpoints (prefixed api/ua/v1/) that work consistently across all product types. A single order placement call handles spot limit orders, cross-margin trades, and perpetual futures — differentiated only by the tradeType parameter and whether you are in unified or classic mode.
The Unified Trading Account is a separate account mode from the standard KuCoin account. You must upgrade to a KuCoin PRO / Unified Account to use these endpoints. Standard spot or futures API keys will not work with UnifiedAPIClient unless you have enabled the unified account on your KuCoin profile.

​
Installation

npm install kucoin-api

​
Initialization

import { UnifiedAPIClient } from 'kucoin-api';

// With credentials (required for all private endpoints)
const client = new UnifiedAPIClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});
Public market-data endpoints (getSymbols, getTickers, getOrderBook, getKlines, etc.) do not require authentication. You can still instantiate the client with credentials and call them freely.

​
Unified vs Classic Mode

Most trading endpoints accept an optional second argument that selects the account mode:
  • 'unified' (default) — uses the unified account balance; tradeType is sent in the JSON request body.
  • 'classic' — targets the classic (non-unified) account; tradeType is sent as a URL query parameter instead.
// Unified mode (default) — body contains tradeType
await client.placeOrder({ tradeType: 'SPOT', ... }, 'unified');

// Classic mode — tradeType goes to the query string
await client.placeOrder({ tradeType: 'SPOT', ... }, 'classic');

​
Feature Overview

Market Data

Unified public endpoints for symbols, tickers, order books, klines, recent trades, announcements, funding rates, and cross-margin configuration — all under the api/ua/v1/market/ path.

Unified Orders

Place, batch-place, query, and cancel orders across Spot, Futures, and Margin with a single consistent API surface. Supports limit, market, GTC/IOC/FOK time-in-force, and batch cancellation by symbol.

Position Management

List open futures positions (with optional pagination), view position history, check funding fee payments, modify margin modes (isolated/cross) in batch, and add/remove isolated futures margin.

Account & Balances

Query the unified account balance, classic account balance by type (SPOT/FUTURES/ISOLATED), account overview, sub-account balances, transfer quotas, and full account ledger.

Leverage & Margin

Modify futures leverage, change cross-margin leverage per currency, and query current leverage settings for any trade type and margin mode combination.

Transfers & Withdrawals

Execute flexible internal transfers (INTERNAL, PARENT_TO_SUB, SUB_TO_PARENT, SUB_TO_SUB), check withdrawal quotas, submit and cancel withdrawals, and manage deposit addresses.

​
Usage Examples

​
Market Data (Public)

import { UnifiedAPIClient } from 'kucoin-api';

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

// Service status
await client.getServiceStatus({ tradeType: 'SPOT' });

// Symbols — tradeType is required
const spotSymbols = await client.getSymbols({ tradeType: 'SPOT' });
const futuresSymbols = await client.getSymbols({ tradeType: 'FUTURES' });

// Tickers
await client.getTickers({ tradeType: 'SPOT' });
await client.getTickers({ tradeType: 'FUTURES', symbol: 'XBTUSDTM' });

// Order book — limit can be '20', '50', '100', or 'FULL'
const spotBook = await client.getOrderBook({
  tradeType: 'SPOT',
  symbol: 'BTC-USDT',
  limit: '20',
});
const futuresBook = await client.getOrderBook({
  tradeType: 'FUTURES',
  symbol: 'XBTUSDTM',
  limit: '100',
  rpiFilter: 0, // 0 = no RPI filter, 1 = include RPI rows (futures only)
});

// Klines / OHLCV
const klines = await client.getKlines({
  tradeType: 'SPOT',
  symbol: 'BTC-USDT',
  interval: '1hour',
  startAt: Date.now() - 24 * 60 * 60 * 1000,
  endAt: Date.now(),
});

​
Funding Rates & Cross-Margin Config

// Current funding rate for a perpetual contract
const fundingRate = await client.getCurrentFundingRate({ symbol: 'XBTUSDTM' });

// Historical funding rates
const rateHistory = await client.getHistoryFundingRate({
  symbol: 'XBTUSDTM',
  startAt: Date.now() - 7 * 24 * 60 * 60 * 1000,
  endAt: Date.now(),
});

// Cross-margin config (spot cross margin)
const crossConfig = await client.getCrossMarginConfig();

// Borrowable currencies and rates/limits
const borrowable = await client.getBorrowableCurrencies();
const limits = await client.getBorrowingRatesAndLimits({ currency: 'USDT' });

​
Account & Balances

// Unified account (UTA) balance overview
const account = await client.getAccount();
const overview = await client.getAccountOverview();

// Classic account balance by type
const spotBalance = await client.getClassicAccount({ accountType: 'SPOT' });
const futuresBalance = await client.getClassicAccount({
  accountType: 'FUTURES',
  currency: 'USDT,XBT',
});
const isolatedBalance = await client.getClassicAccount({
  accountType: 'ISOLATED',
  accountSubtype: 'BTC-USDT',
});

// Account ledger — filter by direction, currency, and time range
const ledger = await client.getAccountLedger({
  accountType: 'UNIFIED',
  currency: 'USDT',
  direction: 'IN',
  pageSize: 100,
  startAt: Date.now() - 24 * 60 * 60 * 1000,
  endAt: Date.now(),
});

// Get/set account mode
const mode = await client.getAccountMode();
await client.setAccountMode({ accountType: 'UNIFIED' });

// Fee rate for spot (up to 10 symbols) or futures (1 symbol)
const feeRate = await client.getFeeRate({
  tradeType: 'SPOT',
  symbol: 'BTC-USDT,ETH-USDT',
});

​
Leverage Management

// Modify futures leverage (Unified)
await client.modifyLeverage({ symbol: 'XBTUSDTM', leverage: '5' });

// Modify cross-margin leverage per currency
await client.modifyMarginCrossLeverage(
  { currency: 'BTC', leverage: '5' },
  'unified',
);

// Query current leverage settings
const futuresLeverage = await client.getLeverage({
  tradeType: 'FUTURES',
  marginMode: 'CROSS',
  symbol: 'XBTUSDTM',
});
const marginLeverage = await client.getLeverage({
  tradeType: 'MARGIN',
  marginMode: 'CROSS',
  currency: 'BTC',
});

​
Order Placement

// Spot limit buy — unified mode (default)
const spotLimit = await client.placeOrder(
  {
    tradeType: 'SPOT',
    clientOid: 'my-client-oid-' + Date.now(),
    symbol: 'BTC-USDT',
    side: 'BUY',
    orderType: 'LIMIT',
    size: '0.001',
    sizeUnit: 'BASECCY',
    price: '40000',
    timeInForce: 'GTC',
  },
  'unified',
);

​
Batch Order Placement

// Batch place up to 20 orders (classic mode)
const batchResult = await client.batchPlaceOrder(
  {
    tradeType: 'SPOT',
    orderList: [
      {
        clientOid: 'batch-1',
        symbol: 'BTC-USDT',
        side: 'BUY',
        orderType: 'LIMIT',
        size: '0.001',
        sizeUnit: 'BASECCY',
        price: '39000',
        timeInForce: 'GTC',
      },
      {
        clientOid: 'batch-2',
        symbol: 'BTC-USDT',
        side: 'BUY',
        orderType: 'LIMIT',
        size: '0.001',
        sizeUnit: 'BASECCY',
        price: '38500',
        timeInForce: 'GTC',
      },
    ],
  },
  'classic',
);

​
Order Queries & Cancellation

// Open order list (all active orders for a symbol)
const openOrders = await client.getOpenOrderList(
  { tradeType: 'FUTURES', symbol: 'XBTUSDTM', orderFilter: 'NORMAL' },
  'unified',
);

// Order history with time range
const orderHistory = await client.getOrderHistory(
  {
    tradeType: 'FUTURES',
    symbol: 'XBTUSDTM',
    startAt: Date.now() - 24 * 60 * 60 * 1000,
    endAt: Date.now(),
    pageSize: 100,
  },
  'unified',
);

// Trade execution history (fills)
const tradeHistory = await client.getTradeHistory(
  {
    tradeType: 'SPOT',
    symbol: 'BTC-USDT',
    startAt: Date.now() - 24 * 60 * 60 * 1000,
    endAt: Date.now(),
    pageSize: 50,
  },
  'unified',
);

// Cancel a single order by orderId
await client.cancelOrder(
  { tradeType: 'FUTURES', symbol: 'XBTUSDTM', orderId: 'your-order-id' },
  'unified',
);

// Batch cancel orders (max 20 per request)
await client.batchCancelOrders(
  {
    tradeType: 'FUTURES',
    cancelOrderList: [
      { symbol: 'XBTUSDTM', orderId: 'id1' },
      { symbol: 'XBTUSDTM', clientOid: 'oid2' },
    ],
  },
  'unified',
);

​
DCP — Disconnection Protect (Deadman Switch)

// Enable DCP: auto-cancel all futures orders if no heartbeat for 300 s
await client.setDCP({
  tradeType: 'FUTURES',
  timeout: 300,  // seconds; -1 to disable; valid range 5–86400
  symbols: ['XBTUSDTM'],
});

// Query current DCP settings
const dcp = await client.getDCP({ tradeType: 'FUTURES' });
DCP (Disconnection Protect) is only supported in classic mode. It triggers a mass cancel if the exchange does not receive a heartbeat within the configured timeout.

​
Positions

// List all open futures positions
const positions = await client.getPositionList();

// Filter by symbol or paginate
const btcPositions = await client.getPositionList({ symbol: 'XBTUSDTM' });
const paged = await client.getPositionList({ pageNumber: 1, pageSize: 50 });

// Historical positions (up to 3 months; max 7-day window per query)
const posHistory = await client.getPositionsHistory({
  symbol: 'XBTUSDTM',
  startAt: Date.now() - 7 * 24 * 60 * 60 * 1000,
  endAt: Date.now(),
  pageSize: 50,
});

// Private funding fee history for a symbol
const fundingFees = await client.getPrivateFundingFeeHistory({
  symbol: 'XBTUSDTM',
});

// Batch change margin mode (isolated or cross) for multiple symbols
await client.batchModifyMarginMode({
  symbolList: ['XBTUSDTM', 'ETHUSDTM'],
  marginMode: 'ISOLATED',
});

// Add margin to an isolated futures position
await client.modifyIsolatedFuturesMargin({
  symbol: 'XBTUSDTM',
  amount: '100',
  type: 'ADD',
});

​
Transfers & Sub-Accounts

// Check transferable balance before moving funds
const quota = await client.getTransferQuotas({
  currency: 'USDT',
  accountType: 'UNIFIED',
});

// Flex transfer — internal (same account, different account types)
await client.flexTransfer({
  clientOid: 'unique-oid-' + Date.now(),
  currency: 'USDT',
  amount: '100',
  type: '0',                 // 0 = INTERNAL
  fromAccountType: 'SPOT',
  toAccountType: 'FUTURES',
});

// Transfer from parent to sub-account
await client.flexTransfer({
  clientOid: 'unique-oid-' + Date.now(),
  currency: 'USDT',
  amount: '50',
  type: '1',                 // 1 = PARENT_TO_SUB
  fromAccountType: 'UNIFIED',
  toAccountType: 'UNIFIED',
  toUid: 'sub_account_uid',
});

// List sub-accounts
const subAccounts = await client.getSubAccount({ pageSize: 20 });

// Create a new sub-account
const newSub = await client.addSubAccount({
  subName: 'my_unified_sub',
  password: 'Str0ngPass!',
  access: 'Spot',
});

​
Withdrawals & Deposits

// Get deposit address for BTC
const depositAddr = await client.getDepositAddress({
  currency: 'BTC',
  chain: 'BTC',
});

// Check withdrawal quotas
const withdrawalQuotas = await client.getWithdrawalQuotas({ currency: 'USDT' });

// Submit a withdrawal
const withdrawal = await client.submitWithdraw({
  currency: 'USDT',
  address: '0xRecipientAddress',
  amount: '50',
  chain: 'ERC20',
});

// Cancel a pending withdrawal
await client.cancelWithdrawal({ withdrawalId: 'your_withdrawal_id' });

​
Key Methods Reference

MethodAuthDescription
getSymbols()❌All symbols for a trade type
getTickers()❌Tickers (24 h stats)
getTrades()❌Last 100 public trades
getOrderBook()❌Aggregated order book
getKlines()❌Candlestick / OHLCV data
getCurrentFundingRate()❌Current futures funding rate
getHistoryFundingRate()❌Historical funding rates
getCrossMarginConfig()❌Cross-margin config
getCurrency()❌Currency details
getAnnouncements()❌Exchange announcements
getServiceStatus()❌Platform status per trade type
MethodAuthDescription
getAccount()✅Unified account balance
getAccountOverview()✅Unified account summary
getClassicAccount()✅Classic balance by account type
getAccountMode()✅Get CLASSIC or UNIFIED mode
setAccountMode()✅Switch account mode
getAccountLedger()✅Full account transaction ledger
getInterestHistory()✅Interest accrual history
getFeeRate()✅Maker/taker fee rates
modifyLeverage()✅Futures leverage (unified)
getLeverage()✅Query current leverage settings
MethodAuthDescription
placeOrder()✅Place a single order
batchPlaceOrder()✅Batch place up to 20 orders
getOrderDetails()✅Order details by ID or client OID
getOpenOrderList()✅Active orders
getOrderHistory()✅Historical order list
getTradeHistory()✅Execution / fill history
cancelOrder()✅Cancel a single order
batchCancelOrders()✅Cancel up to 20 orders
batchCancelOrdersBySymbol()✅Cancel all orders for a symbol
setDCP()✅Set deadman switch (classic)
getDCP()✅Query DCP settings (classic)
MethodAuthDescription
getPositionList()✅Open futures positions
getPositionsHistory()✅Historical positions
getPrivateFundingFeeHistory()✅Private funding fee payments
batchModifyMarginMode()✅Batch switch margin mode
modifyIsolatedFuturesMargin()✅Add/remove isolated margin
getAccountPositionTiers()✅Risk-limit tiers
MethodAuthDescription
getTransferQuotas()✅Transferable balance by type
flexTransfer()✅Internal / parent-sub transfer
getSubAccount()✅List sub-accounts
addSubAccount()✅Create a new sub-account
addSubAccountApi()✅Create a sub-account API key
setSubAccountTransferPermission()✅Enable sub-to-sub transfers

SpotClient

Standard spot account — HF orders, margin trading, deposits, and earn products.

FuturesClient

Standard futures account — contracts, positions, and funding rates.

BrokerClient

Broker sub-account lifecycle and rebate management.

Build docs developers (and LLMs) love

Get started for freeTalk to us