What This SDK Covers

• Gate REST API integrations for exchange-specific workflows.
• Gate WebSocket support for market and account stream handling.
• Node.js-friendly usage patterns for service and automation stacks.
• Routable examples under /examples for implementation reference.

Install Package

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

Quickstart REST Walkthrough

Easily start calling Gate's futures REST APIs in JavaScript.

- Install the Gate.com (previously Gate.io) JavaScript SDK via NPM: `npm install gateio-api`. - Import the RestClient class (REST API wrapper for Gate's APIs). - Create an authenticated RestClient instance with your API credentials. - Call REST API methods as functions and await the promise containing the response.

In this example, we:

- Create both a REST client and authenticated WebSocket client. - Subscribe to private futures balance and user trade topics. - Query futures account balance for `usdt` settlement. - Calculate 50% of available balance and submit a market futures order on `BTC_USDT`. - Log API and stream responses for visibility.

This setup demonstrates a practical flow where private WebSocket subscriptions provide live account updates while REST handles account queries and order submission.

For a full map of available REST API methods, check out the endpoint reference below.

Quickstart REST Example

/**
 * This example demonstrates a simple commented workflow of:
 * - initialising the RestClient and WebsocketClient for Gate.io exchange
 * - connecting to an account’s private websockets (to receive updates asynchronously)
 * - checking if connection is successful
 * - fetching available futures balance
 * - placing an order using 50% of the available balance
 **/
import { RestClient, WebsocketClient } from 'gateio-api';

// Define the account object with API key and secret
const account = {
  // Replace 'yourApiHere' with your actual API key or use environment variables
  key: process.env.API_KEY || 'yourApiHere',
  // Replace 'yourSecretHere' with your actual API secret or use environment variables
  secret: process.env.API_SECRET || 'yourSecretHere',
};

// Initialize the RestClient with the API credentials
const gateRestClient = new RestClient({
  apiKey: account.key,
  apiSecret: account.secret,
});

// initialise websocket client - if you want only public data, you can initialise the client without the apiKey and apiSecret, just WebsocketClient()
const gateWSClient = new WebsocketClient({
  apiKey: account.key,
  apiSecret: account.secret,
});

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

async function subscribePrivateWs() {
  try {
    // Enter your user ID here
    const myUserID = '20011';

    //sub to balances updates
    const userBalances = {
      topic: 'futures.balances',
      payload: [myUserID],
    };

    //sub to trades updates
    const userTrades = {
      topic: 'futures.usertrades',
      payload: [myUserID, '!all'],
    };

    /**
     * Either send one topic (with params) at a time
     */
    // client.subscribe({
    //   topic: 'futures.usertrades',
    //   payload: [myUserID, '!all'],
    // }, 'perpFuturesUSDTV4');

    /**
     * Or send multiple topics in a batch (grouped by ws connection (WsKey))
     * You can also use strings for topics that don't have any parameters, even if you mix multiple requests into one function call:
     */
    gateWSClient.subscribe([userBalances, userTrades], 'perpFuturesUSDTV4');

    return true;
  } catch (e) {
    console.error('Req error: ', e);
    throw e;
  }
}

async function main() {
  try {
    await subscribePrivateWs();
    console.log('Subscribed to privateWs topics!');

    // Get futures account balance via REST
    const balances = await gateRestClient.getFuturesAccount({ settle: 'usdt' });

    // total usdt balance
    // const usdtBalance = Number(balances.total);

    // available usdt balance
    const availableBalance = Number(balances.available);

    // submit market order with 50% of the balance
    const orderAmount = availableBalance * 0.5;

    // Submit a market order with 50% of the balance
    const marketOrder = await gateRestClient.submitFuturesOrder({
      settle: 'usdt', // Specify the settlement currency
      contract: 'BTC_USDT', // Specify the contract
      size: orderAmount, // Order size: positive for long, negative for short, in USDT
      price: '0', // Market order, so price is set to '0'
      tif: 'ioc', // Time in force: 'ioc' (Immediate Or Cancel)
    });

    console.log('Order submitted:', marketOrder);
  } catch (e) {
    console.error(e);
    throw e;
  }
}

main();

// for more detailed ws connection, you can use a lot more listeners like below:

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

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

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

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

// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
gateWSClient.on('response', (data) => {
  console.info('server reply: ', JSON.stringify(data), '\n');
});

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

gateWSClient.on('authenticated', (data) => {
  console.error('authenticated: ', data);
});

Quickstart WebSocket Example

/* eslint-disable @typescript-eslint/no-unused-vars */
import { LogParams, WebsocketClient, WsTopicRequest } from 'gateio-api';

// eslint-disable-next-line @typescript-eslint/no-unused-vars
const account = {
  key: process.env.API_KEY || 'apiKeyHere',
  secret: process.env.API_SECRET || 'apiSecretHere',
};

// Define a custom logger object to handle logging at different levels
const customLogger = {
  // Trace level logging: used for detailed debugging information
  trace: (...params: LogParams): void => {
    // Uncomment the line below to enable trace logging
    // console.log(new Date(), 'trace', ...params);
  },
  // Info level logging: used for general informational messages
  info: (...params: LogParams): void => {
    console.log(new Date(), 'info', ...params);
  },
  // Error level logging: used for error messages
  error: (...params: LogParams): void => {
    console.error(new Date(), 'error', ...params);
  },
};

async function start() {
  const client = new WebsocketClient(
    {
      apiKey: account.key,
      apiSecret: account.secret,
    },
    customLogger,
  );

  // console.log('auth with: ', account);
  client.on('open', (data) => {
    console.log('connected ', data?.wsKey);
  });

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

  // Something happened, attempting to reconnect
  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('server reply: ', JSON.stringify(data), '\n');
  });

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

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

  try {
    // client.subscribe(topics, 'spotV4');

    const topicWithoutParamsAsString = 'spot.balances';

    // This has the same effect as above, it's just a different way of messaging which topic this is for
    // const topicWithoutParamsAsObject: WsTopicRequest = {
    //   topic: 'spot.balances',
    // };

    const userOrders: WsTopicRequest = {
      topic: 'spot.orders',
      payload: ['BTC_USDT', 'ETH_USDT', 'MATIC_USDT'],
    };

    const userTrades: WsTopicRequest = {
      topic: 'spot.usertrades',
      payload: ['BTC_USDT', 'ETH_USDT', 'MATIC_USDT'],
    };

    const userPriceOrders: WsTopicRequest = {
      topic: 'spot.priceorders',
      payload: ['!all'],
    };

    /**
     * Either send one topic (with optional params) at a time
     */
    // client.subscribe(topicWithoutParamsAsObject, 'spotV4');

    /**
     * Or send multiple topics in a batch (grouped by ws connection (WsKey))
     * You can also use strings for topics that don't have any parameters, even if you mix multiple requests into one function call:
     */
    client.subscribe(
      [topicWithoutParamsAsString, userOrders, userTrades, userPriceOrders],
      'spotV4',
    );

    /**
     * You can also subscribe in separate function calls as you wish.
     *
     * Any duplicate requests should get filtered out (e.g. here we subscribed to "spot.balances" twice, but the WS client will filter this out)
     */
    client.subscribe(
      [
        'spot.balances',
        'spot.margin_balances',
        'spot.funding_balances',
        'spot.cross_balances',
      ],
      'spotV4',
    );
  } catch (e) {
    console.error('Req error: ', e);
  }
}

