@blackcube/xgate-sdk 0.21.1 → 0.23.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.
@@ -295,6 +312,120 @@ declare class WsCandlesService {
     private quoteOf;
 }
 
+/**
+ * LE FLUX DE BOUGIES D'UNE VENUE — porté de
+ * `Blips/server/src/candles/services/internal/dex-candles-stream.service.ts`, où il tourne en
+ * production. Même surface, mêmes garanties ; seul le type de bougie change (celui d'XGate).
+ *
+ * **UNE INSTANCE PAR VENUE, DONC UNE SOCKET PAR VENUE.** La façade est mémoïsée (`instance()`) et
+ * `ws()` n'est appelé qu'une fois, hors de la boucle : les N souscriptions partagent la même
+ * connexion. Créer la façade à chaque souscription ouvrirait une socket par marché — 200 marchés
+ * suivis, 200 sockets, quand hyperliquid n'en accepte que 10 par IP.
+ *
+ * **UNE SOUSCRIPTION PAR MARCHÉ, et non `subscribeAllCandles`.** Ce dernier ne coûte qu'un
+ * abonnement, mais il est bâti sur un flux de prix agrégé : mesuré le 2026-08-02, il rend un prix
+ * MILIEU (40 % des valeurs sur un demi-tick contre 8 % au REST) et AUCUN volume (`"v":"0"` sur les
+ * six dex). Le canal `candle` par marché rend la vraie bougie de trades, avec son volume.
+ *
+ * **LE SYMBOLE VIENT DU MESSAGE**, jamais de la souscription. Les SDK hyperliquid et pacifica
+ * livraient tout le canal à tous les abonnés jusqu'à la 0.15.0 — trois souscriptions recevaient le
+ * même flux. C'est corrigé, mais la règle reste : on lit ce que le wire déclare, on ne suppose pas.
+ */
+declare class CandlesStreamService {
+    readonly xex: XgateEx;
+    /** Le marché écouté. Le comptant n'est servi que par binance et bybit. */
+    readonly kind: MarketKind;
+    private readonly logger;
+    private source;
+    private readonly unsubscribes;
+    /** Le plafond de souscriptions documenté par la venue, ou `null` si personne ne l'a publié. */
+    readonly maxSubscriptions: number | null;
+    constructor(xex: XgateEx, 
+    /** Le marché écouté. Le comptant n'est servi que par binance et bybit. */
+    kind?: MarketKind);
+    /**
+     * Ouvre le flux sur une LISTE de marchés, sur une seule socket.
+     *
+     * **UNE ERREUR DE FLUX COUPE TOUT, PUIS LÈVE.** Elle n'arrive pas à la souscription : mesuré le
+     * 2026-08-07, la venue accepte un symbole inconnu sans broncher, puis ferme la connexion en le
+     * découvrant. Le SDK reconnecte, elle referme — cinq cycles en douze secondes, et sur une socket
+     * partagée **tous** les marchés valides cessent de recevoir, en silence.
+     *
+     * On refuse cette boucle : à la première erreur, les souscriptions sont coupées, l'incident est
+     * journalisé en `error`, et l'exception part. Un flux à moitié mort qui se tait coûte plus cher
+     * qu'un arrêt franc — on ne découvre le premier qu'en constatant l'absence de données.
+     *
+     * ⚠️ L'exception naît dans un rappel de socket : elle ne remonte pas à l'appelant de `start()`,
+     * elle sort en erreur non capturée. C'est délibéré — elle doit être impossible à ignorer.
+     *
+     * **binance et bybit ne remontent pas encore leurs erreurs** : leur client gère la fermeture en
+     * interne sans l'exposer. Sur ces deux venues, la boucle silencieuse reste possible.
+     */
+    start(symbolsXex: string[], interval: Timeframe, onCandle: (candle: ICandle) => void): void;
+    /** Coupe tout. Un désabonnement qui échoue ne doit pas empêcher les autres de se fermer. */
+    stop(): void;
+    /** Le nombre de souscriptions ouvertes. La liste des désabonnements EST le compteur. */
+    subscriptionCount(): number;
+    /**
+     * Le client temps réel, sur le bon marché.
+     *
+     * Les deux contrats ne signent pas `ws()` pareil, et c'est voulu : côté comptant le marché est
+     * **obligatoire** (`ws('spot')`), parce que les façades ouvrent du perpétuel par défaut — un
+     * `ws()` nu y diffuserait des prix de perpétuel à qui croit écouter le comptant.
+     */
+    private wire;
+    /** La façade de la venue, créée une seule fois : c'est elle qui porte la socket partagée. */
+    private instance;
+    /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
+    private quoteOf;
+}
+/**
+ * LA FAÇADE : un flux par venue, et un seul.
+ *
+ * Blips instancie `DexCandlesStreamService` une fois par venue et garde la référence. XGate offre
+ * la même chose sans que l'appelant ait à tenir cette table : `of(xex)` rend **toujours la même
+ * instance** pour une venue et un marché donnés — donc toujours la même socket.
+ *
+ * Demander deux fois `of(hyperliquid)` et souscrire 100 marchés à chaque fois ouvre **une** socket
+ * avec 200 souscriptions, pas deux sockets. C'est exactement ce qui manquait.
+ */
+declare class CandlesStreamRegistry {
+    private readonly streams;
+    /** Le flux d'une venue, créé au premier appel puis réutilisé. */
+    of(xex: XgateEx, kind?: MarketKind): CandlesStreamService;
+    /** Coupe tous les flux ouverts, toutes venues confondues. */
+    stopAll(): void;
+    /** Ce qui est ouvert, par venue — pour surveiller sans avoir à tenir de compteur soi-même. */
+    counts(): Record<string, number>;
+}
+
+/**
+ * LES PLAFONDS DE SOUSCRIPTION, PAR VENUE — uniquement ceux qu'une documentation officielle donne.
+ *
+ * Repris de `Blips/server/src/candles/services/internal/dex-candles-stream.service.ts`, où ils ont
+ * été établis puis vérifiés en réel.
+ *
+ * **aster**, section « Websocket Market Streams » : « A single connection can listen to a maximum
+ * of 200 streams », et « A connection that goes beyond the limit will be disconnected; IPs that are
+ * repeatedly disconnected may be banned ». Vérifié le 2026-08-03 sur `fstream.asterdex.com` : 200
+ * tiennent, 300 tuent la connexion.
+ * <https://github.com/asterdex/api-docs/blob/master/V3(Recommended)/EN/aster-finance-futures-api-v3.md>
+ *
+ * **hyperliquid** : 1 000 souscriptions et 10 connexions par IP.
+ *
+ * **Une venue ABSENTE de cette table n'a pas de plafond DOCUMENTÉ** — ce qui n'est pas la même
+ * chose que « 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.
+ */
+declare const WS_SUBSCRIPTION_LIMITS: Partial<Record<XgateEx, number>>;
+/**
+ * Le plafond documenté d'une venue, ou `undefined` si personne ne l'a publié.
+ *
+ * Rendre `Infinity` par défaut serait un mensonge commode : l'absence de plafond connu n'est pas
+ * une garantie d'illimité.
+ */
+declare function subscriptionLimitOf(xex: XgateEx): number | undefined;
+
 /**
  * UNE COTATION, TELLE QU'XGATE LA REND — quelle que soit la venue d'où elle vient.
  *
@@ -407,6 +538,112 @@ 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 s'écarte du comptant**.
+ * C'est cet écart que certaines stratégies exploitent — le confondre le rendrait invisible.
+ *
+ * En revanche, les échelles de cotation ne posent aucun problème entre les deux marchés :
+ * `SATSUSDT` (×1) et `10000SATSUSDT` (×10000) sont **deux paires distinctes**, chacune portant son
+ * `multiplier` au catalogue. Une bougie appartient à une paire, identifiée par `xex` +
+ * `symbolXex` + `kind` : il n'y a rien à réconcilier.
+ *
+ * **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[]>;
+}
+
+/**
+ * LES PRIX DU **COMPTANT** — binance et bybit.
+ *
+ * Séparé de `PricesService` comme le catalogue et les bougies le sont : deux marchés, deux
+ * services. Ici la raison est encore plus directe qu'ailleurs — **un prix comptant et un prix
+ * perpétuel ne sont pas le même nombre**. Le perpétuel porte un funding et s'écarte du comptant ;
+ * c'est justement cet écart que certaines stratégies exploitent, et le confondre le rendrait
+ * invisible.
+ *
+ * **La moitié des champs sont `null` au comptant, et c'est correct** : `mark`, `oracle`, `funding`
+ * et `openInterest` n'existent que pour un perpétuel. Le comptant renseigne `bid`, `ask`, `last`,
+ * `volume24h` — ce qui est mesuré, pas ce qui est dérivé d'un contrat.
+ */
+declare class SpotPricesService {
+    private readonly logger;
+    /** Les venues dont XGate sert les prix comptant. */
+    venues(): readonly XgateEx[];
+    /**
+     * Les prix comptant d'une ou plusieurs venues, en une seule liste.
+     *
+     * Même politique d'échec que partout : seule, une venue en échec fait échouer l'appel ; parmi
+     * d'autres, elle est journalisée et ignorée. Chaque prix porte son `xex`.
+     */
+    prices(...xexes: XgateEx[]): Promise<IPrice[]>;
+    /** Les prix comptant d'UNE venue, traduits vers {@link IPrice}. */
+    private pricesOf;
+}
+
+/**
+ * LES BOUGIES DU **COMPTANT** EN TEMPS RÉEL — binance et bybit.
+ *
+ * Le pendant de `WsCandlesService`, sur l'autre marché. La séparation n'est pas une symétrie
+ * décorative : les façades exposent `ws(kind = 'perp')`, donc **un `ws()` nu ouvre un flux de
+ * perpétuels**. Un service unique qui aurait oublié de passer le marché aurait diffusé des prix
+ * de perpétuel à qui croyait écouter le comptant — deux séries voisines, jamais égales, et rien
+ * pour le signaler.
+ *
+ * Le contrat {@link IXexSpotSource} exige donc `ws('spot')` explicitement, sans valeur par défaut.
+ */
+declare class SpotWsCandlesService {
+    private readonly logger;
+    /** Les venues dont XGate diffuse le comptant en temps réel. */
+    venues(): readonly XgateEx[];
+    /**
+     * Souscrit aux bougies **comptant** d'un marché. Rend la fonction de désabonnement.
+     *
+     * Le handler reçoit une bougie à la fois, au format unifié ; la bougie en cours est repoussée à
+     * chaque mise à jour tant qu'elle n'est pas close.
+     */
+    subscribe(xex: XgateEx, query: {
+        symbol: string;
+        interval: Timeframe;
+    }, handler: (candle: ICandle) => void): Unsubscribe;
+    /**
+     * Souscrit au MÊME marché comptant chez plusieurs venues, avec un seul handler.
+     *
+     * Chaque bougie porte son `xex`. La fonction rendue coupe tous les flux d'un coup.
+     */
+    subscribeAll(xexes: XgateEx[], query: {
+        symbol: string;
+        interval: Timeframe;
+    }, handler: (candle: ICandle) => void): Unsubscribe;
+}
+
 /** Une paire, telle qu'un SDK de venue la rend. */
 interface IXexPair {
     name: string;
@@ -499,6 +736,18 @@ interface IXexSpotSource {
         }): Promise<IXexCandle[]>;
         getPrices?(): Promise<IXexPrice[]>;
     };
