SpotClient: Spot & Margin Trading REST API

SpotClient is the primary REST client for KuCoin’s spot exchange. It maps every endpoint in the official KuCoin Spot and Margin REST API to a typed TypeScript method, covering account management, market data retrieval, high-frequency (HF) order placement, stop orders, OCO orders, margin borrowing and repayment, fund transfers, sub-account management, and earn/staking products. All private methods automatically sign requests using your API credentials, so you never need to construct authentication headers manually.

Installation

npm install kucoin-api

Initialization

Import the client

// ESM / TypeScript
import { SpotClient } from 'kucoin-api';

// CommonJS
const { SpotClient } = require('kucoin-api');

Create an instance

With credentials (private + public)
Without credentials (public only)

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

// Public market-data endpoints work without authentication
const client = new SpotClient();

Store your API key, secret, and passphrase in environment variables. Never hard-code credentials in source files.

Feature Overview

Account & Balances

Query account summaries, spot/margin/isolated margin balances, transaction history (HF and standard), and API key metadata.

Market Data

Fetch all symbols, tickers, 24 h stats, order books (level 2/3), candlestick (kline) data, trade histories, and fiat prices. All endpoints are public.

HF Trading Orders

High-frequency order placement, batch submission, modification, sync cancellation, and dead-cancel-all (auto-cancel) via the api/v1/hf/orders family of endpoints.

Stop Orders & OCO

Submit and manage stop orders with trigger prices, and One-Cancels-the-Other (OCO) orders that atomically cancel the other leg on fill.

Margin Trading

Cross and isolated margin order placement (HF), borrowing, repayment, interest history, mark prices, risk limits, and leveraged token (ETF) data.

Deposits & Withdrawals

Create deposit addresses (v1/v2/v3), list deposits and withdrawals, submit withdrawals, check quotas, and perform flex (universal) transfers between account types.

Sub-Accounts

Create sub-accounts, manage their API keys, retrieve per-sub balances, and transfer funds between master and sub-accounts.

Earn Products

Subscribe to and redeem fixed-income, savings, staking (KCS, ETH), and promotion earn products; query current holdings and dual-investment/structured products.

Usage Examples

Account & Balances

// Get full account summary
const summary = await client.getAccountSummary();

// List all account balances (spot, trade, margin, etc.)
const balances = await client.getBalances();

// Margin balance (cross margin)
const marginBalance = await client.getMarginBalance();

// Isolated margin balances
const isolated = await client.getIsolatedMarginBalance();

// HF account ledger — high-frequency trading transactions
const hfLedger = await client.getHFTransactions({
  bizType: 'TRADE_EXCHANGE',
  currency: 'BTC,USDT',
  startAt: 1601395200000,
});

Market Data

// All tradable symbols
const symbols = await client.getSymbols();

// Single ticker (best bid/ask + last price)
const ticker = await client.getTicker({ symbol: 'BTC-USDT' });

// All tickers in a single call
const allTickers = await client.getTickers();

// Candlestick (kline) data — 1-minute candles for BTC-USDT
const klines = await client.getKlines({
  type: '1min',
  symbol: 'BTC-USDT',
  startAt: 1566703297,
  endAt: 1566789757,
});

// Partial order book — top 20 levels
const book20 = await client.getOrderBookLevel20({ symbol: 'BTC-USDT' });

// 24 h stats for a symbol
const stats = await client.get24hrStats({ symbol: 'BTC-USDT' });

HF Order Placement

HF orders vs regular orders: KuCoin recommends using the HF (High-Frequency) order endpoints (submitHFOrder, cancelHFOrder, etc.) for all new integrations. The older submitOrder / cancelOrderById endpoints still work but are marked deprecated in the SDK. HF orders process faster and support synchronous responses via submitHFOrderSync.

import { SpotClient } from 'kucoin-api';

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

// Market buy 0.00001 BTC
const buyResult = await client.submitHFOrder({
  clientOid: client.generateNewOrderID(),
  side: 'buy',
  type: 'market',
  symbol: 'BTC-USDT',
  size: '0.00001',
});
console.log('Buy order:', JSON.stringify(buyResult, null, 2));

