@blackcube/xgate-sdk 0.20.0

package/dist/index.d.ts

@@ -0,0 +1,1048 @@
+/**
+ * Le module d'XGate : `imports: [XgateModule]`, puis on injecte le SEUL service dont on a besoin.
+ *
+ * Une capacité = un service, indépendant des autres. Le REST et le temps réel sont eux-mêmes
+ * séparés (`CandlesService` / `WsCandlesService`) : rejouer le passé et suivre le présent ne se
+ * consomment pas de la même façon, et une application qui ne fait que du backfill n'a aucune
+ * socket à ouvrir.
+ */
+declare class XgateModule {
+}
+
+/**
+ * Les venues qu'XGate sait interroger.
+ *
+ * Une seule énumération pour les CEX et les DEX : la distinction ne change rien à l'API — on
+ * interroge un catalogue de la même façon des deux côtés. Elle deviendra une donnée portée par la
+ * venue le jour où quelque chose en dépendra.
+ *
+ * **`drift` en est absent**, et ce n'est pas un oubli : son SDK ne porte aucun test (seul de la
+ * famille), sa précision de taille est un placeholder assumé, et son catalogue est une constante
+ * figée dans le paquet. On ne l'agrège pas tant qu'il n'est pas vérifiable.
+ */
+declare enum XgateEx {
+    Hyperliquid = "hyperliquid",
+    Pacifica = "pacifica",
+    Aster = "aster",
+    Lighter = "lighter",
+    Extended = "extended",
+    Paradex = "paradex",
+    Bullet = "bullet",
+    Blofin = "blofin",
+    /**
+     * Les deux seules venues dont XGate sert aussi le **comptant** (cf. `IXexSpotSource`). Leurs SDK
+     * ne couvrent que la lecture publique : catalogue, bougies et prix. Toute route signée y lève.
+     */
+    Binance = "binance",
+    Bybit = "bybit"
+}
+/** Toutes les venues connues, dans l'ordre de déclaration. */
+declare const XGATE_EXCHANGES: readonly XgateEx[];
+
+/** Type de marché. */
+type MarketKind = 'perp' | 'spot';
+/**
+ * UNE PAIRE, TELLE QU'XGATE LA REND — quelle que soit la venue d'où elle vient.
+ *
+ * Trois identifiants coexistent, et ils ne servent pas à la même chose :
+ *
+ * - `symbol` est le nom **canonique** de l'actif (celui de CoinMarketCap) : `PEPE`, jamais
+ *   `kPEPE` ni `1000PEPE`. C'est la clé qui permet de rapprocher le même actif entre venues.
+ * - `symbolXex` est ce que **la venue** attend : c'est lui qu'on lui renvoie pour souscrire,
+ *   passer un ordre ou lire des bougies. Le confondre avec `symbol` fait échouer la requête.
+ * - `xex` dit **d'où vient la ligne**. Sans lui, un catalogue multi-venues perd l'information la
+ *   plus utile qu'il porte : le même actif y figure autant de fois qu'il est listé.
+ *
+ * Le multiplicateur de cotation (`k`, `1000`) disparaît du `symbol` sans rien fausser : il est
+ * absorbé par le prix, donc `prix × taille` reste le notionnel quelle que soit l'unité de la
+ * venue.
+ */
+interface IPair {
+    /** Nom canonique de l'actif (`PEPE`, `BTC`). */
+    symbol: string;
+    /** Actif de cotation (`USDC`, `USDT`). */
+    quote: string;
+    /** Le symbole que la venue attend (`kPEPE`, `1000PEPE`, `BTC-USDT`, `@1`). */
+    symbolXex: string;
+    /** La venue d'où provient cette paire. */
+    xex: XgateEx;
+    /** Type de marché (`perp`/`spot`). */
+    kind: MarketKind;
+    /**
+     * 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.
+     */
+    ref: string | null;
+    /** Décimales de taille → pas de quantité = `10^-szDecimals`. */
+    szDecimals: number;
+    /** Pas de prix, si fourni. */
+    tickSize?: string;
+    /** Pas de quantité, si fourni. */
+    stepSize?: string;
+    /** Quantité minimale d'un ordre, si fournie. */
+    minQty?: string;
+    /** Notionnel minimum d'un ordre, si fourni. */
+    minNotional?: string;
+    /** Levier maximum (perp), si fourni. */
+    maxLeverage?: number;
+    /** État du marché tel que la venue l'écrit, si publié. */
+    status?: string;
+    /** Marché mort chez la venue. `undefined` = la venue ne se prononce pas. */
+    delisted?: boolean;
+    /** Date de listing, quand la venue la publie. */
+    listedAt?: Date;
+    /** Champs natifs hors cœur unifié, tels que le SDK de la venue les a conservés. */
+    xtras?: Record<string, unknown>;
+}
+
+/**
+ * LE CATALOGUE, toutes venues confondues.
+ *
+ * L'appelant ne connaît qu'{@link XgateEx} et les types unifiés ; il n'importe aucun SDK, ne
+ * construit aucune façade, et ne se soucie pas de ce que chaque venue nomme comment.
+ *
+ * **Un service par capacité, pas une façade unique** : une application qui ne veut que le
+ * catalogue n'a aucune raison d'injecter de quoi trader. Les capacités suivantes vivront dans
+ * leurs propres services, injectables séparément.
+ */
+declare class CatalogService {
+    private readonly logger;
+    /**
+     * Le catalogue **perp** d'une ou plusieurs venues, en une seule liste.
+     *
+     * Chaque ligne porte sa venue d'origine (`xex`) et les deux symboles — le canonique pour
+     * rapprocher un actif entre venues, le brut pour parler à celle-ci.
+     *
+     * **Le traitement d'une venue en échec dépend de ce qui a été demandé** : sur une seule venue,
+     * un échec est l'échec de l'appel et il est relancé ; sur plusieurs, la liste partielle garde
+     * sa valeur et l'incident est journalisé. Rendre `[]` en silence serait le pire des deux — un
+     * catalogue vide se lit comme « cette venue ne liste rien », pas comme « je n'ai pas pu
+     * demander ».
+     */
+    catalog(...xexes: XgateEx[]): Promise<IPair[]>;
+    /** Le catalogue d'UNE venue, traduit vers {@link IPair}. */
+    private catalogOf;
+}
+
+/**
+ * Les intervalles de bougies qu'XGate promet — **les mêmes que Blips**, mêmes noms, mêmes valeurs
+ * (`Blips/server/src/shared/timeframe.enum.ts`). Le consommateur n'a pas à traduire pour parler à
+ * la passerelle, ni la passerelle à inventer une échelle concurrente.
+ *
+ * Toutes les venues ne les servent pas : paradex s'arrête à l'heure (`resolution: must be one of
+ * [1 3 5 15 30 60]`, dit la venue), lighter refuse `1w`, extended rend une liste vide pour ce même
+ * intervalle. Ce qu'une venue ne sert pas se **fabrique par agrégation** depuis un intervalle plus
+ * fin, jamais ne se réclame à l'appelant.
+ */
+declare enum Timeframe {
+    M1 = "1m",
+    M5 = "5m",
+    M15 = "15m",
+    H1 = "1h",
+    H4 = "4h",
+    D = "1d",
+    W = "1w"
+}
+/** Durée d'un intervalle, en minutes. */
+declare const TIMEFRAME_MINUTES: Record<Timeframe, number>;
+/** Durée d'un intervalle, en millisecondes. */
+declare function timeframeMs(timeframe: Timeframe): number;
+
+/**
+ * UNE BOUGIE, TELLE QU'XGATE LA REND.
+ *
+ * **Des dates, jamais des timestamps.** Les venues comptent en millisecondes, en secondes ou en
+ * chaînes datées ; aucune ne dit laquelle dans son type. Ici, `openedAt` et `closedAt` sont des
+ * `Date` — l'unité ne se devine plus. C'est la même règle que `IPair.listedAt`, et le même
+ * vocabulaire que Blips (`ICandleRow`).
+ *
+ * **Des prix en chaîne, pas en nombre.** Les SDK les rendent ainsi pour préserver la précision
+ * décimale, et il y a une raison : `0.1 × 0.1` vaut `0.010000000000000002` en JavaScript. XGate est
+ * une couche de venue, pas une couche de stockage — celui qui écrit en base convertit chez lui, en
+ * connaissance de cause.
+ */
+interface ICandle {
+    /** Nom canonique de l'actif (`PEPE`, `BTC`). */
+    symbol: string;
+    /** Actif de cotation (`USDC`, `USDT`). */
+    quote: string;
+    /** Le symbole que la venue attend. */
+    symbolXex: string;
+    /** La venue d'où provient cette bougie. */
+    xex: XgateEx;
+    /** Type de marché (`perp`/`spot`). */
+    kind: MarketKind;
+    /** L'intervalle de cette bougie. */
+    interval: Timeframe;
+    /** Ouverture du créneau. */
+    openedAt: Date;
+    /** Fin du créneau — dernière milliseconde incluse. */
+    closedAt: Date;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    /**
+     * Volume en actif de base. `null` = **inconnu**, pas « aucun échange » : une bougie venue d'un
+     * flux temps réel n'en porte pas toujours. Un `0` reste un vrai volume, celui d'une minute sans
+     * échange.
+     */
+    volume: string | null;
+    /** Volume en cotation. `null` quand la venue ne le publie pas. */
+    quoteVolume: string | null;
+    /** Part achetée à l'initiative du taker, en cotation. Avec `quoteVolume`, donne le CVD. */
+    takerBuyQuoteVolume: string | null;
+    /** Nombre de transactions. `null` quand la venue ne le compte pas. */
+    trades: number | null;
+    /**
+     * `true` = bougie **fabriquée par agrégation**, la venue ne sert pas cet intervalle. C'est une
+     * vraie bougie, mais personne ne l'a servie telle quelle.
+     */
+    derived: boolean;
+}
+/** Ce qu'on demande à `CandlesService`. */
+interface ICandlesQuery {
+    /** Le symbole que la venue attend (`symbolXex` d'un {@link IPair}). */
+    symbol: string;
+    interval: Timeframe;
+    /** Début de la plage. Une **date**, jamais un timestamp. */
+    startTime?: Date;
+    /** Fin de la plage. */
+    endTime?: Date;
+    limit?: number;
+}
+
+/**
+ * LES BOUGIES EN REST — l'historique.
+ *
+ * Le temps réel vit dans `WsCandlesService` : ce sont deux besoins distincts (rejouer le passé,
+ * suivre le présent), et une application qui fait du backfill n'a pas à ouvrir de socket.
+ */
+declare class CandlesService {
+    private readonly logger;
+    /**
+     * Les bougies d'une venue, sur une plage de **dates**.
+     *
+     * L'appelant donne des `Date` et un {@link Timeframe} ; le service traduit vers ce que la venue
+     * attend — chaîne UTC pour huit d'entre elles, millisecondes pour blofin.
+     *
+     * **Un intervalle que la venue ne sert pas est FABRIQUÉ**, pas refusé : on tire l'intervalle
+     * exploitable le plus grand et on agrège. Paradex s'arrête à l'heure, lighter et extended ne
+     * font pas la semaine — l'appelant n'a pas à le savoir. Les bougies fabriquées portent
+     * `derived: true`.
+     *
+     * **Lève si la venue ne sert rien du tout** (bullet, qui n'a pas de REST). Rendre une liste vide
+     * ferait passer une incapacité pour une absence de données, et un backfill silencieusement troué
+     * est pire qu'un backfill en erreur.
+     */
+    candles(xex: XgateEx, query: ICandlesQuery): Promise<ICandle[]>;
+    /** Un appel REST à la venue, dans l'intervalle qu'elle sait servir. */
+    private fetch;
+    /**
+     * Les bougies d'un même marché chez PLUSIEURS venues, en une liste.
+     *
+     * Comme pour le catalogue : une venue en échec parmi d'autres est journalisée et ignorée ; seule,
+     * son échec est celui de l'appel. Chaque bougie porte son `xex`, donc la liste reste
+     * exploitable telle quelle.
+     */
+    candlesOf(xexes: XgateEx[], query: ICandlesQuery): Promise<ICandle[]>;
+    /**
+     * La cotation, déduite du symbole natif. Les bougies ne la portent pas — seul le catalogue la
+     * publie —, et refaire un appel de catalogue pour chaque série coûterait plus cher que ce
+     * qu'elle apporte. `BTC-USDT` → `USDT` ; à défaut de séparateur, on ne prétend rien.
+     */
+    private quoteOf;
+}
+
+/** Couper le flux. */
+type Unsubscribe = () => void;
+/**
+ * LES BOUGIES EN TEMPS RÉEL — le présent.
+ *
+ * Séparé de `CandlesService` à dessein : rejouer un historique et suivre un flux ne se
+ * consomment pas de la même façon, et n'ont pas les mêmes coûts. Une application qui ne fait que
+ * du backfill n'a aucune socket à ouvrir.
+ */
+declare class WsCandlesService {
+    private readonly logger;
+    /**
+     * Souscrit aux bougies d'un marché chez une venue. Rend la fonction de désabonnement.
+     *
+     * Le handler reçoit **une bougie à la fois**, au format unifié — c'est la forme commune aux neuf
+     * SDK. La bougie en cours est repoussée à chaque mise à jour tant qu'elle n'est pas close ;
+     * `closedAt` dit jusqu'où elle porte.
+     *
+     * **Attention à extended** : sur un intervalle qu'elle ne connaît pas, sa façade rend un
+     * désabonnement vide au lieu de lever. L'appelant se croit abonné et n'entend jamais rien — un
+     * silence indiscernable d'un marché sans échange. C'est un défaut du SDK, pas d'XGate, et il est
+     * dans la file des corrections.
+     */
+    subscribe(xex: XgateEx, query: {
+        symbol: string;
+        interval: Timeframe;
+    }, handler: (candle: ICandle) => void): Unsubscribe;
+    /**
+     * Souscrit au MÊME marché chez plusieurs venues, avec un seul handler.
+     *
+     * Chaque bougie porte son `xex` : l'appelant sait toujours qui parle. La fonction rendue coupe
+     * tous les flux d'un coup — sinon il faudrait en garder N et n'en oublier aucun.
+     */
+    subscribeAll(xexes: XgateEx[], query: {
+        symbol: string;
+        interval: Timeframe;
+    }, handler: (candle: ICandle) => void): Unsubscribe;
+    /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
+    private quoteOf;
+}
+
+/**
+ * UNE COTATION, TELLE QU'XGATE LA REND — quelle que soit la venue d'où elle vient.
+ *
+ * Les trois identifiants sont ceux d'{@link IPair} et jouent le même rôle : `symbol` est le nom
+ * **canonique** de l'actif (celui qui permet de comparer un prix entre venues), `symbolXex` est ce
+ * que **la venue** attend, et `xex` dit d'où vient la ligne. Sans ce dernier, un relevé
+ * multi-venues perd ce qu'il a de plus utile : le même actif y figure autant de fois qu'il est
+ * coté, et c'est précisément l'écart entre ces cotations qu'on vient chercher.
+ *
+ * **Tous les prix sont des `string`**, jamais des `number` : ils viennent de la venue en décimal
+ * exact, et les passer en flottant perdrait des décimales avant même le premier calcul.
+ *
+ * **`null` signifie « la venue ne le publie pas »**, et ce n'est pas la même chose que zéro.
+ * Aucune venue ne sert les quatorze champs — voir le DICTIONARY de chaque SDK pour savoir qui
+ * remplit quoi. Deux nuances qui coûtent cher si on les ignore :
+ *
+ * - `mid` n'est servi que par hyperliquid et pacifica. Le dériver de `bid`/`ask` ailleurs
+ *   fabriquerait une valeur qu'aucune venue n'a cotée.
+ * - chez aster, le remplissage varie **d'un symbole à l'autre** : les cotations viennent de deux
+ *   endpoints aux univers différents, et les marchés exotiques n'ont ni `volume24h`, ni
+ *   `prevDayPrice`, ni `last`. C'est la seule venue où deux `IPrice` du même appel n'ont pas les
+ *   mêmes champs servis.
+ */
+interface IPrice {
+    /** Nom canonique de l'actif (`PEPE`, `BTC`). */
+    symbol: string;
+    /** Le symbole que la venue attend (`kPEPE`, `1000PEPE`, `BTC-USDT`). */
+    symbolXex: string;
+    /** La venue d'où provient cette cotation. */
+    xex: XgateEx;
+    /** Type de marché (`perp`/`spot`). */
+    kind: MarketKind;
+    /** Prix de valorisation des positions — la référence pour un PnL. */
+    mark: string | null;
+    /** Prix oracle/index. */
+    oracle: string | null;
+    /** Milieu de fourchette, tel que la venue le cote. */
+    mid: string | null;
+    /** Meilleure offre d'achat. */
+    bid: string | null;
+    /** Meilleure offre de vente. */
+    ask: string | null;
+    /** Dernier prix négocié. */
+    last: string | null;
+    /** Taux de financement courant. */
+    funding: string | null;
+    /** Position ouverte totale sur le marché. */
+    openInterest: string | null;
+    /** Volume des dernières 24 heures, en notionnel. */
+    volume24h: string | null;
+    /** Prix de référence de la veille, pour une variation sur 24 heures. */
+    prevDayPrice: string | null;
+    /** Moment de la cotation ; `null` quand la venue ne le publie pas. */
+    quotedAt: Date | null;
+    /** Champs natifs hors cœur unifié, tels que le SDK de la venue les a conservés. */
+    xtras?: Record<string, unknown>;
+}
+
+/**
+ * LES PRIX, toutes venues confondues.
+ *
+ * Même forme que `CatalogService`, et pour la même raison : l'appelant ne connaît qu'{@link XgateEx}
+ * et les types unifiés. Chaque ligne porte sa venue d'origine, sans quoi un relevé multi-venues
+ * perdrait ce qu'il a de plus utile — l'écart entre les cotations d'un même actif.
+ *
+ * **Ce service ne calcule rien.** Il ne dérive pas un `mid` d'un `bid`/`ask`, ne convertit pas un
+ * volume, ne comble aucun trou : un champ à `null` dit que la venue ne le publie pas, et c'est une
+ * information. Fabriquer la valeur manquante la rendrait indiscernable d'une valeur cotée.
+ */
+declare class PricesService {
+    private readonly logger;
+    /**
+     * Les prix **perp** d'une ou plusieurs venues, en une seule liste.
+     *
+     * **Le traitement d'une venue en échec dépend de ce qui a été demandé** : sur une seule venue, un
+     * échec est l'échec de l'appel et il est relancé ; sur plusieurs, la liste partielle garde sa
+     * valeur et l'incident est journalisé. Rendre `[]` en silence serait le pire des deux — un relevé
+     * vide se lit comme « ce marché ne cote rien », pas comme « je n'ai pas pu demander ».
+     */
+    prices(...xexes: XgateEx[]): Promise<IPrice[]>;
+    /** Les prix d'UNE venue, traduits vers {@link IPrice}. */
+    private pricesOf;
+}
+
+/**
+ * LE CATALOGUE COMPTANT, séparé du catalogue perpétuel.
+ *
+ * **Deux services, pas un service à drapeau.** Un `catalog(xex, { spot: true })` serait plus court
+ * à écrire et plus dangereux à lire : on croirait interroger des perpétuels et on interrogerait du
+ * comptant, sans que rien ne le signale. Ici, le nom de la classe dit ce qu'on lit.
+ *
+ * Le comptant est **minoritaire** dans la famille : deux venues sur dix le servent. Ce n'est pas un
+ * manque à combler, c'est la réalité d'un ensemble de SDK bâti pour le perpétuel.
+ */
+declare class SpotCatalogService {
+    private readonly logger;
+    /** Les venues dont XGate sert le comptant. */
+    venues(): readonly XgateEx[];
+    /**
+     * Le catalogue **spot** d'une ou plusieurs venues, en une seule liste.
+     *
+     * Même politique d'échec que le catalogue perpétuel : sur une seule venue, l'échec est relancé ;
+     * sur plusieurs, la liste partielle garde sa valeur et l'incident est journalisé.
+     *
+     * **Une venue sans comptant lève**, elle ne rend pas une liste vide : « cette venue n'a pas de
+     * spot » et « cette venue ne cote rien au comptant » ne se corrigent pas de la même façon.
+     */
+    catalog(...xexes: XgateEx[]): Promise<IPair[]>;
+    /** Le catalogue comptant d'UNE venue, traduit vers {@link IPair}. */
+    private catalogOf;
+}
+
+/** Une paire, telle qu'un SDK de venue la rend. */
+interface IXexPair {
+    name: string;
+    /**
+     * L'actif de base, **tel que la venue le NOMME**. Décisif chez binance et bybit : leur symbole
+     * concatène la cotation (`BTCUSDT`), et re-parser cette chaîne donnerait un faux canonique sur
+     * tout ce qui n'est pas coté en USDT — `ROSEBTC` deviendrait `ROSEBTC` au lieu de `ROSE`.
+     */
+    base: string;
+    quote: string;
+    kind: string;
+    ref?: string | null;
+    szDecimals: number;
+    tickSize?: string;
+    stepSize?: string;
+    minQty?: string;
+    minNotional?: string;
+    maxLeverage?: number;
+    status?: string;
+    delisted?: boolean;
+    listedAt?: Date;
+    xtras?: Record<string, unknown>;
+}
+/**
+ * Une bougie, telle qu'un SDK de venue la rend : **clés longues et `Date`**.
+ *
+ * Les clés courtes (`t`, `T`, `o`, `qv`…) restent au niveau du wire, dans chaque SDK. Elles ne
+ * remontent plus jusqu'ici — un `candle.T` ne se lit pas, et un `number` ne dit pas s'il compte des
+ * secondes ou des millisecondes.
+ */
+interface IXexCandle {
+    openedAt: Date;
+    closedAt: Date;
+    symbol: string;
+    interval: string;
+    open: string;
+    close: string;
+    high: string;
+    low: string;
+    volume: string;
+    trades: number;
+    kind: string;
+    quoteVolume: string | null;
+    takerBuyBaseVolume: string | null;
+    takerBuyQuoteVolume: string | null;
+    xtras?: Record<string, unknown>;
+}
+/**
+ * Une cotation, telle qu'un SDK de venue la rend : **clés longues et `Date`**, comme
+ * {@link IXexCandle}. Le `time: number` d'origine est devenu `quotedAt: Date` — un nombre nu ne dit
+ * pas s'il compte des secondes ou des millisecondes, et les deux existent selon les venues.
+ */
+interface IXexPrice {
+    name: string;
+    kind: string;
+    mark: string | null;
+    oracle: string | null;
+    mid: string | null;
+    bid: string | null;
+    ask: string | null;
+    last: string | null;
+    funding: string | null;
+    openInterest: string | null;
+    volume24h: string | null;
+    prevDayPrice: string | null;
+    quotedAt: Date | null;
+    xtras?: Record<string, unknown>;
+}
+/**
+ * Ce qu'XGate attend d'une façade de venue **côté COMPTANT**.
+ *
+ * **Volontairement séparé d'{@link IXexSource}, et non fondu dedans avec un paramètre.** Un
+ * `perp()` qui servirait parfois du spot selon un drapeau serait une source d'erreurs silencieuses :
+ * on croirait lire des perpétuels et on lirait du comptant, sans que rien ne le signale. Deux
+ * contrats, deux registres, deux services — l'appelant choisit explicitement ce qu'il interroge.
+ *
+ * **Toutes les venues n'ont pas de spot** : c'est même minoritaire. Le registre lève pour celles qui
+ * n'en servent pas, plutôt que de rendre une liste vide qui se lirait comme « ce marché ne cote
+ * rien ».
+ */
+interface IXexSpotSource {
+    spot(): {
+        getPairs(): Promise<IXexPair[]>;
+        getCandles?(query: {
+            name: string;
+            interval: string;
+            startTime?: Date;
+            endTime?: Date;
+            limit?: number;
+        }): Promise<IXexCandle[]>;
+        getPrices?(): Promise<IXexPrice[]>;
+    };
+}
+/**
+ * De quoi lire UN compte chez une venue.
+ *
+ * **Un sac d'accès volontairement lâche**, dont chaque venue prend ce qu'il lui faut : les huit
+ * n'ont pas la même notion d'identité. Un DEX se lit à l'adresse ; lighter veut un index de compte,
+ * extended une clé d'API plus un coffre, blofin un triplet clé/secret/passphrase. Un type strict par
+ * venue obligerait l'appelant à connaître ces huit formes — c'est précisément ce qu'XGate existe
+ * pour lui épargner.
+ *
+ * Le registre **lève** quand ce qu'il faut manque, avec le nom du champ attendu : mieux vaut un
+ * message précis qu'un compte vide qui se lirait comme « pas d'argent ».
+ */
+interface IXexAccess {
+    /** L'adresse publique du compte. Suffit seule sur les DEX en lecture. */
+    address?: string;
+    privateKey?: string;
+    /**
+     * Le réseau de la venue. **Défaut `mainnet`** — c'est le cas courant, et un défaut `testnet`
+     * ferait lire des soldes fantômes sans que personne ne s'en aperçoive.
+     *
+     * Il devient indispensable dès qu'on écrit : sans lui, `TradingService` ne pourrait ouvrir que sur
+     * de l'argent réel, et le cycle ne serait exerçable nulle part.
+     */
+    network?: 'mainnet' | 'testnet';
+    apiKey?: string;
+    secret?: string;
+    passphrase?: string;
+    accountIndex?: number;
+    apiKeyIndex?: number;
+    vault?: number;
+}
+/**
+ * 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.
+ */
+declare const WALLET_XEXES: readonly XgateEx[];
+/**
+ * Les venues dont XGate sert le **comptant**. Les autres n'ont pas de marché spot exploitable, ou
+ * ne l'exposent pas — et une venue absente d'ici n'est pas un oubli, c'est un fait mesuré.
+ */
+declare const SPOT_XEXES: readonly XgateEx[];
+/** Cette venue sert-elle du comptant via XGate ? */
+declare function servesSpot(xex: XgateEx): boolean;
+
+/**
+ * UN SOLDE, TEL QU'XGATE LE REND.
+ *
+ * `xex` dit d'où vient la ligne : sans lui, un relevé multi-venues additionnerait des USDC détenus
+ * à des endroits différents, et on ne saurait plus lequel est mobilisable où.
+ *
+ * **Tous les montants sont des `string`**, jamais des `number` : ce sont des décimaux exacts venus
+ * de la venue, et les passer en flottant perdrait des décimales avant le premier calcul.
+ */
+interface IBalance {
+    /** La venue qui détient ce solde. */
+    xex: XgateEx;
+    /** L'actif (`USDC`, `USDT`). */
+    asset: string;
+    /**
+     * Le solde total. Attention : chez la plupart des venues perp, il porte l'**equity** — dépôt plus
+     * PnL latent — et non le seul dépôt. Deux venues ne comptent donc pas forcément la même chose.
+     */
+    total: string;
+    /** Ce qui est mobilisable maintenant ; `null` si la venue ne le distingue pas. */
+    available: string | null;
+    /** Contre-valeur en dollars, quand la venue la publie. */
+    usdValue: string | null;
+    /** Champs natifs hors cœur unifié. */
+    xtras?: Record<string, unknown>;
+}
+/** Nature normalisée d'un mouvement d'argent. */
+type MovementKind = 'deposit' | 'withdraw' | 'transfer';
+/** État d'un mouvement. **Seul `completed` a réellement déplacé de l'argent.** */
+type MovementStatus = 'completed' | 'pending' | 'failed';
+/**
+ * UN DÉPLACEMENT D'ARGENT, entrant ou sortant.
+ *
+ * **Le montant est SIGNÉ** — `+` entrant, `-` sortant — alors que plusieurs venues le rendent
+ * toujours positif et n'indiquent le sens que par un type natif. Sans ce signe, la somme des
+ * mouvements ne donnerait pas la variation du solde, ce qui est pourtant le seul usage sérieux de
+ * cette liste.
+ *
+ * Les frais sont **exclus** du montant et portés à part : les mélanger empêcherait de rapprocher un
+ * dépôt de ce que la contrepartie a réellement envoyé.
+ */
+interface IMovement {
+    /** La venue où le mouvement a eu lieu. */
+    xex: XgateEx;
+    /** Nature normalisée (le type natif exact reste dans `xtras`). */
+    kind: MovementKind;
+    /** Montant **signé**, frais exclus. */
+    amount: string;
+    /** Frais prélevés par la venue, positifs ; `'0'` si aucun ou non publié. */
+    fee: string;
+    /** Actif déplacé. */
+    asset: string;
+    /** Moment où le mouvement a eu lieu. */
+    occurredAt: Date;
+    /** État côté venue. */
+    status: MovementStatus;
+    /**
+     * Clé de déduplication **stable** : hash de transaction ou identifiant natif quand la venue en
+     * publie un, sinon une clé dérivée. C'est ce qui rend un import idempotent — relire la même
+     * fenêtre deux fois ne doit pas créer de doublon.
+     */
+    externalId: string;
+    /** Champs natifs hors cœur unifié. */
+    xtras?: Record<string, unknown>;
+}
+/**
+ * UN POINT DE VALEUR DE COMPTE dans le temps.
+ *
+ * **Seules hyperliquid et pacifica le publient.** Les six autres venues n'ont rien d'équivalent, et
+ * XGate ne le fabrique pas : reconstituer une courbe depuis les mouvements et les prix produirait
+ * une valeur qu'aucune venue n'a cotée, avec une méthode différente de celle des deux qui la
+ * publient — donc incomparable avec elles.
+ */
+interface IEquityPoint {
+    /** La venue mesurée. */
+    xex: XgateEx;
+    /** Moment de la mesure. */
+    measuredAt: Date;
+    /** Valeur du compte, marquée au marché. */
+    equity: number;
+}
+
+/** Une venue et de quoi y lire un compte. */
+interface IWalletAccess extends IXexAccess {
+    xex: XgateEx;
+}
+/**
+ * LE PORTEFEUILLE, toutes venues confondues : soldes, mouvements d'argent, valeur du compte.
+ *
+ * **Les positions n'en font pas partie** — elles appartiennent au bloc trading, indissociable des
+ * ordres. Un portefeuille répond à « qu'est-ce que j'ai et d'où ça vient » ; une position répond à
+ * « qu'est-ce que je risque », et les deux ne se lisent pas au même moment.
+ *
+ * **Ce service ne calcule rien.** Il n'additionne pas les soldes entre venues, ne convertit aucun
+ * montant, ne reconstitue aucune courbe d'équité là où la venue n'en publie pas. Chaque ligne porte
+ * son `xex` : c'est à l'appelant de décider ce qui s'additionne, parce que lui seul sait si deux
+ * USDC à deux endroits sont fongibles pour son usage.
+ *
+ * **Lire un portefeuille est PUBLIC sur les DEX** : l'adresse suffit, aucune signature n'est
+ * produite. Seuls les CEX exigent une clé, même en lecture.
+ */
+declare class WalletService {
+    private readonly logger;
+    /** Les venues dont le portefeuille est lisible aujourd'hui. */
+    venues(): readonly XgateEx[];
+    /**
+     * Les soldes d'un ou plusieurs comptes.
+     *
+     * Même politique d'échec que les autres services : sur un seul accès, l'échec est relancé ; sur
+     * plusieurs, la liste partielle garde sa valeur et l'incident est journalisé. Rendre `[]` en
+     * silence ferait passer une venue injoignable pour un compte vide — et un compte vide, ça se
+     * regarde autrement qu'une panne.
+     */
+    balances(...accesses: IWalletAccess[]): Promise<IBalance[]>;
+    /**
+     * Les mouvements d'argent, triés du plus ancien au plus récent, montants **signés**.
+     *
+     * **Lève si la venue ne les sert pas** plutôt que de rendre une liste vide : « cette venue
+     * n'expose pas son historique » et « ce compte n'a jamais bougé » appellent des suites très
+     * différentes.
+     */
+    movements(...accesses: IWalletAccess[]): Promise<IMovement[]>;
+    /**
+     * La valeur du compte dans le temps.
+     *
+     * **Seules hyperliquid et pacifica la publient**, et XGate ne la fabrique pas ailleurs :
+     * reconstituer une courbe depuis les mouvements et les prix donnerait une valeur qu'aucune venue
+     * n'a cotée, avec une méthode incomparable à celle des deux qui la publient. Lève sur une venue
+     * qui n'en sert pas.
+     */
+    equityHistory(...accesses: IWalletAccess[]): Promise<IEquityPoint[]>;
+    /** Le motif commun aux trois lectures : un accès seul relance, plusieurs journalisent. */
+    private collect;
+}
+
+/** Sens de la position. Le SL et les TP se posent au sens OPPOSÉ. */
+type Direction = 'long' | 'short';
+/** Un ordre de protection, prêt à être posé : déclenchement, taille, borne d'exécution. */
+interface IProtectionLeg {
+    /** Prix auquel l'ordre se déclenche. */
+    triggerPrice: string;
+    /** Taille **en unités de base**. */
+    size: string;
+    /**
+     * Borne d'exécution du déclenché : sous le trigger en long, au-dessus en short. Hyperliquid
+     * l'exige ; les autres venues l'ignorent sans que ce soit une erreur.
+     */
+    price: string;
+}
+/** Ce qu'xgate rend : un SL pleine taille, et N take-profits partiels. */
+interface IProtection {
+    sl: IProtectionLeg;
+    tps: IProtectionLeg[];
+}
+/**
+ * Ce que l'appelant fournit. **Les pourcentages sont des écarts au prix d'entrée**, en fraction
+ * (0.01 = 1 %) : `slPct: 0.02` place le stop 2 % sous l'entrée en long, 2 % au-dessus en short.
+ */
+interface IProtectionInput {
+    /** Prix d'entrée de référence. */
+    entry: number;
+    direction: Direction;
+    /** Taille de la position, **en unités de base**. */
+    size: number;
+    /** Écart du stop au prix d'entrée, en fraction. Toujours du côté perdant. */
+    slPct: number;
+    /**
+     * Les take-profits, dans l'ordre. `pct` est l'écart au prix d'entrée (côté gagnant) et `part` la
+     * fraction de la position à sortir à ce niveau.
+     *
+     * **Une part à 0 ne produit AUCUN leg** — c'est un marqueur (un palier de breakeven, par exemple),
+     * pas un ordre. Sauf s'il s'agit du dernier : celui-là clôture toujours.
+     */
+    tps: Array<{
+        pct: number;
+        part: number;
+    }>;
+    /** Pas de prix de la paire. */
+    tickSize?: string | null;
+    /** Pas de quantité de la paire. */
+    lotSize?: string | null;
+    /**
+     * Écart entre le déclenchement et la borne d'exécution, en fraction (défaut 0,5 %). Le déclenché
+     * sort SOUS son trigger en long, AU-DESSUS en short.
+     */
+    slippagePct?: number;
+}
+/**
+ * Arrondit à un pas. `floor` pour les tailles — jamais `nearest` : arrondir au plus proche ferait
+ * dépasser la somme des legs au-delà de la position, et la venue rejetterait le dernier.
+ */
+declare function roundToStep(value: number, step: string | null | undefined, mode: 'floor' | 'nearest'): number;
+/**
+ * Arrondit un PRIX à la grille de la paire : `tickSize` s'il est fourni, sinon la règle Hyperliquid
+ * — cinq chiffres significatifs ET au plus `6 − szDecimals` décimales, `szDecimals` étant déduit du
+ * pas de quantité. Sans cette seconde branche, une venue sans tick fixe reçoit un prix qu'elle
+ * refuse.
+ */
+declare function roundPrice(value: number, tickSize?: string | null, lotSize?: string | null): number;
+/**
+ * LES NIVEAUX DE PROTECTION, calculés depuis des POURCENTAGES.
+ *
+ * L'appelant donne un prix d'entrée, un sens et des écarts ; il ne calcule aucun prix lui-même.
+ * Le stop part du côté perdant, les take-profits du côté gagnant — le sens s'en occupe.
+ */
+declare function buildLevels(entry: number, direction: Direction, slPct: number, tpPcts: readonly number[]): {
+    sl: number;
+    tps: number[];
+};
+/**
+ * LA PROTECTION COMPLÈTE — un stop pleine taille et N take-profits partiels, prêts à poser.
+ *
+ * **GARANTIE ANTI-RÉSIDU, sous condition de seuil.** Quand les parts somment à **plus de 80 %**, le
+ * DERNIER take-profit prend le reliquat EXACT (`size − Σ des précédents`) et la position ferme
+ * entièrement : trois paliers à 33 % font 99 %, et ce 1 % restant est un arrondi, pas une intention.
+ *
+ * **À 80 % ou en dessous, on laisse courir.** Deux paliers à 33 % sortent 66 % et laissent 34 % de
+ * position ouverte — c'est une sortie partielle voulue, et la compléter d'office la trahirait. Le
+ * dernier palier prend alors sa part nominale, sans plus.
+ *
+ * Les paliers intermédiaires s'arrondissent au **plancher**, jamais au plus proche : arrondir au
+ * plus proche ferait dépasser la somme, et c'est le dernier leg — celui qui clôture — que la venue
+ * rejetterait.
+ *
+ * **LE STOP COUVRE TOUJOURS LA TAILLE PLEINE.** Un stop partiel laisserait une fraction de position
+ * sans protection, ce qui est précisément ce qu'on veut rendre impossible : jamais une position
+ * nue, même partiellement.
+ *
+ * Deux cas font disparaître un leg, et c'est voulu :
+ * · une part à 0 sur un palier intermédiaire — c'est un marqueur, pas un ordre ;
+ * · une taille qui tombe à 0 après arrondi — un ordre de taille nulle serait refusé.
+ * Le dernier palier, lui, survit toujours : c'est lui qui ferme.
+ */
+declare function buildProtection(input: IProtectionInput): IProtection;
+
+/** Côté d'un ordre. À ne pas confondre avec le SENS d'une position ({@link Direction}). */
+type Side = 'buy' | 'sell';
+/** Nature d'un ordre, telle qu'XGate la nomme. Le type natif exact reste dans `xtras`. */
+type OrderType = 'limit' | 'market' | 'stop' | 'stopMarket' | 'takeProfit' | 'takeProfitMarket' | 'other';
+/**
+ * ÉTAT D'UN ORDRE — **exactement les sept valeurs des SDK de venue**, orthographe comprise.
+ *
+ * `canceled` prend un seul L : c'est ce que rendent les huit SDK, unanimement. XGate écrivait
+ * `cancelled` et perdait `partiallyFilled` et `expired` ; le `as OrderStatus` de la conversion
+ * masquait l'écart au lieu de le signaler, si bien qu'un consommateur testant `=== 'cancelled'`
+ * ne matchait **jamais** — un ordre annulé passait pour un ordre encore vivant.
+ *
+ * Seul `filled` a déplacé tout ce qui était demandé ; `partiallyFilled` en a déplacé une part et
+ * garde le reste au carnet.
+ */
+type OrderStatus = 'open' | 'partiallyFilled' | 'filled' | 'canceled' | 'rejected' | 'expired' | 'other';
+/**
+ * Les sept statuts, énumérés — pour VALIDER ce qu'une venue rend plutôt que de le caster.
+ *
+ * Un `as OrderStatus` sur une chaîne inconnue produit une valeur qui n'existe dans aucun `switch` et
+ * que personne ne rattrape ; passer par cette liste fait retomber l'inconnu sur `other`, qui lui est
+ * traité partout.
+ */
+declare const ORDER_STATUSES: readonly OrderStatus[];
+/** Durée de validité. `alo` = post-only : l'ordre est refusé s'il devait s'exécuter immédiatement. */
+type TimeInForce = 'gtc' | 'ioc' | 'fok' | 'alo';
+/**
+ * UN ORDRE, tel qu'XGate le rend.
+ *
+ * `xex` dit d'où il vient : un identifiant d'ordre n'a de sens que chez la venue qui l'a émis, et
+ * deux venues peuvent parfaitement produire le même.
+ */
+interface IOrder {
+    xex: XgateEx;
+    /** Le symbole que la venue attend. */
+    symbolXex: string;
+    /** Type de marché. */
+    kind: 'perp' | 'spot';
+    /** L'identifiant de la venue. */
+    id: string;
+    /** L'identifiant fourni par l'appelant, quand il en a donné un. */
+    clientId: string | null;
+    side: Side;
+    type: OrderType;
+    /** `null` pour un ordre au marché. */
+    price: string | null;
+    /** Taille demandée, **en unités de base**. */
+    size: string;
+    /** Taille déjà exécutée, **en unités de base**. */
+    filled: string;
+    status: OrderStatus;
+    tif: TimeInForce | null;
+    /** L'ordre ne peut que réduire une position existante — jamais en ouvrir une. */
+    reduceOnly: boolean | null;
+    /** Moment où l'ordre a été soumis. */
+    placedAt: Date;
+    xtras?: Record<string, unknown>;
+}
+/**
+ * UNE POSITION ouverte.
+ *
+ * `size` est **toujours positive** : le sens est porté par `side`. Mélanger les deux — une taille
+ * négative pour un short — oblige chaque consommateur à se souvenir de la convention, et l'un d'eux
+ * l'oubliera.
+ */
+interface IPosition {
+    xex: XgateEx;
+    symbolXex: string;
+    /** Nom canonique de l'actif, pour rapprocher la même position entre venues. */
+    symbol: string;
+    side: 'long' | 'short' | null;
+    /** Taille **en unités de base**, toujours positive. */
+    size: string;
+    entryPrice: string | null;
+    markPrice: string | null;
+    unrealizedPnl: string | null;
+    leverage: number | null;
+    liquidationPrice: string | null;
+    /** Marge immobilisée par la position. */
+    margin: string | null;
+    xtras?: Record<string, unknown>;
+}
+/** UNE EXÉCUTION du compte — ce qui a réellement été rempli, par opposition à ce qui a été demandé. */
+interface ITrade {
+    xex: XgateEx;
+    symbolXex: string;
+    kind: 'perp' | 'spot';
+    id: string;
+    /** L'ordre dont provient cette exécution. */
+    orderId: string;
+    side: Side;
+    price: string;
+    size: string;
+    fee: string;
+    feeAsset: string | null;
+    /** PnL réalisé, avant et après frais ; `null` quand la venue ne permet pas de l'établir. */
+    grossPnl: string | null;
+    netPnl: string | null;
+    /** L'exécution était côté maker. `null` si la venue ne le dit pas. */
+    maker: boolean | null;
+    /** Moment de l'exécution. */
+    filledAt: Date;
+    xtras?: Record<string, unknown>;
+}
+/**
+ * CE QU'ON DEMANDE POUR OUVRIR UNE POSITION PROTÉGÉE.
+ *
+ * **Les protections sont données en POURCENTAGES**, pas en prix : xgate calcule les niveaux depuis
+ * le prix d'entrée. L'appelant n'a ni à arrondir au tick, ni à se souvenir que le stop d'un short
+ * est au-dessus de l'entrée.
+ *
+ * **`slPct` est OBLIGATOIRE.** C'est la règle qui a motivé tout ce chemin : jamais un ordre sans
+ * stop. Une position ouverte pendant que le serveur tombe reste protégée par la venue elle-même.
+ */
+interface IEntryWithProtection {
+    xex: XgateEx;
+    /** Le symbole que la venue attend. */
+    symbolXex: string;
+    /** Sens de la POSITION à ouvrir. Le stop et les take-profits se posent au sens opposé. */
+    direction: Direction;
+    /** Taille à ouvrir, **en unités de base**. */
+    size: number;
+    /** Prix d'entrée visé. Sert de référence aux pourcentages, et de prix limite. */
+    entry: number;
+    /** Écart du stop au prix d'entrée, en fraction (0.02 = 2 %). Obligatoire. */
+    slPct: number;
+    /**
+     * Les take-profits, dans l'ordre. `part` est la fraction de la position à sortir.
+     *
+     * Au-dessus de 80 % cumulés, le dernier absorbe le reliquat et la position ferme entièrement ;
+     * à 80 % ou en dessous, le reste court.
+     */
+    tps: Array<{
+        pct: number;
+        part: number;
+    }>;
+    /** `ioc` pour entrer au marché (taker), `alo` pour poster (maker). Défaut : `ioc`. */
+    tif?: TimeInForce;
+    /** Identifiant applicatif, remonté tel quel par la venue quand elle le supporte. */
+    clientId?: string;
+    /** Pas de prix et de quantité de la paire — sans eux, la venue refuse des niveaux mal arrondis. */
+    tickSize?: string | null;
+    lotSize?: string | null;
+    /** Écart entre déclenchement et borne d'exécution du déclenché. Défaut 0,5 %. */
+    slippagePct?: number;
+}
+
+/** Une venue et de quoi y agir. */
+interface ITradingAccess extends IXexAccess {
+    xex: XgateEx;
+}
+/**
+ * LE TRADING : positions, ordres et exécutions — un seul service, et c'est délibéré.
+ *
+ * Les séparer laisserait diverger trois vues du même état : une position n'est que la somme des
+ * ordres exécutés, et un ordre ne se lit pas sans savoir ce qu'il a ouvert.
+ *
+ * **JAMAIS UN ORDRE SANS STOP.** `openWithProtection` est la seule façon d'ouvrir une position par
+ * ce service, et elle exige un `slPct`. La protection part avec l'entrée, en un geste que la venue
+ * traite atomiquement : si l'entrée ne remplit pas, la protection ne naît jamais — aucun orphelin.
+ * Poser le stop *après* l'entrée laisse une fenêtre pendant laquelle la position est nue, et cette
+ * fenêtre s'ouvre précisément quand le serveur tombe.
+ *
+ * **L'appelant donne des POURCENTAGES**, jamais des prix : xgate calcule les niveaux, arrondit à la
+ * grille de la paire, et garantit qu'au-dessus de 80 % de parts cumulées la position ferme
+ * entièrement — sans reliquat.
+ */
+declare class TradingService {
+    private readonly logger;
+    /**
+     * OUVRE UNE POSITION AVEC SA PROTECTION, en un geste atomique.
+     *
+     * Le premier ordre rendu est **l'entrée** ; les suivants sont le stop et les take-profits, dans
+     * l'ordre où ils ont été posés.
+     *
+     * Chaque venue applique son mécanisme natif — hyperliquid groupe les enfants sous l'entrée et les
+     * annule lui-même si elle rate, pacifica les embarque dans l'ordre, aster envoie un lot de
+     * conditionnels. Le SDK de la venue s'en charge ; xgate fournit des niveaux justes.
+     */
+    openWithProtection(access: ITradingAccess, input: IEntryWithProtection): Promise<IOrder[]>;
+    /** Les positions ouvertes d'un compte. */
+    positions(access: ITradingAccess, symbolXex?: string): Promise<IPosition[]>;
+    /** Les ordres encore au carnet. */
+    openOrders(access: ITradingAccess): Promise<IOrder[]>;
+    /**
+     * Les exécutions du compte — ce qui a réellement été rempli.
+     *
+     * À ne pas confondre avec les ordres : un ordre annoncé `filled` peut avoir été rempli en
+     * plusieurs fois, à des prix différents. C'est ici que se lit le prix moyen réel.
+     */
+    trades(access: ITradingAccess): Promise<ITrade[]>;
+    /**
+     * FERME UNE POSITION ENTIÈREMENT, sur la taille que **la venue** déclare — jamais celle qu'on croit.
+     *
+     * C'est toute la différence : fermer la taille planifiée laisse un reliquat quand le fill a différé du
+     * plan (une entrée partiellement remplie, un take-profit passé entre-temps), et ce reliquat reste
+     * ouvert, sans stop, à la charge du compte. On relit donc la position juste avant de la fermer.
+     *
+     * Rend `null` quand il n'y a rien à fermer — un appel sur une position déjà close n'est pas une erreur.
+     */
+    closePosition(access: ITradingAccess, symbolXex: string): Promise<IOrder | null>;
+    /**
+     * LE PRIX DE SORTIE RÉEL d'une position, lu dans l'historique de la venue.
+     *
+     * Le prix planifié ne dit pas à quel prix on est sorti : un stop se déclenche au marché, un
+     * take-profit peut remplir en plusieurs fois. Seul l'historique porte le prix réellement obtenu, et
+     * c'est lui qui doit servir au calcul du résultat — sinon le PnL affiché est une fiction.
+     *
+     * On retient le **dernier** ordre de sortie rempli après `openedAt` : les précédents sont les
+     * take-profits partiels, celui-là est la clôture.
+     */
+    exitPrice(access: ITradingAccess, symbolXex: string, direction: Direction, openedAt: Date): Promise<string | null>;
+    /** Annule un ordre par son identifiant de venue. */
+    cancel(access: ITradingAccess, symbolXex: string, orderId: string): Promise<void>;
+    /** Le scope `perp()` de la venue, typé au plus près de ce que le contrat commun garantit. */
+    private perpOf;
+    /**
+     * Le statut de la venue, VALIDÉ — jamais casté. Une venue qui inventerait un statut rendrait sinon
+     * une valeur absente de tous les `switch` en aval, et personne ne la rattraperait.
+     */
+    private toStatus;
+    private toOrder;
+}
+
+/** La venue sert-elle cet intervalle de première main ? */
+declare function servesNatively(xex: XgateEx, interval: Timeframe): boolean;
+/**
+ * L'intervalle SOURCE à demander pour fabriquer `target` chez cette venue.
+ *
+ * On prend le **plus grand** intervalle servi nativement qui divise la cible : le plus grand,
+ * parce qu'il minimise le nombre de bougies à tirer — reconstruire une semaine depuis des minutes
+ * demanderait 10 080 points là où sept journalières suffisent.
+ *
+ * `undefined` = la venue ne sert rien d'exploitable, il n'y a pas de fabrication possible.
+ */
+declare function sourceFor(xex: XgateEx, target: Timeframe): Timeframe | undefined;
+
+/**
+ * SYMBOLE BRUT D'UNE VENUE → CANONIQUE.
+ *
+ * DÉPEND DE LA VENUE, pour ne JAMAIS amputer un stablecoin ni un actif finissant par USD(T/C) :
+ *  - aster/binance/bybit : quote concaténé → on strippe `USDT`/`USDC` FINAL (USDEUSDT→USDE, BTCUSDT→BTC) ;
+ *  - les autres : uniquement les suffixes SÉPARÉS (`-USD-PERP`, `-PERP`, `-USDT`, `-USDC`, `-USD`). Jamais de
+ *    strip nu → un actif nu (USDC, USDT, USDE, BUSD, BTC) reste intact ;
+ *  - dans tous les cas, le multiplicateur tombe d'abord (kPEPE → PEPE).
+ *
+ * `-USDT` A ÉTÉ AJOUTÉ le 2026-08-05, en agrégeant blofin pour la première fois : elle cote
+ * `BTC-USDT` avec un tiret, forme qu'aucune venue de Blips n'utilisait. Sans lui, **477 des 487
+ * symboles blofin restaient non canonisés** (`BTC-USDT` au lieu de `BTC`) et aucun ne se
+ * rapprochait de son homologue chez une autre venue. Le tiret rend le strip sûr : l'actif nu
+ * `USDT` n'y correspond pas.
+ */
+declare function canonicalFromXex(rawSymbol: string, xexId: string): string;
+/**
+ * ACTIF DE BASE NU → CANONIQUE, pour les venues qui NOMMENT leur actif au lieu de le concaténer : binance rend
+ * `baseAsset`, bybit `baseCoin`. On prend ce qu'elles DISENT plutôt que de re-parser leur symbole — sans quoi
+ * `ROSEBTC` (cotée en BTC, pas en USDT) donnerait le faux canonique `ROSEBTC`.
+ *
+ * Mêmes règles que `canonicalFromXex` MOINS le strip de cotation : l'appliquer à une base nue amputerait les
+ * stablecoins (`USDC` → chaîne VIDE). C'est exactement le piège que la connaissance de la venue évite déjà côté
+ * symbole.
+ */
+declare function canonicalFromBase(base: string): string;
+
+export { CandlesService, CatalogService, type Direction, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, 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 };