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 trading methods cover four order systems on KuCoin’s spot exchange: High-Frequency (HF) Orders (the recommended, low-latency path), Standard Orders (the legacy REST interface), Stop Orders (trigger-based orders), and OCO Orders (One-Cancels-the-Other). All trading endpoints require authentication. For best performance and the lowest latency, use the HF endpoints — they operate on a dedicated matching engine and support synchronous result delivery.
Standard order endpoints (submitOrder, cancelOrderById, etc.) are deprecated. Prefer the equivalent HF order endpoints for all new development.

​
HF Orders

HF orders are processed on KuCoin’s high-frequency matching engine. Methods that end in Sync block until order matching completes and return the final order state synchronously.
Places a limit or market HF order. Returns immediately with an orderId and optional clientOid; matching happens asynchronously.Endpoint: POST api/v1/hf/orders — 🔒 Auth required
submitHFOrder(params: SubmitHFOrderRequest): Promise<APISuccessResponse<{ orderId: string; clientOid: string }>>
​
type
string
required
Order type: "limit" or "market".
​
symbol
string
required
Trading pair, e.g. "BTC-USDT".
​
side
string
required
"buy" or "sell".
​
clientOid
string
Client-assigned order ID (UUID recommended). Auto-generated if omitted.
​
price
string
Order price (required for limit orders).
​
size
string
Order quantity in base currency (required for limit orders and market sell orders).
​
funds
string
Order funds in quote currency (for market buy orders if size is omitted).
​
timeInForce
string
"GTC" (default), "GTT", "IOC", or "FOK". Limit orders only.
​
cancelAfter
number
Seconds until auto-cancel (only valid with timeInForce: "GTT").
​
postOnly
boolean
If true, the order is rejected if it would immediately match (maker-only).
​
hidden
boolean
Hidden order — not shown in the order book.
​
iceberg
boolean
Iceberg order — only visibleSize is displayed in the book.
​
visibleSize
string
Visible portion for iceberg orders.
​
stp
string
Self-trade prevention: "DC", "CO", "CN", or "CB".
​
remark
string
Order note (max 100 characters).
​
tags
string
Custom tags (max 20 characters).
​
allowMaxTimeWindow
number
Order fails if clientTimestamp + allowMaxTimeWindow is less than server time (milliseconds).
​
clientTimestamp
number
Client-side timestamp matching KC-API-TIMESTAMP. Required when iceberg is set.
import { SpotClient } from 'kucoin-api';

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

const order = await client.submitHFOrder({
  type: 'limit',
  symbol: 'BTC-USDT',
  side: 'buy',
  price: '60000',
  size: '0.001',
  timeInForce: 'GTC',
});

console.log('Order ID:', order.data.orderId);
Identical signature to submitHFOrder but the order never enters the matching engine. Use it to validate request signatures and parameter formatting.Endpoint: POST api/v1/hf/orders/test — 🔒 Auth required
submitHFOrderTest(params: SubmitHFOrderRequest): Promise<any>
Places an HF order and waits synchronously for matching to complete before returning the final order state.Endpoint: POST api/v1/hf/orders/sync — 🔒 Auth required
submitHFOrderSync(params: SubmitHFOrderRequest): Promise<APISuccessResponse<SubmitHFOrderSyncResponse>>
Accepts the same parameters as submitHFOrder. The response includes status, matchTime, dealSize, dealFunds, and trade result details.
Places up to 20 HF orders in a single request. Orders are processed sequentially.Endpoint: POST api/v1/hf/orders/multi — 🔒 Auth required
submitHFMultipleOrders(params: { orderList: SubmitHFOrderRequest[] }): Promise<APISuccessResponse<SubmitMultipleHFOrdersResponse[]>>
​
orderList
SubmitHFOrderRequest[]
required
Array of up to 20 order request objects. Each object accepts the same fields as submitHFOrder.
Places up to 20 HF orders in a single request and waits synchronously for matching results before returning.Endpoint: POST api/v1/hf/orders/multi/sync — 🔒 Auth required
submitHFMultipleOrdersSync(params: { orderList: SubmitHFOrderRequest[] }): Promise<APISuccessResponse<SubmitMultipleHFOrdersSyncResponse[]>>
​
orderList
SubmitHFOrderRequest[]
required
Array of up to 20 order request objects. Each object accepts the same fields as submitHFOrder.
Sends a cancellation request for an HF order by its orderId. This is asynchronous — the order may still be alive briefly after the call returns.Endpoint: DELETE api/v1/hf/orders/{orderId} — 🔒 Auth required
cancelHFOrder(params: { orderId: string; symbol: string }): Promise<APISuccessResponse<{ orderId: string }>>
​
orderId
string
required
The order ID to cancel.
​
symbol
string
required
The trading pair the order belongs to.
const result = await client.cancelHFOrder({
  orderId: '5bd6e9286d99522a52e458de',
  symbol: 'BTC-USDT',
});
console.log('Cancelled order ID:', result.data.orderId);
Cancels an HF order by orderId and waits synchronously for cancellation to complete.Endpoint: DELETE api/v1/hf/orders/sync/{orderId} — 🔒 Auth required
cancelHFOrderSync(params: { orderId: string; symbol: string }): Promise<APISuccessResponse<SyncCancelHFOrderResponse>>
Sends an asynchronous cancellation request for an HF order using the client-assigned order ID.Endpoint: DELETE api/v1/hf/orders/client-order/{clientOid} — 🔒 Auth required
cancelHFOrderByClientOId(params: { clientOid: string; symbol: string }): Promise<APISuccessResponse<{ clientOid: string }>>
Cancels an HF order by clientOid and waits synchronously for cancellation confirmation.Endpoint: DELETE api/v1/hf/orders/sync/client-order/{clientOid} — 🔒 Auth required
cancelHFOrderSyncByClientOId(params: { clientOid: string; symbol: string }): Promise<APISuccessResponse<SyncCancelHFOrderResponse>>
Cancels a specified quantity of an HF order by orderId, rather than the entire order. Useful for partially cancelling large orders.Endpoint: DELETE api/v1/hf/orders/cancel/{orderId} — 🔒 Auth required
cancelHFOrdersNumber(params: CancelSpecifiedNumberHFOrdersRequest): Promise<{ orderId: string; cancelSize: string }>
​
orderId
string
required
Order ID to partially cancel.
​
symbol
string
required
Trading pair the order belongs to.
​
cancelSize
string
required
Quantity to cancel.
Cancels all open HF orders across all symbols.Endpoint: DELETE api/v1/hf/orders/cancelAll — 🔒 Auth required
cancelHFAllOrders(): Promise<APISuccessResponse<CancelAllHFOrdersResponse>>