Stop Orders & OCO Orders

// Submit a stop-limit sell order (triggers when price drops to stopPrice)
const stopOrder = await client.submitStopOrder({
  clientOid: client.generateNewOrderID(),
  side: 'sell',
  symbol: 'BTC-USDT',
  type: 'limit',
  price: '38000',
  size: '0.001',
  stopPrice: '38500',
  stop: 'loss',
  timeInForce: 'GTC',
});

// OCO order: limit sell at 45000, stop-limit at 38000
const ocoOrder = await client.submitOCOOrder({
  clientOid: client.generateNewOrderID(),
  side: 'sell',
  symbol: 'BTC-USDT',
  price: '45000',
  size: '0.001',
  stopPrice: '38000',
  limitPrice: '37900',
  tradeType: 'TRADE',
});

// List all active stop orders
const stopOrders = await client.getStopOrders({ symbol: 'BTC-USDT' });

Margin Trading (HF)

// Submit an HF margin order (cross margin)
const marginOrder = await client.submitHFMarginOrder({
  clientOid: client.generateNewOrderID(),
  side: 'buy',
  symbol: 'BTC-USDT',
  type: 'limit',
  price: '40000',
  size: '0.001',
  isIsolated: false,
  autoBorrow: true,
  autoRepay: true,
});

// Borrow USDT on cross margin
const borrow = await client.marginBorrowV3({
  currency: 'USDT',
  size: '100',
  timeInForce: 'IOC',
  isIsolated: false,
});

// Check borrow interest rate
const rate = await client.getBorrowInterestRate({ currency: 'USDT,BTC' });

Deposits & Withdrawals

// Create a BTC deposit address
const depositAddr = await client.createDepositAddressV3({
  currency: 'BTC',
  chain: 'BTC',
});

// List recent deposits
const deposits = await client.getDeposits({ currency: 'USDT' });

// Submit a USDT withdrawal (v3)
const withdrawal = await client.submitWithdrawV3({
  currency: 'USDT',
  address: '0xYourAddress',
  amount: 10,
  chain: 'ERC20',
});

// Flex transfer: move USDT from main to trading account
const transfer = await client.submitFlexTransfer({
  clientOid: client.generateNewOrderID(),
  currency: 'USDT',
  amount: '50',
  fromAccountType: 'MAIN',
  toAccountType: 'TRADE',
});

Sub-Accounts

// List all sub-accounts (paginated v2)
const subs = await client.getSubAccountsV2({ currentPage: 1, pageSize: 50 });

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

// Get a specific sub-account's balance
const subBalance = await client.getSubAccountBalance({
  subUserId: '5caefba7d9575a0688f83c45',
  includeBaseAmount: false,
});

// Transfer from master to sub-account
const masterToSub = await client.submitTransferMasterSub({
  clientOid: client.generateNewOrderID(),
  amount: '100',
  currency: 'USDT',
  direction: 'OUT',
  subUserId: 'your_sub_user_id',
});

Earn Products

// Browse fixed-income (savings) products
const savingsProducts = await client.getEarnSavingsProducts({ currency: 'USDT' });

// Subscribe to a fixed-income earn product
const subscription = await client.subscribeEarnFixedIncome({
  productId: 'your_product_id',
  amount: '100',
  accountType: 'MAIN',
});

// Check current holdings
const holdings = await client.getEarnFixedIncomeHoldAssets({
  productId: 'your_product_id',
  currency: 'USDT',
});

// KCS staking products
const kcsStaking = await client.getEarnKcsStakingProducts({ currency: 'KCS' });

Key Methods Reference

Account & Funding

Method	Auth	Description
`getAccountSummary()`	✅	Full user account info
`getBalances()`	✅	All account type balances
`getMarginBalance()`	✅	Cross margin account balance
`getIsolatedMarginBalance()`	✅	Isolated margin account balances
`getTransactions()`	✅	Account ledger entries
`getHFTransactions()`	✅	HF account ledger entries
`getBasicUserFee()`	✅	Maker/taker fee rates
`getTradingPairFee()`	✅	Actual fee for a specific symbol

Market Data (Public)

