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 account group covers everything related to your KuCoin identity and balance state: reading service health, inspecting your API key details, listing spot and margin balances, paging through account ledgers, and managing the full lifecycle of sub-accounts and their dedicated API keys. All authenticated endpoints require apiKey, apiSecret, and apiPassphrase to be provided when constructing the client. Public endpoints (such as getMyIp and getServiceStatus) can be called without credentials.
All authenticated methods automatically sign requests. Pass your credentials once at client construction and every subsequent call will include the correct HMAC signature.

​
Service & Identity

Returns the public IP address that KuCoin sees for the current request. Useful for allowlist verification.Endpoint: GET api/v1/ip — Public
getMyIp(): Promise<APISuccessResponse<number>>
Example
import { SpotClient } from 'kucoin-api';

const client = new SpotClient();
const ip = await client.getMyIp();
console.log(ip.data); // e.g. "203.0.113.42"
Returns the current operational status of the KuCoin platform (open / close / cancelonly).Endpoint: GET api/v1/status — Public
getServiceStatus(): Promise<APISuccessResponse<ServiceStatus>>
Example
const status = await client.getServiceStatus();
console.log(status.data.msg); // "open"
Returns a summary of the authenticated account — UID, sub-account count, KYC level, futures/margin enabled flags, and more.Endpoint: GET api/v2/user-info — 🔒 Auth required
getAccountSummary(): Promise<APISuccessResponse<SpotAccountSummary>>

import { SpotClient } from 'kucoin-api';

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

const summary = await client.getAccountSummary();
console.log(summary.data);
Returns details about the API key currently in use — remark, permissions, IP whitelist, expiry, and whether it belongs to a sub-account.Endpoint: GET api/v1/user/api-key — 🔒 Auth required
getApikeyInfo(): Promise<APISuccessResponse<ApiKeyInfo>>
Returns whether the authenticated account is a high-frequency (HF) trading account (true) or a standard account (false).Endpoint: GET api/v1/hf/accounts/opened — 🔒 Auth required
getUserType(): Promise<APISuccessResponse<boolean>>
Returns a list of KYC-supported regions (countries/regions) for account verification.Endpoint: GET api/kyc/regions/v4 — 🔒 Auth required
getKYCRegions(): Promise<APISuccessResponse<KYCRegion[]>>

​
Balances

Lists all accounts (spot, main, trade, margin) along with their available and hold balances. Optionally filter by currency or type.Endpoint: GET api/v1/accounts — 🔒 Auth required
getBalances(params?: GetBalancesRequest): Promise<APISuccessResponse<Balances[]>>
​
currency
string
Filter by currency ticker, e.g. "BTC".
​
type
string
Account type: "main" or "trade".
import { SpotClient } from 'kucoin-api';

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

// Fetch all trade-account balances
const balances = await client.getBalances({ type: 'trade' });
console.log(balances.data);
Fetches balance and hold amounts for a single account by its accountId.Endpoint: GET api/v1/accounts/{accountId} — 🔒 Auth required
getAccountDetail(params: { accountId: any }): Promise<APISuccessResponse<Account>>
​
accountId
string
required
The unique account ID returned by getBalances.
Returns cross-margin account details including assets, liabilities, and available amounts.Endpoint: GET api/v3/margin/accounts — 🔒 Auth required
getMarginBalance(params?: GetMarginBalanceRequest): Promise<APISuccessResponse<MarginBalance>>
​
quoteCurrency
string
Filter accounts by quote currency.
​
queryType
string
"MARGIN" (default), "MARGIN_V2", or "ALL". Prefer "MARGIN".
Returns isolated-margin account details for one or all trading pairs.Endpoint: GET api/v3/isolated/accounts — 🔒 Auth required
getIsolatedMarginBalance(params?: GetIsolatedMarginBalanceRequest): Promise<APISuccessResponse<IsolatedMarginBalance[]>>
​
symbol
string
Filter by trading pair, e.g. "BTC-USDT".
​
quoteCurrency
string
Filter by quote currency.
​
queryType
string
"ISOLATED" (default), "ISOLATED_V2", or "ALL". Prefer "ISOLATED".

