feat: opt-in X-Gate-Size-Decimal for futures and delivery (v1.7.0)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gateio-api",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "Complete & Robust Node.js SDK for Gate.com's REST APIs, WebSockets & WebSocket APIs, with TypeScript declarations.",
   "scripts": {
     "clean": "rm -rf dist/*",

src/WebsocketClient.ts

@@ -1,6 +1,11 @@
 import { BaseWebsocketClient, EmittableEvent } from './lib/BaseWSClient.js';
 import { neverGuard } from './lib/misc-util.js';
-import { CHANNEL_ID, MessageEventLike } from './lib/requestUtils.js';
+import {
+  CHANNEL_ID,
+  getFuturesSizeDecimalHeaders,
+  isFuturesMarketWsKey,
+  MessageEventLike,
+} from './lib/requestUtils.js';
 import {
   SignAlgorithm,
   SignEncodeMethod,
@@ -44,6 +49,26 @@ export interface WSAPIRequestFlags {
 export type WsTopic = string;
 
 export class WebsocketClient extends BaseWebsocketClient<WsKey> {
+  protected getWsConnectRequestHeaders(wsKey: WsKey): Record<string, string> {
+    if (!isFuturesMarketWsKey(wsKey)) {
+      return {};
+    }
+    return getFuturesSizeDecimalHeaders(this.options.futuresSizeDecimal);
+  }
+
+  private getFuturesWsApiReqHeader(): {
+    'X-Gate-Channel-Id': typeof CHANNEL_ID;
+    'X-Gate-Size-Decimal'?: '1';
+  } {
+    return {
+      'X-Gate-Channel-Id': CHANNEL_ID,
+      ...getFuturesSizeDecimalHeaders(this.options.futuresSizeDecimal),
+    } as {
+      'X-Gate-Channel-Id': typeof CHANNEL_ID;
+      'X-Gate-Size-Decimal'?: '1';
+    };
+  }
+
   /**
    * Request connection of all dependent (public & private) websockets, instead of waiting for automatic connection by library.
    *
@@ -197,9 +222,11 @@ export class WebsocketClient extends BaseWebsocketClient<WsKey> {
       event: 'api',
       payload: {
         req_id: this.getNewRequestId(),
-        req_header: {
-          'X-Gate-Channel-Id': CHANNEL_ID,
-        },
+        req_header: isFuturesMarketWsKey(wsKey)
+          ? this.getFuturesWsApiReqHeader()
+          : {
+              'X-Gate-Channel-Id': CHANNEL_ID,
+            },
         api_key: this.options.apiKey,
         req_param: params ? params : '',
         timestamp: `${timeInSeconds}`,
@@ -802,9 +829,11 @@ export class WebsocketClient extends BaseWebsocketClient<WsKey> {
       event: 'api',
       payload: {
         req_id: this.getNewRequestId(),
-        req_header: {
-          'X-Gate-Channel-Id': CHANNEL_ID,
-        },
+        req_header: isFuturesMarketWsKey(wsKey)
+          ? this.getFuturesWsApiReqHeader()
+          : {
+              'X-Gate-Channel-Id': CHANNEL_ID,
+            },
         api_key: this.options.apiKey,
         req_param: '',
         timestamp: `${timeInSeconds}`,
@@ -844,6 +873,7 @@ export class WebsocketClient extends BaseWebsocketClient<WsKey> {
       payload: {
         ...requestEvent.payload,
         req_header: {
+          ...requestEvent.payload.req_header,
           'X-Gate-Channel-Id': CHANNEL_ID,
         },
         signature: await this.signMessage(

src/lib/BaseRestClient.ts

@@ -6,7 +6,9 @@ import https from 'https';
 import { neverGuard } from './misc-util.js';
 import {
   CHANNEL_ID,
+  getFuturesSizeDecimalHeaders,
   getRestBaseUrl,
+  isFuturesMarketRestEndpoint,
   RestClientOptions,
   serializeParams,
 } from './requestUtils.js';
@@ -517,13 +519,18 @@ export abstract class BaseRestClient {
     params?: ParamsInQueryBodyOrHeader,
     isPublicApi?: boolean,
   ): Promise<AxiosRequestConfig> {
+    const futuresSizeDecimalHeaders = isFuturesMarketRestEndpoint(endpoint)
+      ? getFuturesSizeDecimalHeaders(this.options.futuresSizeDecimal)
+      : {};
+
     const options: AxiosRequestConfig = {
       ...this.globalRequestOptions,
       url: url,
       method: method,
       headers: {
         ...params?.headers,
         ...this.globalRequestOptions.headers,
+        ...futuresSizeDecimalHeaders,
       },
     };
 

src/lib/BaseWSClient.ts

@@ -173,6 +173,14 @@
 
   protected abstract getWsUrl(wsKey: TWSKey): string;
 
+  /** Optional headers for the WebSocket HTTP upgrade request (e.g. Gate size-decimal mode). */
+  protected getWsConnectRequestHeaders(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _wsKey: TWSKey,
+  ): Record<string, string> {
+    return {};
+  }
+
   protected abstract getMaxTopicsPerSubscribeEvent(
     wsKey: TWSKey,
   ): number | null;
@@ -446,8 +454,24 @@
       wsKey,
     });
 
-    const { protocols = [], ...wsOptions } = this.options.wsOptions || {};
-    const ws = new WebSocket(url, protocols, wsOptions);
+    const { protocols = [], headers: wsOptionHeaders, ...wsOptions } =
+      this.options.wsOptions || {};
+    const normalizedWsOptionHeaders =
+      typeof wsOptionHeaders === 'object' &&
+      wsOptionHeaders !== null &&
+      !Array.isArray(wsOptionHeaders)
+        ? (wsOptionHeaders as Record<string, string>)
+        : {};
+    const connectHeaders: Record<string, string> = {
+      ...normalizedWsOptionHeaders,
+      ...this.getWsConnectRequestHeaders(wsKey),
+    };
+    const ws = new WebSocket(url, protocols, {
+      ...wsOptions,
+      ...(Object.keys(connectHeaders).length
+        ? { headers: connectHeaders }
+        : {}),
+    });
 
     ws.onopen = (event: any) => this.onWsOpen(event, wsKey, url, ws);
     ws.onmessage = (event: any) => this.onWsMessage(event, wsKey, ws);

src/lib/requestUtils.ts

@@ -49,6 +49,37 @@ export interface RestClientOptions {
    * Look in the examples folder for a demonstration on using node's createHmac instead.
    */
   customSignMessageFn?: (message: string, secret: string) => Promise<string>;
+
+  /**
+   * When true, sends `X-Gate-Size-Decimal: 1` on futures/delivery REST and WebSocket traffic so size-related fields are returned as decimal strings instead of integers rounded down.
+   * @default false
+   */
+  futuresSizeDecimal?: boolean;
+}
+
+export const FUTURES_SIZE_DECIMAL_HEADER = 'X-Gate-Size-Decimal';
+
+export function isFuturesMarketRestEndpoint(endpoint: string): boolean {
+  return /^\/futures\//.test(endpoint) || /^\/delivery\//.test(endpoint);
+}
+
+export function isFuturesMarketWsKey(wsKey: string): boolean {
+  return (
+    wsKey === 'perpFuturesUSDTV4' ||
+    wsKey === 'perpFuturesBTCV4' ||
+    wsKey === 'deliveryFuturesUSDTV4' ||
+    wsKey === 'deliveryFuturesBTCV4'
+  );
+}
+
+/** Request headers for REST or WS when `futuresSizeDecimal` is enabled. */
+export function getFuturesSizeDecimalHeaders(
+  futuresSizeDecimal?: boolean,
+): Record<string, string> {
+  if (!futuresSizeDecimal) {
+    return {};
+  }
+  return { [FUTURES_SIZE_DECIMAL_HEADER]: '1' };
 }
 
 export function serializeParams<T extends Record<string, any> | undefined = {}>(

src/types/request/delivery.ts

@@ -1,3 +1,5 @@
+import { FuturesContractSize } from '../shared.js';
+
 /**==========================================================================================================================
  * DELIVERY
  * ==========================================================================================================================
@@ -65,8 +67,10 @@ export interface GetDeliveryBookReq {
 export interface SubmitDeliveryFuturesOrderReq {
   settle: 'usdt';
   contract: string;
-  size: number;
-  iceberg?: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size: FuturesContractSize;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  iceberg?: FuturesContractSize;
   price?: string;
   close?: boolean;
   reduce_only?: boolean;

src/types/request/futures.ts

@@ -1,3 +1,5 @@
+import { FuturesContractSize } from '../shared.js';
+
 /**==========================================================================================================================
  * FUTURES
  * ==========================================================================================================================
@@ -124,8 +126,10 @@ export interface SubmitFuturesOrderReq {
   xGateExptime?: number;
   settle: FuturesSettle;
   contract: string;
-  size: number;
-  iceberg?: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size: FuturesContractSize;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  iceberg?: FuturesContractSize;
   price?: string;
   close?: boolean;
   reduce_only?: boolean;
@@ -169,7 +173,8 @@ export interface UpdateFuturesOrderReq {
   xGateExptime?: number;
   settle: FuturesSettle;
   order_id: string;
-  size?: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size?: FuturesContractSize;
   price?: string;
   amend_text?: string;
 }
@@ -214,7 +219,8 @@ export interface GetFuturesLiquidationHistoryReq {
 export interface SubmitFuturesTriggeredOrderReq {
   initial: {
     contract: string;
-    size?: number;
+    /** String when `futuresSizeDecimal` is enabled on the client. */
+    size?: FuturesContractSize;
     /** Decimal contract size; if both `size` and `amount` are set, `amount` takes precedence */
     amount?: string;
     price: string; // Required: Order price. Set to 0 to use market price
@@ -255,7 +261,8 @@ export interface GetFuturesAutoOrdersReq {
 export interface BatchAmendOrderReq {
   order_id?: number; // Order id, order_id and text must contain at least one
   text?: string; // User-defined order text, at least one of order_id and text must be passed
-  size?: number; // The new order size, including the executed order size
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size?: FuturesContractSize; // The new order size, including the executed order size
   price?: string; // New order price
   amend_text?: string; // Custom info during amending order
 }
@@ -280,7 +287,8 @@ export interface UpdateFuturesPriceTriggeredOrderReq {
   settle: FuturesSettle;
   order_id: number | string;
   contract?: string;
-  size?: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size?: FuturesContractSize;
   /** Same semantics as `size` (decimal contract size) */
   amount?: string;
   price?: string;

src/types/response/delivery.ts

@@ -1,3 +1,5 @@
+import { FuturesContractSize } from '../shared.js';
+
 /**==========================================================================================================================
  * DELIVERY
  * ==========================================================================================================================
@@ -7,23 +9,25 @@ export interface DeliveryOrderBook {
   id?: number;
   current: number;
   update: number;
-  asks: { p: string; s: number }[];
-  bids: { p: string; s: number }[];
+  asks: { p: string; s: FuturesContractSize }[];
+  bids: { p: string; s: FuturesContractSize }[];
 }
 
 export interface DeliveryTrade {
   id: number;
   create_time: number;
   create_time_ms: number;
   contract: string;
-  size: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size: FuturesContractSize;
   price: string;
   is_internal?: boolean; // Deprecated
 }
 
 export interface DeliveryCandle {
   t: number;
-  v?: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  v?: FuturesContractSize;
   c: string;
   h: string;
   l: string;
@@ -116,7 +120,8 @@ export interface DeliveryTradingHistoryRecord {
   create_time: number;
   contract: string;
   order_id: string;
-  size: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size: FuturesContractSize;
   price: string;
   role: 'taker' | 'maker';
   text: string;
@@ -143,22 +148,25 @@ export interface DeliveryLiquidationHistoryRecord {
   time: number;
   contract: string;
   leverage?: string;
-  size: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size: FuturesContractSize;
   margin?: string;
   entry_price?: string;
   liq_price?: string;
   mark_price?: string;
   order_id?: number;
   order_price: string;
   fill_price: string;
-  left: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  left: FuturesContractSize;
 }
 
 export interface DeliverySettlementHistoryRecord {
   time: number;
   contract: string;
   leverage: string;
-  size: number;
+  /** String when `futuresSizeDecimal` is enabled on the client. */
+  size: FuturesContractSize;
   margin: string;
   entry_price: string;
   settle_price: string;