KuCoin JavaScript SDK

JavaScript SDK Usage

Use framework-neutral JavaScript request and event flows across Node.js-compatible runtimes.

In JavaScript, use the package directly from readable examples. TypeScript remains useful for larger integrations, but the same client patterns work in plain JavaScript.

What This SDK Covers

• Complete KuCoin REST API integrations for exchange-specific workflows.
• Robust KuCoin WebSocket support for market and account stream handling.
• JavaScript-friendly usage patterns for production integration work.
• Adaptable JavaScript examples & guides under /examples for implementation reference.
• Framework-neutral JavaScript snippets that stay approachable in all JavaScript runtimes.

Install Package

npm install kucoin-api
# or
pnpm install kucoin-api
yarn add kucoin-api

Quickstart REST API Walkthrough

Quickstart REST API Example

import { FuturesClient } from 'kucoin-api';

async function start() {
  const account = {
    key: 'keyHere',
    secret: 'secretHere',
    passphrase: 'memoHere',
  };
  const client = new FuturesClient({
    apiKey: account.key,
    apiSecret: account.secret,
    apiPassphrase: account.passphrase,
  });

  try {
    /**
     * =======
     * Credits for this guide go to user: @DKTradingClient / Code Nerd from the Kucoin API Telegram group!
     * =======

    /**
     * Futures are contracts, not currencies. In the futures symbols list you will see a "multiplier" field for each of the symbols. 
     * Each contract equals to  Multiplier x Size
     * For example:  https://api-futures.kucoin.com/api/v1/contracts/XRPUSDTM  - see the "multiplier" value.
     * */

    const symbolInfo = await client.getSymbol({ symbol: 'XRPUSDTM' });
    const multiplier = symbolInfo.data.multiplier;

    /**
     * E.g. if multiplier is 10(what you can see from the endpoint), that means each SIZE is 10 XRP. So if XRP is currently at $0.5,
     * then each 1 contract (size 10) is going to cost $5.00
     * size = (Funds x leverage) / (price x multiplier)
     */

    const XRPPriceExample = 0.5;
    const leverage = 5;
    const fundsToTradeUSDT = 100;

    const costOfContract = XRPPriceExample * multiplier;

    const size = (fundsToTradeUSDT * leverage) / costOfContract;
    console.log(`Size: ${size}`);

    /**
     * The trade amount indicates the amount of contract to buy or sell, and contract uses the base currency or lot as the trading unit.
     * The trade amount must be no less than 1 lot for the contract and no larger than the maxOrderQty.
     * It should be a multiple number of the lot, or the system will report an error when you place the order.
     * E.g. 1 lot of XBTUSDTM is 0.001 Bitcoin, while 1 lot of XBTUSDM is 1 USD.
     * or check the XRPUSDTM example above.
     *
     * Here are function examples using the Futures Create Order endpoint:
     */

    // A MARKET SHORT of 2 contracts of XBT using leverage of 5:
    const marketShort = client.submitOrder({
      clientOid: '123456789',
      leverage: 5,
      side: 'sell',
      size: 2,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'market',
    });
    console.log('Market short: ', marketShort);

    // A MARKET LONG of 2 contracts of XBT using leverage of 5:
    const marketLong = client.submitOrder({
      clientOid: '123456789',
      leverage: 5,
      side: 'buy',
      size: 2,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'market',
    });
    console.log('Market long: ', marketLong);

    // A LIMIT SHORT of 2 contracts of XBT using leverage of 5:
    const limitShort = client.submitOrder({
      clientOid: '123456789',
      leverage: 5,
      price: '70300.31',
      side: 'sell',
      size: 2,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'limit',
    });
    console.log('Limit short: ', limitShort);

    // A LIMIT LONG of 2 contracts of XBT using leverage of 5:
    const limitLong = client.submitOrder({
      clientOid: '123456789',
      leverage: 5,
      price: '40300.31',
      side: 'buy',
      size: 2,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'limit',
    });
    console.log('Limit long: ', limitLong);
    // On any "close position" action, if you specify a SIZE=0 or leave off the SIZE parameter,
    // then it will close the whole position, regardless of the size.
    // If you specify a SIZE, it will close only the number of contracts you specify.

    // If closeOrder is set to TRUE,
    // the system will close the position and the position size will become 0.
    // Side, Size and Leverage fields can be left empty and the system will determine the side and size automatically.

    // A MARKET CLOSE POSITION example:
    const marketClose = client.submitOrder({
      clientOid: '123456789',
      closeOrder: true,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'market',
      side: 'sell',
      size: 0,
    });
    console.log('Market close: ', marketClose);

    // A LIMIT CLOSE of a LONG example:
    const limitCloseLong = client.submitOrder({
      clientOid: '123456789',
      leverage: 5,
      price: '70300.31',
      closeOrder: true,
      side: 'sell',
      size: 2,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'limit',
    });
    console.log('Limit close long: ', limitCloseLong);

    // A LIMIT CLOSE of a SHORT example:
    const limitCloseShort = client.submitOrder({
      clientOid: '123456789',
      leverage: 5,
      price: '40300.31',
      closeOrder: true,
      side: 'buy',
      size: 2,
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'limit',
    });
    console.log('Limit close short: ', limitCloseShort);

    // A STOP LOSS example for a LONG position:
    const stopLossLong = client.submitOrder({
      clientOid: '123456789',
      closeOrder: true,
      stop: 'down',
      side: 'buy',
      stopPrice: '40200.31',
      stopPriceType: 'TP',
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'market',
    });
    console.log('Stoploss long: ', stopLossLong);

    // A STOP LOSS example for a SHORT position:
    const stopLossShort = client.submitOrder({
      clientOid: '123456789',
      closeOrder: true,
      stop: 'up',
      side: 'sell',
      stopPrice: '40200.31',
      stopPriceType: 'TP',
      symbol: 'XBTUSDTM',
      timeInForce: 'GTC',
      type: 'market',
    });

    console.log('Stoploss short: ', stopLossShort);
  } catch (e) {
    console.error('Req error: ', e);
  }
}

