@blackcube/xgate-sdk 0.21.0 → 0.22.0

package/dist/index.d.cts

@@ -68,6 +68,23 @@ interface IPair {
     xex: XgateEx;
     /** Type de marché (`perp`/`spot`). */
     kind: MarketKind;
+    /**
+     * FACTEUR D'ÉCHELLE DE COTATION — `1000` pour `kPEPE`, `1000000` pour `1MBABYDOGE`, `1` sinon.
+     *
+     * **Aucune venue ne le publie** : l'information n'existe que dans le préfixe du nom, et le
+     * canonique la fait disparaître. Sans elle, comparer des prix entre venues est faux — `SATS`
+     * porte trois échelles sur quatre sources (×1, ×1000, ×10000). Diviser le prix par ce facteur
+     * ramène toutes les venues à la même unité.
+     */
+    multiplier: number;
+    /**
+     * ÉCHÉANCE du contrat. `undefined` pour un perpétuel — l'immense majorité.
+     *
+     * Un future daté ne cote pas le comptant : sa base peut s'écarter de plusieurs pour cent. Neuf
+     * lignes BTC de bybit sont dans ce cas. Dérivée du **type de contrat**, jamais de la date de
+     * livraison : binance publie l'an 2100 sur ses perpétuels.
+     */
+    expiresAt?: Date;
     /**
      * L'identifiant TECHNIQUE que la venue exige pour agir, quand il diffère du symbole (index de
      * marché chez lighter, index spot chez hyperliquid). `null` quand le symbole suffit.
@@ -407,6 +424,45 @@ declare class SpotCatalogService {
     private catalogOf;
 }
 
+/**
+ * LES BOUGIES DU **COMPTANT**, en REST — binance et bybit.
+ *
+ * **Un service à part, et non un drapeau sur {@link CandlesService}.** C'est la même règle que pour
+ * le catalogue : un `candles()` qui servirait tantôt du perpétuel tantôt du comptant selon un
+ * paramètre produirait des erreurs silencieuses — on croirait lire des perpétuels et on lirait du
+ * comptant, sans que rien ne le signale. Deux marchés, deux services ; l'appelant choisit
+ * explicitement ce qu'il interroge.
+ *
+ * La différence n'est pas cosmétique : le perpétuel porte un funding et peut s'écarter du comptant,
+ * et **les échelles de cotation diffèrent d'un marché à l'autre** — `SATSUSDT` au comptant chez
+ * bybit cote ×1 quand son perpétuel cote ×10000. Mélanger les deux séries fabriquerait un graphe
+ * qui saute d'un facteur 10 000.
+ *
+ * **Aucune agrégation ici**, contrairement au perpétuel : binance et bybit servent nativement tous
+ * les intervalles de `1m` à `1w`. Le jour où une venue comptant en manquerait un, ce serait à
+ * ajouter — pas à supposer.
+ */
+declare class SpotCandlesService {
+    private readonly logger;
+    /** Les venues dont XGate sert le comptant. */
+    venues(): readonly XgateEx[];
+    /**
+     * Les bougies comptant d'une venue, sur une plage de **dates**.
+     *
+     * **Lève** si la venue ne sert pas de comptant, plutôt que de rendre une liste vide : « cette
+     * venue n'a pas de marché comptant » et « ce marché n'a pas coté » appellent des suites très
+     * différentes.
+     */
+    candles(xex: XgateEx, query: ICandlesQuery): Promise<ICandle[]>;
+    /**
+     * Les bougies comptant d'un même marché chez PLUSIEURS venues, en une liste.
+     *
+     * Même politique d'échec que partout ailleurs : seule, une venue en échec fait échouer l'appel ;
+     * parmi d'autres, elle est journalisée et ignorée. Chaque bougie porte son `xex`.
+     */
+    candlesOf(xexes: XgateEx[], query: ICandlesQuery): Promise<ICandle[]>;
+}
+
 /** Une paire, telle qu'un SDK de venue la rend. */
 interface IXexPair {
     name: string;
@@ -535,7 +591,7 @@ interface IXexAccess {
  * Les venues dont XGate sait lire le portefeuille aujourd'hui.
  *
  * Les autres ne sont pas exclues par principe : il leur manque un accès (clé d'API pour bullet, une
- * adresse active pour lighter, extended et paradex). Voir le backlog.
+ * adresse active pour extended et paradex). Voir le backlog.
  */
 declare const WALLET_XEXES: readonly XgateEx[];
 /**
@@ -660,6 +716,22 @@ declare class WalletService {
      * regarde autrement qu'une panne.
      */
     balances(...accesses: IWalletAccess[]): Promise<IBalance[]>;
+    /**
+     * 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`.
+     */
+    private perpCollateral;
     /**
      * Les mouvements d'argent, triés du plus ancien au plus récent, montants **signés**.
      *
@@ -1088,5 +1160,48 @@ declare function canonicalFromXex(rawSymbol: string, xexId: string): string;
  * symbole.
  */
 declare function canonicalFromBase(base: string): string;
+/**
+ * LE MULTIPLICATEUR DE COTATION, extrait du nom — **la seule source qui existe**.
+ *
+ * Aucune venue ne le publie : `kPEPE` chez hyperliquid ne porte que `{"marginTableId":52}`,
+ * `1000PEPEUSDT` chez binance ne mentionne aucun facteur. L'information n'est QUE dans le préfixe
+ * du nom, et le canonique la fait disparaître — jusqu'ici sans la conserver nulle part.
+ *
+ * Or elle est indispensable dès qu'on compare des prix entre venues. `SATS` porte **trois échelles
+ * différentes sur quatre sources** : `SATSUSDT` (×1) chez bybit-spot, `1000SATSUSDT` (×1000) chez
+ * binance, `10000SATSUSDT` (×10000) chez bybit. Une médiane calculée sur ces prix bruts ne veut
+ * rien dire ; divisés par leur facteur, ils redeviennent comparables.
+ *
+ * Rend `1` quand le nom ne porte aucune échelle — le cas de l'immense majorité.
+ */
+declare function multiplierFromXex(rawSymbol: string): number;
+
+/**
+ * LES CONTRATS À ÉCHÉANCE, séparés des perpétuels — parce qu'un future daté ne cote pas le comptant.
+ *
+ * Le catalogue les mélangeait : 44 lignes portaient `kind: 'perp'` alors qu'elles expirent, dont
+ * neuf sur le seul BTC chez bybit. Un consommateur qui prend « le prix du BTC » y ramassait une
+ * échéance de décembre, dont la base au comptant peut s'écarter de plusieurs pour cent.
+ *
+ * **`contractType` fait foi, JAMAIS la date de livraison.** binance publie `deliveryDate:
+ * 4133404800000` — le 1er janvier 2100 — sur ses **perpétuels** : s'y fier marquerait tout le
+ * catalogue comme daté. bybit, lui, met `deliveryTime: '0'` sur les siens. Deux conventions
+ * incompatibles pour dire « ceci n'expire pas », d'où la lecture du type et de lui seul.
+ */
+/**
+ * L'ÉCHÉANCE D'UN CONTRAT, ou `undefined` s'il est perpétuel.
+ *
+ * On ne lit la date **que** si le type de contrat annonce une échéance : c'est ce qui neutralise le
+ * `deliveryDate` de l'an 2100 des perpétuels binance. Un type inconnu est traité comme perpétuel —
+ * l'immense majorité des lignes, et se tromper dans ce sens n'invente pas d'échéance.
+ */
+declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
+/**
+ * LE CONTRAT EXPIRE-T-IL ? Vrai pour un future daté, faux pour un perpétuel.
+ *
+ * Séparé d'{@link expiryOf} à dessein : une venue peut annoncer un type daté sans publier de date
+ * exploitable, et il faut alors pouvoir écarter la ligne quand même.
+ */
+declare function isDated(xtras?: Record<string, unknown>): boolean;
 
-export { CandlesService, CatalogService, type Direction, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, SPOT_XEXES, type Side, SpotCatalogService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, timeframeMs };
+export { CandlesService, CatalogService, type Direction, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, timeframeMs };

package/dist/index.d.ts

@@ -68,6 +68,23 @@ interface IPair {
     xex: XgateEx;
     /** Type de marché (`perp`/`spot`). */
     kind: MarketKind;
+    /**
+     * FACTEUR D'ÉCHELLE DE COTATION — `1000` pour `kPEPE`, `1000000` pour `1MBABYDOGE`, `1` sinon.
+     *
+     * **Aucune venue ne le publie** : l'information n'existe que dans le préfixe du nom, et le
+     * canonique la fait disparaître. Sans elle, comparer des prix entre venues est faux — `SATS`
+     * porte trois échelles sur quatre sources (×1, ×1000, ×10000). Diviser le prix par ce facteur
+     * ramène toutes les venues à la même unité.
+     */
+    multiplier: number;
+    /**
+     * ÉCHÉANCE du contrat. `undefined` pour un perpétuel — l'immense majorité.
+     *
+     * Un future daté ne cote pas le comptant : sa base peut s'écarter de plusieurs pour cent. Neuf
+     * lignes BTC de bybit sont dans ce cas. Dérivée du **type de contrat**, jamais de la date de
+     * livraison : binance publie l'an 2100 sur ses perpétuels.
+     */
+    expiresAt?: Date;
     /**
      * L'identifiant TECHNIQUE que la venue exige pour agir, quand il diffère du symbole (index de
      * marché chez lighter, index spot chez hyperliquid). `null` quand le symbole suffit.
@@ -407,6 +424,45 @@ declare class SpotCatalogService {
     private catalogOf;
 }
 
+/**
+ * LES BOUGIES DU **COMPTANT**, en REST — binance et bybit.
+ *
+ * **Un service à part, et non un drapeau sur {@link CandlesService}.** C'est la même règle que pour
+ * le catalogue : un `candles()` qui servirait tantôt du perpétuel tantôt du comptant selon un
+ * paramètre produirait des erreurs silencieuses — on croirait lire des perpétuels et on lirait du
+ * comptant, sans que rien ne le signale. Deux marchés, deux services ; l'appelant choisit
+ * explicitement ce qu'il interroge.
+ *
+ * La différence n'est pas cosmétique : le perpétuel porte un funding et peut s'écarter du comptant,
+ * et **les échelles de cotation diffèrent d'un marché à l'autre** — `SATSUSDT` au comptant chez
+ * bybit cote ×1 quand son perpétuel cote ×10000. Mélanger les deux séries fabriquerait un graphe
+ * qui saute d'un facteur 10 000.
+ *
+ * **Aucune agrégation ici**, contrairement au perpétuel : binance et bybit servent nativement tous
+ * les intervalles de `1m` à `1w`. Le jour où une venue comptant en manquerait un, ce serait à
+ * ajouter — pas à supposer.
+ */
+declare class SpotCandlesService {
+    private readonly logger;
+    /** Les venues dont XGate sert le comptant. */
+    venues(): readonly XgateEx[];
+    /**
+     * Les bougies comptant d'une venue, sur une plage de **dates**.
+     *
+     * **Lève** si la venue ne sert pas de comptant, plutôt que de rendre une liste vide : « cette
+     * venue n'a pas de marché comptant » et « ce marché n'a pas coté » appellent des suites très
+     * différentes.
+     */
+    candles(xex: XgateEx, query: ICandlesQuery): Promise<ICandle[]>;
+    /**
+     * Les bougies comptant d'un même marché chez PLUSIEURS venues, en une liste.
+     *
+     * Même politique d'échec que partout ailleurs : seule, une venue en échec fait échouer l'appel ;
+     * parmi d'autres, elle est journalisée et ignorée. Chaque bougie porte son `xex`.
+     */
+    candlesOf(xexes: XgateEx[], query: ICandlesQuery): Promise<ICandle[]>;
+}
+
 /** Une paire, telle qu'un SDK de venue la rend. */
 interface IXexPair {
     name: string;
@@ -535,7 +591,7 @@ interface IXexAccess {
  * Les venues dont XGate sait lire le portefeuille aujourd'hui.
  *
  * Les autres ne sont pas exclues par principe : il leur manque un accès (clé d'API pour bullet, une
- * adresse active pour lighter, extended et paradex). Voir le backlog.
+ * adresse active pour extended et paradex). Voir le backlog.
  */
 declare const WALLET_XEXES: readonly XgateEx[];
 /**
@@ -660,6 +716,22 @@ declare class WalletService {
      * regarde autrement qu'une panne.
      */
     balances(...accesses: IWalletAccess[]): Promise<IBalance[]>;
+    /**
+     * 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`.
+     */
+    private perpCollateral;
     /**
      * Les mouvements d'argent, triés du plus ancien au plus récent, montants **signés**.
      *
@@ -1088,5 +1160,48 @@ declare function canonicalFromXex(rawSymbol: string, xexId: string): string;
  * symbole.
  */
 declare function canonicalFromBase(base: string): string;
+/**
+ * LE MULTIPLICATEUR DE COTATION, extrait du nom — **la seule source qui existe**.
+ *
+ * Aucune venue ne le publie : `kPEPE` chez hyperliquid ne porte que `{"marginTableId":52}`,
+ * `1000PEPEUSDT` chez binance ne mentionne aucun facteur. L'information n'est QUE dans le préfixe
+ * du nom, et le canonique la fait disparaître — jusqu'ici sans la conserver nulle part.
+ *
+ * Or elle est indispensable dès qu'on compare des prix entre venues. `SATS` porte **trois échelles
+ * différentes sur quatre sources** : `SATSUSDT` (×1) chez bybit-spot, `1000SATSUSDT` (×1000) chez
+ * binance, `10000SATSUSDT` (×10000) chez bybit. Une médiane calculée sur ces prix bruts ne veut
+ * rien dire ; divisés par leur facteur, ils redeviennent comparables.
+ *
+ * Rend `1` quand le nom ne porte aucune échelle — le cas de l'immense majorité.
+ */
+declare function multiplierFromXex(rawSymbol: string): number;
+
+/**
+ * LES CONTRATS À ÉCHÉANCE, séparés des perpétuels — parce qu'un future daté ne cote pas le comptant.
+ *
+ * Le catalogue les mélangeait : 44 lignes portaient `kind: 'perp'` alors qu'elles expirent, dont
+ * neuf sur le seul BTC chez bybit. Un consommateur qui prend « le prix du BTC » y ramassait une
+ * échéance de décembre, dont la base au comptant peut s'écarter de plusieurs pour cent.
+ *
+ * **`contractType` fait foi, JAMAIS la date de livraison.** binance publie `deliveryDate:
+ * 4133404800000` — le 1er janvier 2100 — sur ses **perpétuels** : s'y fier marquerait tout le
+ * catalogue comme daté. bybit, lui, met `deliveryTime: '0'` sur les siens. Deux conventions
+ * incompatibles pour dire « ceci n'expire pas », d'où la lecture du type et de lui seul.
+ */
+/**
+ * L'ÉCHÉANCE D'UN CONTRAT, ou `undefined` s'il est perpétuel.
+ *
+ * On ne lit la date **que** si le type de contrat annonce une échéance : c'est ce qui neutralise le
+ * `deliveryDate` de l'an 2100 des perpétuels binance. Un type inconnu est traité comme perpétuel —
+ * l'immense majorité des lignes, et se tromper dans ce sens n'invente pas d'échéance.
+ */
+declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
+/**
+ * LE CONTRAT EXPIRE-T-IL ? Vrai pour un future daté, faux pour un perpétuel.
+ *
+ * Séparé d'{@link expiryOf} à dessein : une venue peut annoncer un type daté sans publier de date
+ * exploitable, et il faut alors pouvoir écarter la ligne quand même.
+ */
+declare function isDated(xtras?: Record<string, unknown>): boolean;
 
-export { CandlesService, CatalogService, type Direction, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, SPOT_XEXES, type Side, SpotCatalogService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, timeframeMs };
+export { CandlesService, CatalogService, type Direction, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, timeframeMs };

package/dist/index.js

@@ -148,6 +148,8 @@ function sum(left, right) {
 var CONCAT_QUOTE_XEXS = /* @__PURE__ */ new Set(["aster", "binance", "bybit"]);
 var K_MULTIPLIER = /^k(?=[A-Z])/u;
 var NUMERIC_MULTIPLIER = /^10{3,}(?=[A-Z0-9])/u;
+var ABBREV_MULTIPLIER = /^1([MK])(?=[A-Z]{2,})/u;
+var ABBREV_FACTOR = { M: 1e6, K: 1e3 };
 var STOCK_24_5 = /_24_5$/u;
 var TICKER_ALIASES = {
   GOOG: "GOOGL",
@@ -172,13 +174,26 @@ function canonicalFromXex(rawSymbol, xexId) {
     s = s.replace(/-USD-PERP$/u, "").replace(/-PERP$/u, "").replace(/-USDT$/u, "").replace(/-USDC$/u, "").replace(/-USD$/u, "");
   }
   s = s.replace(NUMERIC_MULTIPLIER, "");
+  s = s.replace(ABBREV_MULTIPLIER, "");
   s = s.replace(STOCK_24_5, "");
   return TICKER_ALIASES[s] ?? s;
 }
 function canonicalFromBase(base) {
-  const s = base.replace(K_MULTIPLIER, "").toUpperCase().replace(NUMERIC_MULTIPLIER, "").replace(STOCK_24_5, "");
+  const s = base.replace(K_MULTIPLIER, "").toUpperCase().replace(NUMERIC_MULTIPLIER, "").replace(ABBREV_MULTIPLIER, "").replace(STOCK_24_5, "");
   return TICKER_ALIASES[s] ?? s;
 }
+function multiplierFromXex(rawSymbol) {
+  if (K_MULTIPLIER.test(rawSymbol)) {
+    return 1e3;
+  }
+  const upper = rawSymbol.toUpperCase();
+  const abbrev = ABBREV_MULTIPLIER.exec(upper);
+  if (abbrev !== null) {
+    return ABBREV_FACTOR[abbrev[1]] ?? 1;
+  }
+  const zeros = NUMERIC_MULTIPLIER.exec(upper);
+  return zeros === null ? 1 : Number(zeros[0]);
+}
 
 // src/helpers/candle-mapper.ts
 function toCandle(wire, xex, interval, quote) {
@@ -263,6 +278,19 @@ function createAccountXex(xex, access) {
         },
         { default: "a" }
       );
+    case "lighter" /* Lighter */:
+      return new Lighter(
+        {
+          a: {
+            apiPrivateKey: access.privateKey ?? NULL_KEY,
+            apiKeyIndex: access.apiKeyIndex ?? 0,
+            accountIndex: access.accountIndex ?? 0,
+            l1Address: adresse(),
+            network: access.network ?? "mainnet"
+          }
+        },
+        { default: "a" }
+      );
     case "aster" /* Aster */:
       if (access.privateKey === void 0 || access.privateKey === "") {
         throw new Error(
@@ -303,6 +331,7 @@ var WALLET_XEXES = [
   "hyperliquid" /* Hyperliquid */,
   "pacifica" /* Pacifica */,
   "aster" /* Aster */,
+  "lighter" /* Lighter */,
   "blofin" /* Blofin */
 ];
 function createPublicXex(xex) {
@@ -347,8 +376,11 @@ function createPublicSpotXex(xex) {
 }
 
 // src/helpers/xex-timeframes.ts
+var HYPERLIQUID_NATIVE = Object.values(Timeframe).filter(
+  (interval) => interval !== "1w" /* W */
+);
 var NATIVE = {
-  ["hyperliquid" /* Hyperliquid */]: Object.values(Timeframe),
+  ["hyperliquid" /* Hyperliquid */]: HYPERLIQUID_NATIVE,
   ["pacifica" /* Pacifica */]: Object.values(Timeframe),
   ["aster" /* Aster */]: Object.values(Timeframe),
   ["blofin" /* Blofin */]: Object.values(Timeframe),
@@ -476,6 +508,43 @@ var CandlesService = class {
 CandlesService = __decorateClass([
   Injectable()
 ], CandlesService);
+
+// src/helpers/contract-expiry.ts
+var DATED_CONTRACT_TYPES = /* @__PURE__ */ new Set([
+  // binance : les trimestriels (`BTCUSDT_260925`, `ETHUSDT_261225`).
+  "CURRENT_QUARTER",
+  "NEXT_QUARTER",
+  "CURRENT_QUARTER_DELIVERING",
+  "NEXT_QUARTER_DELIVERING",
+  "PERPETUAL_DELIVERING",
+  // bybit : les datés (`BTCUSDT-25DEC26`), face à `LinearPerpetual`.
+  "LinearFutures",
+  "InverseFutures"
+]);
+var EXPIRY_FIELDS = ["deliveryTime", "deliveryDate", "expiryTime", "settleTime"];
+function expiryOf(xtras) {
+  if (xtras === void 0) {
+    return void 0;
+  }
+  const type = xtras.contractType;
+  if (typeof type !== "string" || DATED_CONTRACT_TYPES.has(type) === false) {
+    return void 0;
+  }
+  for (const field of EXPIRY_FIELDS) {
+    const brut = xtras[field];
+    const ms = typeof brut === "string" ? Number(brut) : brut;
+    if (typeof ms === "number" && Number.isFinite(ms) === true && ms > 0) {
+      return new Date(ms);
+    }
+  }
+  return void 0;
+}
+function isDated(xtras) {
+  const type = xtras?.contractType;
+  return typeof type === "string" && DATED_CONTRACT_TYPES.has(type);
+}
+
+// src/services/catalog.service.ts
 var NAMES_ITS_BASE = /* @__PURE__ */ new Set(["binance" /* Binance */, "bybit" /* Bybit */]);
 var CatalogService = class {
   logger = new Logger(CatalogService.name);
@@ -521,6 +590,8 @@ var CatalogService = class {
       symbolXex: pair.name,
       xex,
       kind: pair.kind,
+      multiplier: multiplierFromXex(pair.name),
+      expiresAt: expiryOf(pair.xtras),
       ref: pair.ref ?? null,
       szDecimals: pair.szDecimals,
       tickSize: pair.tickSize,
@@ -595,6 +666,65 @@ var PricesService = class {
 PricesService = __decorateClass([
   Injectable()
 ], PricesService);
+var SpotCandlesService = class {
+  logger = new Logger(SpotCandlesService.name);
+  /** Les venues dont XGate sert le comptant. */
+  venues() {
+    return SPOT_XEXES;
+  }
+  /**
+   * Les bougies comptant d'une venue, sur une plage de **dates**.
+   *
+   * **Lève** si la venue ne sert pas de comptant, plutôt que de rendre une liste vide : « cette
+   * venue n'a pas de marché comptant » et « ce marché n'a pas coté » appellent des suites très
+   * différentes.
+   */
+  async candles(xex, query) {
+    if (servesSpot(xex) === false) {
+      throw new Error(
+        `spotCandles(${xex}) : cette venue ne sert pas de comptant. Disponibles : ${SPOT_XEXES.join(", ")}.`
+      );
+    }
+    const spot = createPublicSpotXex(xex).spot();
+    if (spot.getCandles === void 0) {
+      throw new Error(`spotCandles(${xex}) : cette venue ne sert pas de bougies comptant en REST.`);
+    }
+    const wires = await spot.getCandles(toXexQuery(query));
+    return wires.map((wire) => toCandle(wire, xex, query.interval, ""));
+  }
+  /**
+   * Les bougies comptant d'un même marché chez PLUSIEURS venues, en une liste.
+   *
+   * Même politique d'échec que partout ailleurs : seule, une venue en échec fait échouer l'appel ;
+   * parmi d'autres, elle est journalisée et ignorée. Chaque bougie porte son `xex`.
+   */
+  async candlesOf(xexes, query) {
+    if (xexes.length === 0) {
+      throw new Error("spotCandlesOf() : aucune venue demand\xE9e \u2014 pr\xE9cise au moins un XgateEx.");
+    }
+    const solo = xexes.length === 1;
+    const collected = await Promise.all(
+      xexes.map(async (xex) => {
+        try {
+          return await this.candles(xex, query);
+        } catch (error) {
+          if (solo === true) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          this.logger.error(
+            `spotCandles(${xex}, ${query.interval}) a \xE9chou\xE9, venue ignor\xE9e : ${message}`
+          );
+          return [];
+        }
+      })
+    );
+    return collected.flat();
+  }
+};
+SpotCandlesService = __decorateClass([
+  Injectable()
+], SpotCandlesService);
 var SpotCatalogService = class {
   logger = new Logger(SpotCatalogService.name);
   /** Les venues dont XGate sert le comptant. */
@@ -646,6 +776,9 @@ var SpotCatalogService = class {
       symbolXex: pair.name,
       xex,
       kind: pair.kind,
+      // Le comptant porte les mêmes échelles que le perp : `SATSUSDT` (×1) et `1000SATSUSDT`
+      // coexistent, et c'est justement entre eux que la comparaison serait fausse.
+      multiplier: multiplierFromXex(pair.name),
       ref: pair.ref ?? null,
       szDecimals: pair.szDecimals,
       tickSize: pair.tickSize,
@@ -1011,8 +1144,9 @@ var WalletService = class {
    */
   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,
@@ -1020,8 +1154,48 @@ var WalletService = class {
         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**.
    *
@@ -1169,6 +1343,7 @@ XgateModule = __decorateClass([
       WsCandlesService,
       PricesService,
       SpotCatalogService,
+      SpotCandlesService,
       WalletService
     ],
     exports: [
@@ -1177,11 +1352,12 @@ XgateModule = __decorateClass([
       WsCandlesService,
       PricesService,
       SpotCatalogService,
+      SpotCandlesService,
       WalletService
     ]
   })
 ], XgateModule);
 
-export { CandlesService, CatalogService, ORDER_STATUSES, PricesService, SPOT_XEXES, SpotCatalogService, TIMEFRAME_MINUTES, Timeframe, TradingService, WALLET_XEXES, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, timeframeMs };
+export { CandlesService, CatalogService, ORDER_STATUSES, PricesService, SPOT_XEXES, SpotCandlesService, SpotCatalogService, TIMEFRAME_MINUTES, Timeframe, TradingService, WALLET_XEXES, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, timeframeMs };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map