const result = await client.cancelHFAllOrders();
console.log('Cancellation result:', result.data);
Cancels all open HF orders for a specific symbol.Endpoint: DELETE api/v1/hf/orders — 🔒 Auth required
cancelHFAllOrdersBySymbol(params: { symbol: string }): Promise<APISuccessResponse<string>>
​
symbol
string
required
Trading pair whose orders should be cancelled, e.g. "BTC-USDT".
Returns a list of all trading symbols that currently have active (open) HF orders.Endpoint: GET api/v1/hf/orders/active/symbols — 🔒 Auth required
getHFActiveSymbols(): Promise<APISuccessResponse<{ symbols: string[] }>>
Returns all active (unfilled) HF orders for a symbol. Results are sorted by latest update time descending.Endpoint: GET api/v1/hf/orders/active — 🔒 Auth required
getHFActiveOrders(params: { symbol: string }): Promise<APISuccessResponse<HFOrder[]>>
​
symbol
string
required
Trading pair to query.
This method is deprecated as of 2025-03-13. Use getHFActiveOrdersPaginated() for new implementations.
Returns active (unfilled) HF orders for a symbol with pagination support. The returned data is sorted in descending order by order creation time.Endpoint: GET api/v1/hf/orders/active/page — 🔒 Auth required
getHFActiveOrdersPaginated(params: { symbol: string; pageNum?: number; pageSize?: number }): Promise<APISuccessResponse<{ currentPage: number; pageSize: number; totalNum: number; totalPage: number; items: HFOrder[] }>>
​
symbol
string
required
Trading pair to query.
​
pageNum
number
Page number (default: 1).
​
pageSize
number
Items per page.
Returns paginated completed (filled or cancelled) HF orders for a symbol. Sorted by latest update time descending.Endpoint: GET api/v1/hf/orders/done — 🔒 Auth required
getHFCompletedOrders(params: GetHFCompletedOrdersRequest): Promise<APISuccessResponse<{ lastId: number; items: HFOrder[] }>>
​
symbol
string
required
Trading pair to query.
​
side
string
"buy" or "sell".
​
type
string
"limit" or "market".
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
​
lastId
number
Cursor for pagination.
​
limit
number
Number of results per page (max: 100).
Returns full details for a single HF order by its orderId.Endpoint: GET api/v1/hf/orders/{orderId} — 🔒 Auth required
getHFOrderDetailsByOrderId(params: { orderId: string; symbol: string }): Promise<APISuccessResponse<HFOrder>>
​
orderId
string
required
Order ID to look up.
​
symbol
string
required
Trading pair the order belongs to.
Returns full details for a single HF order by its client-assigned order ID.Endpoint: GET api/v1/hf/orders/client-order/{clientOid} — 🔒 Auth required
getHFOrderDetailsByClientOid(params: { clientOid: string; symbol: string }): Promise<APISuccessResponse<HFOrder>>
​
clientOid
string
required
Client-assigned order ID to look up.
​
symbol
string
required
Trading pair the order belongs to.
Returns a paginated list of HF trade fills (matched transactions).Endpoint: GET api/v1/hf/fills — 🔒 Auth required
getHFFilledOrders(params: GetHFFilledListRequest): Promise<APISuccessResponse<{ items: HFFilledOrder[]; lastId: number }>>
​
symbol
string
required
Trading pair.
​
orderId
string
Filter fills for a specific order.
​
side
string
"buy" or "sell".
​
type
string
"limit" or "market".
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
​
lastId
number
Cursor for pagination.
​
limit
number
Number of results (max: 100).
Modifies the price and/or quantity of an existing HF order. Identified by orderId or clientOid.Endpoint: POST api/v1/hf/orders/alter — 🔒 Auth required
updateHFOrder(params: ModifyHFOrderRequest): Promise<APISuccessResponse<{ newOrderId: string; clientOid: string }>>
​
symbol
string
required
Trading pair.
​
orderId
string
Order ID to modify (provide either orderId or clientOid).
​
clientOid
string
Client order ID to modify.
​
newPrice
string
Updated order price.
​
newSize
string
Updated order quantity.
Sets the Disconnection Protection (Dead Man’s Switch) for HF orders. After the specified timeout, all orders for the configured trading pairs will be automatically cancelled if this endpoint is not called again before the timeout expires.Endpoint: POST api/v1/hf/orders/dead-cancel-all — 🔒 Auth required
cancelHFOrderAutoSetting(params: { timeout: number; symbols?: string }): Promise<APISuccessResponse<{ currentTime: number; triggerTime: number }>>
​
timeout
number
required
Timeout in seconds after which all orders are cancelled. Set to 0 to disable.
​
symbols
string
Comma-separated trading pairs to apply the setting to. If omitted, applies to all symbols.
Queries the current Disconnection Protection (Dead Man’s Switch) settings for HF orders.Endpoint: GET api/v1/hf/orders/dead-cancel-all/query — 🔒 Auth required
cancelHFOrderAutoSettingQuery(): Promise<APISuccessResponse<AutoCancelHFOrderSettingQueryResponse>>

