@blackcube/xgate-sdk 0.24.0 → 0.25.1

package/README.md

@@ -5,6 +5,46 @@ un catalogue, des bougies, des prix, un portefeuille et du trading — quelle qu
 
 > **SDK communautaire / non officiel.** Non affilié aux exchanges couverts. Usage à vos risques.
 
+## ⚠️ Si ça ne passe pas par XGate, arrête-toi
+
+**XGate est la seule porte vers les venues.** Importer un `@blackcube/*-sdk` directement dans une
+application, c'est contourner — et un contournement ne se voit pas : le code compile, les tests
+passent, et la divergence n'apparaît qu'en production, sur la venue que personne n'a exercée.
+
+Tu t'apprêtes à écrire quelque chose qui ne passe pas par XGate ? **Il n'y a que deux cas, et
+aucun des deux ne consiste à contourner.**
+
+**1. Tu n'as pas trouvé — c'est le cas le plus fréquent.** La méthode existe sous un autre nom. Le
+vocabulaire d'XGate n'est celui d'aucune venue : il est unifié.
+
+| tu cherches | c'est | et pas |
+|---|---|---|
+| passer un ordre | `openWithProtection` | `place` — qui n'existe pas ici |
+| fermer | `closePosition` | un ordre marché `reduceOnly` à la main |
+| modifier un stop | `moveStop` | annuler puis reposer |
+| le levier | `setLeverage` | `updateLeverage` |
+| l'état du compte | `accountInfo` | `getAccountInfo` |
+| l'historique des ordres | `orderHistory` | `getHistory` |
+| le funding payé | `fundingHistory` | `getFundingHistory` |
+| les exécutions en direct | `WsTradesService.subscribe` | `subscribeUserTrades` |
+| N marchés en temps réel | `CandlesStreamRegistry.of()` | N × `WsCandlesService` |
+
+**Vérifie avant de conclure** : `grep -rn "public " node_modules/@blackcube/xgate-sdk/dist/index.d.ts`
+ou la table des services plus bas. Ce README documente **35 méthodes publiques sur 35** — si tu ne
+trouves pas, cherche encore.
+
+**2. C'est un vrai trou.** Alors **dis-le, et discutes-en** — ne le comble pas dans ton coin.
+Certaines absences sont des **décisions** : `place`, `placeProtection`, `cancelProtection`,
+`subscribeAllCandles`, `subscribePrices` n'existent pas *exprès*, et les raisons sont écrites plus
+bas. Les recréer côté application, c'est réintroduire ce qui a été retiré après incident.
+
+D'autres absences sont réelles — `getOrderBook`, `edit`, `getExchangeInfo`, `withdraw`,
+`subscribeOrderBook`, `subscribeBbo`. Elles se comblent **dans XGate**, où elles profitent à tous
+les appelants et sont exercées contre les venues, jamais dans l'application.
+
+> **Le réflexe qui trahit le contournement** : tu es sur le point d'écrire `import { Hyperliquid }
+> from '@blackcube/hyperliquid-sdk'` dans du code applicatif. Arrête-toi là.
+
 ## Installation
 
 ```bash
@@ -230,12 +270,28 @@ venues.
 ## Le trading
 
 **Jamais un ordre sans stop.** `openWithProtection` est la seule façon d'ouvrir une position, et
-elle exige un `slPct`. La protection part **avec** l'entrée, en un geste que la venue traite
+elle exige un `sl`. La protection part **avec** l'entrée, en un geste que la venue traite
 atomiquement : si l'entrée ne remplit pas, la protection ne naît jamais.
 