​
Account Ledgers

Paginated list of transaction records (deposits, withdrawals, trades, transfers) for spot and margin accounts. Results are sorted newest-first.Endpoint: GET api/v1/accounts/ledgers — 🔒 Auth required
getTransactions(params?: GetSpotTransactionsRequest): Promise<APISuccessResponse<SpotAccountTransactions>>
​
currency
string
Filter by currency.
​
direction
string
"in" (credits) or "out" (debits).
​
bizType
string
Business type: "DEPOSIT", "WITHDRAW", "TRANSFER", "SUB_TRANSFER", "TRADE_EXCHANGE", "MARGIN_EXCHANGE", "KUCOIN_BONUS", "BROKER_TRANSFER", or "REBATE".
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
​
currentPage
number
Page number (default: 1).
​
pageSize
number
Page size (default: 50, max: 500).
Paginated ledger for the high-frequency trading (HF) account. Supports multi-coin queries. Results are sorted by createdAt descending.Endpoint: GET api/v1/hf/accounts/ledgers — 🔒 Auth required
getHFTransactions(params: AccountHFTransactionsRequest): Promise<APISuccessResponse<SpotAccountTransaction[]>>
​
currency
string
Filter by currency.
​
direction
string
"in" or "out".
​
bizType
string
"TRANSFER", "TRADE_EXCHANGE", "RETURNED_FEES", "DEDUCTION_FEES", or "OTHER".
​
lastId
number
Cursor for pagination — pass the lastId from the previous page.
​
limit
number
Number of results (max: 200).
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.
Paginated ledger for the high-frequency margin trading account. Supports multi-coin queries. Results are sorted by createdAt and id descending.Endpoint: GET api/v3/hf/margin/account/ledgers — 🔒 Auth required
getHFMarginTransactions(params: AccountHFMarginTransactionsRequest): Promise<APISuccessResponse<AccountHFMarginTransactions[]>>
​
currency
string
Filter by currency.
​
direction
string
"in" or "out".
​
bizType
string
"TRANSFER", "MARGIN_EXCHANGE", "ISOLATED_EXCHANGE", "LIQUIDATION", or "ASSERT_RETURN".
​
lastId
number
Cursor for pagination — pass the lastId from the previous page.
​
limit
number
Number of results (max: 200).
​
startAt
number
Start timestamp in milliseconds.
​
endAt
number
End timestamp in milliseconds.

​
Sub-Accounts

Creates a new sub-account under the master account.Endpoint: POST api/v2/sub/user/created — 🔒 Auth required
createSubAccount(params: CreateSubAccountRequest): Promise<APISuccessResponse<CreateSubAccount>>
​
subName
string
required
Username for the sub-account (5–32 alphanumeric characters).
​
password
string
required
Login password for the sub-account.
​
access
string
required
Permission scope, e.g. "Spot".
​
remarks
string
Optional label or note.
Returns a paginated list of sub-accounts with summary information.Endpoint: GET api/v2/sub/user — 🔒 Auth required
getSubAccountsV2(params?: { currentPage?: number; pageSize?: number }): Promise<APISuccessResponse<SubAccountsV2>>
​
currentPage
number
Page number (default: 1).
​
pageSize
number
Items per page (default: 10, max: 100).
Returns the balance detail for a specific sub-account by its user ID.Endpoint: GET api/v1/sub-accounts/{subUserId} — 🔒 Auth required
getSubAccountBalance(params: {
  subUserId: string;
  includeBaseAmount: boolean;
  baseCurrency?: string;
  baseAmount?: string;
}): Promise<APISuccessResponse<SubAccountBalance>>
​
subUserId
string
required
The sub-account’s unique user ID.
​
includeBaseAmount
boolean
required
Whether to include base-currency equivalent balances.
​
baseCurrency
string
Base currency for amount conversion (e.g. "USDT").
Returns paginated spot balances for all sub-accounts.Endpoint: GET api/v2/sub-accounts — 🔒 Auth required
getSubAccountBalancesV2(params?: { currentPage?: number; pageSize?: number }): Promise<APISuccessResponse<SubAccountBalancesV2>>
Returns a non-paginated list of all sub-accounts. Deprecated — use getSubAccountsV2 for new integrations.Endpoint: GET api/v1/sub/user — 🔒 Auth required
getSubAccountsV1(): Promise<APISuccessResponse<SubAccountInfo[]>>
Deprecated — use getSubAccountsV2() instead.
Returns spot balances for all sub-accounts using the legacy V1 endpoint. Deprecated — use getSubAccountBalancesV2 for new integrations.Endpoint: GET api/v1/sub-accounts — 🔒 Auth required
getSubAccountBalancesV1(): Promise<APISuccessResponse<SubAccountBalance>>
Deprecated — use getSubAccountBalancesV2() instead.

​
Sub-Account API Keys

Creates a new API key for a sub-account.Endpoint: POST api/v1/sub/api-key — 🔒 Auth required
createSubAPI(params: CreateSubAccountAPIRequest): Promise<APISuccessResponse<CreateSubAPI>>
​
subName
string
required
The sub-account username.
​
passphrase
string
required
Passphrase for the new API key.
​
remark
string
required
Label for the key.
​
permission
string
Comma-separated permissions: "General", "Spot", "Futures", "Margin".
​
ipWhitelist
string
Comma-separated IP addresses allowed to use the key.
​
expire
string
Expiry in days: "30", "90", "180", or "0" (no expiry).
Modifies an existing sub-account API key’s permissions, IP whitelist, or expiry.Endpoint: POST api/v1/sub/api-key/update — 🔒 Auth required
updateSubAPI(params: UpdateSubAccountAPIRequest): Promise<APISuccessResponse<UpdateSubAPI>>
​
subName
string
required
Sub-account username.
​
apiKey
string
required
The API key string to modify.
​
passphrase
string
required
Current passphrase for authentication.
​
permission
string
Updated permissions.
​
ipWhitelist
string
Updated IP whitelist.
​
expire
string
Updated expiry in days.
Lists all API keys belonging to a sub-account.Endpoint: GET api/v1/sub/api-key — 🔒 Auth required
getSubAPIs(params: { apiKey?: string; subName: string }): Promise<APISuccessResponse<SubAccountAPIInfo[]>>
​
subName
string
required
Sub-account username.
​
apiKey
string
Filter by a specific API key string.
Permanently deletes a sub-account API key.Endpoint: DELETE api/v1/sub/api-key — 🔒 Auth required
deleteSubAPI(params: DeleteSubAccountAPIRequest): Promise<APISuccessResponse<DeleteSubAccountAPI>>
​
apiKey
string
required
The API key string to delete.
​
passphrase
string
required
Passphrase for authentication.
​
subName
string
required
Sub-account username.

​
Trading Fees

Returns the base taker and maker fee rates for spot/margin trading at the current VIP level.Endpoint: GET api/v1/base-fee — 🔒 Auth required
getBasicUserFee(params: { currencyType: number }): Promise<APISuccessResponse<{ takerFeeRate: string; makerFeeRate: string }>>
​
currencyType
number
required
0 for crypto, 1 for fiat.
Response fields
​
takerFeeRate
string
Taker fee rate as a decimal string (e.g. "0.001").
​
makerFeeRate
string
Maker fee rate as a decimal string.
Returns the actual taker/maker fee rates for up to 10 trading pairs (comma-separated).Endpoint: GET api/v1/trade-fees — 🔒 Auth required
getTradingPairFee(params: { symbol: string }): Promise<APISuccessResponse<{ symbol: string; takerFeeRate: string; makerFeeRate: string }[]>>
​
symbol
string
required
Comma-separated trading pairs, e.g. "BTC-USDT,ETH-USDT".
const fees = await client.getTradingPairFee({ symbol: 'BTC-USDT,ETH-USDT' });
fees.data.forEach(f => console.log(f.symbol, f.takerFeeRate, f.makerFeeRate));

Build docs developers (and LLMs) love

Get started for freeTalk to us