start();

Quickstart WebSocket API Example

import { WebsocketAPIClient, WS_KEY_MAP } from 'gateio-api';

const account = {
  key: process.env.API_KEY || 'insert_key_here',
  secret: process.env.API_SECRET || 'insert_secret_here',
};

async function start() {
  const client = new WebsocketAPIClient({
    apiKey: account.key,
    apiSecret: account.secret,
    reauthWSAPIOnReconnect: true,
  });

  try {
    /**
     * Optional: authenticate in advance. This will prepare and authenticate a connection.
     * Useful to save time for the first request but completely optional. It will also happen automatically when you make your first request.
     */
    // console.log(new Date(), 'Authenticating in advance...');
    // await client.getWSClient().connectWSAPI('spotV4');
    // console.log(new Date(), 'Authenticating in advance...OK!');

    /* ============ SPOT TRADING EXAMPLES ============ */

    // SPOT ORDER PLACE - Submit a new spot order
    const newOrder = await client.submitNewSpotOrder({
      text: 't-my-custom-id',
      currency_pair: 'BTC_USDT',
      type: 'limit',
      account: 'spot',
      side: 'buy',
      amount: '1',
      price: '10000',
    });
    console.log(new Date(), 'Result of the order:', newOrder.data);

    // SPOT ORDER CANCEL - Cancel a specific spot order
    const cancelOrder = await client.cancelSpotOrder({
      order_id: '1700664330',
      currency_pair: 'BTC_USDT',
      account: 'spot',
    });
    console.log(new Date(), 'Cancel order result:', cancelOrder.data);

    // SPOT ORDER CANCEL BY IDS - Cancel orders by ID list
    const cancelOrdersByIds = await client.cancelSpotOrderById([
      {
        currency_pair: 'BTC_USDT',
        id: '1700664343',
        account: 'spot',
      },
    ]);
    console.log(
      new Date(),
      'Cancel orders by IDs result:',
      cancelOrdersByIds.data,
    );

    // SPOT ORDER CANCEL BY CURRENCY PAIR - Cancel all orders for a currency pair
    const cancelOrdersByCurrencyPair = await client.cancelSpotOrderForSymbol({
      currency_pair: 'BTC_USDT',
      side: 'buy',
      account: 'spot',
    });
    console.log(
      new Date(),
      'Cancel orders by currency pair result:',
      cancelOrdersByCurrencyPair.data,
    );

    // SPOT ORDER AMEND - Update an existing spot order
    const amendOrder = await client.updateSpotOrder({
      order_id: '1700664330',
      currency_pair: 'BTC_USDT',
      price: '12000',
      amount: '0.002',
      amend_text: 'price-update',
    });
    console.log(new Date(), 'Amend order result:', amendOrder.data);

    // SPOT ORDER STATUS - Get status of a specific spot order
    const orderStatus = await client.getSpotOrderStatus({
      order_id: '1700664330',
      currency_pair: 'BTC_USDT',
      account: 'spot',
    });
    console.log(new Date(), 'Order status result:', orderStatus.data);

    // SPOT ORDER LIST - Get list of spot orders
    const getOrders = await client.getSpotOrders({
      currency_pair: 'BTC_USDT',
      status: 'open',
      page: 1,
      limit: 10,
      account: 'spot',
      side: 'buy',
    });
    console.log(new Date(), 'Result of the orders:', getOrders.data);

    /* ============ FUTURES TRADING EXAMPLES ============ */

    /**
     * Gate has different websocket groups depending on the futures product.
     *
     * This affects which connection your command is sent to, so make sure to pass one matching your request. Look at WS_KEY_MAP (or the examples below) for details on the available product groups.
     */
    const FUTURES_CONNECTION_GROUP_WS_KEY = WS_KEY_MAP.perpFuturesUSDTV4;

    /**
     * Also optional, as for spot. Keep in mind the first parameter (wsKey) might vary depending on which WS URL is needed.
     */

    // console.log(new Date(), 'Authenticating in advance...');
    // await client.getWSClient().connectWSAPI(futuresConnectionGroup);
    // await client.getWSClient().connectWSAPI('perpFuturesUSDTV4');
    // await client.getWSClient().connectWSAPI('perpFuturesBTCV4');
    // await client.getWSClient().connectWSAPI('deliveryFuturesUSDTV4');
    // await client.getWSClient().connectWSAPI('perpFuturesBTCV4');
    // console.log(new Date(), 'Authenticating in advance...OK!');

    // FUTURES ORDER PLACE - Submit a new futures order
    const newFuturesOrder = await client.submitNewFuturesOrder(
      {
        contract: 'BTC_USDT',
        size: 10,
        price: '31503.28',
        tif: 'gtc',
        text: 't-my-custom-id',
        iceberg: 0,
        close: false,
        reduce_only: false,
        auto_size: undefined,
        stp_act: 'cn',
      },
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(new Date(), 'New futures order result:', newFuturesOrder.data);

    // FUTURES ORDER BATCH PLACE - Submit multiple futures orders
    const batchFuturesOrders = await client.submitNewFuturesBatchOrder(
      [
        {
          contract: 'BTC_USDT',
          size: 10,
          price: '31403.18',
          tif: 'gtc',
          text: 't-my-custom-id-1',
        },
        {
          contract: 'ETH_USDT',
          size: 20,
          price: '2500.50',
          tif: 'gtc',
          text: 't-my-custom-id-2',
        },
      ],
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Batch futures orders result:',
      batchFuturesOrders.data,
    );

    // FUTURES ORDER CANCEL - Cancel a specific futures order
    const cancelFuturesOrder = await client.cancelFuturesOrder(
      {
        order_id: '74046514',
      },
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Cancel futures order result:',
      cancelFuturesOrder.data,
    );

    // FUTURES ORDER CANCEL BY IDS - Cancel futures orders by ID list
    const cancelFuturesOrdersByIds = await client.cancelFuturesOrderById(
      ['1694883366', '123'],
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Cancel futures orders by IDs result:',
      cancelFuturesOrdersByIds.data,
    );

    // FUTURES ORDER CANCEL ALL - Cancel all open futures orders
    const cancelAllFuturesOrders = await client.cancelFuturesAllOpenOrders(
      {
        contract: 'BTC_USDT',
        side: 'bid',
      },
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Cancel all futures orders result:',
      cancelAllFuturesOrders.data,
    );

    // FUTURES ORDER AMEND - Update an existing futures order
    const amendFuturesOrder = await client.updateFuturesOrder(
      {
        order_id: '74046543',
        price: '31303.18',
        size: 15,
        amend_text: 'price-and-size-update',
      },
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Amend futures order result:',
      amendFuturesOrder.data,
    );

    // FUTURES ORDER LIST - Get list of futures orders
    const getFuturesOrders = await client.getFuturesOrders(
      {
        contract: 'BTC_USDT',
        status: 'open',
        limit: 10,
        offset: 0,
        last_id: undefined,
        count_total: 0,
      },
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Futures orders list result:',
      getFuturesOrders.data,
    );

    // FUTURES ORDER STATUS - Get status of a specific futures order
    const futuresOrderStatus = await client.getFuturesOrderStatus(
      {
        order_id: '74046543',
      },
      FUTURES_CONNECTION_GROUP_WS_KEY,
    );
    console.log(
      new Date(),
      'Futures order status result:',
      futuresOrderStatus.data,
    );
  } catch (e) {
    console.error(new Date(), 'Error:', e);
  }
}

start();

Endpoint Function Reference

Source: View endpoint map source

Reference Links

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