-**L'appelant donne des pourcentages, jamais des prix.** XGate calcule les niveaux depuis le prix
-d'entrée, les arrondit à la grille de la paire, et garantit qu'au-delà de 80 % de parts cumulées la
-position ferme entièrement — sans reliquat de 0,01 qui traîne.
+### Un niveau se dit en écart OU en prix
+
+```typescript
+sl: { pct: 0.02 }        // 2 % sous l'entrée en long, 2 % au-dessus en short
+sl: { price: 62500 }     // exactement 62 500, quel que soit le prix d'entrée
+```
+
+Les deux façons de penser un objectif coexistent réellement : « je sors si ça monte de 10 % »
+raisonne en **risque**, « je sors si ça touche 62 500 » raisonne en **niveau technique**. Obliger à
+convertir l'un dans l'autre reviendrait à faire calculer l'appelant, donc à déplacer l'erreur chez
+lui. Les deux modes se mélangent librement dans le même appel.
+
+**`part` reste toujours une fraction de la POSITION** — les deux modes ne portent que sur le niveau.
+
+Le type rend l'ambiguïté impossible : `ITarget` est une union **exclusive**, donc
+`{ pct: 0.1, price: 62500 }` **ne compile pas**, et `{}` non plus.
+
+**XGate arrondit les niveaux à la grille de la paire** et garantit qu'au-delà de 80 % de parts
+cumulées la position ferme entièrement — sans reliquat de 0,01 qui traîne.
 
 ```typescript
 import { TradingService, XgateEx } from '@blackcube/xgate-sdk';
@@ -254,9 +310,9 @@ const orders = await trading.openWithProtection(access, {
   direction: 'long',
   size: 0.02,
   entry: 3120,
-  slPct: 0.02,                              // stop à 2 % sous l'entrée
+  sl: { pct: 0.02 },                        // stop à 2 % sous l'entrée
   tps: [{ pct: 0.03, part: 0.5 },           // 50 % à +3 %
-        { pct: 0.06, part: 0.5 }],          // 50 % à +6 % → somme 100 %, clôture intégrale
+        { price: 62500, part: 0.5 }],       // 50 % si le prix touche 62 500
   tif: 'ioc',
 });
 ```

package/dist/index.cjs

@@ -97,6 +97,24 @@ function toCandle(wire, xex, interval, quote) {
   };
 }
 