​
Standard Orders (Deprecated)

These endpoints are maintained for backward compatibility. For new integrations, use the HF order endpoints above.
Places a standard spot limit or market order.Endpoint: POST api/v1/orders — 🔒 Auth required
submitOrder(params: SubmitOrderRequest): Promise<APISuccessResponse<{ orderId: string }>>
​
clientOid
string
required
Unique client-assigned order ID.
​
side
string
required
"buy" or "sell".
​
symbol
string
required
Trading pair.
​
type
string
"limit" (default) or "market".
​
price
string
Limit price.
​
size
string
Order quantity.
​
funds
string
Quote funds for market buy orders.
​
timeInForce
string
"GTC", "GTT", "IOC", or "FOK".
​
stp
string
Self-trade prevention: "CN", "CO", "CB", or "DC".
​
tradeType
string
"TRADE" (default) or "MARGIN_TRADE".
Test endpoint for submitOrder. Request is validated but the order is never matched.Endpoint: POST api/v1/orders/test — 🔒 Auth required
submitOrderTest(): Promise<any>
Places up to 5 standard limit orders in a single request.Endpoint: POST api/v1/orders/multi — 🔒 Auth required
submitMultipleOrders(params: { symbol: string; orderList: SubmitMultipleOrdersRequest[] }): Promise<APISuccessResponse<MultipleOrdersResponse[]>>
Cancels a standard spot order by its exchange-assigned order ID.Endpoint: DELETE api/v1/orders/{orderId} — 🔒 Auth required
cancelOrderById(params: { orderId: string }): Promise<APISuccessResponse<{ cancelledOrderIds: string[] }>>
Cancels a standard spot order using the client-assigned order ID.Endpoint: DELETE api/v1/order/client-order/{clientOid} — 🔒 Auth required
cancelOrderByClientOid(params: { clientOid: string }): Promise<any>
Cancels all open standard orders. Optionally filter by symbol or tradeType.Endpoint: DELETE api/v1/orders — 🔒 Auth required
cancelAllOrders(params?: CancelAllOrdersRequest): Promise<APISuccessResponse<{ cancelledOrderIds: string[] }>>
​
symbol
string
Filter by trading pair.
​
tradeType
string
"TRADE", "MARGIN_TRADE", or "MARGIN_ISOLATED_TRADE".
Returns a paginated list of standard orders filtered by status and other criteria.Endpoint: GET api/v1/orders — 🔒 Auth required
getOrders(params?: GetOrderListRequest): Promise<APISuccessResponse<OrderList>>
​
status
string
"active" (default) or "done".
​
symbol
string
Filter by trading pair.
​
side
string
"buy" or "sell".
​
type
string
"limit", "market", "limit_stop", or "market_stop".
​
tradeType
string
"TRADE", "MARGIN_TRADE", or "MARGIN_ISOLATED_TRADE".
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
​
currentPage
number
Page number.
​
pageSize
number
Items per page (max: 500).
Fetches a single standard order by its exchange order ID.Endpoint: GET api/v1/orders/{orderId} — 🔒 Auth required
getOrderByOrderId(params: { orderId: string }): Promise<APISuccessResponse<Order>>
Returns paginated fill records for standard orders.Endpoint: GET api/v1/fills — 🔒 Auth required
getFills(params?: GetFillsRequest): Promise<APISuccessResponse<Fills>>
​
tradeType
string
required
"TRADE", "MARGIN_TRADE", or "MARGIN_ISOLATED_TRADE".
​
orderId
string
Filter fills for a specific order.
​
symbol
string
Trading pair filter.
​
side
string
"buy" or "sell".
​
type
string
"limit", "market", "limit_stop", or "market_stop".
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
Returns the most recent 1000 fills across all standard orders in the past 24 hours.Endpoint: GET api/v1/limit/fills — 🔒 Auth required
getRecentFills(): Promise<APISuccessResponse<Fill[]>>

