@blackcube/xgate-sdk 0.20.0 → 0.21.1

package/README.md

@@ -58,7 +58,40 @@ Chacun est un `@Injectable()` NestJS, utilisable seul ou via `XgateModule`.
 | `WsCandlesService` | les bougies en temps réel, un handler pour N venues |
 | `PricesService` | mark, oracle, mid, bid/ask, funding, open interest |
 | `WalletService` | soldes, mouvements, historique d'équité |
-| `TradingService` | positions, ordres, exécutions, ouverture protégée, clôture |
+| `TradingService` | positions, ordres, exécutions — et le cycle **ouvrir → gérer → fermer** |
+
+Le cycle de vie d'une position tient en trois gestes, et chacun préserve le même invariant : la
+position n'est jamais sans stop.
+
+| geste | méthode | venues |
+|---|---|---|
+| ouvrir avec sa protection | `openWithProtection` | hyperliquid, pacifica |
+| déplacer le stop | `moveStop` | hyperliquid, pacifica, aster |
+| fermer sans reliquat | `closePosition` | toutes celles qui tradent |
+| relire le prix de sortie réel | `exitPrice` | toutes celles qui tradent |
+
+## Le portefeuille
+
+`balances()` rend **le comptant et le collatéral**, chaque ligne portant sa nature :
+
+```typescript
+const soldes = await wallet.balances(access);
+soldes.filter((solde) => solde.xtras?.scope === 'perp');   // la marge
+soldes.filter((solde) => solde.xtras?.scope !== 'perp');   // le comptant
+```
+
+Les SDK de venue, eux, ne rendent que le comptant — c'est leur convention, et la documentation de
+chacune le confirme. **Sans le collatéral, un portefeuille peut paraître vide** : sur un compte
+pacifica dont tout le solde est en marge, les soldes comptant valent `[]`, ce qui se lit « pas
+d'argent » alors qu'il y a 499 USDC. XGate lit donc aussi la marge et l'ajoute, marquée.
+
+```
+pacifica     USDC 499.204355 (perp)
+hyperliquid  USDC 1137.565924 (spot) + USDC 7.320954 (perp)
+```
+
+Les deux lignes s'additionnent sans se recouvrir : le collatéral est hors comptant chez les deux
+venues.
 
 ## Le trading
 
