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.

The UnifiedAPIClient provides access to KuCoin’s Unified Trading Account (UTA) — also called the PRO account — through a single, cohesive REST client. Instead of managing separate spot, futures, and margin clients, the UTA exposes one set of endpoints that works across all asset classes. Market data is public; account, trading, position, funding, and sub-account endpoints require API credentials. The UnifiedAPIClient extends the SDK’s BaseRestClient, inheriting automatic request signing, rate-limit handling, error normalisation, and retry logic. Methods that require authentication call getPrivate or postPrivate internally; public market data methods use get.

​
Initialization

import { UnifiedAPIClient } from 'kucoin-api';

const client = new UnifiedAPIClient({
  apiKey: process.env.KUCOIN_API_KEY || 'your-api-key',
  apiSecret: process.env.KUCOIN_API_SECRET || 'your-api-secret',
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE || 'your-api-passphrase',
});
You can omit credentials for public market data endpoints; they are required for any private (authenticated) calls.

​
Account Methods

Retrieve the balance and asset details for the Unified Trading Account.
getAccount(): Promise<APISuccessResponse<GetClassicAccountResponseUTA>>
Endpoint: GET api/ua/v1/unified/account/balance — Private
const account = await client.getAccount();
console.log(account.data);
Get a high-level overview of the Unified Trading Account, including aggregated equity, margin, and unrealised PnL.
getAccountOverview(): Promise<APISuccessResponse<GetAccountOverviewResponseUTA>>
Endpoint: GET api/ua/v1/unified/account/overview — Private
const overview = await client.getAccountOverview();
console.log(overview.data);
Query the current account mode and list of unified/classic sub-accounts.
getAccountMode(): Promise<APISuccessResponse<GetAccountModeResponseUTA>>
Endpoint: GET api/ua/v1/account/mode — Private
const mode = await client.getAccountMode();
console.log(mode.data);
Set the account mode to UTA (Unified Trading Account).
setAccountMode(
  params: SetAccountModeRequestUTA,
): Promise<APISuccessResponse<null>>
Endpoint: POST api/ua/v1/account/mode — Private
await client.setAccountMode({ /* mode params */ });
Get balances for a Classic Account type: FUNDING, SPOT, FUTURES, CROSS, or ISOLATED.
getClassicAccount(
  params: GetClassicAccountRequestUTA,
): Promise<APISuccessResponse<GetClassicAccountResponseUTA>>
Endpoint: GET api/ua/v1/account/balance — Private
// Spot balance
const spot = await client.getClassicAccount({ accountType: 'SPOT' });

// Futures balance filtered by currency
const futures = await client.getClassicAccount({
  accountType: 'FUTURES',
  currency: 'USDT,XBT',
});

​
Market Data Methods

All market data endpoints are public. No credentials are required to call them.
Retrieve the list of available trading instruments for a given trade type.
getSymbols(
  params: GetSymbolRequestUTA,
): Promise<APISuccessResponse<GetSymbolResponseUTA>>
Endpoint: GET api/ua/v1/market/instrument — Public
​
tradeType
string
required
One of 'SPOT' or 'FUTURES'.
​
symbol
string
Optional symbol filter, e.g. 'BTC-USDT'.
const spotSymbols = await client.getSymbols({ tradeType: 'SPOT' });
const futuresSymbols = await client.getSymbols({ tradeType: 'FUTURES' });