+    /**
+     * Le temps réel du COMPTANT. **`kind` est obligatoire ici**, contrairement aux façades qui le
+     * rendent optionnel : leur défaut est `'perp'`, et un `ws()` nu ouvre donc un flux de perpétuels
+     * en croyant écouter le comptant — deux marchés dont les prix diffèrent, sans que rien ne le
+     * signale.
+     */
+    ws(kind: 'spot'): {
+        subscribeCandles(query: {
+            name: string;
+            interval: string;
+        }, handler: (candle: IXexCandle) => void): () => void;
+    };
 }
 /**
  * De quoi lire UN compte chez une venue.
@@ -535,7 +784,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[];
 /**
@@ -1104,5 +1353,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, CandlesStreamRegistry, CandlesStreamService, 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, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, 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.
@@ -295,6 +312,120 @@ declare class WsCandlesService {
     private quoteOf;
 }
 
+/**
+ * LE FLUX DE BOUGIES D'UNE VENUE — porté de
+ * `Blips/server/src/candles/services/internal/dex-candles-stream.service.ts`, où il tourne en
+ * production. Même surface, mêmes garanties ; seul le type de bougie change (celui d'XGate).
+ *
+ * **UNE INSTANCE PAR VENUE, DONC UNE SOCKET PAR VENUE.** La façade est mémoïsée (`instance()`) et
+ * `ws()` n'est appelé qu'une fois, hors de la boucle : les N souscriptions partagent la même
+ * connexion. Créer la façade à chaque souscription ouvrirait une socket par marché — 200 marchés
+ * suivis, 200 sockets, quand hyperliquid n'en accepte que 10 par IP.
+ *
+ * **UNE SOUSCRIPTION PAR MARCHÉ, et non `subscribeAllCandles`.** Ce dernier ne coûte qu'un
+ * abonnement, mais il est bâti sur un flux de prix agrégé : mesuré le 2026-08-02, il rend un prix
+ * MILIEU (40 % des valeurs sur un demi-tick contre 8 % au REST) et AUCUN volume (`"v":"0"` sur les
+ * six dex). Le canal `candle` par marché rend la vraie bougie de trades, avec son volume.
+ *
+ * **LE SYMBOLE VIENT DU MESSAGE**, jamais de la souscription. Les SDK hyperliquid et pacifica
+ * livraient tout le canal à tous les abonnés jusqu'à la 0.15.0 — trois souscriptions recevaient le
+ * même flux. C'est corrigé, mais la règle reste : on lit ce que le wire déclare, on ne suppose pas.
+ */
+declare class CandlesStreamService {
+    readonly xex: XgateEx;
+    /** Le marché écouté. Le comptant n'est servi que par binance et bybit. */
+    readonly kind: MarketKind;
+    private readonly logger;
+    private source;
+    private readonly unsubscribes;
+    /** Le plafond de souscriptions documenté par la venue, ou `null` si personne ne l'a publié. */
+    readonly maxSubscriptions: number | null;
+    constructor(xex: XgateEx, 
+    /** Le marché écouté. Le comptant n'est servi que par binance et bybit. */
+    kind?: MarketKind);
+    /**
+     * Ouvre le flux sur une LISTE de marchés, sur une seule socket.
+     *
+     * **UNE ERREUR DE FLUX COUPE TOUT, PUIS LÈVE.** Elle n'arrive pas à la souscription : mesuré le
+     * 2026-08-07, la venue accepte un symbole inconnu sans broncher, puis ferme la connexion en le
+     * découvrant. Le SDK reconnecte, elle referme — cinq cycles en douze secondes, et sur une socket
+     * partagée **tous** les marchés valides cessent de recevoir, en silence.
+     *
+     * On refuse cette boucle : à la première erreur, les souscriptions sont coupées, l'incident est
+     * journalisé en `error`, et l'exception part. Un flux à moitié mort qui se tait coûte plus cher
+     * qu'un arrêt franc — on ne découvre le premier qu'en constatant l'absence de données.
+     *
+     * ⚠️ L'exception naît dans un rappel de socket : elle ne remonte pas à l'appelant de `start()`,
+     * elle sort en erreur non capturée. C'est délibéré — elle doit être impossible à ignorer.
+     *
+     * **binance et bybit ne remontent pas encore leurs erreurs** : leur client gère la fermeture en
+     * interne sans l'exposer. Sur ces deux venues, la boucle silencieuse reste possible.
+     */
+    start(symbolsXex: string[], interval: Timeframe, onCandle: (candle: ICandle) => void): void;
+    /** Coupe tout. Un désabonnement qui échoue ne doit pas empêcher les autres de se fermer. */
+    stop(): void;
+    /** Le nombre de souscriptions ouvertes. La liste des désabonnements EST le compteur. */
+    subscriptionCount(): number;
+    /**
+     * Le client temps réel, sur le bon marché.
+     *
+     * Les deux contrats ne signent pas `ws()` pareil, et c'est voulu : côté comptant le marché est
+     * **obligatoire** (`ws('spot')`), parce que les façades ouvrent du perpétuel par défaut — un
+     * `ws()` nu y diffuserait des prix de perpétuel à qui croit écouter le comptant.
+     */
+    private wire;
+    /** La façade de la venue, créée une seule fois : c'est elle qui porte la socket partagée. */
+    private instance;
+    /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
+    private quoteOf;
+}
+/**
+ * LA FAÇADE : un flux par venue, et un seul.
+ *
+ * Blips instancie `DexCandlesStreamService` une fois par venue et garde la référence. XGate offre
+ * la même chose sans que l'appelant ait à tenir cette table : `of(xex)` rend **toujours la même
+ * instance** pour une venue et un marché donnés — donc toujours la même socket.
+ *
+ * Demander deux fois `of(hyperliquid)` et souscrire 100 marchés à chaque fois ouvre **une** socket
+ * avec 200 souscriptions, pas deux sockets. C'est exactement ce qui manquait.
+ */
+declare class CandlesStreamRegistry {
+    private readonly streams;
+    /** Le flux d'une venue, créé au premier appel puis réutilisé. */
+    of(xex: XgateEx, kind?: MarketKind): CandlesStreamService;
+    /** Coupe tous les flux ouverts, toutes venues confondues. */
+    stopAll(): void;
+    /** Ce qui est ouvert, par venue — pour surveiller sans avoir à tenir de compteur soi-même. */
+    counts(): Record<string, number>;
+}
+
+/**
+ * LES PLAFONDS DE SOUSCRIPTION, PAR VENUE — uniquement ceux qu'une documentation officielle donne.
+ *
+ * Repris de `Blips/server/src/candles/services/internal/dex-candles-stream.service.ts`, où ils ont
+ * été établis puis vérifiés en réel.
+ *
+ * **aster**, section « Websocket Market Streams » : « A single connection can listen to a maximum
+ * of 200 streams », et « A connection that goes beyond the limit will be disconnected; IPs that are
+ * repeatedly disconnected may be banned ». Vérifié le 2026-08-03 sur `fstream.asterdex.com` : 200
+ * tiennent, 300 tuent la connexion.
+ * <https://github.com/asterdex/api-docs/blob/master/V3(Recommended)/EN/aster-finance-futures-api-v3.md>
+ *
+ * **hyperliquid** : 1 000 souscriptions et 10 connexions par IP.
+ *
+ * **Une venue ABSENTE de cette table n'a pas de plafond DOCUMENTÉ** — ce qui n'est pas la même
+ * chose que « 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.
+ */
+declare const WS_SUBSCRIPTION_LIMITS: Partial<Record<XgateEx, number>>;
+/**
+ * Le plafond documenté d'une venue, ou `undefined` si personne ne l'a publié.
+ *
+ * Rendre `Infinity` par défaut serait un mensonge commode : l'absence de plafond connu n'est pas
+ * une garantie d'illimité.
+ */
+declare function subscriptionLimitOf(xex: XgateEx): number | undefined;
+
 /**
  * UNE COTATION, TELLE QU'XGATE LA REND — quelle que soit la venue d'où elle vient.
  *
@@ -407,6 +538,112 @@ 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 s'écarte du comptant**.
+ * C'est cet écart que certaines stratégies exploitent — le confondre le rendrait invisible.
+ *
+ * En revanche, les échelles de cotation ne posent aucun problème entre les deux marchés :
+ * `SATSUSDT` (×1) et `10000SATSUSDT` (×10000) sont **deux paires distinctes**, chacune portant son
+ * `multiplier` au catalogue. Une bougie appartient à une paire, identifiée par `xex` +
+ * `symbolXex` + `kind` : il n'y a rien à réconcilier.
+ *
+ * **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[]>;
+}
+
+/**
+ * LES PRIX DU **COMPTANT** — binance et bybit.
+ *
+ * Séparé de `PricesService` comme le catalogue et les bougies le sont : deux marchés, deux
+ * services. Ici la raison est encore plus directe qu'ailleurs — **un prix comptant et un prix
+ * perpétuel ne sont pas le même nombre**. Le perpétuel porte un funding et s'écarte du comptant ;
+ * c'est justement cet écart que certaines stratégies exploitent, et le confondre le rendrait
+ * invisible.
+ *
+ * **La moitié des champs sont `null` au comptant, et c'est correct** : `mark`, `oracle`, `funding`
+ * et `openInterest` n'existent que pour un perpétuel. Le comptant renseigne `bid`, `ask`, `last`,
+ * `volume24h` — ce qui est mesuré, pas ce qui est dérivé d'un contrat.
+ */
+declare class SpotPricesService {
+    private readonly logger;
+    /** Les venues dont XGate sert les prix comptant. */
+    venues(): readonly XgateEx[];
+    /**
+     * Les prix comptant d'une ou plusieurs venues, en une seule liste.
+     *
+     * Même politique d'échec que partout : seule, une venue en échec fait échouer l'appel ; parmi
+     * d'autres, elle est journalisée et ignorée. Chaque prix porte son `xex`.
+     */
+    prices(...xexes: XgateEx[]): Promise<IPrice[]>;
+    /** Les prix comptant d'UNE venue, traduits vers {@link IPrice}. */
+    private pricesOf;
+}
+
+/**
+ * LES BOUGIES DU **COMPTANT** EN TEMPS RÉEL — binance et bybit.
+ *
+ * Le pendant de `WsCandlesService`, sur l'autre marché. La séparation n'est pas une symétrie
+ * décorative : les façades exposent `ws(kind = 'perp')`, donc **un `ws()` nu ouvre un flux de
+ * perpétuels**. Un service unique qui aurait oublié de passer le marché aurait diffusé des prix
+ * de perpétuel à qui croyait écouter le comptant — deux séries voisines, jamais égales, et rien
+ * pour le signaler.
+ *
+ * Le contrat {@link IXexSpotSource} exige donc `ws('spot')` explicitement, sans valeur par défaut.
+ */
+declare class SpotWsCandlesService {
+    private readonly logger;
+    /** Les venues dont XGate diffuse le comptant en temps réel. */
+    venues(): readonly XgateEx[];
+    /**
+     * Souscrit aux bougies **comptant** d'un marché. Rend la fonction de désabonnement.
+     *
+     * Le handler reçoit une bougie à la fois, au format unifié ; la bougie en cours est repoussée à
+     * chaque mise à jour tant qu'elle n'est pas close.
+     */
+    subscribe(xex: XgateEx, query: {
+        symbol: string;
+        interval: Timeframe;
+    }, handler: (candle: ICandle) => void): Unsubscribe;
+    /**
+     * Souscrit au MÊME marché comptant chez plusieurs venues, avec un seul handler.
+     *
+     * Chaque bougie porte son `xex`. La fonction rendue coupe tous les flux d'un coup.
+     */
+    subscribeAll(xexes: XgateEx[], query: {
+        symbol: string;
+        interval: Timeframe;
+    }, handler: (candle: ICandle) => void): Unsubscribe;
+}
+
 /** Une paire, telle qu'un SDK de venue la rend. */
 interface IXexPair {
     name: string;
@@ -499,6 +736,18 @@ interface IXexSpotSource {
         }): Promise<IXexCandle[]>;
         getPrices?(): Promise<IXexPrice[]>;
     };
+    /**
+     * Le temps réel du COMPTANT. **`kind` est obligatoire ici**, contrairement aux façades qui le
+     * rendent optionnel : leur défaut est `'perp'`, et un `ws()` nu ouvre donc un flux de perpétuels
+     * en croyant écouter le comptant — deux marchés dont les prix diffèrent, sans que rien ne le
+     * signale.
+     */
+    ws(kind: 'spot'): {
+        subscribeCandles(query: {
+            name: string;
+            interval: string;
+        }, handler: (candle: IXexCandle) => void): () => void;
+    };
 }
 /**
  * De quoi lire UN compte chez une venue.
@@ -535,7 +784,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[];
 /**
@@ -1104,5 +1353,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, CandlesStreamRegistry, CandlesStreamService, 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, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };