Node.js & JavaScript SDK for Gate.com (Gate.io) REST APIs, WebSockets & WebSocket API

Updated & performant JavaScript & Node.js SDK for the Gate.com (gate.io) REST APIs and WebSockets:

• Extensive integration with Gate.com (Gate.io) REST APIs and WebSockets.
• TypeScript support (with type declarations for most API requests & responses).
• Gate.com REST APIs for Gate.com Spot, Margin, Perpetual Futures, Delivery Futures, Options & Announcements APIs.
  • Strongly typed on most requests and responses.
• Extremely robust & performant JavaScript/Node.js Gate.com SDK.
• Actively maintained with a modern, promise-driven interface.
• Support for seamless API authentication for private Gate.com REST API and WebSocket calls.
• Gate.com Spot, Margin, Perpetual Futures, Delivery Futures & Options.
  • Event driven messaging.
  • Smart websocket persistence
    • Automatically handle silent websocket disconnections through timed heartbeats, including the scheduled 24hr disconnect.
    • Automatically handle listenKey persistence and expiration/refresh.
    • Emit reconnected event when dropped connection is restored.
• Websocket API for Gate.com Spot, Margin, Perpetual Futures & Delivery Futures.
  • Automatic connectivity via existing WebsocketClient, just call sendWSAPIRequest to trigger a request.
  • Automatic authentication, just call sendWSAPIRequest with channel & parameters.
  • Choose between two interfaces for WS API communication:
    • Event-driven interface, fire & forget via sendWSAPIRequest and receive async replies via wsClient's event emitter.
    • Promise-driven interface, simply use the WebsocketAPIClient for a REST-like experience. Use the WebSocket API like a REST API! See examples/ws-api-client.ts for a demonstration.
• Proxy support via axios integration.
• Active community support & collaboration in telegram: Node.js Algo Traders.

Installation

npm install --save gateio-api

Issues & Discussion

• Issues? Check the issues tab.
• Discuss & collaborate with other node devs? Join our Node.js Algo Traders engineering community on telegram.
• Follow our announcement channel for real-time updates on X/Twitter

Related projects

Check out my related JavaScript/TypeScript/Node.js projects:

• Try my REST API & WebSocket SDKs:
  • Bybit-api Node.js SDK
  • Okx-api Node.js SDK
  • Binance Node.js SDK
  • Gateio-api Node.js SDK
  • Bitget-api Node.js SDK
  • Kucoin-api Node.js SDK
  • Coinbase-api Node.js SDK
  • Bitmart-api Node.js SDK
• Try my misc utilities:
  • OrderBooks Node.js
  • Crypto Exchange Account State Cache
• Check out my examples:
  • awesome-crypto-examples Node.js

Documentation

Most methods accept JS objects. These can be populated using parameters specified by gateio's API documentation.

• Gate.com/gate.io API Documentation
• REST Endpoint Function List
• TSDoc Documentation (autogenerated using typedoc)

Structure

This project uses typescript. Resources are stored in 2 key structures:

• src - the whole connector written in typescript
• examples - some implementation examples & demonstrations. Contributions are welcome!

---

Usage

Create API credentials

• Gate.com API Key Management

REST API

To use any of Gate.com's REST APIs in JavaScript/TypeScript/Node.js, import (or require) the RestClient:

1const { RestClient } = require('gateio-api');
2
3const API_KEY = 'xxx';
4const PRIVATE_KEY = 'yyy';
5
6const client = new RestClient({
7  apiKey: API_KEY,
8  apiSecret: PRIVATE_KEY,
9});
10
11client
12  .getSpotTicker()
13  .then((result) => {
14    console.log('all spot tickers result: ', result);
15  })
16  .catch((err) => {
17    console.error('spot ticker error: ', err);
18  });
19
20client
21  .getSpotOrders({
22    currency_pair: 'BTC_USDT', // Specify the currency pair
23    status: 'open', // Specify the status of the orders to fetch
24  })
25  .then((result) => {
26    console.log('getSpotOrders result: ', result);
27  })
28  .catch((err) => {
29    console.error('getSpotOrders error: ', err);
30  });

See RestClient for further information, or the examples for lots of usage examples.

WebSockets

