gateio-api 1.1.11 → 1.1.12

package/README.md

@@ -1,4 +1,4 @@
-# Node.js & JavaScript SDK for Gate.io REST APIs, WebSockets & WebSocket API
+# Node.js & JavaScript SDK for Gate.com (Gate.io) REST APIs, WebSockets & WebSocket API
 
 <p align="center">
   <a href="https://www.npmjs.com/package/gateio-api">
@@ -18,27 +18,27 @@
 
 [1]: https://www.npmjs.com/package/gateio-api
 
-Updated & performant JavaScript & Node.js SDK for the Gate.io REST APIs and WebSockets:
+Updated & performant JavaScript & Node.js SDK for the Gate.com (gate.io) REST APIs and WebSockets:
 
-- Extensive integration with 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.io REST APIs for Gate.io Spot, Margin, Perpetual Futures, Delivery Futures, Options & Announcements APIs.
+- 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.io SDK.
+- 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.io REST API and WebSocket calls.
-- Gate.io Spot, Margin, Perpetual Futures, Delivery Futures & Options.
+- 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.io Spot, Margin, Perpetual Futures & Delivery Futures.
+- 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 call and await sendWSAPIRequest for a REST-API-like behaviour with the WS API.
+    - 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](./examples/ws-api-client.ts) for a demonstration.
 - Proxy support via axios integration.
 - Active community support & collaboration in telegram: [Node.js Algo Traders](https://t.me/nodetraders).
 
@@ -78,7 +78,7 @@ Check out my related JavaScript/TypeScript/Node.js projects:
 
 Most methods accept JS objects. These can be populated using parameters specified by gateio's API documentation.
 
-- [Gate.io API Documentation](https://www.gate.io/docs/developers/apiv4/en/)
+- [Gate.com/gate.io API Documentation](https://www.gate.com/docs/developers/apiv4/en/)
 - [REST Endpoint Function List](./docs/endpointFunctionList.md)
 - [TSDoc Documentation (autogenerated using typedoc)](https://tsdocs.dev/docs/gateio-api)
 
@@ -95,11 +95,11 @@ This project uses typescript. Resources are stored in 2 key structures:
 
 Create API credentials
 
-- [Gate.io API Key Management](https://www.gate.io/myaccount/api_key_manage)
+- [Gate.com API Key Management](https://www.gate.com/myaccount/api_key_manage)
 
 ### REST API
 
-To use any of Gate.io's REST APIs in JavaScript/TypeScript/Node.js, import (or require) the `RestClient`:
+To use any of Gate.com's REST APIs in JavaScript/TypeScript/Node.js, import (or require) the `RestClient`:
 
 ```javascript
 const { RestClient } = require('gateio-api');
@@ -252,107 +252,114 @@ See [WebsocketClient](./src/WebsocketClient.ts) for further information and make
 
 ### Websocket API
 
-The [WebsocketClient](./src/WebsocketClient.ts) supports this exchange's Websocket API. There are two ways to use the WS API, depending on individual preference:
+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](./src/WebsocketClient.ts) 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)`, fire and forget, don't use await
+  - 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
 
-The below example demonstrates the promise-driven approach, which behaves similar to a REST API. For more detailed examples, refer to the [examples](./examples/) folder (e.g the [ws-private-spot-wsapi.ts](./examples/ws-private-spot-wsapi.ts) example).
+#### 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.
 
 ```javascript
-const { WebsocketClient } = require('gateio-api');
+const { WebsocketAPIClient } = require('gateio-api');
 
 const API_KEY = 'xxx';
-const PRIVATE_KEY = 'yyy';
+const API_SECRET = 'yyy';
 
 async function start() {
-  const client = new WebsocketClient({
+  // Make an instance of the WS API Client
+  const wsClient = new WebsocketAPIClient({
     apiKey: API_KEY,
-    apiSecret: PRIVATE_KEY,
+    apiSecret: API_SECRET,
     // Automatically re-auth WS API, if we were auth'd before and get reconnected
     reauthWSAPIOnReconnect: true,
   });
 
-  /**
-   * Setup basic event handlers for core connectivity events.
-   * Note for this approach, the `response` and `update` events are not needed (but you can use them too/instead if you prefer).
-   **/
-
-  // Successfully connected
-  client.on('open', (data) => {
-    console.log(new Date(), 'ws connected ', data?.wsKey);
-  });
-
-  // Something happened, attempting to reconnect
-  client.on('reconnect', (data) => {
-    console.log(new Date(), 'ws reconnect: ', data);
-  });
-
-  // Reconnect successful
-  client.on('reconnected', (data) => {
-    console.log(new Date(), 'ws reconnected: ', data);
-  });
-
-  // Connection closed. If unexpected, expect reconnect -> reconnected.
-  client.on('close', (data) => {
-    console.error(new Date(), 'ws close: ', data);
-  });
-
-  client.on('exception', (data) => {
-    console.error(new Date(), 'ws exception: ', data);
-  });
-
-  client.on('authenticated', (data) => {
-    console.error(new Date(), 'ws authenticated: ', data);
-  });
-
   try {
-    /**
-     * All WebSocket API (WS API) messaging should be done via the sendWSAPIRequest method.
-     */
-
-    // The WSKey identifies which connection this request is for.
-    // (e.g. "spotV4" | "perpFuturesUSDTV4" | "perpFuturesBTCV4" | "deliveryFuturesUSDTV4" | "deliveryFuturesBTCV4" | "optionsV4")
-    const wsKey = 'spotV4';
-
-    /**
-     * To authenticate, send an empty request to "spot.login". The SDK will handle all the parameters.
-     *
-     * By default (reauthWSAPIOnReconnect: true), if we get reconnected later on (e.g. connection temporarily lost), we will try to re-authenticate the WS API automatically when the connection is restored.
-     */
-    console.log(new Date(), 'try authenticate');
-    const loginResult = await client.sendWSAPIRequest(wsKey, 'spot.login');
-    console.log(new Date(), 'authenticated!', loginResult);
-
-    /**
-     * For other channels, you should include any parameters for the request (the payload) in your call.
-     *
-     * Note that internal parameters such as "signature" etc are all handled automatically by the SDK. Only the core request parameters are needed.
-     */
-    console.log(new Date(), 'try get order status');
-    const orderStatus = await client.sendWSAPIRequest(
-      wsKey,
-      'spot.order_status',
-      {
-        order_id: '600995435390',
-        currency_pair: 'BTC_USDT',
-      },
-    );
-
-    console.log(new Date(), 'orderStatus result!', orderStatus);
+    // Connection will authenticate automatically before first request
+    // Make WebSocket API calls, very similar to a REST API:
+
+    /* ============ SPOT TRADING EXAMPLES ============ */
+
+    // Submit a new spot order
+    const newOrder = await wsClient.submitNewSpotOrder({
+      text: 't-my-custom-id',
+      currency_pair: 'BTC_USDT',
+      type: 'limit',
+      account: 'spot',
+      side: 'buy',
+      amount: '1',
+      price: '10000',
+    });
+    console.log('Order result:', newOrder.data);
+
+    // Cancel a spot order
+    const cancelOrder = await wsClient.cancelSpotOrder({
+      order_id: '1700664330',
+      currency_pair: 'BTC_USDT',
+      account: 'spot',
+    });
+    console.log('Cancel result:', cancelOrder.data);
+
+    // Get spot order status
+    const orderStatus = await wsClient.getSpotOrderStatus({
+      order_id: '1700664330',
+      currency_pair: 'BTC_USDT',
+      account: 'spot',
+    });
+    console.log('Order status:', orderStatus.data);
+
+    /* ============ FUTURES TRADING EXAMPLES ============ */
+
+    // Submit a new futures order
+    const newFuturesOrder = await wsClient.submitNewFuturesOrder({
+      contract: 'BTC_USDT',
+      size: 10,
+      price: '31503.28',
+      tif: 'gtc',
+      text: 't-my-custom-id',
+    });
+    console.log('Futures order result:', newFuturesOrder.data);
+
+    // Cancel a futures order
+    const cancelFuturesOrder = await wsClient.cancelFuturesOrder({
+      order_id: '74046514',
+    });
+    console.log('Cancel futures order result:', cancelFuturesOrder.data);
+
+    // Get futures order status
+    const futuresOrderStatus = await wsClient.getFuturesOrderStatus({
+      order_id: '74046543',
+    });
+    console.log('Futures order status:', futuresOrderStatus.data);
   } catch (e) {
-    console.error(`WS API Error: `, e);
+    console.error('WS API Error:', e);
   }
 }
 
 start();
 ```
 
+For more detailed examples using any approach, refer to the [examples](./examples/) folder (e.g. [ws-api-client.ts](./examples/ws-api-client.ts)).
+
 ---
 
 ## Customise Logging

package/dist/cjs/WebsocketAPIClient.d.ts

@@ -0,0 +1,136 @@
+import { DefaultLogger } from './lib/logger.js';
+import { WSClientConfigurableOptions } from './types/websockets/client.js';
+import { WSAPIFuturesOrder, WSAPIFuturesOrderAmendReq, WSAPIFuturesOrderBatchPlaceRespItem, WSAPIFuturesOrderCancelCPReq, WSAPIFuturesOrderCancelIdsRespItem, WSAPIFuturesOrderCancelReq, WSAPIFuturesOrderListReq, WSAPIFuturesOrderPlaceReq, WSAPIFuturesOrderStatusReq, WSAPIResponse, WSAPISpotOrder, WSAPISpotOrderAmendReq, WSAPISpotOrderCancelCPReq, WSAPISpotOrderCancelIdsReq, WSAPISpotOrderCancelIdsRespItem, WSAPISpotOrderCancelReq, WSAPISpotOrderListReq, WSAPISpotOrderPlaceReq, WSAPISpotOrderStatusReq, WSAPIWsKey } from './types/websockets/wsAPI.js';
+import { WebsocketClient } from './WebsocketClient.js';
+/**
+ * Configurable options specific to only the REST-like WebsocketAPIClient
+ */
+export interface WSAPIClientConfigurableOptions {
+    /**
+     * Default: true
+     *
+     * Attach default event listeners, which will console log any high level
+     * events (opened/reconnecting/reconnected/etc).
+     *
+     * If you disable this, you should set your own event listeners
+     * on the embedded WS Client `wsApiClient.getWSClient().on(....)`.
+     */
+    attachEventListeners: boolean;
+}
+/**
+ * This is a minimal Websocket API wrapper around the WebsocketClient.
+ *
+ * Some methods support passing in a custom "wsKey". This is a reference to which WS connection should
+ * be used to transmit that message. This is only useful if you wish to use an alternative wss
+ * domain that is supported by the SDK.
+ *
+ * Note: To use testnet, don't set the wsKey - use `testnet: true` in
+ * the constructor instead.
+ *
+ * Note: You can also directly use the sendWSAPIRequest() method to make WS API calls, but some
+ * may find the below methods slightly more intuitive.
+ *
+ * Refer to the WS API promises example for a more detailed example on using sendWSAPIRequest() directly:
+ * https://github.com/tiagosiebler/gateio-api/blob/master/examples/ws-private-spot-wsapi.ts#L119
+ */
+export declare class WebsocketAPIClient {
+    private wsClient;
+    private options;
+    constructor(options?: WSClientConfigurableOptions & Partial<WSAPIClientConfigurableOptions>, logger?: DefaultLogger);
+    getWSClient(): WebsocketClient;
+    setTimeOffsetMs(newOffset: number): void;
+    /**
+     * Submit a spot order
+     */
+    submitNewSpotOrder(params: WSAPISpotOrderPlaceReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrder>>;
+    /**
+     * Cancel a spot order
+     */
+    cancelSpotOrder(params: WSAPISpotOrderCancelReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrder>>;
+    /**
+     * Cancel all spot orders with the given id list
+     */
+    cancelSpotOrderById(params: WSAPISpotOrderCancelIdsReq[], wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrderCancelIdsRespItem[]>>;
+    /**
+     * Cancel a spot order for a given symbol
+     */
+    cancelSpotOrderForSymbol(params: WSAPISpotOrderCancelCPReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrder[]>>;
+    /**
+     * Update a spot order
+     */
+    updateSpotOrder(params: WSAPISpotOrderAmendReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrder>>;
+    /**
+     * Get the status of a spot order
+     */
+    getSpotOrderStatus(params: WSAPISpotOrderStatusReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrder>>;
+    /**
+     * Get all spot orders
+     */
+    getSpotOrders(params: WSAPISpotOrderListReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPISpotOrder[]>>;
+    /**
+     * Submit a futures order.
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    submitNewFuturesOrder(params: WSAPIFuturesOrderPlaceReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrder>>;
+    /**
+     * Submit a batch of futures orders
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    submitNewFuturesBatchOrder(params: WSAPIFuturesOrderPlaceReq[], wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrderBatchPlaceRespItem[]>>;
+    /**
+     * Cancel a futures order
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    cancelFuturesOrder(params: WSAPIFuturesOrderCancelReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrder>>;
+    /**
+     * Cancel futures orders by id list
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    cancelFuturesOrderById(params: string[], wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrderCancelIdsRespItem[]>>;
+    /**
+     * Cancel all open futures orders
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    cancelFuturesAllOpenOrders(params: WSAPIFuturesOrderCancelCPReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrder[]>>;
+    /**
+     * Update a futures order
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    updateFuturesOrder(params: WSAPIFuturesOrderAmendReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrder>>;
+    /**
+     * Get all futures orders
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    getFuturesOrders(params: WSAPIFuturesOrderListReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrder[]>>;
+    /**
+     * Get futures order status
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    getFuturesOrderStatus(params: WSAPIFuturesOrderStatusReq, wsKey?: WSAPIWsKey): Promise<WSAPIResponse<WSAPIFuturesOrder>>;
+    /**
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     * Private methods for handling some of the convenience/automation provided by the WS API Client
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     */
+    private setupDefaultEventListeners;
+}

package/dist/cjs/WebsocketAPIClient.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebsocketAPIClient = void 0;
+const websocket_util_js_1 = require("./lib/websocket/websocket-util.js");
+const WebsocketClient_js_1 = require("./WebsocketClient.js");
+/**
+ * This is a minimal Websocket API wrapper around the WebsocketClient.
+ *
+ * Some methods support passing in a custom "wsKey". This is a reference to which WS connection should
+ * be used to transmit that message. This is only useful if you wish to use an alternative wss
+ * domain that is supported by the SDK.
+ *
+ * Note: To use testnet, don't set the wsKey - use `testnet: true` in
+ * the constructor instead.
+ *
+ * Note: You can also directly use the sendWSAPIRequest() method to make WS API calls, but some
+ * may find the below methods slightly more intuitive.
+ *
+ * Refer to the WS API promises example for a more detailed example on using sendWSAPIRequest() directly:
+ * https://github.com/tiagosiebler/gateio-api/blob/master/examples/ws-private-spot-wsapi.ts#L119
+ */
+class WebsocketAPIClient {
+    wsClient;
+    options;
+    constructor(options, logger) {
+        this.wsClient = new WebsocketClient_js_1.WebsocketClient(options, logger);
+        this.options = {
+            attachEventListeners: true,
+            ...options,
+        };
+        this.setupDefaultEventListeners();
+    }
+    getWSClient() {
+        return this.wsClient;
+    }
+    setTimeOffsetMs(newOffset) {
+        return this.getWSClient().setTimeOffsetMs(newOffset);
+    }
+    /*
+     *
+     * SPOT - Trading requests
+     *
+     */
+    /**
+     * Submit a spot order
+     */
+    submitNewSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_place', params);
+    }
+    /**
+     * Cancel a spot order
+     */
+    cancelSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_cancel', params);
+    }
+    /**
+     * Cancel all spot orders with the given id list
+     */
+    cancelSpotOrderById(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_cancel_ids', params);
+    }
+    /**
+     * Cancel a spot order for a given symbol
+     */
+    cancelSpotOrderForSymbol(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_cancel_cp', params);
+    }
+    /**
+     * Update a spot order
+     */
+    updateSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_amend', params);
+    }
+    /**
+     * Get the status of a spot order
+     */
+    getSpotOrderStatus(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_status', params);
+    }
+    /**
+     * Get all spot orders
+     */
+    getSpotOrders(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.spotV4, 'spot.order_list', params);
+    }
+    /*
+     *
+     * Futures - Trading requests
+     *
+     */
+    /**
+     * Submit a futures order.
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    submitNewFuturesOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_place', params);
+    }
+    /**
+     * Submit a batch of futures orders
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    submitNewFuturesBatchOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_batch_place', params);
+    }
+    /**
+     * Cancel a futures order
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    cancelFuturesOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_cancel', params);
+    }
+    /**
+     * Cancel futures orders by id list
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    cancelFuturesOrderById(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_cancel_ids', params);
+    }
+    /**
+     * Cancel all open futures orders
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    cancelFuturesAllOpenOrders(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_cancel_cp', params);
+    }
+    /**
+     * Update a futures order
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    updateFuturesOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_amend', params);
+    }
+    /**
+     * Get all futures orders
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    getFuturesOrders(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_list', params);
+    }
+    /**
+     * Get futures order status
+     *
+     * Note: without a wsKey, this defaults to the perpFuturesUSDTV4 connection
+     */
+    getFuturesOrderStatus(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || websocket_util_js_1.WS_KEY_MAP.perpFuturesUSDTV4, 'futures.order_status', params);
+    }
+    /**
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     * Private methods for handling some of the convenience/automation provided by the WS API Client
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     */
+    setupDefaultEventListeners() {
+        if (this.options.attachEventListeners) {
+            /**
+             * General event handlers for monitoring the WebsocketClient
+             */
+            this.wsClient
+                .on('open', (data) => {
+                console.log(new Date(), 'ws connected', data.wsKey);
+            })
+                .on('reconnect', ({ wsKey }) => {
+                console.log(new Date(), 'ws automatically reconnecting.... ', wsKey);
+            })
+                .on('reconnected', (data) => {
+                console.log(new Date(), 'ws has reconnected ', data?.wsKey);
+            })
+                .on('authenticated', (data) => {
+                console.info(new Date(), 'ws has authenticated ', data?.wsKey);
+            })
+                .on('exception', (data) => {
+                console.error(new Date(), 'ws exception: ', JSON.stringify(data));
+            });
+        }
+    }
+}
+exports.WebsocketAPIClient = WebsocketAPIClient;
+//# sourceMappingURL=WebsocketAPIClient.js.map

package/dist/cjs/WebsocketAPIClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketAPIClient.js","sourceRoot":"","sources":["../../src/WebsocketAPIClient.ts"],"names":[],"mappings":"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"}

package/dist/cjs/WebsocketClient.d.ts

@@ -3,10 +3,14 @@ import { MessageEventLike } from './lib/requestUtils.js';
 import { WsKey, WsMarket, WsTopicRequest } from './lib/websocket/websocket-util.js';
 import { WSConnectedResult } from './lib/websocket/WsStore.types.js';
 import { WsOperation } from './types/websockets/requests.js';
-import { WsAPITopicRequestParamMap, WsAPITopicResponseMap, WsAPIWsKeyTopicMap } from './types/websockets/wsAPI.js';
+import { WsAPITopicRequestParamMap, WsAPITopicResponseMap, WSAPIWsKey, WsAPIWsKeyTopicMap } from './types/websockets/wsAPI.js';
 export declare const WS_LOGGER_CATEGORY: {
     category: string;
 };
+export interface WSAPIRequestFlags {
+    /** If true, will skip auth requirement for WS API connection */
+    authIsOptional?: boolean | undefined;
+}
 /**
  * WS topics are always a string for gate. Some exchanges use complex objects
  */
@@ -18,6 +22,13 @@ export declare class WebsocketClient extends BaseWebsocketClient<WsKey> {
      * Returns array of promises that individually resolve when each connection is successfully opened.
      */
     connectAll(): Promise<WSConnectedResult | undefined>[];
+    /**
+     * Ensures the WS API connection is active and ready.
+     *
+     * You do not need to call this, but if you call this before making any WS API requests,
+     * it can accelerate the first request (by preparing the connection in advance).
+     */
+    connectWSAPI(wsKey: WSAPIWsKey, skipAuth?: boolean): Promise<unknown>;
     /**
      * Request subscription to one or more topics. Pass topics as either an array of strings, or array of objects (if the topic has parameters).
      * Objects should be formatted as {topic: string, params: object}.
@@ -59,7 +70,7 @@ export declare class WebsocketClient extends BaseWebsocketClient<WsKey> {
      * @param params - Any request parameters for the payload (contents of req_param in the docs). Signature generation is automatic, only send parameters such as order ID as per the docs.
      * @returns Promise - tries to resolve with async WS API response. Rejects if disconnected or exception is seen in async WS API response
      */
-    sendWSAPIRequest<TWSKey extends keyof WsAPIWsKeyTopicMap, TWSChannel extends WsAPIWsKeyTopicMap[TWSKey] = WsAPIWsKeyTopicMap[TWSKey], TWSParams extends WsAPITopicRequestParamMap[TWSChannel] = WsAPITopicRequestParamMap[TWSChannel], TWSAPIResponse extends WsAPITopicResponseMap[TWSChannel] | object = WsAPITopicResponseMap[TWSChannel]>(wsKey: TWSKey, channel: TWSChannel, ...params: TWSParams extends undefined ? [] : [TWSParams]): Promise<TWSAPIResponse>;
+    sendWSAPIRequest<TWSKey extends keyof WsAPIWsKeyTopicMap, TWSChannel extends WsAPIWsKeyTopicMap[TWSKey] = WsAPIWsKeyTopicMap[TWSKey], TWSParams extends WsAPITopicRequestParamMap[TWSChannel] = WsAPITopicRequestParamMap[TWSChannel], TWSAPIResponse extends WsAPITopicResponseMap[TWSChannel] | object = WsAPITopicResponseMap[TWSChannel]>(wsKey: TWSKey, channel: TWSChannel, params?: TWSParams extends void | never ? undefined : TWSParams, requestFlags?: WSAPIRequestFlags): Promise<TWSAPIResponse>;
     /**
      *
      * Internal methods - not intended for public use
@@ -86,6 +97,7 @@ export declare class WebsocketClient extends BaseWebsocketClient<WsKey> {
      * Not in use for gate.io
      */
     protected getPrivateWSKeys(): WsKey[];
+    protected isAuthOnConnectWsKey(wsKey: WsKey): boolean;
     /** Force subscription requests to be sent in smaller batches, if a number is returned */
     protected getMaxTopicsPerSubscribeEvent(_wsKey: WsKey): number | null;
     /**