Authenticate Requests with the KuCoin API SDK

KuCoin’s REST API uses a three-part credential set — an API key, an API secret, and a passphrase — to authenticate every private request. The SDK handles all signing logic automatically: for each request it constructs a pre-sign string, signs it with HMAC-SHA256 using your apiSecret, and attaches the resulting signature, timestamp, and passphrase headers. You only need to pass your credentials once at client construction time.

How KuCoin Authentication Works

Every authenticated REST request must include four headers:

Header	Value
`KC-API-KEY`	Your API key
`KC-API-SIGN`	HMAC-SHA256 signature of `timestamp + method + path + body`
`KC-API-TIMESTAMP`	Current timestamp in milliseconds
`KC-API-PASSPHRASE`	Your passphrase (HMAC-SHA256 signed when `apiKeyVersion` is `"2"`)
`KC-API-KEY-VERSION`	`"2"` (recommended default)

The SDK builds and attaches all of these headers automatically on every private call. WebSocket private connections are authenticated the same way during the initial handshake.

Your API passphrase is a value you set yourself when you created the API key on KuCoin. It is not your KuCoin account login password.

Constructor Options (`RestClientOptions`)

All REST clients (SpotClient, FuturesClient, BrokerClient, UnifiedAPIClient) and the WebsocketClient accept a RestClientOptions object as their first constructor argument.

Credential Options

apiKey

string

Your KuCoin API key. Create one at kucoin.com/account/api. Omit for public-only usage.

apiSecret

string

Your API secret, used to sign the KC-API-SIGN header via HMAC-SHA256. Never log or expose this value.

apiPassphrase

string

The passphrase you set when creating the API key. This is not your account password. When apiKeyVersion is "2" (the default), this value is also HMAC-SHA256 signed before sending.

apiAccessToken

string

An alternative to key-based signing. When provided, the SDK skips HMAC signing entirely and attaches this value via an Authorization header instead. See Using an Access Token below.

apiKeyVersion

number | string

default:"2"

The API key version shown in your KuCoin API management page. Defaults to "2", which requires the passphrase to also be signed. Set to "1" only for legacy keys.

Regional Options

apiRegion

'global' | 'EU' | 'AU'

default:"global"

The KuCoin region your account belongs to:

'global' — kucoin.com (default)
'EU' — kucoin.eu — routes Spot/Margin requests to api.kucoin.eu. Note: Futures is not available in the EU region.
'AU' — kucoin.com/en-au — appends the X-SITE-TYPE: australia header and ensures AU-specific market data.

baseUrl

string

Directly override the base URL for all requests, bypassing apiRegion routing entirely. Example: 'https://api.kucoin.com'. Useful for testing or custom proxy setups.

Behaviour Options

strictParamValidation

boolean

default:"false"

When true, the SDK throws an error if any request parameter is undefined. Useful during development to catch missing fields early.

parseExceptions

boolean

default:"true"

When true, HTTP error responses are parsed and rethrown as structured exceptions rather than raw Axios errors.

keepAlive

boolean

Enables HTTP KeepAlive for REST API requests via the underlying Axios instance.

keepAliveMsecs

number

default:"1000"

When keepAlive is true, controls how often TCP KeepAlive packets are sent (milliseconds). Defaults to 1000 as inherited from the Node.js HTTPS agent.

customTimestampFn

() => number

Override the function used to generate the request timestamp. By default, Date.now() is used. Useful for testing or clock-skew scenarios.

customSignMessageFn

(message: string, secret: string) => Promise<string>

Inject a custom HMAC-SHA256 signing function. The SDK defaults to the Web Crypto API, which works in both Node.js and browsers. For latency-sensitive applications in Node.js, you can inject Node’s native createHmac for faster signing. See Faster HMAC Signing below.

Basic Authentication Setup

Pass your credentials to any REST client constructor. Read them from environment variables to keep secrets out of source code:

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,
});

const balances = await client.getBalances();
console.log(balances);

The same pattern applies to every other REST client:

import { FuturesClient, BrokerClient, UnifiedAPIClient } from 'kucoin-api';

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

Using an Access Token

If you already have a KuCoin access token (for example, from an OAuth-style flow), you can provide it via apiAccessToken. When this option is set, the SDK skips HMAC request signing and sends the token in an Authorization header instead.

import { SpotClient } from 'kucoin-api';

const client = new SpotClient({
  apiAccessToken: 'accessTokenHere!',
});

try {
  const result = await client.getBalances();
  console.log('result ', JSON.stringify(result, null, 2));
} catch (e) {
  console.error('Req error: ', e);
}

// If you later need to update the token (e.g. after expiry):
client.setAccessToken('newAccessTokenHere');

Do not provide both apiAccessToken and apiKey/apiSecret at the same time. When apiAccessToken is present, it takes priority and signing is skipped.

Regional Configuration

Use apiRegion to route your requests to the correct KuCoin domain. This is important for users on KuCoin EU or KuCoin AU, as the API hostnames and some behaviours differ:

import { SpotClient, WebsocketClient } from 'kucoin-api';

// KuCoin EU users
const client = new SpotClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
  apiRegion: 'EU', // Routes REST requests to https://api.kucoin.eu
});

const accountSummary = await client.getAccountSummary();
console.log('accountSummary ', JSON.stringify(accountSummary, null, 2));

// WebSocket client for EU region
const wsClient = new WebsocketClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
  apiRegion: 'EU', // or 'AU' for Australia, 'global' for kucoin.com (default)
});

