@syldel/hl-shared-types 0.0.18 → 0.0.20

package/dist/interfaces/infos/collateral-balance.interfaces.d.ts

@@ -0,0 +1,60 @@
+import { DecimalString } from '../common';
+import { AccountAbstractionMode } from './account-abstraction.type';
+/**
+ * ============================================================================
+ * LE COLLATÉRAL D'UN MARCHÉ : TROIS RÉPONSES, PAS UN NOMBRE
+ *
+ * Réponse de `GET /hyperliquid/info/collateral-balance` du gateway.
+ *
+ * Ce type vit ici parce qu'il **traverse** le réseau : le gateway le produit,
+ * le bot le consomme. Une copie de chaque côté finirait par diverger, et la
+ * divergence porterait sur un chiffre qui dimensionne des ordres.
+ *
+ * Trois cas, parce que leurs remèdes sont trois : approvisionner le compte,
+ * corriger le nom du marché, ou attendre que le registre soit synchronisé.
+ * Jusqu'au 2026-10-01 les trois rendaient `'0'`, donc aucun n'était
+ * distinguable d'un compte vide — et `'0'` sur un calcul de taille fait
+ * dimensionner un ordre sur un capital qui n'a jamais été lu.
+ * ============================================================================
+ */
+export type CollateralBalance = 
+/** Le solde a été lu. `total` et `used` sont ceux du collatéral nommé. */
+{
+    status: 'ok';
+    /** Le mode qui a décidé d'où le solde a été lu — spot, ou état perp du dex. */
+    mode: AccountAbstractionMode;
+    /** Symbole du collatéral, pour l'affichage et les journaux. */
+    collateral: string;
+    /**
+     * Index du token, qui fait autorité pour apparier un solde.
+     * `null` quand l'appelant a imposé un symbole plutôt qu'un index.
+     */
+    collateralToken: number | null;
+    total: DecimalString;
+    used: DecimalString;
+}
+/**
+ * Le collatéral est identifié, mais le compte ne porte aucune ligne pour lui.
+ *
+ * ⚠️ Ce n'est **pas** la même chose qu'un solde nul. Hyperliquid n'énumère
+ * que les actifs que le compte a touchés : une absence vaut probablement
+ * zéro, mais « probablement » ne se présente pas comme un solde.
+ */
+ | {
+    status: 'no-balance-entry';
+    mode: AccountAbstractionMode;
+    collateral: string;
+    collateralToken: number | null;
+}
+/**
+ * Le catalogue ne dit pas dans quoi ce marché se règle — nom inconnu, ou
+ * registre pas encore synchronisé.
+ *
+ * Aucune valeur de repli n'est fournie, et c'est le point : la table en dur
+ * que ce contrat remplace répondait « USDC » à cette question.
+ */
+ | {
+    status: 'unknown-collateral';
+    mode: AccountAbstractionMode;
+    asset: string;
+};

package/dist/interfaces/infos/collateral-balance.interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/infos/index.d.ts

@@ -3,3 +3,4 @@ export * from './portfolio.interfaces';
 export * from './l2Book.interfaces';
 export * from './active-asset.interfaces';
 export * from './account-abstraction.type';
+export * from './collateral-balance.interfaces';

package/dist/interfaces/infos/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./portfolio.interfaces"), exports);
 __exportStar(require("./l2Book.interfaces"), exports);
 __exportStar(require("./active-asset.interfaces"), exports);
 __exportStar(require("./account-abstraction.type"), exports);
+__exportStar(require("./collateral-balance.interfaces"), exports);

package/dist/interfaces/perp/meta.interfaces.d.ts

@@ -46,6 +46,29 @@ export interface HLPerpMeta {
     universe: HLPerpMarketInfo[];
     /** Margin configuration tables. */
     marginTables: HLPerpMarginTableEntry[];
+    /**
+     * Index du token qui sert de collatéral à **tout** ce dex — `0` pour USDC.
+     *
+     * C'est la correspondance dex → collatéral que l'exchange publie, et la seule
+     * qui ne vieillit pas. Les trois dépôts en tenaient jusqu'ici une copie en
+     * dur (`cash → USDT`, `hyna → USDE`, sinon USDC) : elle était **juste** quand
+     * elle a été écrite — les marchés Dreamcash s'appelaient bien `TSLA-USDT` et
+     * la marge HyENA était rendue en USDE — mais ces deux dex ont été éteints en
+     * juin et août 2026, et elle ne couvrait de toute façon que 2 des 10 dex
+     * déployés. Relevé le 2026-09-30 : les quatre dex vivants (`xyz`, `para`,
+     * `mkts`, `io`) rendent tous `collateralToken: 0`.
+     *
+     * Un `index`, et non un symbole : c'est ce que fait le calcul officiel du
+     * ratio de compte unifié, qui apparie ensuite `spotBalances[].token`. Deux
+     * tokens peuvent porter le même nom ; aucun ne partage un index. Le symbole
+     * se retrouve dans `spotMeta.tokens[].name`, pour l'affichage seulement.
+     *
+     * ⚠️ Optionnel, bien que l'API le rende sur tous les dex mesurés — y compris
+     * le principal : la doc de `meta` ne le montre pas dans son exemple (celle de
+     * `metaAndAssetCtxs`, si). Une réponse qui ne le porterait pas doit se
+     * traiter comme une absence de réponse, jamais comme « USDC par défaut ».
+     */
+    collateralToken?: number;
 }
 /**
  * Market metadata including its index in the universe list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syldel/hl-shared-types",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",