Expand types, add type guards, flesh out futures position example

examples/rest-trade-futures.ts

@@ -1,7 +1,19 @@
-import { FuturesClient, WebsocketClient } from '../src/index';
+import {
+  FuturesClient,
+  isWsFuturesAccountSnapshotEvent,
+  isWsFuturesPositionsSnapshotEvent,
+  NewFuturesOrder,
+  WebsocketClient,
+} from '../src';
 
 // or
-// import { SpotClient } from 'bitget-api';
+// import {
+//   FuturesClient,
+//   isWsFuturesAccountSnapshotEvent,
+//   isWsFuturesPositionsSnapshotEvent,
+//   NewFuturesOrder,
+//   WebsocketClient,
+// } from 'bitget-api';
 
 // read from environmental variables
 const API_KEY = process.env.API_KEY_COM;
@@ -39,11 +51,39 @@ function roundDown(value, decimals) {
   );
 }
 
-/** This is a simple script wrapped in a immediately invoked function expression, designed to check for any available BTC balance and immediately sell the full amount for USDT */
+/** WS event handler that uses type guards to narrow down event type */
+async function handleWsUpdate(event) {
+  if (isWsFuturesAccountSnapshotEvent(event)) {
+    console.log(new Date(), 'ws update (account balance):', event);
+    return;
+  }
+
+  if (isWsFuturesPositionsSnapshotEvent(event)) {
+    console.log(new Date(), 'ws update (positions):', event);
+    return;
+  }
+
+  logWSEvent('update (unhandled)', event);
+}
+
+/**
+ * This is a simple script wrapped in a immediately invoked function expression (to execute the below workflow immediately).
+ *
+ * It is designed to:
+ * - open a private websocket channel to log account events
+ * - check for any available USDT balance in the futures account
+ * - immediately open a minimum sized long position on BTCUSDT
+ * - check active positions
+ * - immediately send closing orders for any active futures positions
+ * - check positions again
+ *
+ * The corresponding UI for this is at https://www.bitget.com/en/mix/usdt/BTCUSDT_UMCBL
+ */
 (async () => {
   try {
     // Add event listeners to log websocket events on account
-    wsClient.on('update', (data) => logWSEvent('update', data));
+    wsClient.on('update', (data) => handleWsUpdate(data));
+
     wsClient.on('open', (data) => logWSEvent('open', data));
     wsClient.on('response', (data) => logWSEvent('response', data));
     wsClient.on('reconnect', (data) => logWSEvent('reconnect', data));
@@ -79,13 +119,14 @@ function roundDown(value, decimals) {
     const bitcoinUSDFuturesRule = symbolRulesResult.data.find(
       (row) => row.symbol === symbol
     );
+
     console.log('symbol rules: ', bitcoinUSDFuturesRule);
     if (!bitcoinUSDFuturesRule) {
       console.error('Failed to get trading rules for ' + symbol);
       return;
     }
 
-    const order = {
+    const order: NewFuturesOrder = {
       marginCoin,
       orderType: 'market',
       side: 'open_long',
@@ -98,6 +139,36 @@ function roundDown(value, decimals) {
     const result = await client.submitOrder(order);
 
     console.log('order result: ', result);
+
+    const positionsResult = await client.getPositions('umcbl');
+    const positionsToClose = positionsResult.data.filter(
+      (pos) => pos.total !== '0'
+    );
+
+    console.log('open positions to close: ', positionsToClose);
+
+    // Loop through any active positions and send a closing market order on each position
+    for (const position of positionsToClose) {
+      const closingSide =
+        position.holdSide === 'long' ? 'close_long' : 'close_short';
+      const closingOrder: NewFuturesOrder = {
+        marginCoin: position.marginCoin,
+        orderType: 'market',
+        side: closingSide,
+        size: position.available,
+        symbol: position.symbol,
+      };
+
+      console.log('closing position with market order: ', closingOrder);
+
+      const result = await client.submitOrder(closingOrder);
+      console.log('position closing order result: ', result);
+    }
+
+    console.log(
+      'positions after closing all: ',
+      await client.getPositions('umcbl')
+    );
   } catch (e) {
     console.error('request failed: ', e);
   }

src/futures-client.ts

@@ -17,6 +17,8 @@ import {
   NewFuturesPlanStopOrder,
   FuturesAccount,
   FuturesSymbolRule,
+  FuturesMarginMode,
+  FuturesPosition,
 } from './types';
 import { REST_CLIENT_TYPE_ENUM } from './util';
 import BaseRestClient from './util/BaseRestClient';
@@ -198,7 +200,7 @@ export class FuturesClient extends BaseRestClient {
   setMarginMode(
     symbol: string,
     marginCoin: string,
-    marginMode: 'fixed' | 'crossed'
+    marginMode: FuturesMarginMode
   ): Promise<APIResponse<any>> {
     return this.postPrivate('/api/mix/v1/account/setMarginMode', {
       symbol,
@@ -208,7 +210,10 @@ export class FuturesClient extends BaseRestClient {
   }
 
   /** Get Symbol Position */
-  getPosition(symbol: string, marginCoin?: string): Promise<APIResponse<any>> {
+  getPosition(
+    symbol: string,
+    marginCoin?: string
+  ): Promise<APIResponse<FuturesPosition[]>> {
     return this.getPrivate('/api/mix/v1/position/singlePosition', {
       symbol,
       marginCoin,
@@ -219,7 +224,7 @@ export class FuturesClient extends BaseRestClient {
   getPositions(
     productType: FuturesProductType,
     marginCoin?: string
-  ): Promise<APIResponse<any>> {
+  ): Promise<APIResponse<FuturesPosition[]>> {
     return this.getPrivate('/api/mix/v1/position/allPosition', {
       productType,
       marginCoin,

src/types/request/futures.ts

@@ -8,6 +8,12 @@ export type FuturesProductType =
   | 'sdmcbl'
   | 'scmcbl';
 
+export type FuturesHoldSide = 'long' | 'short';
+
+export type FuturesMarginMode = 'fixed' | 'crossed';
+
+export type FuturesHoldMode = 'double_hold' | 'single_hold';
+
 export interface FuturesAccountBillRequest {
   symbol: string;
   marginCoin: string;
@@ -95,7 +101,6 @@ export interface ModifyFuturesPlanOrderTPSL {
 }
 
 export type FuturesPlanType = 'profit_plan' | 'loss_plan';
-export type FuturesHoldSide = 'long' | 'short';
 
 export interface NewFuturesPlanStopOrder {
   symbol: string;

src/types/response/futures.ts

@@ -1,3 +1,9 @@
+import {
+  FuturesHoldMode,
+  FuturesHoldSide,
+  FuturesMarginMode,
+} from '../request';
+
 export interface FuturesAccount {
   marginCoin: string;
   locked: number;
@@ -33,3 +39,24 @@ export interface FuturesSymbolRule {
   takerFeeRate: string;
   volumePlace: string;
 }
+
+export interface FuturesPosition {
+  marginCoin: string;
+  symbol: string;
+  holdSide: FuturesHoldSide;
+  openDelegateCount: string;
+  margin: string;
+  available: string;
+  locked: string;
+  total: string;
+  leverage: number;
+  achievedProfits: string;
+  averageOpenPrice: string;
+  marginMode: FuturesMarginMode;
+  holdMode: FuturesHoldMode;
+  unrealizedPL: string;
+  liquidationPrice: string;
+  keepMarginRate: string;
+  marketPrice: string;
+  cTime: string;
+}

src/types/websockets/client.ts

@@ -1,4 +1,4 @@
-import { WS_KEY_MAP } from '../util';
+import { WS_KEY_MAP } from '../../util';
 
 export type WsPublicSpotTopic =
   | 'ticker'

src/types/websockets/events.ts

@@ -0,0 +1,82 @@
+export interface WsBaseEvent<TAction = 'snapshot' | string, TData = unknown> {
+  action: TAction;
+  arg: unknown;
+  data: TData[];
+}
+
+export interface WsSnapshotChannelEvent extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: string;
+    channel: string;
+    instId: string;
+  };
+}
+
+export interface WsSnapshotAccountEvent extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: string;
+    channel: 'account';
+    instId: string;
+  };
+}
+
+export interface WsSnapshotPositionsEvent extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: string;
+    channel: 'positions';
+    instId: string;
+  };
+}
+
+export interface WsAccountSnapshotUMCBL extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: 'umcbl';
+    channel: 'account';
+    instId: string;
+  };
+  data: WsAccountSnapshotDataUMCBL[];
+}
+
+export interface WsAccountSnapshotDataUMCBL {
+  marginCoin: string;
+  locked: string;
+  available: string;
+  maxOpenPosAvailable: string;
+  maxTransferOut: string;
+  equity: string;
+  usdtEquity: string;
+}
+
+export interface WSPositionSnapshotUMCBL extends WsBaseEvent<'snapshot'> {
+  arg: {
+    instType: 'umcbl';
+    channel: 'positions';
+    instId: string;
+  };
+  data: WsPositionSnapshotDataUMCBL[];
+}
+
+export interface WsPositionSnapshotDataUMCBL {
+  posId: string;
+  instId: string;
+  instName: string;
+  marginCoin: string;
+  margin: string;
+  marginMode: string;
+  holdSide: string;
+  holdMode: string;
+  total: string;
+  available: string;
+  locked: string;
+  averageOpenPrice: string;
+  leverage: number;
+  achievedProfits: string;
+  upl: string;
+  uplRate: string;
+  liqPx: string;
+  keepMarginRate: string;
+  marginRate: string;
+  cTime: string;
+  uTime: string;
+  markPrice: string;
+}

src/types/websockets/index.ts

@@ -0,0 +1,2 @@
+export * from './client';
+export * from './events';

src/util/index.ts

@@ -2,4 +2,5 @@ export * from './BaseRestClient';
 export * from './requestUtils';
 export * from './WsStore';
 export * from './logger';
+export * from './type-guards';
 export * from './websocket-util';

src/util/type-guards.ts

@@ -0,0 +1,73 @@
+import {
+  WsAccountSnapshotUMCBL,
+  WsBaseEvent,
+  WSPositionSnapshotUMCBL,
+  WsSnapshotAccountEvent,
+  WsSnapshotChannelEvent,
+  WsSnapshotPositionsEvent,
+} from '../types';
+
+/** TypeGuard: event has a string "action" property */
+function isWsEvent(event: unknown): event is WsBaseEvent {
+  return (
+    typeof event === 'object' &&
+    event &&
+    typeof event['action'] === 'string' &&
+    event['data']
+  );
+}
+
+/** TypeGuard: event has "action === snapshot" */
+function isWsSnapshotEvent(event: unknown): event is WsBaseEvent<'snapshot'> {
+  return isWsEvent(event) && event.action === 'snapshot';
+}
+
+/** TypeGuard: event has a string channel name */
+function isWsChannelEvent(event: WsBaseEvent): event is WsSnapshotChannelEvent {
+  if (
+    typeof event['arg'] === 'object' &&
+    event.arg &&
+    typeof event?.arg['channel'] === 'string'
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/** TypeGuard: event is an account update (balance) */
+export function isWsAccountSnapshotEvent(
+  event: unknown
+): event is WsSnapshotAccountEvent {
+  return (
+    isWsSnapshotEvent(event) &&
+    isWsChannelEvent(event) &&
+    event.arg.channel === 'account' &&
+    Array.isArray(event.data)
+  );
+}
+
+/** TypeGuard: event is a positions update */
+export function isWsPositionsSnapshotEvent(
+  event: unknown
+): event is WsSnapshotPositionsEvent {
+  return (
+    isWsSnapshotEvent(event) &&
+    isWsChannelEvent(event) &&
+    event.arg.channel === 'positions' &&
+    Array.isArray(event.data)
+  );
+}
+
+/** TypeGuard: event is a UMCBL account update (balance) */
+export function isWsFuturesAccountSnapshotEvent(
+  event: unknown
+): event is WsAccountSnapshotUMCBL {
+  return isWsAccountSnapshotEvent(event) && event.arg.instType === 'umcbl';
+}
+
+/** TypeGuard: event is a UMCBL positions update */
+export function isWsFuturesPositionsSnapshotEvent(
+  event: unknown
+): event is WSPositionSnapshotUMCBL {
+  return isWsPositionsSnapshotEvent(event) && event.arg.instType === 'umcbl';
+}