All available WebSockets can be used via a shared WebsocketClient. The WebSocket client will automatically open/track/manage connections as needed. Each unique connection (one per server URL) is tracked using a WsKey (each WsKey is a string - see WS_KEY_MAP for a list of supported values).

Any subscribe/unsubscribe events will need to include a WsKey, so the WebSocket client understands which connection the event should be routed to. See examples below or in the examples folder on GitHub.

Data events are emitted from the WebsocketClient via the update event, see example below:

1const { WebsocketClient } = require('gateio-api');
2
3const API_KEY = 'xxx';
4const PRIVATE_KEY = 'yyy';
5
6const wsConfig = {
7  apiKey: API_KEY,
8  apiSecret: PRIVATE_KEY,
9
10  /*
11    The following parameters are optional:
12  */
13
14  // Livenet is used by default, use this to enable testnet:
15  // useTestnet: true
16
17  // how long to wait (in ms) before deciding the connection should be terminated & reconnected
18  // pongTimeout: 1000,
19
20  // how often to check (in ms) that WS connection is still alive
21  // pingInterval: 10000,
22
23  // how long to wait before attempting to reconnect (in ms) after connection is closed
24  // reconnectTimeout: 500,
25
26  // config options sent to RestClient (used for time sync). See RestClient docs.
27  // restOptions: { },
28
29  // config for axios used for HTTP requests. E.g for proxy support
30  // requestOptions: { }
31};
32
33const ws = new WebsocketClient(wsConfig);
34
35/**
36 * Subscribing to data:
37 **/
38
39const userOrders = {
40  topic: 'spot.orders',
41  payload: ['BTC_USDT', 'ETH_USDT', 'MATIC_USDT'],
42};
43
44const userTrades = {
45  topic: 'spot.usertrades',
46  payload: ['BTC_USDT', 'ETH_USDT', 'MATIC_USDT'],
47};
48
49const userPriceOrders = {
50  topic: 'spot.priceorders',
51  payload: ['!all'],
52};
53
54// subscribe to multiple topics at once
55ws.subscribe([userOrders, userTrades, userPriceOrders], 'spotV4');
56
57// and/or subscribe to individual topics on demand
58ws.subscribe(
59  {
60    topic: 'spot.priceorders',
61    payload: ['!all'],
62  },
63  'spotV4',
64);
65
66// Some topics don't need params, for those you can just subscribe with a string (or use a topic + payload object as above)
67ws.subscribe('spot.balances', 'spotV4');
68
69/**
70 * Handling events:
71 **/
72
73// Listen to events coming from websockets. This is the primary data source
74ws.on('update', (data) => {
75  console.log('data', data);
76});
77
78// Optional: Listen to websocket connection open event (automatic after subscribing to one or more topics)
79ws.on('open', ({ wsKey, event }) => {
80  console.log('connection open for websocket with ID: ' + wsKey);
81});
82
83// Optional: Listen to responses to websocket queries (e.g. the reply after subscribing to a topic)
84ws.on('response', (response) => {
85  console.log('response', response);
86});
87
88// Optional: Listen to connection close event. Unexpected connection closes are automatically reconnected.
89ws.on('close', () => {
90  console.log('connection closed');
91});
92
93// Optional: listen to internal exceptions. Useful for debugging if something weird happens
94ws.on('exception', (data) => {
95  console.error('exception: ', data);
96});
97
98// Optional: Listen to raw error events.
99ws.on('error', (err) => {
100  console.error('ERR', err);
101});

See WebsocketClient for further information and make sure to check the examples folder for much more detail.

Websocket API

Gate.com supports sending requests (commands) over an active WebSocket connection. This is called the WebSocket API.

The WebSocket API is available through two approaches, depending on individual preference:

Event Driven API

The WebSocket API is available in the WebsocketClient via the sendWSAPIRequest(wsKey, channel, params) method.

Each call to this method is wrapped in a promise, which you can async await for a response, or handle it in a raw event-driven design.

• event-driven:
  • send requests via client.sendWSAPIRequest(wsKey, channel, params).catch(e => console.error('WS API exception for channel', channel, e)), fire and forget, don't use await
  • handle async replies via event handlers on client.on('exception', cb) and client.on('response', cb)
