Merge pull request #613 from jinusean/wsapi-algo

feat: add WebSocket API algo orders & type definitions

Author: tiagosiebler

examples/WebSockets/ws-api-client.ts

@@ -689,6 +689,33 @@ async function main() {
   } catch (e) {
     console.log('getFuturesAccountStatus error: ', e);
   }
+
+  try {
+    const response = await wsClient.submitNewFuturesAlgoOrder({
+      algoType: 'CONDITIONAL',
+      symbol: 'BTCUSDT',
+      side: 'BUY',
+      type: 'STOP',
+      timeInForce: 'GTC',
+      price: '100000.10000000',
+      stopPrice: '100000.10000000',
+      quantity: '0.00847000',
+      timestamp: Date.now(),
+    });
+    console.log('submitNewFuturesAlgoOrder response: ', response);
+  } catch (e) {
+    console.log('submitNewFuturesAlgoOrder error: ', e);
+  }
+
+  try {
+    const response = await wsClient.cancelFuturesAlgoOrder({
+      algoid: 1028312903,
+      timestamp: Date.now(),
+    });
+    console.log('cancelFuturesAlgoOrder response: ', response);
+  } catch (e) {
+    console.log('cancelFuturesAlgoOrder error: ', e);
+  }
 }
 
 // Start executing the example workflow

examples/apidoc/WebsocketAPIClient/cancelFuturesAlgoOrder.js

@@ -0,0 +1,26 @@
+const { WebsocketAPIClient } = require('binance');
+
+// This example shows how to call this Binance WebSocket API endpoint with either node.js, javascript (js) or typescript (ts) with the npm module "binance" for Binance exchange
+// This Binance API SDK is available on npm via "npm install binance"
+// WS API ENDPOINT: order.cancel
+// METHOD: WebSocket API
+// PUBLIC: YES
+
+// Create a WebSocket API client instance
+const client = new WebsocketAPIClient({
+  api_key: 'insert_api_key_here',
+  api_secret: 'insert_api_secret_here',
+});
+
+// The WebSocket connection is established automatically when needed
+// You can use the client to make requests immediately
+
+// Example use of the cancelFuturesOrder method
+client.cancelFuturesAlgoOrder(params)
+  .then((response) => {
+    console.log(response);
+  })
+  .catch((error) => {
+    console.error(error);
+  });
+

examples/apidoc/WebsocketAPIClient/submitNewFuturesAlgoOrder.js

@@ -0,0 +1,26 @@
+const { WebsocketAPIClient } = require('binance');
+
+// This example shows how to call this Binance WebSocket API endpoint with either node.js, javascript (js) or typescript (ts) with the npm module "binance" for Binance exchange
+// This Binance API SDK is available on npm via "npm install binance"
+// WS API ENDPOINT: order.place
+// METHOD: WebSocket API
+// PUBLIC: YES
+
+// Create a WebSocket API client instance
+const client = new WebsocketAPIClient({
+  api_key: 'insert_api_key_here',
+  api_secret: 'insert_api_secret_here',
+});
+
+// The WebSocket connection is established automatically when needed
+// You can use the client to make requests immediately
+
+// Example use of the submitNewFuturesOrder method
+client.submitNewFuturesAlgoOrder(params)
+  .then((response) => {
+    console.log(response);
+  })
+  .catch((error) => {
+    console.error(error);
+  });
+

src/index.ts

@@ -7,6 +7,7 @@ export * from './types/portfolio-margin';
 export * from './types/shared';
 export * from './types/spot';
 export * from './types/websockets/ws-api';
+export * from './types/websockets/ws-api-requests';
 export * from './types/websockets/ws-api-responses';
 export * from './types/websockets/ws-events-formatted';
 export * from './types/websockets/ws-events-raw';

src/types/futures.ts

@@ -976,19 +976,31 @@ export interface FuturesConvertOrderStatus {
 
 export type FuturesAlgoOrderType = 'CONDITIONAL';
 
+export type FuturesAlgoConditionalOrderTypes =
+  | 'STOP_MARKET'
+  | 'TAKE_PROFIT_MARKET'
+  | 'STOP'
+  | 'TAKE_PROFIT'
+  | 'TRAILING_STOP_MARKET';
+
+/**
+ * Ref: https://developers.binance.com/docs/derivatives/usds-margined-futures/user-data-streams/Event-Algo-Order-Update
+ */
 export type FuturesAlgoOrderStatus =
   | 'NEW'
   | 'CANCELED'
+  | 'TRIGGERING'
   | 'TRIGGERED'
-  | 'EXPIRED'
-  | 'FINISHED';
+  | 'FINISHED'
+  | 'REJECTED'
+  | 'EXPIRED';
 
 export interface FuturesNewAlgoOrderParams {
   algoType: FuturesAlgoOrderType;
   symbol: string;
   side: OrderSide;
   positionSide?: PositionSide;
-  type: FuturesOrderType;
+  type: FuturesAlgoConditionalOrderTypes;
   timeInForce?: OrderTimeInForce;
   quantity?: numberInString;
   price?: numberInString;
@@ -1009,7 +1021,7 @@ export interface FuturesAlgoOrderResponse {
   algoId: number;
   clientAlgoId: string;
   algoType: FuturesAlgoOrderType;
-  orderType: FuturesOrderType;
+  orderType: FuturesAlgoConditionalOrderTypes;
   symbol: string;
   side: OrderSide;
   positionSide: PositionSide;

src/types/shared.ts

@@ -62,8 +62,7 @@ export type OrderIdProperty =
   | 'workingClientOrderId'
   | 'pendingAboveClientOrderId'
   | 'pendingBelowClientOrderId'
-  | 'pendingClientOrderId'
-  | 'clientAlgoId';
+  | 'pendingClientOrderId';
 
 export type OrderSide = 'BUY' | 'SELL';
 

src/types/websockets/ws-api-requests.ts

@@ -1,4 +1,6 @@
 import {
+  FuturesAlgoConditionalOrderTypes,
+  FuturesAlgoOrderType,
   FuturesOrderType,
   PositionSide,
   PriceMatchMode,
@@ -9,6 +11,7 @@ import {
   BooleanStringCapitalised,
   KlineInterval,
   numberInString,
+  OrderResponseType,
   OrderSide,
   OrderTimeInForce,
   OrderType,
@@ -671,3 +674,41 @@ export interface WSAPIAccountInformationRequest {
 export interface WSAPIAccountCommissionWSAPIRequest {
   symbol: string;
 }
+
+/**
+ * Ref: https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/websocket-api
+ */
+export interface WSAPINewFuturesAlgoOrderRequest<numberType = numberInString> {
+  algoType: FuturesAlgoOrderType;
+  symbol: string;
+  side: OrderSide;
+  positionSide?: PositionSide;
+  type: FuturesAlgoConditionalOrderTypes;
+  timeInForce?: OrderTimeInForce;
+  quantity?: numberType;
+  reduceOnly?: BooleanString;
+  price?: numberInString;
+  newClientOrderId?: string;
+  stopPrice?: numberInString;
+  closePosition?: BooleanString;
+  activationPrice?: numberInString;
+  callbackRate?: numberInString;
+  workingType?: WorkingType;
+  priceProtect?: BooleanStringCapitalised;
+  newOrderRespType?: OrderResponseType;
+  priceMatch?: PriceMatchMode;
+  selfTradePreventionMode?: SelfTradePreventionMode;
+  goodTillDate?: number; // Mandatory when timeInForce is GTD
+  recvWindow?: number;
+  timestamp: number;
+}
+
+/**
+ * Ref: https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/websocket-api/Cancel-Algo-Order
+ */
+export interface WSAPIFuturesAlgoOrderCancelRequest {
+  algoid?: number;
+  clientalgoid?: string;
+  recvWindow?: number;
+  timestamp: number;
+}

src/types/websockets/ws-api-responses.ts

@@ -1,4 +1,17 @@
-import { numberInString } from '../shared';
+import type {
+  FuturesAlgoConditionalOrderTypes,
+  FuturesAlgoOrderStatus,
+  FuturesAlgoOrderType,
+  PositionSide,
+  PriceMatchMode,
+  WorkingType,
+} from '../futures.js';
+import {
+  numberInString,
+  OrderSide,
+  OrderTimeInForce,
+  SelfTradePreventionMode,
+} from '../shared';
 import { OrderResponse } from '../spot';
 
 /**
@@ -541,6 +554,37 @@ export interface WSAPIFuturesPositionV2 {
   updateTime: number;
 }
 
+export interface WSAPIFuturesAlgoOrder {
+  algoId: number;
+  clientAlgoId: string;
+  algoType: FuturesAlgoOrderType;
+  orderType: FuturesAlgoConditionalOrderTypes;
+  symbol: string;
+  side: OrderSide;
+  positionSide: PositionSide;
+  timeInForce: OrderTimeInForce;
+  quantity: numberInString;
+  algoStatus: FuturesAlgoOrderStatus;
+  triggerPrice: numberInString;
+  price: numberInString;
+  icebergQuantity: numberInString | null;
+  selfTradePreventionMode: SelfTradePreventionMode;
+  workingType: WorkingType;
+  priceMatch: PriceMatchMode;
+  closePosition: boolean;
+  priceProtect: boolean;
+  reduceOnly: boolean;
+  createTime: number;
+  updateTime: number;
+  triggerTime: number;
+  goodTillDate: number;
+}
+
+export interface WSAPIFuturesAlgoOrderCancelResponse extends ErrorResponse {
+  algoId: number;
+  clientAlgoId: string;
+}
+
 /**
  * Futures account response types
  */

src/types/websockets/ws-api.ts

@@ -8,6 +8,7 @@ import {
   WSAPIAllOrdersRequest,
   WSAPIAvgPriceRequest,
   WSAPIExchangeInfoRequest,
+  WSAPIFuturesAlgoOrderCancelRequest,
   WSAPIFuturesOrderBookRequest,
   WSAPIFuturesOrderCancelRequest,
   WSAPIFuturesOrderModifyRequest,
@@ -18,6 +19,7 @@ import {
   WSAPIMyAllocationsRequest,
   WSAPIMyPreventedMatchesRequest,
   WSAPIMyTradesRequest,
+  WSAPINewFuturesAlgoOrderRequest,
   WSAPINewFuturesOrderRequest,
   WSAPINewSpotOrderRequest,
   WSAPIOpenOrdersCancelAllRequest,
@@ -59,6 +61,8 @@ import {
   WSAPIFullTicker,
   WSAPIFuturesAccountBalanceItem,
   WSAPIFuturesAccountStatus,
+  WSAPIFuturesAlgoOrder,
+  WSAPIFuturesAlgoOrderCancelResponse,
   WSAPIFuturesBookTicker,
   WSAPIFuturesOrder,
   WSAPIFuturesOrderBook,
@@ -148,6 +152,8 @@ export const WS_API_Operations = [
   'order.modify',
   'openOrders.status',
   'openOrders.cancelAll',
+  'algoOrder.place',
+  'algoOrder.cancel',
   // Order list commands
   'orderList.place',
   'orderList.place.oco',
@@ -370,12 +376,14 @@ export interface WsAPITopicRequestParamMap<TWSKey = WsKey> {
     ? WSAPIFuturesOrderCancelRequest
     : WSAPIOrderCancelRequest;
   'order.modify': WSAPIFuturesOrderModifyRequest; // order.modify only futures
-
   'order.cancelReplace': WSAPIOrderCancelReplaceRequest;
   'order.amend.keepPriority': WSAPIOrderAmendKeepPriorityRequest;
   'openOrders.status': WSAPIOpenOrdersStatusRequest;
   'openOrders.cancelAll': WSAPIOpenOrdersCancelAllRequest;
 
+  'algoOrder.place': WSAPINewFuturesAlgoOrderRequest;
+  'algoOrder.cancel': WSAPIFuturesAlgoOrderCancelRequest;
+
   /**
    * Order list requests & parameters:
    */
@@ -527,7 +535,8 @@ export interface WsAPIOperationResponseMap {
   'openOrders.cancelAll': WSAPIResponse<
     (WSAPIOrderCancel | WSAPIOrderListCancelResponse)[]
   >;
-
+  'algoOrder.place': WSAPIResponse<WSAPIFuturesAlgoOrder>;
+  'algoOrder.cancel': WSAPIResponse<WSAPIFuturesAlgoOrderCancelResponse>;
   /**
    * Order list responses
    */

src/types/websockets/ws-events-formatted.ts

@@ -1,8 +1,12 @@
 import {
+  FuturesAlgoConditionalOrderTypes,
+  FuturesAlgoOrderStatus,
+  FuturesAlgoOrderType,
   FuturesContractType,
   FuturesOrderType,
   MarginType,
   PositionSide,
+  PriceMatchMode,
   WorkingType,
 } from '../futures';
 import {
@@ -523,28 +527,28 @@ export interface WsMessageFuturesUserDataAlgoUpdateFormatted
   eventTime: number;
   transactionTime: number;
   algoOrder: {
-    algoId: number;
     clientAlgoId: string;
-    side: string;
-    positionSide: string;
-    algoStatus: string;
-    algoType: string;
-    orderType: string;
-    timeInForce: string;
-    workingType: string;
-    quantity: string;
-    activationPrice: string;
-    triggerPrice: string;
-    price: string;
-    callbackRate: string;
-    priceMatch: string;
+    algoId: number;
+    algoType: FuturesAlgoOrderType;
+    orderType: FuturesAlgoConditionalOrderTypes;
+    symbol: string;
+    side: OrderSide;
+    positionSide: PositionSide;
+    timeInForce: OrderTimeInForce;
+    quantity: numberInString;
+    algoStatus: FuturesAlgoOrderStatus;
+    orderId: string;
+    averagePrice: numberInString;
+    executedQty: numberInString;
+    actualOrderType: numberInString; // TODO unsure if it's FuturesOrderType
+    triggerPrice: numberInString;
+    price: numberInString;
+    selfTradePreventionMode: SelfTradePreventionMode;
+    workingType: WorkingType;
+    priceMatch: PriceMatchMode;
     closePosition: boolean;
     priceProtect: boolean;
     reduceOnly: boolean;
-    isOrderOnBook: boolean;
-    selfTradePreventionMode: string;
-    createTime: number;
-    updateTime: number;
     triggerTime: number;
     goodTillDate: number;
   };
@@ -561,13 +565,13 @@ export type WsMessageFuturesUserDataEventFormatted =
   | WsMessageFuturesUserDataListenKeyExpiredFormatted
   | WsMessageFuturesUserDataMarginCallFormatted
   | WsMessageFuturesUserDataTradeUpdateEventFormatted
+  | WsMessageFuturesUserDataAlgoUpdateFormatted
   | WsMessageFuturesUserDataAccountConfigUpdateEventFormatted
   | WsMessageFuturesUserDataCondOrderTriggerRejectEventFormatted
   | WsMessageFuturesUserDataTradeLiteEventFormatted
   | WsMessageFuturesUserDataStrategyUpdateFormatted
   | WsMessageFuturesUserDataGridUpdateFormatted
-  | WsMessageFuturesUserDataContractInfoFormatted
-  | WsMessageFuturesUserDataAlgoUpdateFormatted;
+  | WsMessageFuturesUserDataContractInfoFormatted;
 
 export type WsUserDataEvents =
   | WsMessageSpotUserDataEventFormatted