​
Stop Orders

Places a stop (trigger) order that activates once the market reaches the specified stopPrice.Endpoint: POST api/v1/stop-order — 🔒 Auth required
submitStopOrder(params: SubmitStopOrderRequest): Promise<APISuccessResponse<{ orderId: string; clientOid: string }>>
​
symbol
string
required
Trading pair.
​
side
string
required
"buy" or "sell".
​
stopPrice
string
required
Trigger price.
​
type
string
required
"limit" or "market".
​
price
string
Limit price (required when type is "limit").
​
size
string
Order quantity.
​
funds
string
Quote funds (for market orders).
​
clientOid
string
Client-assigned order ID.
​
stp
string
Self-trade prevention strategy.
​
tradeType
string
"TRADE", "MARGIN_TRADE", or "MARGIN_ISOLATED_TRADE".
​
timeInForce
string
"GTC", "GTT", "IOC", or "FOK".
Cancels a single stop order by its exchange order ID.Endpoint: DELETE api/v1/stop-order/{orderId} — 🔒 Auth required
cancelStopOrderById(params: { orderId: string }): Promise<APISuccessResponse<{ cancelledOrderIds: string[] }>>
Returns a paginated list of untriggered stop orders.Endpoint: GET api/v1/stop-order — 🔒 Auth required
getStopOrders(params?: GetStopOrdersListRequest): Promise<APISuccessResponse<StopOrders>>
​
symbol
string
Filter by trading pair.
​
side
string
"buy" or "sell".
​
type
string
Order type filter.
​
tradeType
string
"TRADE", "MARGIN_TRADE", or "MARGIN_ISOLATED_TRADE".
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
​
currentPage
number
Page number.
​
pageSize
number
Items per page.
​
orderIds
string
Comma-separated order IDs to query.

​
OCO Orders

OCO (One-Cancels-the-Other) orders pair a limit order with a stop-limit order on the same symbol. When one leg triggers or fills, the other is automatically cancelled.
Places an OCO order on the spot market.Endpoint: POST api/v3/oco/order — 🔒 Auth required
submitOCOOrder(params: SubmitOCOOrderRequest): Promise<APISuccessResponse<{ orderId: string }>>
​
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 for the stop-limit leg after trigger.
​
clientOid
string
required
Client-assigned order ID.
​
tradeType
string
Currently only "TRADE" is supported.
​
remark
string
Optional order note.
Cancels a single OCO order by its exchange order ID.Endpoint: DELETE api/v3/oco/order/{orderId} — 🔒 Auth required
cancelOCOOrderById(params: { orderId: string }): Promise<APISuccessResponse<{ cancelledOrderIds: string[] }>>
Returns a paginated list of OCO orders.Endpoint: GET api/v3/oco/orders — 🔒 Auth required
getOCOOrders(params: GetOCOOrdersRequest): Promise<APISuccessResponse<OCOOrders>>
​
pageSize
string
required
Items per page.
​
currentPage
string
required
Page number.
​
symbol
string
Filter by trading pair.
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
​
orderIds
string
Comma-separated order IDs to filter.

Build docs developers (and LLMs) love

Get started for freeTalk to us