start();

Quickstart WebSocket Walkthrough

Quickstart WebSocket Example

import { WebsocketClient } from 'kucoin-api';

async function start() {
  // Optional: inject a custom logger to override internal logging behaviour
  // const logger: typeof DefaultLogger = {
  //   ...DefaultLogger,
  //   trace: (...params) => {
  //     if (
  //       [
  //         'Sending ping',
  //         // 'Sending upstream ws message: ',
  //         'Received pong',
  //       ].includes(params[0])
  //     ) {
  //       return;
  //     }
  //     console.log('trace', JSON.stringify(params, null, 2));
  //   },
  // };

  const account = {
    key: process.env.API_KEY || 'keyHere',
    secret: process.env.API_SECRET || 'secretHere',
    passphrase: process.env.API_PASSPHRASE || 'apiPassPhraseHere', // This is NOT your account password
  };

  console.log('connecting with ', account);
  const client = new WebsocketClient(
    {
      apiKey: account.key,
      apiSecret: account.secret,
      apiPassphrase: account.passphrase,
    },
    // logger,
  );

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

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

  // Something happened, attempting to reconenct
  client.on('reconnect', (data) => {
    console.log('reconnect: ', data);
  });

  // Reconnect successful
  client.on('reconnected', (data) => {
    console.log('reconnected: ', data);
  });

  // Connection closed. If unexpected, expect reconnect -> reconnected.
  client.on('close', (data) => {
    console.error('close: ', data);
  });

  // Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
  client.on('response', (data) => {
    console.info('response: ', data);
    // throw new Error('res?');
  });

  client.on('exception', (data) => {
    console.error('exception: ', {
      msg: data.msg,
      errno: data.errno,
      code: data.code,
      syscall: data.syscall,
      hostname: data.hostname,
    });
  });

  try {
    // Optional: await a connection to be ready before subscribing (this is not necessary)
    // await client.connect('spotPrivateV1');
    // console.log('connected');

    /**
     * For more detailed usage info, refer to the ws-spot-public.ts example.
     *
     * Below are some examples for subscribing to private spot & margin websockets.
     * Note: all "private" websocket topics should use the "spotPrivateV1" wsKey.
     */
    client.subscribe(
      [
        '/market/match:BTC-USDT',
        '/spotMarket/tradeOrders',
        '/spotMarket/tradeOrdersV2',
        '/account/balance',
        '/spotMarket/advancedOrders',
      ],
      'spotPrivateV1',
    );

    /**
     * Other margin websocket topics, which also use the "spotPrivateV1" WsKey:
     */
    client.subscribe(
      [
        '/margin/position',
        '/margin/isolatedPosition:BTC-USDT',
        '/spotMarket/advancedOrders',
      ],
      'spotPrivateV1',
    );
  } catch (e) {
    console.error('Subscribe exception: ', e);
  }
}

