@blackcube/xgate-sdk 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -969,23 +969,42 @@ interface IProtection {
  * 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.
  */
+/**
+ * UN NIVEAU DE SORTIE — dit en ÉCART ou en PRIX, jamais les deux.
+ *
+ * Les deux façons de penser un objectif coexistent réellement : « je sors si ça monte de 10 % »
+ * raisonne en risque, « je sors si ça touche 62 500 » raisonne en niveau technique. Obliger à
+ * convertir l'un dans l'autre revient à faire calculer l'appelant, donc à déplacer l'erreur chez lui.
+ *
+ * L'union est **exclusive** par construction : donner les deux ne compile pas, et n'en donner aucun
+ * non plus. C'est ce qui rend impossible un objectif à moitié défini.
+ */
+type ITarget = {
+    pct: number;
+    price?: never;
+} | {
+    price: number;
+    pct?: never;
+};
 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.
+     * Le stop — en **écart** au prix d'entrée (`{ pct: 0.02 }`) ou en **prix absolu**
+     * (`{ price: 62500 }`). Toujours du côté perdant quand il est donné en écart.
+     */
+    sl: ITarget;
+    /**
+     * Les take-profits, dans l'ordre. Chacun porte son niveau — en écart ou en prix — et `part`, la
+     * fraction de la POSITION à sortir là (toujours un pourcentage, jamais un prix).
      *
      * **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;
+    tps: Array<ITarget & {
         part: number;
     }>;
     /** Pas de prix de la paire. */
@@ -1016,6 +1035,12 @@ declare function roundPrice(value: number, tickSize?: string | null, lotSize?: s
  * 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.
  */
+/**
+ * Les niveaux depuis des POURCENTAGES seuls — forme courte quand tout est exprimé en écart.
+ *
+ * {@link buildProtection} ne l'utilise plus : il résout chaque niveau séparément, puisqu'un stop
+ * peut être donné en écart et un take-profit en prix absolu dans le même appel.
+ */
 declare function buildLevels(entry: number, direction: Direction, slPct: number, tpPcts: readonly number[]): {
     sl: number;
     tps: number[];
@@ -1128,6 +1153,69 @@ interface IPosition {
     margin: string | null;
     xtras?: Record<string, unknown>;
 }
+/**
+ * UNE TRANSACTION PUBLIQUE — celles de tout le monde sur un marché, pas les siennes.
+ *
+ * À ne pas confondre avec {@link ITrade}, qui est une exécution **du compte**. Celle-ci n'a ni
+ * frais, ni PnL, ni identifiant d'ordre : on ne voit que ce que le marché montre.
+ */
+interface IPublicTrade {
+    xex: XgateEx;
+    symbolXex: string;
+    price: string;
+    size: string;
+    /** Sens de l'AGRESSEUR : `buy` = quelqu'un a pris l'offre. */
+    side: Side;
+    tradedAt: Date;
+    xtras?: Record<string, unknown>;
+}
+/**
+ * L'ÉTAT D'UN COMPTE — ce que toutes les venues disent, sous des noms différents.
+ *
+ * Les formes natives ne se ressemblent pas : hyperliquid range son équité sous
+ * `marginSummary.accountValue`, pacifica sous `accountEquity`, aster sous `totalMarginBalance`.
+ * **Mais les concepts, eux, sont les mêmes** — c'est exactement ce qu'XGate existe pour normaliser.
+ *
+ * `xtras` conserve la forme native complète : ce qui est propre à une venue n'est pas perdu, il
+ * n'est simplement pas promu au rang de contrat.
+ */
+interface IAccountState {
+    xex: XgateEx;
+    /** Valeur totale du compte, PnL latent compris. */
+    equity: string;
+    /** Ce qui reste mobilisable — pour ouvrir ou retirer. `null` si la venue ne le publie pas. */
+    available: string | null;
+    /** Marge immobilisée par les positions et ordres en cours. */
+    marginUsed: string | null;
+    /** Marge de maintenance : sous ce seuil, la liquidation menace. */
+    maintenanceMargin: string | null;
+    /**
+     * PnL non réalisé des positions ouvertes.
+     *
+     * **Seule aster le publie au niveau du compte.** hyperliquid et pacifica ne l'exposent pas là —
+     * il se lit alors sur les positions (`IPosition.unrealizedPnl`), qui le portent toutes. On rend
+     * `null` plutôt que de le reconstituer : une somme calculée ici passerait pour une donnée de la
+     * venue.
+     */
+    unrealizedPnl: string | null;
+    /** L'état natif COMPLET, tel que la venue le publie. */
+    xtras?: Record<string, unknown>;
+}
+/**
+ * UN FUNDING PAYÉ — ce qui a réellement été prélevé ou reçu sur une position.
+ *
+ * À ne pas confondre avec le taux courant d'`IPrice.funding`, qui annonce ce qui *sera* payé. Un
+ * calcul de résultat qui ignore ce qui l'a été surestime toute position tenue longtemps.
+ */
+interface IFundingPaid {
+    xex: XgateEx;
+    symbolXex: string;
+    /** Le taux appliqué, en fraction. */
+    rate: string;
+    /** Moment où il a été prélevé. */
+    appliedAt: Date;
+    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;
@@ -1198,16 +1286,34 @@ interface IEntryWithProtection {
     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.
+     * LE STOP — en **écart** au prix d'entrée ou en **prix absolu**, jamais les deux.
+     *
+     * ```typescript
+     * sl: { pct: 0.02 }      // 2 % sous l'entrée en long, 2 % au-dessus en short
+     * sl: { price: 62500 }   // exactement 62 500, quel que soit le prix d'entrée
+     * ```
+     *
+     * **Obligatoire.** C'est la règle qui a motivé tout ce chemin : jamais un ordre sans stop.
+     */
+    sl: ITarget;
+    /**
+     * LES TAKE-PROFITS, dans l'ordre. Chacun dit son NIVEAU et sa PART.
+     *
+     * ```typescript
+     * tps: [{ pct: 0.03, part: 0.5 },     // sortir 50 % si ça monte de 3 %
+     *        { price: 62500, part: 0.5 }] // sortir 50 % si ça touche 62 500
+     * ```
+     *
+     * **`part` est toujours une fraction de la POSITION**, jamais un prix : les deux modes ne portent
+     * que sur le niveau. Un objectif se pense soit en risque (« +3 % »), soit en niveau technique
+     * (« 62 500 ») — obliger à convertir l'un dans l'autre déplacerait le calcul, donc l'erreur, chez
+     * l'appelant.
      *
      * 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;
+    tps: Array<ITarget & {
         part: number;
     }>;
     /** `ioc` pour entrer au marché (taker), `alo` pour poster (maker). Défaut : `ioc`. */
@@ -1254,6 +1360,18 @@ declare class TradingService {
      * conditionnels. Le SDK de la venue s'en charge ; xgate fournit des niveaux justes.
      */
     openWithProtection(access: ITradingAccess, input: IEntryWithProtection): Promise<IOrder[]>;
+    /**
+     * CE QUE LA VENUE A RÉELLEMENT FAIT, après une réponse perdue.
+     *
+     * Un timeout ne dit pas « rien n'a été créé » : mesuré sur aster, deux exécutions identiques ont
+     * produit deux sous-ensembles différents — une fois le stop et un take-profit, une fois l'entrée
+     * seule. La seule vérité est au carnet, donc on va l'y chercher.
+     *
+     * **Lève si la position est nue** : une entrée remplie sans stop est exactement ce que ce service
+     * existe pour empêcher, et le silence serait pire que l'erreur. L'appelant doit savoir qu'il a une
+     * position à protéger, tout de suite.
+     */
+    private etatApres;
     /** Les positions ouvertes d'un compte. */
     positions(access: ITradingAccess, symbolXex?: string): Promise<IPosition[]>;
     /** Les ordres encore au carnet. */
@@ -1302,10 +1420,120 @@ declare class TradingService {
      * take-profits partiels, celui-là est la clôture.
      */
     exitPrice(access: ITradingAccess, symbolXex: string, direction: Direction, openedAt: Date): Promise<string | null>;
+    /**
+     * L'HISTORIQUE DES ORDRES du compte — ce qui a été soumis, rempli, annulé ou expiré.
+     *
+     * À distinguer de {@link trades} : un ordre est une **intention**, une exécution est un **fait**.
+     * Un ordre `filled` peut avoir été rempli en plusieurs fois, à des prix différents.
+     *
+     * Servi par les huit venues qui tradent.
+     */
+    orderHistory(access: ITradingAccess, symbolXex?: string): Promise<IOrder[]>;
+    /**
+     * L'ÉTAT DU COMPTE — équité, disponible, marge immobilisée, marge de maintenance, PnL latent.
+     *
+     * Les venues rangent ces valeurs sous des noms qui n'ont rien à voir : `marginSummary.accountValue`
+     * chez hyperliquid, `accountEquity` chez pacifica, `totalMarginBalance` chez aster — **mais elles
+     * disent la même chose**. La forme native complète reste dans `xtras`, rien n'est perdu.
+     *
+     * **blofin ne l'expose pas** et lève ; les sept autres le servent.
+     */
+    accountInfo(access: ITradingAccess): Promise<IAccountState>;
+    /**
+     * RÈGLE LE LEVIER d'une paire, avant d'ouvrir.
+     *
+     * Le levier détermine la marge immobilisée, donc la taille tenable : le changer après l'ouverture
+     * ne rejoue pas la position déjà prise. C'est un réglage préalable, pas un ajustement.
+     *
+     * **bullet ne l'expose pas** — son levier se fixe au compte, pas à la position — et lève.
+     */
+    setLeverage(access: ITradingAccess, symbolXex: string, leverage: number): Promise<void>;
+    /**
+     * CHOISIT LE MODE DE MARGE d'une paire : **isolée** ou **croisée**.
+     *
+     * En **croisée**, tout le solde du compte garantit la position : elle tient plus longtemps, mais
+     * une liquidation emporte l'ensemble. En **isolée**, seule la marge affectée est en jeu : la perte
+     * est bornée à ce montant, la liquidation arrive plus tôt.
+     *
+     * **À régler AVANT d'ouvrir.** Changer le mode d'une position vivante est refusé par la plupart
+     * des venues, et là où c'est accepté, cela redistribue la garantie sous les pieds de la position.
+     *
+     * Servi par les trois venues de référence.
+     */
+    setMarginMode(access: ITradingAccess, symbolXex: string, isolated: boolean): Promise<void>;
+    /**
+     * AJOUTE DE LA MARGE à une position isolée — pour éloigner le prix de liquidation.
+     *
+     * C'est le geste qui sauve une position sous pression sans la réduire : on renforce la garantie
+     * plutôt que de couper. **N'a de sens qu'en marge isolée** ; en croisée, tout le solde garantit
+     * déjà la position et il n'y a rien à ajouter.
+     *
+     * Servi par les trois venues de référence.
+     */
+    addMargin(access: ITradingAccess, symbolXex: string, amount: string): Promise<void>;
+    /**
+     * RETIRE DE LA MARGE d'une position isolée — pour libérer du capital.
+     *
+     * L'inverse d'{@link addMargin} : la garantie diminue, donc le prix de liquidation **se rapproche**.
+     * La venue refuse ce qui mettrait la position sous son seuil de maintenance.
+     *
+     * ⚠️ **pacifica ne l'expose pas** et lève : chez elle, la marge s'ajoute mais ne se retire pas.
+     * Fermer partiellement la position libère alors le capital.
+     */
+    removeMargin(access: ITradingAccess, symbolXex: string, amount: string): Promise<void>;
+    /**
+     * L'HISTORIQUE DU FUNDING **PAYÉ** sur une paire — ce qui a réellement été prélevé ou reçu.
+     *
+     * À ne pas confondre avec le taux courant, que rend `PricesService` : celui-ci annonce ce qui
+     * *sera* payé, celui-là dit ce qui *l'a été*. Un backtest qui ignore le funding réel surestime le
+     * résultat d'une position tenue longtemps.
+     *
+     * Servi par les huit venues qui tradent.
+     */
+    fundingHistory(access: ITradingAccess, symbolXex: string, range?: {
+        startTime?: Date;
+        endTime?: Date;
+        limit?: number;
+    }): Promise<IFundingPaid[]>;
+    /**
+     * UN IDENTIFIANT APPLICATIF pour un ordre, **au format que la venue accepte**.
+     *
+     * C'est lui qui relie un ordre à la décision qui l'a produit : la venue le rend tel quel dans
+     * `IOrder.clientId`, ce qui permet de retrouver son origine sans tenir de table de correspondance.
+     *
+     * **hyperliquid exige un hexadécimal préfixé `0x`** (128 bits) là où les autres acceptent un UUID
+     * ordinaire. Passer le mauvais format fait rejeter l'ordre — d'où cette méthode plutôt qu'un
+     * `randomUUID()` chez l'appelant.
+     */
+    newClientOrderId(xex: XgateEx): string;
+    /**
+     * LE COUPE-CIRCUIT : annule TOUS les ordres d'une paire, d'un geste.
+     *
+     * À réserver aux situations où l'on veut reprendre la main sans discuter — un état incohérent, un
+     * arrêt d'urgence, une reprise après incident. Annuler un par un laisse une fenêtre pendant
+     * laquelle certains ordres vivent encore.
+     *
+     * ⚠️ **Cela retire aussi les PROTECTIONS.** Stops et take-profits sont des ordres comme les
+     * autres : une position ouverte se retrouve **nue** après ce geste. À n'employer que si la
+     * position est fermée, ou si l'on repose une protection immédiatement — jamais pour « faire le
+     * ménage » sur une position vivante.
+     *
+     * Rend le nombre d'ordres annulés quand la venue le publie, `null` sinon.
+     */
+    cancelAll(access: ITradingAccess, symbolXex: string): Promise<number | 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;
+    /**
+     * L'état natif d'une venue → {@link IAccountState}.
+     *
+     * Une lecture EXPLICITE par venue plutôt qu'un parcours à l'aveugle : les noms ne se devinent pas,
+     * et prendre le premier champ qui ressemble à une équité produirait un chiffre faux sans que rien
+     * ne le signale. `null` là où la venue ne publie pas la valeur — pas `0`, qui se lirait comme
+     * « rien » alors que personne n'a rien dit.
+     */
+    private toAccountState;
     /**
      * 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.
@@ -1314,6 +1542,75 @@ declare class TradingService {
     private toOrder;
 }
 
+/**
+ * LE FLUX DES EXÉCUTIONS DU COMPTE — savoir ce qui s'est rempli, à l'instant où ça se remplit.
+ *
+ * **C'est la seule façon de connaître son état exact.** Sans lui, on interroge en boucle et on
+ * apprend un remplissage avec le retard du sondage : entre-temps, un take-profit partiel a pu
+ * modifier la taille de la position, et toute décision prise sur l'ancienne valeur est fausse.
+ *
+ * Le flux ne dit pas ce qu'on a **demandé** mais ce qui a été **obtenu** : un ordre annoncé `filled`
+ * peut l'avoir été en plusieurs fois, à des prix différents. Chaque exécution porte son prix réel.
+ *
+ * **ON NE TRANSMET QUE CE QUI ARRIVE APRÈS L'OUVERTURE DU FLUX.** Les venues rejouent leur
+ * historique à la souscription : mesuré le 2026-08-09 sur hyperliquid, 30 exécutions arrivent dans
+ * les six premières secondes, **toutes antérieures** à l'abonnement, la plus ancienne de plus de
+ * deux jours. Sans filtre, chaque reconnexion rejouerait deux jours de trades — et un consommateur
+ * qui compte les remplissages compterait deux fois les mêmes.
+ *
+ * Le filtre se fait sur `filledAt` contre l'instant d'abonnement. Un flux dit le **présent** ;
+ * l'historique se lit avec `TradingService.trades()`, qui est fait pour ça.
+ *
+ * **blofin est la seule venue qui ne l'expose pas** ; elle lève. Les sept autres le servent.
+ */
+declare class WsTradesService {
+    private readonly logger;
+    /**
+     * S'abonne aux exécutions d'un compte. Rend la fonction de désabonnement.
+     *
+     * Le handler reçoit **une exécution à la fois**, au format unifié, et **uniquement celles
+     * survenues après l'abonnement** — le rejeu d'historique de la venue est écarté.
+     */
+    subscribe(access: ITradingAccess, handler: (trade: ITrade) => void): Unsubscribe;
+    /**
+     * S'abonne aux exécutions de PLUSIEURS comptes, avec un seul handler.
+     *
+     * Chaque exécution porte son `xex` : l'appelant sait toujours de quelle venue elle vient. La
+     * fonction rendue coupe tous les flux d'un coup — sinon il faudrait en garder N et n'en oublier
+     * aucun.
+     *
+     * Une venue qui refuse est journalisée et ignorée : le reste des comptes doit continuer d'être
+     * suivi. Sur un seul accès, l'échec est celui de l'appel.
+     */
+    subscribeAll(accesses: ITradingAccess[], handler: (trade: ITrade) => void): Unsubscribe;
+    /**
+     * S'abonne aux ORDRES du compte — leur naissance, leur remplissage, leur mort.
+     *
+     * À distinguer des exécutions : un ordre est une **intention** dont on suit le cycle de vie
+     * (`open` → `partiallyFilled` → `filled`, ou `canceled`), une exécution est un **fait** ponctuel.
+     * Pour savoir qu'un stop vient de se déclencher, c'est ici qu'il faut écouter ; pour savoir à quel
+     * prix, c'est {@link subscribe}.
+     *
+     * **Même règle que pour les exécutions** : seuls les ordres postérieurs à l'abonnement sont
+     * transmis, le rejeu d'historique est écarté.
+     */
+    subscribeOrders(access: ITradingAccess, handler: (order: IOrder) => void): Unsubscribe;
+    /**
+     * S'abonne aux TRANSACTIONS PUBLIQUES d'un marché — celles de tout le monde, pas les siennes.
+     *
+     * C'est le flux qui dit ce qui se négocie réellement : prix, taille, sens agresseur. Il sert à
+     * mesurer l'activité d'une paire, pas à suivre son compte — pour cela, {@link subscribe}.
+     *
+     * **Aucun filtre temporel ici** : un trade public est daté de son exécution et arrive en direct,
+     * il n'y a pas d'historique rejoué à écarter.
+     */
+    subscribePublicTrades(access: ITradingAccess, symbolXex: string, handler: (trade: IPublicTrade) => void): Unsubscribe;
+    /** Le client temps réel d'un compte, avec ses souscriptions signées. */
+    private wsOf;
+    private toOrder;
+    private toTrade;
+}
+
 /** La venue sert-elle cet intervalle de première main ? */
 declare function servesNatively(xex: XgateEx, interval: Timeframe): boolean;
 /**
@@ -1397,4 +1694,4 @@ declare function expiryOf(xtras?: Record<string, unknown>): Date | undefined;
  */
 declare function isDated(xtras?: Record<string, unknown>): boolean;
 
-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 };
+export { CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, type Direction, type IAccountState, type IBalance, type ICandle, type ICandlesQuery, type IEntryWithProtection, type IEquityPoint, type IFundingPaid, type IMoveStop, type IMovement, type IOrder, type IPair, type IPosition, type IPrice, type IProtection, type IProtectionInput, type IProtectionLeg, type IPublicTrade, type ITarget, type ITrade, type ITradingAccess, type IWalletAccess, type IXexAccess, type IXexSpotSource, type MarketKind, type MovementKind, type MovementStatus, ORDER_STATUSES, type OrderStatus, type OrderType, PricesService, SPOT_XEXES, type Side, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, type TimeInForce, Timeframe, TradingService, type Unsubscribe, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };