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 SpotClient margin methods provide access to KuCoin’s cross-margin and isolated-margin trading systems. The High-Frequency Margin Order interface (submitHFMarginOrder) is the recommended path for all margin order placement — it operates on the same low-latency engine as HF spot orders and supports both cross-margin and isolated-margin modes via the isIsolated flag. Additional methods cover mark-price feeds, borrowing and repaying funds (V3 API), isolated-margin account queries, risk-limit configuration, and advanced order types including margin stop orders and margin OCO orders. All endpoints require authentication.
Set isIsolated: true on margin order and borrow/repay requests to operate in isolated-margin mode; false (or omitting the flag) uses cross-margin.

​
HF Margin Orders

Places a margin order (cross or isolated) on the HF matching engine. Supports limit and market order types with auto-borrow and auto-repay options.Endpoint: POST api/v3/hf/margin/order — 🔒 Auth required
submitHFMarginOrder(params: SubmitHFMarginOrderRequest): Promise<APISuccessResponse<MarginSubmitOrderV3Response>>
​
clientOid
string
required
Unique client-assigned order ID.
​
side
string
required
"buy" or "sell".
​
symbol
string
required
Trading pair, e.g. "BTC-USDT".
​
type
string
"limit" (default) or "market".
​
isIsolated
boolean
true for isolated margin; false (default) for cross margin.
​
autoBorrow
boolean
Automatically borrow funds if balance is insufficient.
​
autoRepay
boolean
Automatically repay borrowed funds when the order fills.
​
price
string
Order price (required for limit orders).
​
size
string
Order quantity.
​
funds
string
Quote funds (for market buy orders).
​
timeInForce
string
"GTC", "GTT", "IOC", or "FOK".
​
cancelAfter
number
Seconds until auto-cancel (GTT strategy only).
​
postOnly
boolean
Maker-only flag — rejects if order would immediately match.
​
hidden
boolean
Hidden order (not visible in the order book).
​
iceberg
boolean
Iceberg order — only visibleSize is displayed.
​
visibleSize
string
Visible quantity for iceberg orders.
​
stp
string
Self-trade prevention: "CN", "CO", "CB", or "DC".
import { SpotClient } from 'kucoin-api';

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

const order = await client.submitHFMarginOrder({
  clientOid: 'my-margin-order-001',
  side: 'buy',
  symbol: 'BTC-USDT',
  type: 'limit',
  price: '60000',
  size: '0.001',
  isIsolated: false,
  autoBorrow: true,
  autoRepay: true,
});
console.log('Margin order ID:', order.data.orderId);
Cancels a margin HF order by its exchange order ID.Endpoint: DELETE api/v3/hf/margin/orders/{orderId} — 🔒 Auth required
cancelHFMarginOrder(params: { orderId: string; symbol: string }): Promise<APISuccessResponse<{ orderId: string }>>
​
orderId
string
required
The exchange-assigned order ID to cancel.
​
symbol
string
required
The trading pair the order belongs to.
Returns all active (unfilled) HF margin orders for a symbol. Filtered by tradeType to distinguish cross vs. isolated margin.Endpoint: GET api/v3/hf/margin/orders/active — 🔒 Auth required
getHFActiveMarginOrders(params: HFMarginRequestOrder): Promise<APISuccessResponse<HFMarginOrder[]>>
​
symbol
string
required
Trading pair to query.
​
tradeType
string
required
"MARGIN_TRADE" (cross) or "MARGIN_ISOLATED_TRADE" (isolated).

​
Mark Prices

Returns the current mark price for a specific margin trading pair.Endpoint: GET api/v1/mark-price/{symbol}/current — Public
getMarginMarkPrice(params: { symbol: string }): Promise<APISuccessResponse<MarginMarkPrice>>
​
symbol
string
required
Trading pair, e.g. "BTC-USDT".
const markPrice = await client.getMarginMarkPrice({ symbol: 'BTC-USDT' });
console.log('Mark price:', markPrice.data.value);
Returns the current mark prices for all margin trading pairs in a single call.Endpoint: GET api/v3/mark-price/all-symbols — Public
getMarginMarkPrices(): Promise<APISuccessResponse<MarginMarkPrice[]>>

​
Margin Config & Risk

Returns global cross-margin configuration: supported currencies, maximum leverage, and enabled features.Endpoint: GET api/v1/margin/config — Public
getMarginConfigInfo(): Promise<APISuccessResponse<MarginConfigInfo>>
Returns the risk limit and currency configuration for cross or isolated margin accounts.Endpoint: GET api/v3/margin/currencies — 🔒 Auth required
getMarginRiskLimitConfig(params: MarginRiskLimitRequest): Promise<APISuccessResponse<MarginRiskLimit[]>>
​
isIsolated
boolean
required
true for isolated margin; false for cross margin.
​
symbol
string
Filter by isolated-margin symbol (only relevant when isIsolated: true).
​
currency
string
Filter by currency.

​
Margin Collateral & Inventory

Returns the collateral ratio for margin currencies. If currencyList is not specified, all currencies are returned.Endpoint: GET api/v3/margin/collateralRatio — Public
getMarginCollateralRatio(params?: GetMarginCollateralRatioRequest): Promise<APISuccessResponse<MarginCollateralRatioData[]>>
​
currencyList
string
Comma-separated list of currencies to query (e.g. "BTC,ETH"). Returns all currencies if omitted.
Returns the platform’s available inventory for margin lending, optionally filtered by currency.Endpoint: GET api/v3/margin/available-inventory — Public
getMarketAvailableInventory(params?: { currency?: string }): Promise<APISuccessResponse<MarketAvailableInventoryItem[]>>
​
currency
string
Filter by currency ticker (e.g. "USDT").

​
Borrow & Repay (V3)

Returns the borrowing interest rate for margin currencies at the specified VIP level.Endpoint: GET api/v3/margin/borrowRate — 🔒 Auth required
getBorrowInterestRate(params?: GetBorrowInterestRateRequest): Promise<APISuccessResponse<BorrowInterestRate>>
​
vipLevel
number
VIP level (0–12). Defaults to the current user’s VIP level if omitted.
​
currency
string
Comma-separated list of currencies to query (up to 50).
Initiates a borrow order for cross or isolated margin accounts.Endpoint: POST api/v3/margin/borrow — 🔒 Auth required
marginBorrowV3(params: MarginBorrowV3Request): Promise<APISuccessResponse<MarginOrderV3>>
​
currency
string
required
Currency to borrow, e.g. "USDT".
​
size
number
required
Amount to borrow.
​
timeInForce
string
required
"IOC" (immediate-or-cancel) or "FOK" (fill-or-kill).
​
isHf
boolean
required
true to use the HF account; false for the standard margin account.
​
isIsolated
boolean
true for isolated margin; false (default) for cross margin.
​
symbol
string
Isolated-margin symbol (required when isIsolated: true).
import { SpotClient } from 'kucoin-api';

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

const borrow = await client.marginBorrowV3({
  currency: 'USDT',
  size: 100,
  timeInForce: 'IOC',
  isHf: false,
  isIsolated: false,
});
console.log('Borrow order:', borrow.data.orderNo);
Initiates a repayment for cross or isolated margin borrowed funds.Endpoint: POST api/v3/margin/repay — 🔒 Auth required
marginRepayV3(params: MarginRepayV3Request): Promise<APISuccessResponse<MarginOrderV3>>
​
currency
string
required
Currency to repay.
​
size
number
required
Amount to repay.
​
isHf
boolean
required
true for HF margin account; false for standard margin account.
​
isIsolated
boolean
true for isolated margin; false for cross margin.
​
symbol
string
Required when isIsolated: true.
Returns paginated borrow order history for cross and isolated margin accounts.Endpoint: GET api/v3/margin/borrow — 🔒 Auth required
getMarginBorrowHistoryV3(params: MarginHistoryV3Request): Promise<APISuccessResponse<MarginBorrowHistoryV3[]>>
​
currency
string
required
Currency to query.
​
isIsolated
boolean
true for isolated; false for cross.
​
symbol
string
Isolated-margin symbol filter.
​
orderNo
string
Filter by a specific borrow order number.
​
startTime
number
Start timestamp in milliseconds.
​
endTime
number
End timestamp in milliseconds.
​
currentPage
number
Page number.
​
pageSize
number
Items per page (max: 100).
Returns paginated repayment history for cross and isolated margin accounts.Endpoint: GET api/v3/margin/repay — 🔒 Auth required
getMarginRepayHistoryV3(params: MarginHistoryV3Request): Promise<APISuccessResponse<MarginRepayHistoryV3[]>>
Accepts the same query parameters as getMarginBorrowHistoryV3.
Returns paginated interest charge records for cross and isolated margin lending positions.Endpoint: GET api/v3/margin/interest — 🔒 Auth required
getMarginInterestRecordsV3(params?: MarginInterestRecordsRequest): Promise<APISuccessResponse<MarginInterestRecords>>
​
isIsolated
boolean
true for isolated margin; false for cross margin.
​
symbol
string
Filter by isolated-margin symbol.
​
currency
string
Filter by currency.
​
startTime
number
Start timestamp in milliseconds.
​
endTime
number
End timestamp in milliseconds.
​
currentPage
number
Page number.
​
pageSize
number
Items per page (max: 100).
Updates the leverage multiplier for a cross or isolated margin account.Endpoint: POST api/v3/position/update-user-leverage — 🔒 Auth required
updateMarginLeverageV3(params: { leverage: string; symbol?: string; isIsolated?: boolean }): Promise<APISuccessResponse<any>>
​
leverage
string
required
New leverage multiplier as a string (e.g. "5").
​
symbol
string
Trading pair for isolated-margin accounts (e.g. "BTC-USDT").
​
isIsolated
boolean
true for isolated margin; false (default) for cross margin.