// Single symbol lookup
const btc = await client.getSymbols({ tradeType: 'SPOT', symbol: 'BTC-USDT' });
Get 24-hour market ticker data (last price, volume, bid/ask) for a trade type.
getTickers(
  params: GetTickerRequestUTA,
): Promise<APISuccessResponse<GetTickerResponseUTA>>
Endpoint: GET api/ua/v1/market/ticker — Public
const spotTickers = await client.getTickers({ tradeType: 'SPOT' });
const futuresTicker = await client.getTickers({
  tradeType: 'FUTURES',
  symbol: 'XBTUSDTM',
});
Get OHLCV candlestick data for a symbol.
getKlines(
  params: GetKlinesRequestUTA,
): Promise<APISuccessResponse<GetKlinesResponseUTA>>
Endpoint: GET api/ua/v1/market/kline — Public
const klines = await client.getKlines({
  tradeType: 'SPOT',
  symbol: 'BTC-USDT',
  interval: '1hour',
  startAt: Date.now() - 24 * 60 * 60 * 1000,
  endAt: Date.now(),
});
Get aggregated order book depth for a symbol.
getOrderBook(
  params: GetOrderBookRequestUTA,
): Promise<APISuccessResponse<GetOrderBookResponseUTA>>
Endpoint: GET api/ua/v1/market/orderbook — Public
const book = await client.getOrderBook({
  tradeType: 'SPOT',
  symbol: 'BTC-USDT',
  limit: '20', // '20' | '50' | '100' | 'FULL'
});
Get trade execution history for the authenticated account.
getTradeHistory(
  params: GetTradeHistoryRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<GetTradeHistoryResponseUTA>>
Endpoint: GET api/ua/v1/{accountMode}/order/execution — Private
const trades = await client.getTradeHistory(
  {
    tradeType: 'SPOT',
    symbol: 'BTC-USDT',
    startAt: Date.now() - 24 * 60 * 60 * 1000,
    endAt: Date.now(),
    pageSize: 50,
  },
  'unified',
);

​
Trading Methods

Place a single order for spot, margin, or futures. The accountMode parameter (default 'unified') determines both the endpoint path and how tradeType is transmitted.
  • Unified mode ('unified'): tradeType is sent in the JSON request body.
  • Classic mode ('classic'): tradeType is appended as a query parameter.
placeOrder(
  params: PlaceOrderRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<PlaceOrderResponseUTA>>
Endpoint: POST api/ua/v1/{accountMode}/order/place — Private
const order = await client.placeOrder(
  {
    tradeType: 'SPOT',
    clientOid: 'spot-' + Date.now(),
    symbol: 'BTC-USDT',
    side: 'BUY',
    orderType: 'LIMIT',
    size: '0.001',
    sizeUnit: 'BASECCY',
    price: '40000',
    timeInForce: 'GTC',
  },
  'unified',
);
console.log('Order ID:', order.data);
Place multiple orders in a single request (default accountMode: 'classic'). Maximum batch size is determined by the exchange.
batchPlaceOrder(
  params: BatchPlaceOrderRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<BatchPlaceOrderResponseUTA>>
Endpoint: POST api/ua/v1/{accountMode}/order/place-batch — Private
const batch = 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',
);
Cancel a single order by order ID or client order ID.
cancelOrder(
  params: CancelOrderRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<CancelOrderResponseUTA>>
Endpoint: POST api/ua/v1/{accountMode}/order/cancel — Private
// Cancel by orderId
await client.cancelOrder(
  { tradeType: 'FUTURES', symbol: 'XBTUSDTM', orderId: 'order-id' },
  'unified',
);

// Cancel by clientOid
await client.cancelOrder(
  { tradeType: 'SPOT', symbol: 'BTC-USDT', clientOid: 'my-client-oid' },
  'unified',
);
Cancel up to 20 orders in a single request.
batchCancelOrders(
  params: BatchCancelOrdersRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<BatchCancelOrdersResponseUTA>>
Endpoint: POST api/ua/v1/{accountMode}/order/cancel-batch — Private
await client.batchCancelOrders(
  {
    tradeType: 'FUTURES',
    cancelOrderList: [
      { symbol: 'XBTUSDTM', orderId: 'id1' },
      { symbol: 'XBTUSDTM', clientOid: 'oid2' },
    ],
  },
  'unified',
);
Cancel all open orders for one or more symbols in Unified account mode. Supports SPOT, FUTURES, and MARGIN (Spot-Margin).
batchCancelOrdersBySymbol(
  params: BatchCancelOrdersBySymbolRequestUTA,
): Promise<APISuccessResponse<BatchCancelOrdersBySymbolResponseUTA>>
Endpoint: POST api/ua/v1/unified/order/cancel-all — Private (UTA only)
await client.batchCancelOrdersBySymbol({
  tradeType: 'FUTURES',
  symbol: 'XBTUSDTM',
});
Retrieve details for a single order.
getOrderDetails(
  params: GetOrderDetailsRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<OrderDetailsUTA>>
Endpoint: GET api/ua/v1/{accountMode}/order/detail — Private
const details = await client.getOrderDetails(
  { tradeType: 'SPOT', symbol: 'BTC-USDT', orderId: 'order-id-here' },
  'unified',
);
Get historical (completed or cancelled) orders with optional filters.
getOrderHistory(
  params: GetOrderHistoryRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<GetOrderHistoryResponseUTA>>
Endpoint: GET api/ua/v1/{accountMode}/order/history — Private
const history = await client.getOrderHistory(
  {
    tradeType: 'FUTURES',
    symbol: 'XBTUSDTM',
    startAt: Date.now() - 24 * 60 * 60 * 1000,
    endAt: Date.now(),
    pageSize: 100,
  },
  'unified',
);
List all currently open orders, optionally filtered by symbol or trade type.
getOpenOrderList(
  params: GetOpenOrderListRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<GetOpenOrderListResponseUTA>>
Endpoint: GET api/ua/v1/{accountMode}/order/open-list — Private
const openOrders = await client.getOpenOrderList(
  { tradeType: 'SPOT', symbol: 'BTC-USDT', pageSize: 50 },
  'unified',
);
Get the latest 100 public trades for a symbol (no authentication required).
getTrades(
  params: GetTradesRequestUTA,
): Promise<APISuccessResponse<GetTradesResponseUTA>>
Endpoint: GET api/ua/v1/market/trade — Public
const trades = await client.getTrades({ tradeType: 'SPOT', symbol: 'BTC-USDT' });

​
Position Methods

Get all open futures positions for the Unified account, optionally filtered by symbol.
getPositionList(
  params?: GetPositionListRequestUTA,
): Promise<APISuccessResponse<PositionUTA[]>>
Endpoint: GET api/ua/v1/unified/position/open-list — Private
// All open positions
const positions = await client.getPositionList();

// Filter by symbol, with pagination
const btcPositions = await client.getPositionList({
  symbol: 'XBTUSDTM',
  pageNumber: 1,
  pageSize: 50,
});
Query closed position history. Data is retained for up to 3 months; each query is limited to a 7-day time range.
getPositionsHistory(
  params?: GetPositionsHistoryRequestUTA,
): Promise<APISuccessResponse<GetPositionsHistoryResponseUTA>>
Endpoint: GET api/ua/v1/position/history — Private
const history = await client.getPositionsHistory({
  symbol: 'XBTUSDTM',
  startAt: Date.now() - 7 * 24 * 60 * 60 * 1000,
  endAt: Date.now(),
  pageSize: 50,
});
Modify the leverage for a specified futures symbol in the Unified account.
modifyLeverage(
  params: ModifyLeverageRequestUTA,
): Promise<APISuccessResponse<null>>
Endpoint: POST api/ua/v1/unified/account/modify-leverage — Private
await client.modifyLeverage({ symbol: 'XBTUSDTM', leverage: '5' });
Query the current leverage for MARGIN (by currency) or FUTURES (by symbol).
getLeverage(
  params: GetLeverageRequestUTA,
): Promise<APISuccessResponse<GetLeverageItemUTA[]>>
Endpoint: GET api/ua/v1/unified/account/leverage — Private
// Futures leverage
const futuresLev = await client.getLeverage({
  tradeType: 'FUTURES',
  marginMode: 'CROSS',
  symbol: 'XBTUSDTM',
});

// Cross margin leverage for a currency
const marginLev = await client.getLeverage({
  tradeType: 'MARGIN',
  marginMode: 'CROSS',
  currency: 'BTC',
});
Retrieve the risk limit / position tier information for a futures contract. Currently supports Classic account, isolated margin only.
getAccountPositionTiers(
  params: GetAccountPositionTiersRequestUTA,
  accountMode?: 'classic' | 'unified',
): Promise<APISuccessResponse<PositionTierUTA[]>>
Endpoint: GET api/ua/v1/{accountMode}/position/tiers — Private
const tiers = await client.getAccountPositionTiers(
  { symbol: 'XBTUSDTM', tradeType: 'FUTURES', marginMode: 'ISOLATED' },
  'classic',
);

​
Funding Methods

Get the deposit address for a currency. If both currency and chain are provided, the address is created if it does not yet exist.
getDepositAddress(
  params: GetDepositAddressRequestUTA,
): Promise<APISuccessResponse<DepositAddressUTA[]>>
Endpoint: GET api/ua/v1/asset/deposit/address — Private
const addresses = await client.getDepositAddress({ currency: 'BTC' });
const btcAddress = await client.getDepositAddress({ currency: 'BTC', chain: 'BTC' });
Initiate a withdrawal for the specified currency.
submitWithdraw(
  params: SubmitWithdrawRequestUTA,
): Promise<APISuccessResponse<SubmitWithdrawResponseUTA>>
Endpoint: POST api/ua/v1/withdrawal — Private
const withdrawal = await client.submitWithdraw({
  currency: 'USDT',
  address: '0xYourWalletAddress',
  amount: '100',
  chain: 'ERC20',
});
Cancel a withdrawal that is still in PROCESSING status.
cancelWithdrawal(params?: {
  withdrawalId?: string;
}): Promise<APISuccessResponse<string | null>>
Endpoint: DELETE api/ua/v1/withdrawal — Private
await client.cancelWithdrawal({ withdrawalId: 'your-withdrawal-id' });
Get the transferable balance for a specified account type.
getTransferQuotas(
  params: GetTransferQuotasRequestUTA,
): Promise<APISuccessResponse<GetTransferQuotasResponseUTA>>
Endpoint: GET api/ua/v1/account/transfer-quota — Private
const quotas = await client.getTransferQuotas({ accountType: 'SPOT' });
Transfer funds between master and sub-accounts, or between account types (FUNDING, SPOT, FUTURES, CROSS, ISOLATED, UNIFIED).
flexTransfer(
  params: FlexTransferRequestUTA,
): Promise<APISuccessResponse<FlexTransferResponseUTA>>
Endpoint: POST api/ua/v1/account/transfer — Private
const transfer = await client.flexTransfer({
  fromAccountType: 'SPOT',
  toAccountType: 'FUTURES',
  currency: 'USDT',
  amount: '500',
});

​
Sub-Account Methods

Create a new sub-account under the master account.
addSubAccount(
  params: AddSubAccountRequestUTA,
): Promise<APISuccessResponse<AddSubAccountResponseUTA>>
Endpoint: POST api/ua/v1/user/sub/create-sub-account — Private
const subAccount = await client.addSubAccount({
  subName: 'my-sub-account',
  password: 'securePassword123',
  remarks: 'trading sub-account',
});
Create an API key for an existing sub-account.
addSubAccountApi(
  params: AddSubAccountApiRequestUTA,
): Promise<APISuccessResponse<AddSubAccountApiResponseUTA>>
Endpoint: POST api/ua/v1/user/create-sub-api-key — Private
const subApi = await client.addSubAccountApi({
  subName: 'my-sub-account',
  passphrase: 'apiPassphrase',
  remark: 'trading key',
  permission: 'General,Trade',
});
Retrieve sub-account balance information.
getSubAccount(
  params?: GetSubAccountRequestUTA,
): Promise<APISuccessResponse<GetSubAccountResponseUTA>>
Endpoint: GET api/ua/v1/sub-account/balance — Private
// All sub-accounts
const subAccounts = await client.getSubAccount();

// Specific sub-account
const specific = await client.getSubAccount({ subUserId: 'sub-user-id' });

​
Full Code Examples

import { UnifiedAPIClient } from 'kucoin-api';

const client = new UnifiedAPIClient({
  apiKey: process.env.KUCOIN_API_KEY || 'your-api-key',
  apiSecret: process.env.KUCOIN_API_SECRET || 'your-api-secret',
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE || 'your-api-passphrase',
});

client.placeOrder(
  {
    tradeType: 'SPOT',
    clientOid: 'order-' + Date.now(),
    symbol: 'BTC-USDT',
    side: 'BUY',
    orderType: 'LIMIT',
    size: '0.001',
    sizeUnit: 'BASECCY',
    price: '40000',
    timeInForce: 'GTC',
  },
  'unified',
)
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.error(error);
  });
The accountMode parameter accepted by order methods ('unified' or 'classic') defaults to 'unified' for most calls. Use 'classic' when operating a Classic account, where tradeType must be sent as a query parameter rather than in the request body.

Build docs developers (and LLMs) love

Get started for freeTalk to us