start();

Quickstart WebSocket API Walkthrough

Quickstart WebSocket API Example

/**
 * KuCoin WebSocket API Client - Complete Example
 *
 * This example demonstrates all available WebSocket API operations:
 * - Spot trading: submit, modify, cancel, sync operations
 * - Margin trading: submit and cancel orders
 * - Futures trading: submit, cancel, batch operations
 *
 * Usage:
 * Make sure to set your API credentials in environment variables:
 *    - API_KEY
 *    - API_SECRET
 *    - API_PASSPHRASE
 *
 *  or pass them as arguments to the constructor
 */

import { DefaultLogger, WebsocketAPIClient } from 'kucoin-api';

async function main() {
  const customLogger = {
    ...DefaultLogger,
    // For a more detailed view of the WebsocketClient, enable the `trace` level by uncommenting the below line:
    // trace: (...params) => console.log(new Date(), 'trace', ...params),
  };

  const account = {
    key: process.env.API_KEY || 'keyHere',
    secret: process.env.API_SECRET || 'secretHere',
    passphrase: process.env.API_PASSPHRASE || 'apiPassPhraseHere', // This is NOT your account password
  };

  const wsClient = new WebsocketAPIClient(
    {
      apiKey: account.key,
      apiSecret: account.secret,
      apiPassphrase: account.passphrase,

      // If you want your own event handlers instead of the default ones with logs, disable this setting and see the `attachEventHandlers` example below:
      // attachEventListeners: false
    },
    customLogger,
  );

  // Example usage for each WebSocket API operation
  console.log('Starting WebSocket API examples...\n');

  // 1. Submit Spot Order
  try {
    console.log('\n2. Testing submitNewSpotOrder...');
    const spotOrderResponse = await wsClient.submitNewSpotOrder({
      side: 'buy',
      symbol: 'BTC-USDT',
      type: 'limit',
      price: '20000', // Very low price to avoid accidental execution
      size: '0.0001',
    });
    console.log('Spot order response:', spotOrderResponse);
  } catch (e) {
    console.log('Spot order error:', e);
  }

  // 2. Submit Sync Spot Order
  try {
    console.log('\n3. Testing submitSyncSpotOrder...');
    const syncSpotOrderResponse = await wsClient.submitSyncSpotOrder({
      side: 'buy',
      symbol: 'BTC-USDT',
      type: 'limit',
      price: '1000', // Very high price to avoid accidental execution
      size: '0.01',
    });
    console.log('Sync spot order response:', syncSpotOrderResponse);
  } catch (e) {
    console.log('Sync spot order error:', e);
  }

  // 3. Modify Spot Order (requires existing order ID)
  try {
    console.log('\n4. Testing modifySpotOrder...');
    const modifyResponse = await wsClient.modifySpotOrder({
      symbol: 'BTC-USDT',
      orderId: '68cc3476693c1c00072ef1d9', // Replace with actual order ID
      newPrice: '2000',
    });
    console.log('Modify spot order response:', modifyResponse);
  } catch (e) {
    console.log('Modify spot order error:', e);
  }

  // 4. Cancel Spot Order
  try {
    console.log('\n5. Testing cancelSpotOrder...');
    const cancelSpotResponse = await wsClient.cancelSpotOrder({
      symbol: 'BTC-USDT',
      orderId: '68cc34c6693c1c0007301929', // Replace with actual order ID
    });
    console.log('Cancel spot order response:', cancelSpotResponse);
  } catch (e) {
    console.log('Cancel spot order error:', e);
  }

  // 5. Cancel Sync Spot Order
  try {
    console.log('\n6. Testing cancelSyncSpotOrder...');
    const cancelSyncResponse = await wsClient.cancelSyncSpotOrder({
      symbol: 'BTC-USDT',
      orderId: '68cc3530b9870a0007670294', // Replace with actual client order ID
    });
    console.log('Cancel sync spot order response:', cancelSyncResponse);
  } catch (e) {
    console.log('Cancel sync spot order error:', e);
  }

  // 6. Submit Margin Order
  try {
    console.log('\n7. Testing submitMarginOrder...');
    const marginOrderResponse = await wsClient.submitMarginOrder({
      clientOid: 'margin-test-' + Date.now(),
      side: 'buy',
      symbol: 'BTC-USDT',
      type: 'limit',
      price: '19000', // Very low price to avoid accidental execution
      size: '0.0001',
      isIsolated: false, // false for cross margin, true for isolated
    });
    console.log('Margin order response:', marginOrderResponse);
  } catch (e) {
    console.log('Margin order error:', e);
  }

  // 7. Cancel Margin Order
  try {
    console.log('\n8. Testing cancelMarginOrder...');
    const cancelMarginResponse = await wsClient.cancelMarginOrder({
      symbol: 'BTC-USDT',
      orderId: 'your-margin-order-id-here', // Replace with actual order ID
    });
    console.log('Cancel margin order response:', cancelMarginResponse);
  } catch (e) {
    console.log('Cancel margin order error:', e);
  }

  // 8. Submit Futures Order
  try {
    console.log('\n9. Testing submitFuturesOrder...');
    const futuresOrderResponse = await wsClient.submitFuturesOrder({
      clientOid: 'futures-test-' + Date.now(),
      side: 'buy',
      symbol: 'XBTUSDTM',
      marginMode: 'CROSS',
      type: 'limit',
      price: '1000', // Very low price to avoid accidental execution
      qty: '0.01',
      leverage: 10,
      positionSide: 'LONG', // needed if trading two-way (hedge) position mode
    });
    console.log('Futures order response:', futuresOrderResponse);
  } catch (e) {
    console.log('Futures order error:', e);
  }

  // 9. Cancel Futures Order
  try {
    console.log('\n10. Testing cancelFuturesOrder...');
    const cancelFuturesResponse = await wsClient.cancelFuturesOrder({
      symbol: 'XBTUSDTM',
      orderId: '358196976308797441', // Replace with actual order ID
    });
    console.log('Cancel futures order response:', cancelFuturesResponse);
  } catch (e) {
    console.log('Cancel futures order error:', e);
  }

  // 10. Submit Multiple Futures Orders
  try {
    console.log('\n11. Testing submitMultipleFuturesOrders...');
    const multiFuturesResponse = await wsClient.submitMultipleFuturesOrders([
      {
        clientOid: 'futures-test-1-' + Date.now(),
        side: 'buy',
        symbol: 'XBTUSDTM',
        marginMode: 'CROSS',
        type: 'limit',
        price: '1000', // Very low price to avoid accidental execution
        qty: '0.01',
        leverage: 10,
        positionSide: 'LONG', // Needed if trading hedge/two-way mode. Optional in one-way mode.
      },
      {
        clientOid: 'futures-test-2-' + Date.now(),
        side: 'buy',
        symbol: 'XBTUSDTM',
        marginMode: 'CROSS',
        type: 'limit',
        price: '1010', // Very low price to avoid accidental execution
        qty: '0.01',
        leverage: 10,
        positionSide: 'LONG',
      },
    ]);
    console.log('Multiple futures orders response:', multiFuturesResponse);
  } catch (e) {
    console.log('Multiple futures orders error:', e);
  }

  // 11. Cancel Multiple Futures Orders
  try {
    console.log('\n12. Testing cancelMultipleFuturesOrders...');
    const cancelMultiFuturesResponse =
      await wsClient.cancelMultipleFuturesOrders({
        orderIdsList: ['order-id-1', 'order-id-2'], // Replace with actual order IDs
      });
    console.log(
      'Cancel multiple futures orders response:',
      cancelMultiFuturesResponse,
    );
  } catch (e) {
    console.log('Cancel multiple futures orders error:', e);
  }

  console.log('\nCompleted all WebSocket API examples!');
  process.exit(1);
}

// Start executing the example workflow
main();

Endpoint Function Reference

Source: View endpoint map source

KuCoin JavaScript FAQ

Direct Example Files

Open the example files below if you want the clearest general-purpose starting point for REST API, WebSocket, and authentication workflows in plain JavaScript.

• KuCoin REST API example file (Kucoin/Rest/rest-futures-orders-guide.ts)
• KuCoin WebSocket example file (Kucoin/WebSockets/ws-spot-private.ts)
• KuCoin WebSocket API example file (Kucoin/WebSockets/WS-API/ws-api-client.ts)

Reference Links

• npm: kucoin-api
• GitHub: kucoin-api
• Release feed
• Support and feature requests