@@ -96,6 +129,38 @@ const orders = await trading.openWithProtection(access, {
 
 Le premier ordre rendu est l'entrée ; les suivants sont le stop et les take-profits.
 
+### Déplacer le stop
+
+Le geste du point mort : une position qui a couru se sécurise en remontant son stop. Le SDK de la
+venue pose le **nouveau** stop avant d'annuler l'ancien — la position n'est jamais nue, pas même une
+milliseconde.
+
+```typescript
+const carnet = await trading.openOrders(access);
+const stop = carnet.find((order) => order.symbolXex === 'ETH' && order.reduceOnly === true);
+
+await trading.moveStop(access, {
+  xex: XgateEx.Hyperliquid,
+  symbolXex: 'ETH',
+  direction: 'long',
+  stopId: stop.id,
+  triggerPrice: 3120,        // arrondi au tick par XGate
+  size: 0.02,
+}, markPrice);
+```
+
+**Disponible sur hyperliquid, pacifica et aster** — les trois seules venues qui exposent la
+capacité. Ailleurs la méthode lève : déplacer un stop y demanderait d'annuler puis de reposer, ce
+qui rouvre exactement la fenêtre nue que tout ceci existe pour fermer.
+
+**Un stop du mauvais côté est refusé avant l'appel réseau.** Pour un long, un stop au-dessus du
+marché se déclenche immédiatement et solde la position — la venue l'accepte sans broncher, et
+l'erreur ne se voit qu'une fois l'argent parti. Le prix courant est donc un argument obligatoire.
+
+> **L'identifiant du stop ne vient pas de l'ouverture.** Hyperliquid répond `"waitingForTrigger"` —
+> une chaîne nue, sans identifiant — pour un stop groupé sous son entrée. Il se retrouve au carnet,
+> où `reduceOnly === true` le distingue.
+
 ### Fermer
 
 `closePosition` relit la position **sur la venue** avant de la fermer, et sort la taille que la venue
@@ -106,6 +171,19 @@ fill a différé du plan, et ce reliquat reste ouvert, sans stop.
 await trading.closePosition(access, 'ETH');   // null s'il n'y avait rien à fermer
 ```
 
+### Le prix de sortie réel
+
+Le prix planifié ne dit pas à quel prix on est sorti : un stop se déclenche au marché, un take-profit
+peut remplir en plusieurs fois. `exitPrice` relit l'historique de la venue et rend le prix du
+**dernier ordre de sortie réellement rempli** — c'est lui qui doit servir au calcul du résultat,
+sinon le PnL affiché est une fiction.
+
+```typescript
+const prix = await trading.exitPrice(access, 'ETH', 'long', ouvertureDate);
+```
+
+Rend `null` quand la venue n'expose rien d'exploitable ; à l'appelant de décider de son repli.
+
 ### Le réseau est explicite
 
 `network` vaut `mainnet` par défaut. **Le préciser est la seule chose qui sépare un test d'un ordre
@@ -137,6 +215,15 @@ passerelle tel quel : `ORDER_STATUSES` est exporté pour valider plutôt que cas
 - **Une taille de position est toujours positive** : le sens est porté par `side`.
 - **Pas de mensuel.** Les intervalles s'arrêtent à `1w`.
 
+## Versions
+
+La famille avance **en version iso** : XGate et les SDK qu'il agrège portent le même numéro, pour
+qu'un `0.20.0` désigne le même état partout et qu'aucune combinaison ne soit à vérifier.
+
+**bullet est l'exception, et elle est délibérée** : il suit **son propre cycle** (`0.55.x`), parce
+qu'il était déjà publié bien plus haut quand la famille s'est alignée. Le forcer à redescendre
+inventerait une version antérieure à ce qui existe. XGate le référence donc à son numéro à lui.
+
 ## Documentation
 
 Le détail par service vit dans les docblocks — ils portent le *pourquoi*, pas la paraphrase du code.

package/dist/index.cjs

@@ -761,6 +761,7 @@ var ORDER_STATUSES = [
 
 // src/services/trading.service.ts
 var VENUES_PROUVEES = ["pacifica" /* Pacifica */, "hyperliquid" /* Hyperliquid */];
+var VENUES_MOVE_STOP = ["hyperliquid" /* Hyperliquid */, "pacifica" /* Pacifica */, "aster" /* Aster */];
 exports.TradingService = class TradingService {
   logger = new common.Logger(exports.TradingService.name);
   /**
@@ -901,6 +902,45 @@ exports.TradingService = class TradingService {
     }
     return closed;
   }
+  /**
+   * DÉPLACE LE STOP d'une position ouverte — le geste du point mort.
+   *
+   * Le SDK de la venue pose le NOUVEAU stop **avant** d'annuler l'ancien : la position n'est jamais
+   * nue, pas même une milliseconde. C'est le même invariant qu'à l'ouverture, appliqué au milieu de
+   * la vie de la position.
+   *
+   * **Un stop du mauvais côté est refusé ici**, avant l'appel réseau. Pour un long, un stop au-dessus
+   * du marché se déclenche immédiatement et solde la position — la venue l'accepte sans broncher, et
+   * l'erreur ne se voit qu'une fois l'argent parti. Ce refus n'est pas de la prudence décorative :
+   * il a été écrit après avoir vu le cas se produire.
+   */
+  async moveStop(access, input, markPrice) {
+    const trigger = roundPrice(input.triggerPrice, input.tickSize, input.lotSize);
+    const perdant = input.direction === "long" ? trigger >= markPrice : trigger <= markPrice;
+    if (perdant === true) {
+      throw new Error(
+        `moveStop(${access.xex}/${input.symbolXex}) : un stop ${input.direction} \xE0 ${trigger} est du mauvais c\xF4t\xE9 du march\xE9 (${markPrice}) \u2014 il se d\xE9clencherait aussit\xF4t et solderait la position.`
+      );
+    }
+    const perp = this.perpOf(access);
+    if (typeof perp.moveStop !== "function") {
+      throw new Error(
+        `moveStop(${access.xex}) : cette venue ne sait pas d\xE9placer un stop. Disponible sur ${VENUES_MOVE_STOP.join(", ")}.`
+      );
+    }
+    const glissement = input.slippagePct ?? 5e-3;
+    const borne = input.direction === "long" ? 1 - glissement : 1 + glissement;
+    const moved = await perp.moveStop({
+      name: input.symbolXex,
+      side: input.direction === "long" ? "buy" : "sell",
+      stopId: input.stopId,
+      triggerPrice: String(trigger),
+      size: String(roundToStep(input.size, input.lotSize, "floor")),
+      price: String(roundPrice(trigger * borne, input.tickSize, input.lotSize))
+    });
+    this.logger.log(`moveStop(${access.xex}/${input.symbolXex}) : stop port\xE9 \xE0 ${trigger}`);
+    return { symbolXex: moved.name, id: moved.id };
+  }
   /**
    * LE PRIX DE SORTIE RÉEL d'une position, lu dans l'historique de la venue.
    *
@@ -973,8 +1013,9 @@ exports.WalletService = class WalletService {
    */
   async balances(...accesses) {
     return this.collect(accesses, "balances", async (access) => {
-      const balances = await createAccountXex(access.xex, access).account().getBalances();
-      return balances.map((balance) => ({
+      const source = createAccountXex(access.xex, access);
+      const balances = await source.account().getBalances();
+      const lignes = balances.map((balance) => ({
         xex: access.xex,
         asset: balance.asset,
         total: balance.total,
@@ -982,8 +1023,48 @@ exports.WalletService = class WalletService {
         usdValue: balance.usdValue,
         xtras: balance.xtras
       }));
+      const collateral = await this.perpCollateral(source, access.xex);
+      return collateral === null ? lignes : [...lignes, collateral];
     });
   }
+  /**
+   * LE COLLATÉRAL PERPÉTUEL, ajouté aux soldes comptant — sans lui, un portefeuille peut paraître VIDE.
+   *
+   * `getBalances` ne rend que le **comptant**, chez les huit venues : c'est leur convention, et la
+   * documentation de chacune le dit. Or l'argent qui sert à trader n'y est pas. Sur un compte
+   * pacifica dont tout le solde est en marge, `getBalances` rend `[]` — ce qui se lit « pas
+   * d'argent » alors qu'il y a 499 USDC. Sur hyperliquid, le comptant s'affiche mais la marge
+   * manque.
+   *
+   * La ligne est **marquée `scope: 'perp'`** dans `xtras` : elle s'additionne au comptant sans le
+   * doubler, et un appelant qui ne veut que l'un des deux peut trancher.
+   *
+   * Le champ diffère par venue et n'est pas devinable — d'où la lecture explicite, venue par venue,
+   * plutôt qu'un parcours à l'aveugle d'un objet `unknown`.
+   */
+  async perpCollateral(source, xex) {
+    const facade = source;
+    if (typeof facade.perp !== "function") {
+      return null;
+    }
+    const scope = facade.perp();
+    if (typeof scope.getAccountInfo !== "function") {
+      return null;
+    }
+    const info = await scope.getAccountInfo();
+    const total = info.balance ?? info.marginSummary?.accountValue;
+    if (total === void 0 || Number(total) === 0) {
+      return null;
+    }
+    return {
+      xex,
+      asset: "USDC",
+      total,
+      available: info.availableToSpend ?? info.withdrawable ?? null,
+      usdValue: total,
+      xtras: { scope: "perp" }
+    };
+  }
   /**
    * Les mouvements d'argent, triés du plus ancien au plus récent, montants **signés**.
    *