@blackcube/xgate-sdk 0.25.4 → 0.56.0

package/dist/index.d.cts

@@ -39,6 +39,37 @@ declare enum XgateEx {
 /** Toutes les venues connues, dans l'ordre de déclaration. */
 declare const XGATE_EXCHANGES: readonly XgateEx[];
 
+/**
+ * CE QUE COTE UNE PAIRE — de la crypto, ou autre chose.
+ *
+ * Les venues perpétuelles ne listent plus seulement des cryptos : bybit publie 164 actions, 43 ETF et
+ * quatre matières premières, binance ouvre des `TRADIFI_PERPETUAL` sur NVDA et l'or, extended range
+ * ses actions en `RWA`. Le catalogue les rendait toutes indistinctes.
+ *
+ * ⚠️ CE N'EST PAS UNE COMMODITÉ DE CLASSEMENT. Le 2026-08-24, `PURR` cotait 11 $ chez bybit et
+ * 0,13 $ chez hyperliquid : le premier est une ACTION, le second le memecoin natif d'Hyperliquid.
+ * Même ticker, deux actifs — et un consommateur qui médiane « le prix de PURR » entre venues
+ * publiait un nombre qui n'était le prix d'aucun des deux. Le rapport n'était même pas constant
+ * (71 à 116 sur douze jours), ce qui excluait une échelle de cotation.
+ *
+ * ⚠️ ET CE N'EST PAS DÉDUCTIBLE DU TICKER. `SPX` est le memecoin SPX6900 chez binance, bybit et
+ * extended — qui le disent tous les trois (`underlyingSubType: ["Meme"]`, `subCategory: "Meme"`) —
+ * alors que l'indice S&P 500 s'appelle `SP500` chez pacifica. Une règle sur le nom aurait classé les
+ * deux à l'envers.
+ */
+type AssetClass = 'crypto' | 'stock' | 'commodity' | 'index' | 'etf' | 'forex';
+/**
+ * LA CLASSE D'ACTIF D'UNE PAIRE, ou `undefined` quand la venue ne se prononce pas.
+ *
+ * ⚠️ `undefined` N'EST PAS « CRYPTO ». hyperliquid et pacifica cotent NVDA, TSLA, XAU et PLTR sans
+ * publier la moindre catégorie : les classer d'office en crypto reproduirait exactement l'erreur
+ * qu'on corrige ici. « On ne sait pas » est une information ; une valeur inventée n'en est pas une.
+ *
+ * Une catégorie inconnue rend `undefined` plutôt que de retomber sur `crypto` — le jour où une venue
+ * en ajoute une, on veut le voir, pas l'absorber.
+ */
+declare function assetClassOf(xex: XgateEx, xtras?: Record<string, unknown>): AssetClass | undefined;
+
 /** Type de marché. */
 type MarketKind = 'perp' | 'spot';
 /**
@@ -77,6 +108,18 @@ interface IPair {
      * ramène toutes les venues à la même unité.
      */
     multiplier: number;
+    /**
+     * CE QUE LA PAIRE COTE — `undefined` quand la venue ne le dit pas.
+     *
+     * Les venues perpétuelles ne listent plus que de la crypto : bybit publie 164 actions, 43 ETF et
+     * quatre matières premières, binance ouvre des `TRADIFI_PERPETUAL` sur NVDA et l'or. Sans ce
+     * champ, un consommateur mélange deux actifs qui partagent un ticker — `PURR` valait 11 $ chez
+     * bybit (une ACTION) et 0,13 $ chez hyperliquid (le memecoin) le 2026-08-24.
+     *
+     * ⚠️ `undefined` NE VEUT PAS DIRE « crypto ». hyperliquid et pacifica cotent NVDA, TSLA et XAU
+     * sans publier de catégorie : les supposer crypto referait l'erreur qu'on corrige.
+     */
+    assetClass?: AssetClass;
     /**
      * ÉCHÉANCE du contrat. `undefined` pour un perpétuel — l'immense majorité.
      *
@@ -480,10 +523,23 @@ declare function subscriptionLimitOf(xex: XgateEx): number | undefined;
  *
  * **aster** — 1500 ; non documenté, API de forme binance.
  *
- * **hyperliquid** et **pacifica** n'acceptent AUCUN `limit` : leurs SDK n'envoient que `startTime`/`endTime`
- * (`get-candle-snapshot.ts`, `get-candle-data.ts`). Le nombre sert alors à dimensionner la FENÊTRE demandée, pas
- * à remplir un paramètre. Pour hyperliquid, la venue borne d'elle-même à ~5 000 bougies par (coin, intervalle) —
- * et l'horizon que ça couvre dépend de l'activité du coin, ce n'est donc pas une durée fixe.
+ * **pacifica** — **4 000**, et c'est SA DOCUMENTATION qui le dit : « `limit` : Capped at 4000; defaults to 4000
+ * if not provided » (`docs.pacifica.fi/api-documentation/api/rest-api/markets/get-candle-data`). Le plafond joue
+ * même sans `limit`, puisque 4 000 est aussi le défaut.
+ *
+ * ⚠️ AU-DELÀ, ELLE NE TRONQUE PAS : ELLE REND UN TABLEAU VIDE, avec `success: true`. Vérifié le 2026-08-24 sur
+ * SOL en 15m — 4 000 barres demandées rendent 3 883 bougies, 4 010 en rendent ZÉRO. Une fenêtre trop large ne
+ * coûte donc pas quelques barres perdues, elle coûte l'appel entier, en silence.
+ *
+ * ⚠️ CETTE ENTRÉE A VALU 500 PENDANT DES MOIS, sur la foi du commentaire ci-dessous qui affirmait que pacifica
+ * « n'accepte aucun limit ». C'est faux : son endpoint le documente. Huit fois trop d'appels, à quatre secondes
+ * de cadence chacun — mesuré le 2026-08-24, un backfill 15m sur ses 74 séries a coûté 1 026 appels et 72
+ * minutes là où il en fallait huit fois moins.
+ *
+ * **hyperliquid** n'accepte, elle, aucun `limit` : son SDK n'envoie que `startTime`/`endTime`
+ * (`get-candle-snapshot.ts`). Le nombre sert alors à dimensionner la FENÊTRE demandée, pas à remplir un
+ * paramètre. La venue borne d'elle-même à ~5 000 bougies par (coin, intervalle) — et l'horizon que ça couvre
+ * dépend de l'activité du coin, ce n'est donc pas une durée fixe.
  *
  * ⚠️ UNE VENUE ABSENTE DE CETTE TABLE N'A PAS DE PLAFOND DOCUMENTÉ — ce qui n'est pas « pas de plafond ». On ne
  * devine aucun chiffre : le jour où l'une d'elles s'en approche, on lit sa documentation et on l'ajoute.
@@ -1844,4 +1900,4 @@ declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
  */
 declare function isDated(xtras?: Record<string, unknown>): boolean;
 
-export { CANDLES_MAX_HISTORY, CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, type Direction, type IAccountState, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IFundingPaid, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type IPublicTrade, type ITarget, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, REST_THROTTLE_MS, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, candlesMaxHistoryOf, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };
+export { type AssetClass, CANDLES_MAX_HISTORY, CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, type Direction, type IAccountState, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IFundingPaid, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type IPublicTrade, type ITarget, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, REST_THROTTLE_MS, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, assetClassOf, buildLevels, buildProtection, candlesMaxHistoryOf, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };

package/dist/index.d.ts

@@ -39,6 +39,37 @@ declare enum XgateEx {
 /** Toutes les venues connues, dans l'ordre de déclaration. */
 declare const XGATE_EXCHANGES: readonly XgateEx[];
 
+/**
+ * CE QUE COTE UNE PAIRE — de la crypto, ou autre chose.
+ *
+ * Les venues perpétuelles ne listent plus seulement des cryptos : bybit publie 164 actions, 43 ETF et
+ * quatre matières premières, binance ouvre des `TRADIFI_PERPETUAL` sur NVDA et l'or, extended range
+ * ses actions en `RWA`. Le catalogue les rendait toutes indistinctes.
+ *
+ * ⚠️ CE N'EST PAS UNE COMMODITÉ DE CLASSEMENT. Le 2026-08-24, `PURR` cotait 11 $ chez bybit et
+ * 0,13 $ chez hyperliquid : le premier est une ACTION, le second le memecoin natif d'Hyperliquid.
+ * Même ticker, deux actifs — et un consommateur qui médiane « le prix de PURR » entre venues
+ * publiait un nombre qui n'était le prix d'aucun des deux. Le rapport n'était même pas constant
+ * (71 à 116 sur douze jours), ce qui excluait une échelle de cotation.
+ *
+ * ⚠️ ET CE N'EST PAS DÉDUCTIBLE DU TICKER. `SPX` est le memecoin SPX6900 chez binance, bybit et
+ * extended — qui le disent tous les trois (`underlyingSubType: ["Meme"]`, `subCategory: "Meme"`) —
+ * alors que l'indice S&P 500 s'appelle `SP500` chez pacifica. Une règle sur le nom aurait classé les
+ * deux à l'envers.
+ */
+type AssetClass = 'crypto' | 'stock' | 'commodity' | 'index' | 'etf' | 'forex';
+/**
+ * LA CLASSE D'ACTIF D'UNE PAIRE, ou `undefined` quand la venue ne se prononce pas.
+ *
+ * ⚠️ `undefined` N'EST PAS « CRYPTO ». hyperliquid et pacifica cotent NVDA, TSLA, XAU et PLTR sans
+ * publier la moindre catégorie : les classer d'office en crypto reproduirait exactement l'erreur
+ * qu'on corrige ici. « On ne sait pas » est une information ; une valeur inventée n'en est pas une.
+ *
+ * Une catégorie inconnue rend `undefined` plutôt que de retomber sur `crypto` — le jour où une venue
+ * en ajoute une, on veut le voir, pas l'absorber.
+ */
+declare function assetClassOf(xex: XgateEx, xtras?: Record<string, unknown>): AssetClass | undefined;
+
 /** Type de marché. */
 type MarketKind = 'perp' | 'spot';
 /**
@@ -77,6 +108,18 @@ interface IPair {
      * ramène toutes les venues à la même unité.
      */
     multiplier: number;
+    /**
+     * CE QUE LA PAIRE COTE — `undefined` quand la venue ne le dit pas.
+     *
+     * Les venues perpétuelles ne listent plus que de la crypto : bybit publie 164 actions, 43 ETF et
+     * quatre matières premières, binance ouvre des `TRADIFI_PERPETUAL` sur NVDA et l'or. Sans ce
+     * champ, un consommateur mélange deux actifs qui partagent un ticker — `PURR` valait 11 $ chez
+     * bybit (une ACTION) et 0,13 $ chez hyperliquid (le memecoin) le 2026-08-24.
+     *
+     * ⚠️ `undefined` NE VEUT PAS DIRE « crypto ». hyperliquid et pacifica cotent NVDA, TSLA et XAU
+     * sans publier de catégorie : les supposer crypto referait l'erreur qu'on corrige.
+     */
+    assetClass?: AssetClass;
     /**
      * ÉCHÉANCE du contrat. `undefined` pour un perpétuel — l'immense majorité.
      *
@@ -480,10 +523,23 @@ declare function subscriptionLimitOf(xex: XgateEx): number | undefined;
  *
  * **aster** — 1500 ; non documenté, API de forme binance.
  *
- * **hyperliquid** et **pacifica** n'acceptent AUCUN `limit` : leurs SDK n'envoient que `startTime`/`endTime`
- * (`get-candle-snapshot.ts`, `get-candle-data.ts`). Le nombre sert alors à dimensionner la FENÊTRE demandée, pas
- * à remplir un paramètre. Pour hyperliquid, la venue borne d'elle-même à ~5 000 bougies par (coin, intervalle) —
- * et l'horizon que ça couvre dépend de l'activité du coin, ce n'est donc pas une durée fixe.
+ * **pacifica** — **4 000**, et c'est SA DOCUMENTATION qui le dit : « `limit` : Capped at 4000; defaults to 4000
+ * if not provided » (`docs.pacifica.fi/api-documentation/api/rest-api/markets/get-candle-data`). Le plafond joue
+ * même sans `limit`, puisque 4 000 est aussi le défaut.
+ *
+ * ⚠️ AU-DELÀ, ELLE NE TRONQUE PAS : ELLE REND UN TABLEAU VIDE, avec `success: true`. Vérifié le 2026-08-24 sur
+ * SOL en 15m — 4 000 barres demandées rendent 3 883 bougies, 4 010 en rendent ZÉRO. Une fenêtre trop large ne
+ * coûte donc pas quelques barres perdues, elle coûte l'appel entier, en silence.
+ *
+ * ⚠️ CETTE ENTRÉE A VALU 500 PENDANT DES MOIS, sur la foi du commentaire ci-dessous qui affirmait que pacifica
+ * « n'accepte aucun limit ». C'est faux : son endpoint le documente. Huit fois trop d'appels, à quatre secondes
+ * de cadence chacun — mesuré le 2026-08-24, un backfill 15m sur ses 74 séries a coûté 1 026 appels et 72
+ * minutes là où il en fallait huit fois moins.
+ *
+ * **hyperliquid** n'accepte, elle, aucun `limit` : son SDK n'envoie que `startTime`/`endTime`
+ * (`get-candle-snapshot.ts`). Le nombre sert alors à dimensionner la FENÊTRE demandée, pas à remplir un
+ * paramètre. La venue borne d'elle-même à ~5 000 bougies par (coin, intervalle) — et l'horizon que ça couvre
+ * dépend de l'activité du coin, ce n'est donc pas une durée fixe.
  *
  * ⚠️ UNE VENUE ABSENTE DE CETTE TABLE N'A PAS DE PLAFOND DOCUMENTÉ — ce qui n'est pas « pas de plafond ». On ne
  * devine aucun chiffre : le jour où l'une d'elles s'en approche, on lit sa documentation et on l'ajoute.
@@ -1844,4 +1900,4 @@ declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
  */
 declare function isDated(xtras?: Record<string, unknown>): boolean;
 
-export { CANDLES_MAX_HISTORY, CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, type Direction, type IAccountState, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IFundingPaid, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type IPublicTrade, type ITarget, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, REST_THROTTLE_MS, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, candlesMaxHistoryOf, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };
+export { type AssetClass, CANDLES_MAX_HISTORY, CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, type Direction, type IAccountState, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IFundingPaid, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type IPublicTrade, type ITarget, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, REST_THROTTLE_MS, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, assetClassOf, buildLevels, buildProtection, candlesMaxHistoryOf, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };

package/dist/index.js

@@ -677,6 +677,57 @@ CandlesService = __decorateClass([
   Injectable()
 ], CandlesService);
 
+// src/helpers/asset-class.ts
+var BINANCE = {
+  COIN: "crypto",
+  EQUITY: "stock",
+  CN_EQUITY: "stock",
+  HK_EQUITY: "stock",
+  KR_EQUITY: "stock",
+  PREMARKET: "stock",
+  COMMODITY: "commodity",
+  INDEX: "index"
+};
+var BYBIT = {
+  "": "crypto",
+  innovation: "crypto",
+  stock: "stock",
+  commodity: "commodity",
+  ETF: "etf"
+};
+var EXTENDED = {
+  Equity: "stock",
+  Commodity: "commodity",
+  "ETF/Index": "index",
+  FX: "forex",
+  "Pre-market": "stock"
+};
+function assetClassOf(xex, xtras) {
+  if (xtras === void 0) {
+    return void 0;
+  }
+  if (xex === "binance") {
+    const brut = xtras.underlyingType;
+    return typeof brut === "string" ? BINANCE[brut] : void 0;
+  }
+  if (xex === "bybit") {
+    const brut = xtras.symbolType;
+    return typeof brut === "string" ? BYBIT[brut] : void 0;
+  }
+  if (xex === "extended") {
+    const categorie = xtras.category;
+    if (typeof categorie !== "string") {
+      return void 0;
+    }
+    if (categorie !== "RWA") {
+      return "crypto";
+    }
+    const sous = xtras.subCategory;
+    return typeof sous === "string" ? EXTENDED[sous] : void 0;
+  }
+  return void 0;
+}
+
 // src/helpers/contract-expiry.ts
 var DATED_CONTRACT_TYPES = /* @__PURE__ */ new Set([
   // binance : les trimestriels (`BTCUSDT_260925`, `ETHUSDT_261225`).
@@ -759,6 +810,7 @@ var CatalogService = class {
       xex,
       kind: pair.kind,
       multiplier: multiplierFromXex(pair.name),
+      assetClass: assetClassOf(xex, pair.xtras),
       expiresAt: expiryOf(pair.xtras),
       ref: pair.ref ?? null,
       szDecimals: pair.szDecimals,
@@ -947,6 +999,7 @@ var SpotCatalogService = class {
       // 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),
+      assetClass: assetClassOf(xex, pair.xtras),
       ref: pair.ref ?? null,
       szDecimals: pair.szDecimals,
       tickSize: pair.tickSize,
@@ -2137,7 +2190,7 @@ var CANDLES_PER_CALL = {
   blofin: 1440,
   aster: 1500,
   hyperliquid: 5e3,
-  pacifica: 500
+  pacifica: 4e3
 };
 function candlesPerCallOf(xex) {
   return CANDLES_PER_CALL[xex];
@@ -2163,6 +2216,6 @@ function candlesMaxHistoryOf(xex) {
   return CANDLES_MAX_HISTORY[xex];
 }
 
-export { CANDLES_MAX_HISTORY, CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, ORDER_STATUSES, PricesService, REST_THROTTLE_MS, SPOT_XEXES, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, Timeframe, TradingService, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, candlesMaxHistoryOf, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };
+export { CANDLES_MAX_HISTORY, CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, ORDER_STATUSES, PricesService, REST_THROTTLE_MS, SPOT_XEXES, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, Timeframe, TradingService, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, assetClassOf, buildLevels, buildProtection, candlesMaxHistoryOf, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map