@blackcube/xgate-sdk 0.22.0 → 0.23.0

package/dist/index.d.cts

@@ -312,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.
  *
@@ -433,10 +547,13 @@ declare class SpotCatalogService {
  * 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.
+ * 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 à
@@ -463,6 +580,70 @@ declare class SpotCandlesService {
     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;
@@ -555,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.
@@ -1204,4 +1397,4 @@ declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
  */
 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, 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 };
+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

@@ -312,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.
  *
@@ -433,10 +547,13 @@ declare class SpotCatalogService {
  * 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.
+ * 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 à
@@ -463,6 +580,70 @@ declare class SpotCandlesService {
     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;
@@ -555,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.
@@ -1204,4 +1397,4 @@ declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
  */
 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, 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 };
+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 };