@blackcube/xgate-sdk 0.23.0 → 0.24.0

package/dist/index.cjs

@@ -11,6 +11,7 @@ var hyperliquidSdk = require('@blackcube/hyperliquid-sdk');
 var lighterSdk = require('@blackcube/lighter-sdk');
 var pacificaSdk = require('@blackcube/pacifica-sdk');
 var paradexSdk = require('@blackcube/paradex-sdk');
+var crypto = require('crypto');
 
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __decorateClass = (decorators, target, key, kind) => {
@@ -1169,7 +1170,8 @@ var ORDER_STATUSES = [
 ];
 
 // src/services/trading.service.ts
-var VENUES_PROUVEES = ["pacifica" /* Pacifica */, "hyperliquid" /* Hyperliquid */];
+var VENUES_PROUVEES = ["pacifica" /* Pacifica */, "hyperliquid" /* Hyperliquid */, "aster" /* Aster */];
+var ASTER_TIMEOUT = "The request has timed out.";
 var VENUES_MOVE_STOP = ["hyperliquid" /* Hyperliquid */, "pacifica" /* Pacifica */, "aster" /* Aster */];
 exports.TradingService = class TradingService {
   logger = new common.Logger(exports.TradingService.name);
@@ -1206,26 +1208,76 @@ exports.TradingService = class TradingService {
         `openWithProtection(${access.xex}) : cette venue n'expose pas l'ouverture prot\xE9g\xE9e atomique.`
       );
     }
-    const orders = await perp.createEntryWithProtection(
-      {
-        name: input.symbolXex,
-        side,
-        type: "limit",
-        size: String(input.size),
-        price: String(input.entry),
-        tif: input.tif ?? "ioc",
-        reduceOnly: false,
-        clientId: input.clientId
-      },
-      {
-        name: input.symbolXex,
-        side,
-        sl: protection.sl,
-        tps: protection.tps,
-        clientId: input.clientId
+    const entry = {
+      name: input.symbolXex,
+      side,
+      type: "limit",
+      size: String(input.size),
+      price: String(input.entry),
+      tif: input.tif ?? "ioc",
+      reduceOnly: false,
+      clientId: input.clientId
+    };
+    const consigne = {
+      name: input.symbolXex,
+      side,
+      sl: protection.sl,
+      tps: protection.tps,
+      clientId: input.clientId
+    };
+    try {
+      const orders = await perp.createEntryWithProtection(entry, consigne);
+      return orders.map((order) => this.toOrder(order, access.xex));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes(ASTER_TIMEOUT) === false) {
+        throw error;
+      }
+      this.logger.warn(
+        `openWithProtection(${access.xex}) : la venue a coup\xE9 avant de r\xE9pondre. Statut inconnu \u2014 relecture de l'\xE9tat r\xE9el.`
+      );
+      return await this.etatApres(access, input.symbolXex);
+    }
+  }
+  /**
+   * CE QUE LA VENUE A RÉELLEMENT FAIT, après une réponse perdue.
+   *
+   * Un timeout ne dit pas « rien n'a été créé » : mesuré sur aster, deux exécutions identiques ont
+   * produit deux sous-ensembles différents — une fois le stop et un take-profit, une fois l'entrée
+   * seule. La seule vérité est au carnet, donc on va l'y chercher.
+   *
+   * **Lève si la position est nue** : une entrée remplie sans stop est exactement ce que ce service
+   * existe pour empêcher, et le silence serait pire que l'erreur. L'appelant doit savoir qu'il a une
+   * position à protéger, tout de suite.
+   */
+  async etatApres(access, symbolXex) {
+    const perp = this.perpOf(access);
+    const [ouverts, positions] = await Promise.all([
+      perp.getOpens(),
+      perp.getPositions({ name: symbolXex })
+    ]);
+    const surLaPaire = ouverts.filter((order) => order.name === symbolXex);
+    const position = positions.find(
+      (candidate) => candidate.name === symbolXex && Number(candidate.size) !== 0
+    );
+    const protege = surLaPaire.some((order) => order.reduceOnly === true);
+    if (position !== void 0 && protege === false) {
+      throw new Error(
+        `openWithProtection(${access.xex}/${symbolXex}) : POSITION NUE \u2014 ${position.size} ouvert sans stop au carnet apr\xE8s une r\xE9ponse perdue. \xC0 prot\xE9ger imm\xE9diatement.`
+      );
+    }
+    if (position === void 0 && surLaPaire.length > 0) {
+      for (const orphelin of surLaPaire) {
+        await perp.cancel({ name: symbolXex, id: orphelin.id }).catch(() => void 0);
       }
+      throw new Error(
+        `openWithProtection(${access.xex}/${symbolXex}) : r\xE9ponse perdue, lot incomplet \u2014 ${surLaPaire.length} ordre(s) orphelin(s) ANNUL\xC9(S). Rien n'est ouvert, rien ne tra\xEEne.`
+      );
+    }
+    this.logger.log(
+      `openWithProtection(${access.xex}/${symbolXex}) : ${surLaPaire.length} ordre(s) au carnet, position ${position === void 0 ? "absente" : position.size}.`
     );
-    return orders.map((order) => this.toOrder(order, access.xex));
+    return surLaPaire.map((order) => this.toOrder(order, access.xex));
   }
   /** Les positions ouvertes d'un compte. */
   async positions(access, symbolXex) {
@@ -1367,6 +1419,193 @@ exports.TradingService = class TradingService {
     const last = exits[0];
     return last === void 0 ? null : last.price;
   }
+  /**
+   * L'HISTORIQUE DES ORDRES du compte — ce qui a été soumis, rempli, annulé ou expiré.
+   *
+   * À distinguer de {@link trades} : un ordre est une **intention**, une exécution est un **fait**.
+   * Un ordre `filled` peut avoir été rempli en plusieurs fois, à des prix différents.
+   *
+   * Servi par les huit venues qui tradent.
+   */
+  async orderHistory(access, symbolXex) {
+    const orders = await this.perpOf(access).getHistory(
+      symbolXex === void 0 ? void 0 : { name: symbolXex }
+    );
+    return orders.map((order) => this.toOrder(order, access.xex));
+  }
+  /**
+   * L'ÉTAT DU COMPTE — équité, disponible, marge immobilisée, marge de maintenance, PnL latent.
+   *
+   * Les venues rangent ces valeurs sous des noms qui n'ont rien à voir : `marginSummary.accountValue`
+   * chez hyperliquid, `accountEquity` chez pacifica, `totalMarginBalance` chez aster — **mais elles
+   * disent la même chose**. La forme native complète reste dans `xtras`, rien n'est perdu.
+   *
+   * **blofin ne l'expose pas** et lève ; les sept autres le servent.
+   */
+  async accountInfo(access) {
+    const perp = this.perpOf(access);
+    if (typeof perp.getAccountInfo !== "function") {
+      throw new Error(
+        `accountInfo(${access.xex}) : cette venue n'expose pas l'\xE9tat de son compte.`
+      );
+    }
+    const brut = await perp.getAccountInfo();
+    return this.toAccountState(brut, access.xex);
+  }
+  /**
+   * RÈGLE LE LEVIER d'une paire, avant d'ouvrir.
+   *
+   * Le levier détermine la marge immobilisée, donc la taille tenable : le changer après l'ouverture
+   * ne rejoue pas la position déjà prise. C'est un réglage préalable, pas un ajustement.
+   *
+   * **bullet ne l'expose pas** — son levier se fixe au compte, pas à la position — et lève.
+   */
+  async setLeverage(access, symbolXex, leverage) {
+    const perp = this.perpOf(access);
+    if (typeof perp.updateLeverage !== "function") {
+      throw new Error(`setLeverage(${access.xex}) : cette venue ne r\xE8gle pas le levier par paire.`);
+    }
+    await perp.updateLeverage({ name: symbolXex, leverage });
+    this.logger.log(`setLeverage(${access.xex}/${symbolXex}) : levier port\xE9 \xE0 ${leverage}`);
+  }
+  /**
+   * CHOISIT LE MODE DE MARGE d'une paire : **isolée** ou **croisée**.
+   *
+   * En **croisée**, tout le solde du compte garantit la position : elle tient plus longtemps, mais
+   * une liquidation emporte l'ensemble. En **isolée**, seule la marge affectée est en jeu : la perte
+   * est bornée à ce montant, la liquidation arrive plus tôt.
+   *
+   * **À régler AVANT d'ouvrir.** Changer le mode d'une position vivante est refusé par la plupart
+   * des venues, et là où c'est accepté, cela redistribue la garantie sous les pieds de la position.
+   *
+   * Servi par les trois venues de référence.
+   */
+  async setMarginMode(access, symbolXex, isolated) {
+    const perp = this.perpOf(access);
+    if (typeof perp.setMarginMode !== "function") {
+      throw new Error(
+        `setMarginMode(${access.xex}) : cette venue ne choisit pas son mode de marge.`
+      );
+    }
+    await perp.setMarginMode({ name: symbolXex, isolated });
+    this.logger.log(
+      `setMarginMode(${access.xex}/${symbolXex}) : marge ${isolated === true ? "ISOL\xC9E" : "CROIS\xC9E"}`
+    );
+  }
+  /**
+   * AJOUTE DE LA MARGE à une position isolée — pour éloigner le prix de liquidation.
+   *
+   * C'est le geste qui sauve une position sous pression sans la réduire : on renforce la garantie
+   * plutôt que de couper. **N'a de sens qu'en marge isolée** ; en croisée, tout le solde garantit
+   * déjà la position et il n'y a rien à ajouter.
+   *
+   * Servi par les trois venues de référence.
+   */
+  async addMargin(access, symbolXex, amount) {
+    const perp = this.perpOf(access);
+    if (typeof perp.addIsolatedMargin !== "function") {
+      throw new Error(`addMargin(${access.xex}) : cette venue n'ajoute pas de marge isol\xE9e.`);
+    }
+    await perp.addIsolatedMargin({ name: symbolXex, amount });
+    this.logger.log(`addMargin(${access.xex}/${symbolXex}) : +${amount} de marge isol\xE9e`);
+  }
+  /**
+   * RETIRE DE LA MARGE d'une position isolée — pour libérer du capital.
+   *
+   * L'inverse d'{@link addMargin} : la garantie diminue, donc le prix de liquidation **se rapproche**.
+   * La venue refuse ce qui mettrait la position sous son seuil de maintenance.
+   *
+   * ⚠️ **pacifica ne l'expose pas** et lève : chez elle, la marge s'ajoute mais ne se retire pas.
+   * Fermer partiellement la position libère alors le capital.
+   */
+  async removeMargin(access, symbolXex, amount) {
+    const perp = this.perpOf(access);
+    if (typeof perp.removeIsolatedMargin !== "function") {
+      throw new Error(
+        `removeMargin(${access.xex}) : cette venue ne retire pas de marge isol\xE9e \u2014 ferme partiellement la position pour lib\xE9rer du capital.`
+      );
+    }
+    await perp.removeIsolatedMargin({ name: symbolXex, amount });
+    this.logger.log(`removeMargin(${access.xex}/${symbolXex}) : \u2212${amount} de marge isol\xE9e`);
+  }
+  /**
+   * L'HISTORIQUE DU FUNDING **PAYÉ** sur une paire — ce qui a réellement été prélevé ou reçu.
+   *
+   * À ne pas confondre avec le taux courant, que rend `PricesService` : celui-ci annonce ce qui
+   * *sera* payé, celui-là dit ce qui *l'a été*. Un backtest qui ignore le funding réel surestime le
+   * résultat d'une position tenue longtemps.
+   *
+   * Servi par les huit venues qui tradent.
+   */
+  async fundingHistory(access, symbolXex, range) {
+    const perp = this.perpOf(access);
+    if (typeof perp.getFundingHistory !== "function") {
+      throw new Error(
+        `fundingHistory(${access.xex}) : cette venue ne publie pas son historique de funding.`
+      );
+    }
+    const rates = await perp.getFundingHistory({
+      name: symbolXex,
+      startTime: range?.startTime === void 0 ? void 0 : toXexDate(range.startTime),
+      endTime: range?.endTime === void 0 ? void 0 : toXexDate(range.endTime),
+      limit: range?.limit
+    });
+    return rates.map((rate) => ({
+      xex: access.xex,
+      symbolXex: rate.name,
+      rate: rate.rate,
+      appliedAt: rate.appliedAt,
+      xtras: rate.xtras
+    }));
+  }
+  /**
+   * UN IDENTIFIANT APPLICATIF pour un ordre, **au format que la venue accepte**.
+   *
+   * C'est lui qui relie un ordre à la décision qui l'a produit : la venue le rend tel quel dans
+   * `IOrder.clientId`, ce qui permet de retrouver son origine sans tenir de table de correspondance.
+   *
+   * **hyperliquid exige un hexadécimal préfixé `0x`** (128 bits) là où les autres acceptent un UUID
+   * ordinaire. Passer le mauvais format fait rejeter l'ordre — d'où cette méthode plutôt qu'un
+   * `randomUUID()` chez l'appelant.
+   */
+  newClientOrderId(xex) {
+    const uuid = crypto.randomUUID();
+    return xex === "hyperliquid" /* Hyperliquid */ ? `0x${uuid.replace(/-/gu, "")}` : uuid;
+  }
+  /**
+   * LE COUPE-CIRCUIT : annule TOUS les ordres d'une paire, d'un geste.
+   *
+   * À réserver aux situations où l'on veut reprendre la main sans discuter — un état incohérent, un
+   * arrêt d'urgence, une reprise après incident. Annuler un par un laisse une fenêtre pendant
+   * laquelle certains ordres vivent encore.
+   *
+   * ⚠️ **Cela retire aussi les PROTECTIONS.** Stops et take-profits sont des ordres comme les
+   * autres : une position ouverte se retrouve **nue** après ce geste. À n'employer que si la
+   * position est fermée, ou si l'on repose une protection immédiatement — jamais pour « faire le
+   * ménage » sur une position vivante.
+   *
+   * Rend le nombre d'ordres annulés quand la venue le publie, `null` sinon.
+   */
+  async cancelAll(access, symbolXex) {
+    const perp = this.perpOf(access);
+    if (typeof perp.cancelAll !== "function") {
+      throw new Error(`cancelAll(${access.xex}) : cette venue n'annule pas en masse.`);
+    }
+    const positions = await perp.getPositions({ name: symbolXex });
+    const ouverte = positions.find(
+      (candidate) => candidate.name === symbolXex && Number(candidate.size) !== 0
+    );
+    if (ouverte !== void 0) {
+      this.logger.warn(
+        `cancelAll(${access.xex}/${symbolXex}) : ${ouverte.size} EN POSITION \u2014 ses protections partent avec. La position sera NUE.`
+      );
+    }
+    const { cancelled } = await perp.cancelAll({ name: symbolXex });
+    this.logger.log(
+      `cancelAll(${access.xex}/${symbolXex}) : ${cancelled ?? "?"} ordre(s) annul\xE9(s)`
+    );
+    return cancelled;
+  }
   /** Annule un ordre par son identifiant de venue. */
   async cancel(access, symbolXex, orderId) {
     await this.perpOf(access).cancel({ name: symbolXex, id: orderId });
@@ -1376,6 +1615,27 @@ exports.TradingService = class TradingService {
     const source = createAccountXex(access.xex, access);
     return source.perp();
   }
+  /**
+   * L'état natif d'une venue → {@link IAccountState}.
+   *
+   * Une lecture EXPLICITE par venue plutôt qu'un parcours à l'aveugle : les noms ne se devinent pas,
+   * et prendre le premier champ qui ressemble à une équité produirait un chiffre faux sans que rien
+   * ne le signale. `null` là où la venue ne publie pas la valeur — pas `0`, qui se lirait comme
+   * « rien » alors que personne n'a rien dit.
+   */
+  toAccountState(brut, xex) {
+    const texte = (valeur) => valeur === void 0 || valeur === null ? null : String(valeur);
+    const marge = brut.marginSummary;
+    return {
+      xex,
+      equity: texte(marge?.accountValue) ?? texte(brut.accountEquity) ?? texte(brut.totalMarginBalance) ?? "0",
+      available: texte(brut.withdrawable) ?? texte(brut.availableToSpend) ?? texte(brut.availableBalance),
+      marginUsed: texte(marge?.totalMarginUsed) ?? texte(brut.totalMarginUsed) ?? texte(brut.totalInitialMargin),
+      maintenanceMargin: texte(brut.crossMaintenanceMarginUsed) ?? texte(brut.crossMmr) ?? texte(brut.totalMaintMargin),
+      unrealizedPnl: texte(brut.totalUnrealizedProfit),
+      xtras: brut
+    };
+  }
   /**
    * Le statut de la venue, VALIDÉ — jamais casté. Une venue qui inventerait un statut rendrait sinon
    * une valeur absente de tous les `switch` en aval, et personne ne la rattraperait.
@@ -1406,6 +1666,9 @@ exports.TradingService = class TradingService {
 exports.TradingService = __decorateClass([
   common.Injectable()
 ], exports.TradingService);
+function toXexDate(date) {
+  return date.toISOString().slice(0, 19).replace("T", " ");
+}
 exports.WalletService = class WalletService {
   logger = new common.Logger(exports.WalletService.name);
   /** Les venues dont le portefeuille est lisible aujourd'hui. */
@@ -1609,6 +1872,176 @@ exports.WsCandlesService = class WsCandlesService {
 exports.WsCandlesService = __decorateClass([
   common.Injectable()
 ], exports.WsCandlesService);
+exports.WsTradesService = class WsTradesService {
+  logger = new common.Logger(exports.WsTradesService.name);
+  /**
+   * S'abonne aux exécutions d'un compte. Rend la fonction de désabonnement.
+   *
+   * Le handler reçoit **une exécution à la fois**, au format unifié, et **uniquement celles
+   * survenues après l'abonnement** — le rejeu d'historique de la venue est écarté.
+   */
+  subscribe(access, handler) {
+    const source = createAccountXex(access.xex, access);
+    if (typeof source.ws !== "function") {
+      throw new Error(`userTrades(${access.xex}) : cette venue n'expose pas de temps r\xE9el.`);
+    }
+    const ws = source.ws();
+    if (typeof ws.subscribeUserTrades !== "function") {
+      throw new Error(
+        `userTrades(${access.xex}) : cette venue ne diffuse pas les ex\xE9cutions du compte.`
+      );
+    }
+    const depuis = Date.now();
+    let ecartees = 0;
+    this.logger.log(`souscription ex\xE9cutions sur ${access.xex}`);
+    return ws.subscribeUserTrades((trade) => {
+      if (trade.filledAt.getTime() < depuis) {
+        ecartees += 1;
+        if (ecartees === 1) {
+          this.logger.log(`${access.xex} : rejeu d'historique \xE9cart\xE9 (ant\xE9rieur \xE0 l'abonnement).`);
+        }
+        return;
+      }
+      handler(this.toTrade(trade, access.xex));
+    });
+  }
+  /**
+   * S'abonne aux exécutions de PLUSIEURS comptes, avec un seul handler.
+   *
+   * Chaque exécution porte son `xex` : l'appelant sait toujours de quelle venue elle vient. La
+   * fonction rendue coupe tous les flux d'un coup — sinon il faudrait en garder N et n'en oublier
+   * aucun.
+   *
+   * Une venue qui refuse est journalisée et ignorée : le reste des comptes doit continuer d'être
+   * suivi. Sur un seul accès, l'échec est celui de l'appel.
+   */
+  subscribeAll(accesses, handler) {
+    if (accesses.length === 0) {
+      throw new Error("userTrades() : aucun compte demand\xE9 \u2014 pr\xE9cise au moins un acc\xE8s.");
+    }
+    const solo = accesses.length === 1;
+    const stops = [];
+    for (const access of accesses) {
+      try {
+        stops.push(this.subscribe(access, handler));
+      } catch (error) {
+        if (solo === true) {
+          throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        this.logger.error(`souscription ${access.xex} refus\xE9e, venue ignor\xE9e : ${message}`);
+      }
+    }
+    return () => {
+      for (const stop of stops) {
+        try {
+          stop();
+        } catch {
+        }
+      }
+    };
+  }
+  /**
+   * S'abonne aux ORDRES du compte — leur naissance, leur remplissage, leur mort.
+   *
+   * À distinguer des exécutions : un ordre est une **intention** dont on suit le cycle de vie
+   * (`open` → `partiallyFilled` → `filled`, ou `canceled`), une exécution est un **fait** ponctuel.
+   * Pour savoir qu'un stop vient de se déclencher, c'est ici qu'il faut écouter ; pour savoir à quel
+   * prix, c'est {@link subscribe}.
+   *
+   * **Même règle que pour les exécutions** : seuls les ordres postérieurs à l'abonnement sont
+   * transmis, le rejeu d'historique est écarté.
+   */
+  subscribeOrders(access, handler) {
+    const ws = this.wsOf(access);
+    if (typeof ws.subscribeOrders !== "function") {
+      throw new Error(`orders(${access.xex}) : cette venue ne diffuse pas ses ordres.`);
+    }
+    const depuis = Date.now();
+    this.logger.log(`souscription ordres sur ${access.xex}`);
+    return ws.subscribeOrders((order) => {
+      if (order.placedAt.getTime() >= depuis) {
+        handler(this.toOrder(order, access.xex));
+      }
+    });
+  }
+  /**
+   * S'abonne aux TRANSACTIONS PUBLIQUES d'un marché — celles de tout le monde, pas les siennes.
+   *
+   * C'est le flux qui dit ce qui se négocie réellement : prix, taille, sens agresseur. Il sert à
+   * mesurer l'activité d'une paire, pas à suivre son compte — pour cela, {@link subscribe}.
+   *
+   * **Aucun filtre temporel ici** : un trade public est daté de son exécution et arrive en direct,
+   * il n'y a pas d'historique rejoué à écarter.
+   */
+  subscribePublicTrades(access, symbolXex, handler) {
+    const ws = this.wsOf(access);
+    if (typeof ws.subscribeTrades !== "function") {
+      throw new Error(`publicTrades(${access.xex}) : cette venue ne diffuse pas les transactions.`);
+    }
+    this.logger.log(`souscription transactions ${symbolXex} sur ${access.xex}`);
+    return ws.subscribeTrades({ name: symbolXex }, (trade) => {
+      handler({
+        xex: access.xex,
+        symbolXex: trade.name,
+        price: trade.price,
+        size: trade.size,
+        side: trade.side,
+        tradedAt: trade.tradedAt,
+        xtras: trade.xtras
+      });
+    });
+  }
+  /** Le client temps réel d'un compte, avec ses souscriptions signées. */
+  wsOf(access) {
+    const source = createAccountXex(access.xex, access);
+    if (typeof source.ws !== "function") {
+      throw new Error(`${access.xex} : cette venue n'expose pas de temps r\xE9el.`);
+    }
+    return source.ws();
+  }
+  toOrder(order, xex) {
+    return {
+      xex,
+      symbolXex: order.name,
+      kind: order.kind,
+      id: order.id,
+      clientId: order.clientId,
+      side: order.side,
+      type: order.type,
+      price: order.price,
+      size: order.size,
+      filled: order.filled,
+      status: ORDER_STATUSES.includes(order.status) ? order.status : "other",
+      tif: order.tif,
+      reduceOnly: order.reduceOnly,
+      placedAt: order.placedAt,
+      xtras: order.xtras
+    };
+  }
+  toTrade(trade, xex) {
+    return {
+      xex,
+      symbolXex: trade.name,
+      kind: trade.kind,
+      id: trade.id,
+      orderId: trade.orderId,
+      side: trade.side,
+      price: trade.price,
+      size: trade.size,
+      fee: trade.fee,
+      feeAsset: trade.feeAsset,
+      grossPnl: trade.grossPnl,
+      netPnl: trade.netPnl,
+      maker: trade.maker,
+      filledAt: trade.filledAt,
+      xtras: trade.xtras
+    };
+  }
+};
+exports.WsTradesService = __decorateClass([
+  common.Injectable()
+], exports.WsTradesService);
 
 // src/xgate.module.ts
 exports.XgateModule = class XgateModule {
@@ -1620,6 +2053,7 @@ exports.XgateModule = __decorateClass([
       exports.CandlesService,
       exports.CandlesStreamRegistry,
       exports.WsCandlesService,
+      exports.WsTradesService,
       exports.PricesService,
       exports.SpotCatalogService,
       exports.SpotCandlesService,
@@ -1632,6 +2066,7 @@ exports.XgateModule = __decorateClass([
       exports.CandlesService,
       exports.CandlesStreamRegistry,
       exports.WsCandlesService,
+      exports.WsTradesService,
       exports.PricesService,
       exports.SpotCatalogService,
       exports.SpotCandlesService,