​
Isolated Margin

Returns isolated-margin account details using the legacy V1 endpoint. Deprecated — use getIsolatedMarginBalance() from the Balances section instead.Endpoint: GET api/v1/isolated/accounts — 🔒 Auth required
getIsolatedMarginAccounts(params?: { balanceCurrency?: 'USDT' | 'KCS' | 'BTC' }): Promise<APISuccessResponse<IsolatedMarginAccountInfo>>
​
balanceCurrency
string
Express balances in this currency: "USDT", "KCS", or "BTC".
Deprecated — use getIsolatedMarginBalance() instead.
Returns isolated-margin account detail for a specific trading pair using the legacy V1 endpoint.Endpoint: GET api/v1/isolated/account/{symbol} — 🔒 Auth required
getIsolatedMarginAccount(params: { symbol: string }): Promise<APISuccessResponse<SingleIsolatedMarginAccountInfo>>
​
symbol
string
required
Trading pair, e.g. "BTC-USDT".
Deprecated — use getIsolatedMarginBalance({ symbol }) instead.
Returns the symbol configuration for all enabled isolated-margin pairs: leverage, quote currency, and trading status.Endpoint: GET api/v1/isolated/symbols — 🔒 Auth required
getIsolatedMarginSymbolsConfig(): Promise<APISuccessResponse<IsolatedMarginSymbolsConfig[]>>

​
Cross-Margin Active Pairs

Returns the configuration for cross-margin trading pairs. Optionally filter by symbol.Endpoint: GET api/v3/margin/symbols — 🔒 Auth required
getMarginActivePairsV3(params?: { symbol?: string }): Promise<APISuccessResponse<{ timestamp: number; items: MarginActivePairsV3[] }>>
​
symbol
string
Filter by trading pair, e.g. "BTC-USDT".

​
Lending Market (V3)

