@blackcube/xgate-sdk 0.21.0 → 0.22.0

package/README.md

@@ -23,10 +23,10 @@ une capacité n'est comptée que si un test réel l'a exercée.
 | **hyperliquid** | ✔ | ✔ | ✔ | ✔ **prouvée** |
 | **pacifica** | ✔ | ✔ | ✔ | ✔ **prouvée** |
 | **aster** | ✔ | ✔ | ✔ | ⚠ **à valider** |
-| lighter | ✔ | — | — | — |
+| lighter | ✔ | ✔ *(sans clé)* | — | — |
 | extended | ✔ | — | — | — |
 | paradex | ✔ | — | — | — |
-| bullet | ✔ | — | — | — |
+| bullet | ✔ *(bougies en WS seulement)* | — | — | — |
 | blofin | ✔ | ✔ | ✔ | — |
 | binance | ✔ *(+ comptant)* | — | — | — |
 | bybit | ✔ *(+ comptant)* | — | — | — |
@@ -41,9 +41,19 @@ sur une ouverture protégée, c'est la position nue que ce paquet existe pour re
 `openWithProtection` y **lève** tant que la preuve manque. Tout le reste (positions, ordres,
 historique, clôture) fonctionne. Détail complet dans le backlog.
 
+**lighter se lit sans aucune clé.** Sa documentation classe `/account`, `accountsByL1Address` et
+`positions` parmi les routes **sans authentification**, et `/account` accepte « an account's index,
+**or L1 address** » : une adresse suffit, comme sur les autres DEX. Son trading, lui, demanderait
+une clé d'API — aucune n'existe aujourd'hui.
+
+**bullet ne sert aucune bougie en REST.** Sa documentation officielle ne comporte aucune section de
+données historiques, et six noms d'endpoint testés répondent tous 404 — son REST existe pourtant
+(`/fapi/v1/depth`, `trades`, `premiumIndex`, `fundingRate`, `ticker/24hr`, `openInterest`). Ses
+bougies passent donc par `WsCandlesService` ; `CandlesService` y lève.
+
 **Les autres sont en lecture.** Elles servent le catalogue, les bougies et les prix ; il leur manque