Method	Auth	Description
`getSymbols()`	❌	All tradable spot symbols
`getTicker()`	❌	Best bid/ask + last price
`getTickers()`	❌	All tickers in one response
`getKlines()`	❌	Candlestick / OHLCV data
`getOrderBookLevel20()`	❌	Top 20 bid/ask levels
`getOrderBookLevel100()`	❌	Top 100 bid/ask levels
`getFullOrderBook()`	✅	Complete order book
`get24hrStats()`	❌	24 h volume and price stats
`getTradeHistories()`	❌	Recent public trades

HF Spot Trading

Method	Auth	Description
`submitHFOrder()`	✅	Place a single HF order
`submitHFOrderSync()`	✅	Place HF order (synchronous response)
`submitHFMultipleOrders()`	✅	Batch-place HF orders
`cancelHFOrder()`	✅	Cancel by order ID
`cancelHFOrderByClientOId()`	✅	Cancel by client order ID
`cancelHFAllOrdersBySymbol()`	✅	Cancel all HF orders for a symbol
`updateHFOrder()`	✅	Modify price/size of active HF order
`getHFActiveOrders()`	✅	List active HF orders
`getHFCompletedOrders()`	✅	List completed HF orders
`getHFFilledOrders()`	✅	List HF order fills

Stop Orders & OCO

Method	Auth	Description
`submitStopOrder()`	✅	Place a stop/stop-limit order
`cancelStopOrderById()`	✅	Cancel stop order by ID
`cancelStopOrders()`	✅	Batch cancel stop orders
`getStopOrders()`	✅	List untriggered stop orders
`submitOCOOrder()`	✅	Place an OCO (spot) order
`cancelOCOOrderById()`	✅	Cancel OCO by order ID
`getOCOOrders()`	✅	List OCO orders

Margin Trading (HF)

Method	Auth	Description
`submitHFMarginOrder()`	✅	Place an HF margin order
`cancelHFMarginOrder()`	✅	Cancel HF margin order
`getHFActiveMarginOrders()`	✅	List active HF margin orders
`marginBorrowV3()`	✅	Borrow on cross/isolated margin
`marginRepayV3()`	✅	Repay borrowed margin
`getMarginBorrowHistoryV3()`	✅	Borrow history
`getMarginInterestRecordsV3()`	✅	Interest accrual records
`getBorrowInterestRate()`	✅	Current borrow rates

FuturesClient

Perpetual and delivery futures contracts, positions, and funding rates.

UnifiedAPIClient

KuCoin PRO unified account — cross-product trading from a single client.

BrokerClient

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

Get Started

REST Clients

WebSockets

Guides

SpotClient: Spot & Margin Trading REST API

Installation

Initialization

Feature Overview

Account & Balances

Market Data

HF Trading Orders

Stop Orders & OCO

Margin Trading

Deposits & Withdrawals

Sub-Accounts

Earn Products

Usage Examples

Account & Balances

Market Data

HF Order Placement

Stop Orders & OCO Orders

Margin Trading (HF)

Deposits & Withdrawals

Sub-Accounts

Earn Products

Key Methods Reference

FuturesClient

UnifiedAPIClient

BrokerClient

Build docs developers (and LLMs) love

Get Started

REST Clients

WebSockets

Guides

Documentation Index

​Installation

​Initialization

​Feature Overview

Account & Balances

Market Data

HF Trading Orders

Stop Orders & OCO

Margin Trading

Deposits & Withdrawals

Sub-Accounts

Earn Products

​Usage Examples

​Account & Balances

​Market Data

​HF Order Placement

​Stop Orders & OCO Orders

​Margin Trading (HF)

​Deposits & Withdrawals

​Sub-Accounts

​Earn Products

​Key Methods Reference

​Related Pages

FuturesClient

UnifiedAPIClient

BrokerClient

Build docs developers (and LLMs) love

Installation

Initialization

Feature Overview

Usage Examples

Account & Balances

Market Data

HF Order Placement

Stop Orders & OCO Orders

Margin Trading (HF)

Deposits & Withdrawals

Sub-Accounts

Earn Products

Key Methods Reference

Related Pages