The lending market endpoints allow you to lend idle funds to margin traders in exchange for interest. Funds must be in the main (funding) account before subscribing.
Returns information about the currencies available for lending on the margin lending market.Endpoint: GET api/v3/project/list — Public
getLendingCurrencyV3(params?: { currency?: string }): Promise<APISuccessResponse<LendingCurrencyV3>>
​
currency
string
Filter by currency ticker (e.g. "USDT").
Returns the lending market interest rates for a currency over the past 7 days.Endpoint: GET api/v3/project/marketInterestRate — Public
getLendingInterestRateV3(params: { currency: string }): Promise<APISuccessResponse<{ time: string; marketInterestRate: string }[]>>
​
currency
string
required
Currency ticker (e.g. "USDT").
Invests credit in the lending market to earn interest. Funds must be in the main (funding) account.Endpoint: POST api/v3/purchase — 🔒 Auth required
submitLendingSubscriptionV3(params: InitiateLendingSubscriptionV3Request): Promise<APISuccessResponse<{ orderNo: string }[]>>
​
currency
string
required
Currency to lend (e.g. "USDT").
​
size
string
required
Amount to subscribe.
​
interestRate
string
required
Daily interest rate to offer.
Updates the interest rate on an existing lending subscription order. Takes effect at the beginning of the next hour.Endpoint: POST api/v3/lend/purchase/update — 🔒 Auth required
updateLendingSubscriptionOrdersV3(params: ModifyLendingSubscriptionOrdersV3Request): Promise<any>
​
currency
string
required
Currency of the subscription order.
​
purchaseOrderNo
string
required
Order number of the subscription to modify.
​
interestRate
string
required
New daily interest rate.
Returns paginated lending subscription (purchase) orders.Endpoint: GET api/v3/purchase/orders — 🔒 Auth required
getLendingSubscriptionOrdersV3(params: GetLendingSubscriptionOrdersV3Request): Promise<APISuccessResponse<LendingRedemption>>
​
currency
string
required
Currency to query.
​
status
string
required
"DONE" (completed) or "PENDING" (in progress).
​
purchaseOrderNo
string
Filter by a specific order number.
​
currentPage
number
Page number.
​
pageSize
number
Items per page.
Redeems (withdraws) a lending subscription order.Endpoint: POST api/v3/redeem — 🔒 Auth required
submitLendingRedemptionV3(params: InitiateLendingRedemptionV3Request): Promise<APISuccessResponse<{ orderNo: string }[]>>
​
currency
string
required
Currency to redeem.
​
size
string
required
Amount to redeem.
​
purchaseOrderNo
string
required
Order number of the subscription to redeem.
Returns paginated lending redemption orders.Endpoint: GET api/v3/redeem/orders — 🔒 Auth required
getLendingRedemptionOrdersV3(params: GetLendingRedemptionOrdersV3Request): Promise<APISuccessResponse<LendingRedemption>>
​
currency
string
required
Currency to query.
​
status
string
required
"DONE" (completed) or "PENDING" (in progress).
​
redeemOrderNo
string
Filter by a specific redemption order number.
​
currentPage
number
Page number.
​
pageSize
number
Items per page.

​
Margin OCO & Stop Orders

Places an OCO (One-Cancels-the-Other) order on the margin trading system (cross or isolated).Endpoint: POST api/v3/hf/margin/oco-order — 🔒 Auth required
addMarginOcoOrder(params: SubmitMarginOcoOrderRequest): Promise<APISuccessResponse<MarginOcoOrderResponse>>
​
symbol
string
required
Trading pair, e.g. "BTC-USDT".
​
side
string
required
"buy" or "sell".
​
price
string
required
Limit order price.
​
size
string
required
Order quantity.
​
stopPrice
string
required
Trigger price for the stop leg.
​
limitPrice
string
required
Limit price after the stop triggers.
​
clientOid
string
required
Client-assigned order ID.
​
isIsolated
boolean
required
true for isolated margin; false for cross margin.
​
autoBorrow
boolean
Auto-borrow on insufficient balance.
​
autoRepay
boolean
Auto-repay on fill.
Places a stop order on the margin trading system.Endpoint: POST api/v3/hf/margin/stop-order — 🔒 Auth required
addMarginStopOrder(params: SubmitMarginStopOrderRequest): Promise<APISuccessResponse<MarginStopOrderResponse>>
​
clientOid
string
required
Client-assigned order ID.
​
side
string
required
"buy" or "sell".
​
symbol
string
required
Trading pair.
​
stopPrice
string
required
Trigger price.
​
isIsolated
boolean
required
true for isolated margin; false for cross margin.
​
autoBorrow
boolean
required
Auto-borrow on insufficient balance.
​
autoRepay
boolean
required
Auto-repay on fill.
​
type
string
"limit" (default) or "market".
​
price
string
Limit price (required for limit orders).
​
size
string
Order quantity.
​
timeInForce
string
"GTC", "GTT", "IOC", or "FOK".
​
stp
string
Self-trade prevention.
​
remark
string
Order note (max 100 characters).
​
funds
string
Quote funds for market orders.

Build docs developers (and LLMs) love

Get started for freeTalk to us