-un accès de compte (clé d'API pour bullet, adresse active pour lighter, extended et paradex) ou la
-partie signée n'est pas câblée. Binance et bybit sont volontairement limitées au **public** : leurs
+un accès de compte (clé d'API pour bullet, adresse active pour extended et paradex) ou la partie
+signée n'est pas câblée. Binance et bybit sont volontairement limitées au **public** : leurs
 SDK ne couvrent que catalogue, bougies et prix, et toute route signée y lève.
 
 ## Les services
@@ -54,7 +64,8 @@ Chacun est un `@Injectable()` NestJS, utilisable seul ou via `XgateModule`.
 |---|---|
 | `CatalogService` | les paires perpétuelles de toutes les venues, normalisées |
 | `SpotCatalogService` | les paires **comptant** — binance et bybit uniquement |
-| `CandlesService` | les bougies REST, avec agrégation quand la venue ne sert pas l'intervalle |
+| `CandlesService` | les bougies REST **perpétuelles**, avec agrégation quand la venue ne sert pas l'intervalle |
+| `SpotCandlesService` | les bougies REST **comptant** — binance et bybit |
 | `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é |
@@ -70,6 +81,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
@@ -181,6 +215,58 @@ open · partiallyFilled · filled · canceled · rejected · expired · other
 `canceled` prend **un seul L**. Un statut inconnu retombe sur `other` plutôt que de traverser la
 passerelle tel quel : `ORDER_STATUSES` est exporté pour valider plutôt que caster.
 
+## Comptant et perpétuel ne se mélangent pas
+
+Deux services, jamais un drapeau : `CandlesService` sert le perpétuel, `SpotCandlesService` le
+comptant.
+
+```typescript
+await spotCandles.candles(XgateEx.Binance, { symbol: 'BTCUSDT', interval: '1h', limit: 100 });
+await spotCandles.candlesOf([XgateEx.Binance, XgateEx.Bybit], { symbol: 'BTCUSDT', interval: '1h' });
+```
+
+Ce n'est pas de la coquetterie d'API : **les échelles de cotation diffèrent entre les deux
+marchés**. `SATSUSDT` au comptant chez bybit cote ×1 quand son perpétuel cote ×10000 — mélanger les
+deux séries fabrique un graphe qui saute d'un facteur 10 000. Une venue sans comptant lève.
+
+## La semaine s'ouvre le lundi, partout
+
+`hyperliquid` sert des bougies `1w` **alignées sur jeudi** (elle aligne ses seaux sur l'epoch Unix,
+qui tombe un jeudi), là où binance et pacifica ouvrent le lundi. XGate ne les prend donc pas : il
+**reconstruit sa semaine depuis le journalier**, et les bougies rendues portent `derived: true`.
+
+```
+hyperliquid  lun 2026-06-01*  lun 2026-06-08*  lun 2026-06-15*     ← reconstruites
+binance      lun 2026-06-01   lun 2026-06-08   lun 2026-06-15      ← natives
+```
+
+Sans cela, deux séries portant le même intervalle `1w` couvriraient des jours différents et se
+compareraient silencieusement.
+
+## Le catalogue : deux pièges que les venues ne signalent pas
+
+**Le multiplicateur de cotation.** Aucune venue ne le publie — il n'existe que dans le préfixe du
+nom, que le canonique fait disparaître. `IPair.multiplier` le conserve :
+
+```
+SATS   binance:1000SATSUSDT = ×1000   bybit:10000SATSUSDT = ×10000   bybit-spot:SATSUSDT = ×1
+```
+
+Trois échelles pour le même actif sur trois sources. **Une médiane calculée sur ces prix bruts ne
+veut rien dire** ; divisés par `multiplier`, ils redeviennent comparables. 98 lignes du catalogue
+sont concernées.
+
+**Les contrats à échéance.** 44 lignes portent `kind: 'perp'` alors qu'elles expirent, dont neuf
+sur le seul BTC chez bybit. `IPair.expiresAt` les distingue — `undefined` pour un perpétuel.
+
+```typescript
+pairs.filter((pair) => pair.expiresAt === undefined);   // les vrais perpétuels
+```
+
+L'échéance est dérivée du **type de contrat**, jamais de la date de livraison : binance publie
+`deliveryDate: 4133404800000` — le 1ᵉʳ janvier 2100 — sur **tous** ses perpétuels. S'y fier
+marquerait le catalogue entier comme daté.
+
 ## Les conventions qui traversent tout
 
 - **Une bougie inclut sa dernière milliseconde** : 10:00:00.000 → 10:59:59.999. `closedAt` se
@@ -191,6 +277,10 @@ passerelle tel quel : `ORDER_STATUSES` est exporté pour valider plutôt que cas
   compte.
 - **Une taille de position est toujours positive** : le sens est porté par `side`.
 - **Pas de mensuel.** Les intervalles s'arrêtent à `1w`.
+- **Le suffixe d'un symbole n'est pas sa cotation.** bybit nomme ses perpétuels USDC avec `PERP`
+  (`1000BONKPERP` → `BONK`/`USDC`), binance suffixe ses trimestriels par leur date
+  (`BTCUSDT_260925`). XGate lit ce que la venue **déclare** (`baseAsset`, `baseCoin`) plutôt que de
+  re-parser le nom.
 
 ## Versions
 

package/dist/index.cjs

@@ -150,6 +150,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",
@@ -174,13 +176,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) {
@@ -265,6 +280,19 @@ function createAccountXex(xex, access) {
         },
         { default: "a" }
       );
+    case "lighter" /* Lighter */:
+      return new lighterSdk.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(
@@ -305,6 +333,7 @@ var WALLET_XEXES = [
   "hyperliquid" /* Hyperliquid */,
   "pacifica" /* Pacifica */,
   "aster" /* Aster */,
+  "lighter" /* Lighter */,
   "blofin" /* Blofin */
 ];
 function createPublicXex(xex) {
@@ -349,8 +378,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),
@@ -478,6 +510,43 @@ exports.CandlesService = class CandlesService {
 exports.CandlesService = __decorateClass([
   common.Injectable()
 ], exports.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 */]);
 exports.CatalogService = class CatalogService {
   logger = new common.Logger(exports.CatalogService.name);
@@ -523,6 +592,8 @@ exports.CatalogService = class CatalogService {
       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,
@@ -597,6 +668,65 @@ exports.PricesService = class PricesService {
 exports.PricesService = __decorateClass([
   common.Injectable()
 ], exports.PricesService);
+exports.SpotCandlesService = class SpotCandlesService {
+  logger = new common.Logger(exports.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();
+  }
+};
+exports.SpotCandlesService = __decorateClass([
+  common.Injectable()
+], exports.SpotCandlesService);
 exports.SpotCatalogService = class SpotCatalogService {
   logger = new common.Logger(exports.SpotCatalogService.name);
   /** Les venues dont XGate sert le comptant. */
@@ -648,6 +778,9 @@ exports.SpotCatalogService = class SpotCatalogService {
       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,
@@ -1013,8 +1146,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 +1156,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**.
    *
@@ -1171,6 +1345,7 @@ exports.XgateModule = __decorateClass([
       exports.WsCandlesService,
       exports.PricesService,
       exports.SpotCatalogService,
+      exports.SpotCandlesService,
       exports.WalletService
     ],
     exports: [
@@ -1179,6 +1354,7 @@ exports.XgateModule = __decorateClass([
       exports.WsCandlesService,
       exports.PricesService,
       exports.SpotCatalogService,
+      exports.SpotCandlesService,
       exports.WalletService
     ]
   })
@@ -1195,6 +1371,9 @@ exports.buildLevels = buildLevels;
 exports.buildProtection = buildProtection;
 exports.canonicalFromBase = canonicalFromBase;
 exports.canonicalFromXex = canonicalFromXex;
+exports.expiryOf = expiryOf;
+exports.isDated = isDated;
+exports.multiplierFromXex = multiplierFromXex;
 exports.roundPrice = roundPrice;
 exports.roundToStep = roundToStep;
 exports.servesNatively = servesNatively;