+// src/helpers/socket-error.ts
+function lisible(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  const event = error;
+  if (event !== null && typeof event === "object") {
+    const message = event.message ?? event.error?.message;
+    if (typeof message === "string" && message !== "") {
+      return message;
+    }
+    if (typeof event.type === "string" && event.type !== "") {
+      return `\xE9v\xE9nement \xAB ${event.type} \xBB`;
+    }
+  }
+  return String(error);
+}
+
 // src/helpers/ws-limits.ts
 var WS_SUBSCRIPTION_LIMITS = {
   aster: 200,
@@ -266,20 +284,36 @@ var CandlesStreamService = class {
   unsubscribes = [];
   /** Le plafond de souscriptions documenté par la venue, ou `null` si personne ne l'a publié. */
   maxSubscriptions;
+  /**
+   * Notifié quand le flux meurt — après que les souscriptions ont été coupées.
+   *
+   * **Ce crochet a remplacé un `throw`.** Lever depuis un rappel de socket ne remonte à aucun
+   * appelant : l'exception sort en `unhandledRejection` et **tue le process entier**, ce qui est
+   * arrivé le 2026-08-13 sur Blips par un autre chemin. « Impossible à ignorer » et « fatal pour
+   * tout le monde » ne sont pas la même chose : la première est une garantie, la seconde une panne.
+   *
+   * Le contrat reste franc — le flux est coupé, il ne repartira pas tout seul, et le silence est
+   * journalisé en `.error` de toute façon. Mais c'est à l'appelant de décider ce qu'il en fait :
+   * rouvrir, basculer de venue, ou s'arrêter.
+   */
+  onFailure = null;
   /**
    * Ouvre le flux sur une LISTE de marchés, sur une seule socket.
    *
-   * **UNE ERREUR DE FLUX COUPE TOUT, PUIS LÈVE.** Elle n'arrive pas à la souscription : mesuré le
+   * **UNE ERREUR DE FLUX COUPE TOUT, PUIS NOTIFIE.** Elle n'arrive pas à la souscription : mesuré le
    * 2026-08-07, la venue accepte un symbole inconnu sans broncher, puis ferme la connexion en le
    * découvrant. Le SDK reconnecte, elle referme — cinq cycles en douze secondes, et sur une socket
    * partagée **tous** les marchés valides cessent de recevoir, en silence.
    *
    * On refuse cette boucle : à la première erreur, les souscriptions sont coupées, l'incident est
-   * journalisé en `error`, et l'exception part. Un flux à moitié mort qui se tait coûte plus cher
-   * qu'un arrêt franc — on ne découvre le premier qu'en constatant l'absence de données.
+   * journalisé en `error`, et {@link onFailure} est notifié. Un flux à moitié mort qui se tait
+   * coûte plus cher qu'un arrêt franc — on ne découvre le premier qu'en constatant l'absence de
+   * données.
    *
-   * ⚠️ L'exception naît dans un rappel de socket : elle ne remonte pas à l'appelant de `start()`,
-   * elle sort en erreur non capturée. C'est délibéré — elle doit être impossible à ignorer.
+   * ⚠️ **On ne lève pas depuis le rappel de socket.** Une exception née là ne remonte à aucun
+   * appelant de `start()` : elle sort en `unhandledRejection` et emporte le process entier — pas
+   * seulement le flux fautif, mais les crons et tout ce qui tournait à côté. C'est {@link onFailure}
+   * qui porte l'information, et l'appelant qui décide.
    *
    * **binance et bybit ne remontent pas encore leurs erreurs** : leur client gère la fermeture en
    * interne sans l'exposer. Sur ces deux venues, la boucle silencieuse reste possible.
@@ -291,7 +325,7 @@ var CandlesStreamService = class {
         const raison = lisible(error);
         this.logger.error(`${this.xex} : erreur de flux \u2014 ${raison}. Souscriptions coup\xE9es.`);
         this.stop();
-        throw new Error(`stream(${this.xex}) : flux interrompu \u2014 ${raison}`);
+        this.onFailure?.(new Error(`stream(${this.xex}) : flux interrompu \u2014 ${raison}`));
       };
     }
     for (const symbolXex of symbolsXex) {
@@ -374,22 +408,6 @@ exports.CandlesStreamRegistry = class CandlesStreamRegistry {
 exports.CandlesStreamRegistry = __decorateClass([
   common.Injectable()
 ], exports.CandlesStreamRegistry);
-function lisible(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  const event = error;
-  if (event !== null && typeof event === "object") {
-    const message = event.message ?? event.error?.message;
-    if (typeof message === "string" && message !== "") {
-      return message;
-    }
-    if (typeof event.type === "string" && event.type !== "") {
-      return `\xE9v\xE9nement \xAB ${event.type} \xBB`;
-    }
-  }
-  return String(error);
-}
 
 // src/enums/timeframe.enums.ts
 var Timeframe = /* @__PURE__ */ ((Timeframe2) => {
@@ -1077,6 +1095,13 @@ exports.SpotWsCandlesService = __decorateClass([
 ], exports.SpotWsCandlesService);
 
 // src/helpers/protection.ts
+function priceOf(cible, entry, direction, gagnant) {
+  if (cible.price !== void 0) {
+    return round8(cible.price);
+  }
+  const dir = (direction === "long" ? 1 : -1) * (gagnant === true ? 1 : -1);
+  return round8(entry * (1 + dir * cible.pct));
+}
 var SLIPPAGE_DEFAUT = 5e-3;
 var SEUIL_CLOTURE = 0.8;
 function round8(value) {
@@ -1119,12 +1144,8 @@ function buildLevels(entry, direction, slPct, tpPcts) {
 function buildProtection(input) {
   const slippage = input.slippagePct ?? SLIPPAGE_DEFAUT;
   const long = input.direction === "long";
-  const { sl, tps: niveaux } = buildLevels(
-    input.entry,
-    input.direction,
-    input.slPct,
-    input.tps.map((tp) => tp.pct)
-  );
+  const sl = priceOf(input.sl, input.entry, input.direction, false);
+  const niveaux = input.tps.map((tp) => priceOf(tp, input.entry, input.direction, true));
   const borne = (trigger) => long === true ? trigger * (1 - slippage) : trigger * (1 + slippage);
   const sommeParts = input.tps.reduce((total, tp) => total + tp.part, 0);
   const clotureIntegrale = sommeParts > SEUIL_CLOTURE;
@@ -1195,7 +1216,7 @@ exports.TradingService = class TradingService {
       entry: input.entry,
       direction: input.direction,
       size: input.size,
-      slPct: input.slPct,
+      sl: input.sl,
       tps: input.tps,
       tickSize: input.tickSize,
       lotSize: input.lotSize,
@@ -1818,6 +1839,8 @@ exports.WalletService = __decorateClass([
 ], exports.WalletService);
 exports.WsCandlesService = class WsCandlesService {
   logger = new common.Logger(exports.WsCandlesService.name);
+  /** Un client temps réel par venue — voir {@link wireOf}. La clé EST la venue. */
+  wires = /* @__PURE__ */ new Map();
   /**
    * Souscrit aux bougies d'un marché chez une venue. Rend la fonction de désabonnement.
    *
@@ -1833,9 +1856,12 @@ exports.WsCandlesService = class WsCandlesService {
   subscribe(xex, query, handler) {
     const quote = this.quoteOf(query.symbol);
     this.logger.log(`souscription bougies ${query.symbol} ${query.interval} sur ${xex}`);
-    return createPublicXex(xex).ws().subscribeCandles({ name: query.symbol, interval: query.interval }, (wire) => {
-      handler(toCandle(wire, xex, query.interval, quote));
-    });
+    return this.wireOf(xex).subscribeCandles(
+      { name: query.symbol, interval: query.interval },
+      (wire) => {
+        handler(toCandle(wire, xex, query.interval, quote));
+      }
+    );
   }
   /**
    * Souscrit au MÊME marché chez plusieurs venues, avec un seul handler.
@@ -1862,6 +1888,35 @@ exports.WsCandlesService = class WsCandlesService {
       }
     };
   }
+  /**
+   * Le client temps réel d'une venue — **créé une seule fois, donc UNE SOCKET PAR VENUE**.
+   *
+   * C'est la règle que `CandlesStreamService` énonce déjà et que ce service violait : chaque
+   * `subscribe()` appelait `createPublicXex(xex)`, qui construit une façade NEUVE. Or la façade
+   * mémoïse son client temps réel (`unifiedWs()`), et c'est lui qui porte la socket : une façade
+   * par souscription, c'est une socket par souscription.
+   *
+   * Mesuré le 2026-08-13 sur Blips : 1 104 souscriptions ont ouvert **1 104 sockets** sur sept
+   * venues, quand hyperliquid n'en accepte que 10 par IP. Les descripteurs s'épuisent, les venues
+   * refusent, et chaque connexion refusée rejetait une promesse que personne n'attendait — le
+   * process entier mourait deux minutes après l'ouverture des flux. Ici : **sept sockets**.
+   *
+   * Rien à fermer explicitement : le ref-count vit dans les SDK (`refs += 1` / `release()`), donc
+   * la socket se ferme d'elle-même au dernier désabonnement de la venue, et se rouvre au suivant.
+   */
+  wireOf(xex) {
+    let wire = this.wires.get(xex);
+    if (wire === void 0) {
+      wire = createPublicXex(xex).ws();
+      if ("onError" in wire) {
+        wire.onError = (error) => {
+          this.logger.error(`${xex} : erreur de flux \u2014 ${lisible(error)}`);
+        };
+      }
+      this.wires.set(xex, wire);
+    }
+    return wire;
+  }
   /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
   quoteOf(symbolXex) {
     const parts = symbolXex.split("-");