• promise-driven:
  • send requests via const result = await client.sendWSAPIRequest(wsKey, channel, params), which returns a promise
  • await each call
  • use try/catch blocks to handle promise rejections

REST-like API

The WebSocket API is also available in a promise-wrapped REST-like format. Either, as above, await any calls to sendWSAPIRequest(...), or directly use the convenient WebsocketAPIClient. This class is very similar to existing REST API classes (such as the RestClient).

It provides one function per endpoint, feels like a REST API and will automatically route your request via an automatically persisted, authenticated and health-checked WebSocket API connection.

Below is an example showing how easy it is to use the WebSocket API without any concern for the complexity of managing WebSockets.

1const { WebsocketAPIClient } = require('gateio-api');
2
3const API_KEY = 'xxx';
4const API_SECRET = 'yyy';
5
6async function start() {
7  // Make an instance of the WS API Client
8  const wsClient = new WebsocketAPIClient({
9    apiKey: API_KEY,
10    apiSecret: API_SECRET,
11    // Automatically re-auth WS API, if we were auth'd before and get reconnected
12    reauthWSAPIOnReconnect: true,
13  });
14
15  try {
16    // Connection will authenticate automatically before first request
17    // Make WebSocket API calls, very similar to a REST API:
18
19    /* ============ SPOT TRADING EXAMPLES ============ */
20
21    // Submit a new spot order
22    const newOrder = await wsClient.submitNewSpotOrder({
23      text: 't-my-custom-id',
24      currency_pair: 'BTC_USDT',
25      type: 'limit',
26      account: 'spot',
27      side: 'buy',
28      amount: '1',
29      price: '10000',
30    });
31    console.log('Order result:', newOrder.data);
32
33    // Cancel a spot order
34    const cancelOrder = await wsClient.cancelSpotOrder({
35      order_id: '1700664330',
36      currency_pair: 'BTC_USDT',
37      account: 'spot',
38    });
39    console.log('Cancel result:', cancelOrder.data);
40
41    // Get spot order status
42    const orderStatus = await wsClient.getSpotOrderStatus({
43      order_id: '1700664330',
44      currency_pair: 'BTC_USDT',
45      account: 'spot',
46    });
47    console.log('Order status:', orderStatus.data);
48
49    /* ============ FUTURES TRADING EXAMPLES ============ */
50
51    // Submit a new futures order
52    const newFuturesOrder = await wsClient.submitNewFuturesOrder({
53      contract: 'BTC_USDT',
54      size: 10,
55      price: '31503.28',
56      tif: 'gtc',
57      text: 't-my-custom-id',
58    });
59    console.log('Futures order result:', newFuturesOrder.data);
60
61    // Cancel a futures order
62    const cancelFuturesOrder = await wsClient.cancelFuturesOrder({
63      order_id: '74046514',
64    });
65    console.log('Cancel futures order result:', cancelFuturesOrder.data);
66
67    // Get futures order status
68    const futuresOrderStatus = await wsClient.getFuturesOrderStatus({
69      order_id: '74046543',
70    });
71    console.log('Futures order status:', futuresOrderStatus.data);
72  } catch (e) {
73    console.error('WS API Error:', e);
74  }
75}
76
77start();

For more detailed examples using any approach, refer to the examples folder (e.g. ws-api-client.ts).

---

Customise Logging

Pass a custom logger which supports the log methods silly, debug, notice, info, warning and error, or override methods from the default logger as desired.

1const { WebsocketClient, DefaultLogger } = require('gateio-api');
2
3// Disable all logging on the silly level
4DefaultLogger.silly = () => {};
5
6const ws = new WebsocketClient({ key: 'xxx', secret: 'yyy' }, DefaultLogger);

---

Contributions & Thanks

Have my projects helped you? Share the love, there are many ways you can show your thanks:

• Star & share my projects.
• Are my projects useful? Sponsor me on Github and support my effort to maintain & improve them: https://github.com/sponsors/tiagosiebler
• Have an interesting project? Get in touch & invite me to it.
• Or buy me all the coffee:
  • ETH(ERC20): 0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C

Contributions & Pull Requests

Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.

Star History