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.

This guide walks you through everything required to go from a blank project to a running integration with KuCoin’s REST and WebSocket APIs. You will install the package, import the clients, fetch public market data without credentials, and then make an authenticated private call — all in a few dozen lines of code.
Always store your API credentials in environment variables. Never hardcode apiKey, apiSecret, or apiPassphrase directly in source files that may be committed to version control.

​
Prerequisites

  • Node.js 18 or later (the SDK uses the Web Crypto API for signing, which is built into Node 18+).
  • A KuCoin account. Create API keys at kucoin.com/account/api.
  • (Optional) A .env file or shell environment with KUCOIN_API_KEY, KUCOIN_API_SECRET, and KUCOIN_API_PASSPHRASE set.
1
Install the package
2
npm
npm install kucoin-api
yarn
yarn add kucoin-api
pnpm
pnpm add kucoin-api
3
Import the SDK
4
The package ships both ESM and CJS builds. Use whichever import style matches your project:
5
ESM (TypeScript / import)
import { SpotClient, WebsocketClient } from 'kucoin-api';
CJS (require)
const { SpotClient, WebsocketClient } = require('kucoin-api');
6
Make a public REST call
7
Public endpoints do not require API credentials. Instantiate SpotClient with no arguments and call any market data method:
8
import { SpotClient } from 'kucoin-api';

async function start() {
  const client = new SpotClient();

  try {
    // Fetch all symbols
    const symbols = await client.getSymbols();
    console.log('symbols:', JSON.stringify(symbols, null, 2));

    // Fetch ticker for a specific symbol
    const ticker = await client.getTicker({ symbol: 'BTC-USDT' });
    console.log('ticker:', JSON.stringify(ticker, null, 2));

    // Fetch daily klines
    const klines = await client.getKlines({
      symbol: 'BTC-USDT',
      type: '1day',
    });
    console.log(klines);
  } catch (e) {
    console.error('Req error: ', e);
  }
}

start();
9
getSymbols(), getTicker(), getTickers(), getKlines(), and all order-book methods are public and work without API credentials.
10
Authenticate and make a private call
11
Provide your API credentials via environment variables and pass them to the SpotClient constructor. Once authenticated, you can call private endpoints like getBalances():
12
import { SpotClient } from 'kucoin-api';

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

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

start();
13
Place a spot order
14
Use submitHFOrder() for high-frequency spot trading. The generateNewOrderID() helper produces a unique client order ID:
15
import { SpotClient } from 'kucoin-api';

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

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

    const spotSellResult = await client.submitHFOrder({
      clientOid: client.generateNewOrderID(),
      side: 'sell',
      type: 'market',
      symbol: 'BTC-USDT',
      size: '0.00001',
    });
    console.log('spotSellResult ', JSON.stringify(spotSellResult, null, 2));
  } catch (e) {
    console.error('Req error: ', e);
  }
}

start();
16
Subscribe to a WebSocket ticker
17
The WebsocketClient manages connections, heartbeats, and reconnections automatically. Subscribe to a topic with a WsKey string that identifies the connection type:
18
import { WebsocketClient } from 'kucoin-api';

const client = new WebsocketClient();

client.on('open', (data) => {
  console.log('open: ', data?.wsKey);
});

// All market data arrives here
client.on('update', (data) => {
  console.info('data received: ', JSON.stringify(data));
});

client.on('reconnect', (data) => {
  console.log('reconnect: ', data);
});

client.on('reconnected', (data) => {
  console.log('reconnected: ', data?.wsKey);
});

client.on('close', (data) => {
  console.error('close: ', data);
});

client.on('response', (data) => {
  console.info('response: ', data);
});

client.on('exception', (data) => {
  console.error('exception: ', data);
});

// Subscribe to BTC-USDT and ETH-USDT tickers on the spot V1 connection
client.subscribe('/market/ticker:BTC-USDT,ETH-USDT', 'spotPublicV1');
19
Each unique wsKey string (such as 'spotPublicV1', 'spotPrivateV1', 'futuresPublicV1') maps to a distinct WebSocket connection. The client opens and tracks connections automatically as you subscribe.

​
Complete Working Example

The following combines a public call, private balance fetch, and a WebSocket subscription in a single script: 
import { SpotClient, WebsocketClient } from 'kucoin-api';

async function main() {
  // --- REST: public ---
  const publicClient = new SpotClient();
  const ticker = await publicClient.getTicker({ symbol: 'BTC-USDT' });
  console.log('BTC-USDT ticker:', ticker);

  // --- REST: private ---
  const privateClient = new SpotClient({
    apiKey: process.env.KUCOIN_API_KEY,
    apiSecret: process.env.KUCOIN_API_SECRET,
    apiPassphrase: process.env.KUCOIN_API_PASSPHRASE,
  });

  const balances = await privateClient.getBalances();
  console.log('Account balances:', JSON.stringify(balances, null, 2));

  // --- WebSocket: public ticker stream ---
  const wsClient = new WebsocketClient();

  wsClient.on('update', (data) => {
    console.log('WS update:', JSON.stringify(data));
  });

  wsClient.on('exception', (data) => {
    console.error('WS exception:', data);
  });

  wsClient.subscribe('/market/ticker:BTC-USDT', 'spotPublicV1');
}

main().catch(console.error);

​
What’s Next

Authentication

Deep-dive into API key options, access tokens, custom signing, and regional configuration.

KuCoin API Docs

Official KuCoin REST API reference for all endpoint parameters and response schemas.

Build docs developers (and LLMs) love

Get started for freeTalk to us