@blackcube/xgate-sdk 0.24.0 → 0.25.0

package/dist/index.d.cts

@@ -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[];
@@ -1261,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`. */
@@ -1651,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 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 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 };
+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 };

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[];
@@ -1261,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`. */
@@ -1651,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 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 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 };
+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 };

package/dist/index.js

@@ -1075,6 +1075,13 @@ SpotWsCandlesService = __decorateClass([
 ], SpotWsCandlesService);
 
 // src/helpers/protection.ts
+function priceOf(cible, entry, direction, gagnant) {
+  if (cible.price !== void 0) {
+    return round8(cible.price);
+  }
+  const dir = (direction === "long" ? 1 : -1) * (gagnant === true ? 1 : -1);
+  return round8(entry * (1 + dir * cible.pct));
+}
 var SLIPPAGE_DEFAUT = 5e-3;
 var SEUIL_CLOTURE = 0.8;
 function round8(value) {
@@ -1117,12 +1124,8 @@ function buildLevels(entry, direction, slPct, tpPcts) {
 function buildProtection(input) {
   const slippage = input.slippagePct ?? SLIPPAGE_DEFAUT;
   const long = input.direction === "long";
-  const { sl, tps: niveaux } = buildLevels(
-    input.entry,
-    input.direction,
-    input.slPct,
-    input.tps.map((tp) => tp.pct)
-  );
+  const sl = priceOf(input.sl, input.entry, input.direction, false);
+  const niveaux = input.tps.map((tp) => priceOf(tp, input.entry, input.direction, true));
   const borne = (trigger) => long === true ? trigger * (1 - slippage) : trigger * (1 + slippage);
   const sommeParts = input.tps.reduce((total, tp) => total + tp.part, 0);
   const clotureIntegrale = sommeParts > SEUIL_CLOTURE;
@@ -1193,7 +1196,7 @@ var TradingService = class {
       entry: input.entry,
       direction: input.direction,
       size: input.size,
-      slPct: input.slPct,
+      sl: input.sl,
       tps: input.tps,
       tickSize: input.tickSize,
       lotSize: input.lotSize,