Futures trading is not available for EU-region accounts at this time. If you instantiate a FuturesClient with apiRegion: 'EU', the SDK will log a warning and API requests may not function as expected.

The base URLs resolved per region and client type are:

Client	Region	Base URL
`SpotClient`	`global` / `AU`	`https://api.kucoin.com`
`SpotClient`	`EU`	`https://api.kucoin.eu`
`FuturesClient`	`global` / `AU`	`https://api-futures.kucoin.com`
`BrokerClient`	all	`https://api-broker.kucoin.com`
`UnifiedAPIClient`	`global` / `AU`	`https://api.kucoin.com`

Faster HMAC Signing (Node.js)

By default, the SDK uses the Web Crypto API for HMAC-SHA256 signing to maintain browser compatibility. In Node.js, the native crypto.createHmac method is measurably faster. For latency-sensitive trading bots, you can inject it via customSignMessageFn:

import { createHmac } from 'crypto';
import { SpotClient, WebsocketClient, DefaultLogger } from 'kucoin-api';

const restClient = new SpotClient({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPassphrase: process.env.API_PASS_COM,
  /**
   * Overkill in almost every case, but if you need any optimisation available,
   * you can inject a faster sign mechanism such as node's native createHmac:
   */
  customSignMessageFn: async (message, secret) => {
    return createHmac('sha256', secret).update(message).digest('hex');
  },
});

const customLogger = {
  ...DefaultLogger,
  // trace: (...params) => console.log('trace', ...params),
};

const wsClient = new WebsocketClient(
  {
    apiKey: process.env.API_KEY_COM,
    apiSecret: process.env.API_SECRET_COM,
    apiPassphrase: process.env.API_PASS_COM,
    /**
     * Overkill in almost every case, but if you need any optimisation available,
     * you can inject a faster sign mechanism such as node's native createHmac:
     */
    customSignMessageFn: async (message, secret) => {
      return createHmac('sha256', secret).update(message).digest('hex');
    },
  },
  customLogger,
);

The customSignMessageFn receives the pre-sign message string and your raw apiSecret. It must return a Promise<string> containing the hex-encoded HMAC-SHA256 digest. The same function is used for signing both REST request headers and WebSocket authentication handshakes.

Public vs Authenticated Endpoints

The SDK determines automatically whether a request requires authentication. Public endpoints (market data, order book, tickers, klines) are called without any auth headers even when credentials are configured. Private endpoints (balances, order placement, account history) always include the full authentication header set. You do not need to manage this distinction in your code. Simply instantiate the client with credentials and call any method — the SDK routes authentication appropriately.

import { SpotClient } from 'kucoin-api';

// Credentials present, but public calls still work without sending auth headers
const client = new SpotClient({
  apiKey: process.env.KUCOIN_API_KEY,
  apiSecret: process.env.KUCOIN_API_SECRET,
  apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
});

// Public — no auth headers sent
const ticker = await client.getTicker({ symbol: 'BTC-USDT' });

// Private — auth headers sent automatically
const balances = await client.getBalances();

Best Practices

Use environment variables

Always load apiKey, apiSecret, and apiPassphrase from process.env or a secrets manager. Never commit credentials to source control.

Restrict API key permissions

On KuCoin’s API management page, grant only the permissions your integration needs (e.g. read-only for data bots, trade-only for execution bots). Disable withdrawal permissions unless strictly required.

Rotate keys periodically

Regularly rotate your API keys and update your environment configuration. Immediately revoke any key you suspect has been compromised.

Use IP allowlists

KuCoin allows you to restrict API key usage to specific IP addresses. Enable this for production deployments to reduce the blast radius of a leaked key.

Example Environment Setup

# .env (never commit this file)
KUCOIN_API_KEY=your_api_key_here
KUCOIN_API_SECRET=your_api_secret_here
KUCOIN_API_PASSPHRASE=your_api_passphrase_here

// Load with dotenv (npm install dotenv)
import 'dotenv/config';
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,
});

Get Started

REST Clients

WebSockets

Guides

Authenticate Requests with the KuCoin API SDK

How KuCoin Authentication Works

Constructor Options (`RestClientOptions`)

Credential Options

Regional Options

Behaviour Options

Basic Authentication Setup

Using an Access Token

Regional Configuration

Faster HMAC Signing (Node.js)

Public vs Authenticated Endpoints

Best Practices

Use environment variables

Restrict API key permissions

Rotate keys periodically

Use IP allowlists

Example Environment Setup

Build docs developers (and LLMs) love

Get Started

REST Clients

WebSockets

Guides

Documentation Index

​How KuCoin Authentication Works

​Constructor Options (RestClientOptions)

​Credential Options

​Regional Options

​Behaviour Options

​Basic Authentication Setup

​Using an Access Token

​Regional Configuration

​Faster HMAC Signing (Node.js)

​Public vs Authenticated Endpoints

​Best Practices

Use environment variables

Restrict API key permissions

Rotate keys periodically

Use IP allowlists

​Example Environment Setup

Build docs developers (and LLMs) love

How KuCoin Authentication Works

Constructor Options (`RestClientOptions`)

Credential Options

Regional Options

Behaviour Options

Basic Authentication Setup

Using an Access Token

Regional Configuration

Faster HMAC Signing (Node.js)

Public vs Authenticated Endpoints

Best Practices

Example Environment Setup