KuCoin TypeScript SDK

TypeScript SDK Usage

Use typed requests, responses, and event flows in stricter TypeScript services and shared libraries.

In TypeScript, use the package types to check request shapes, response fields, WebSocket payloads, and refactors around exchange-specific code.

What This SDK Covers

• Complete KuCoin REST API integrations for exchange-specific workflows.
• Robust KuCoin WebSocket support for market and account stream handling.
• TypeScript-friendly usage patterns for production integration work.
• Adaptable TypeScript examples & guides under /examples for implementation reference.
• Type-rich examples that emphasize request and response shapes, editor hints, and safer refactors.
• Implementation patterns for larger TypeScript services, shared libraries, and stricter TypeScript application code.

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 TypeScript FAQ

Direct Example Files

Open the example files for typed patterns that translate well into shared interfaces, services, and stricter application code.

• 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