@blackcube/xgate-sdk 0.21.0 → 0.21.1

package/README.md

@@ -70,6 +70,29 @@ position n'est jamais sans stop.
 | 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
 
 **Jamais un ordre sans stop.** `openWithProtection` est la seule façon d'ouvrir une position, et

package/dist/index.cjs

@@ -1013,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,
@@ -1022,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**.
    *