@blackcube/xgate-sdk 0.25.1 → 0.25.3

package/dist/index.d.cts

@@ -461,6 +461,92 @@ declare const WS_SUBSCRIPTION_LIMITS: Partial<Record<XgateEx, number>>;
  */
 declare function subscriptionLimitOf(xex: XgateEx): number | undefined;
 
+/**
+ * COMBIEN DE BOUGIES UNE VENUE SERT PAR APPEL — uniquement ce qu'une documentation ou un SDK affirme.
+ *
+ * Le budget d'une venue se compte en APPELS, pas en bougies : dix fois plus de barres par appel, c'est dix fois
+ * moins d'appels ET dix fois moins d'attente cumulée. C'est le seul levier qui décide de la durée d'un backfill.
+ *
+ * **binance** — « `limit` est plafonné à 1500 par la venue **sur les deux marchés** ; au-delà, elle refuse la
+ * requête au lieu de tronquer » (`binance-sdk`, docblock de `getCandles`). Le plafond vaut donc pour le comptant
+ * comme pour le perpétuel.
+ *
+ * **bybit** — `limit [1, 1000]`, défaut **200** (doc officielle v5, `/v5/market/kline`). C'est `category` qui
+ * distingue comptant et perpétuel chez elle, pas la limite. ⚠️ SANS `limit` EXPLICITE, BYBIT EN REND 200, quelle
+ * que soit la fenêtre demandée — mesuré le 2026-08-16 : 197 bougies par appel sur les six intervalles, les
+ * huit cents manquantes n'étant jamais redemandées puisque le curseur avance de la fenêtre entière.
+ *
+ * **blofin** — 1440 ; la venue clampe EN SILENCE et le SDK lève au-delà (`blofin-sdk`, `getCandles`).
+ *
+ * **aster** — 1500 ; non documenté, API de forme binance.
+ *
+ * **hyperliquid** et **pacifica** n'acceptent AUCUN `limit` : leurs SDK n'envoient que `startTime`/`endTime`
+ * (`get-candle-snapshot.ts`, `get-candle-data.ts`). Le nombre sert alors à dimensionner la FENÊTRE demandée, pas
+ * à remplir un paramètre. Pour hyperliquid, la venue borne d'elle-même à ~5 000 bougies par (coin, intervalle) —
+ * et l'horizon que ça couvre dépend de l'activité du coin, ce n'est donc pas une durée fixe.
+ *
+ * ⚠️ UNE VENUE ABSENTE DE CETTE TABLE N'A PAS DE PLAFOND DOCUMENTÉ — ce qui n'est pas « 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 CANDLES_PER_CALL: Partial<Record<XgateEx, number>>;
+/**
+ * Combien de bougies demander à une venue en un appel, ou `undefined` si personne ne l'a publié.
+ *
+ * ⚠️ LA CLÉ EST LA VENUE, PAS LA LIGNE DE CATALOGUE DE L'APPELANT. Un consommateur qui distingue le comptant du
+ * perpétuel par deux identifiants à lui (`binance` / `binance-spot`) doit résoudre vers la venue avant de
+ * demander : le plafond appartient à binance, pas à l'un de ses marchés. Interroger cette table avec un
+ * identifiant maison rendait `undefined` et faisait retomber l'appelant sur une valeur de repli — trois fois trop
+ * petite pour binance, deux fois pour bybit.
+ */
+declare function candlesPerCallOf(xex: XgateEx): number | undefined;
+/**
+ * LA CADENCE MINIMALE ENTRE DEUX APPELS, PAR VENUE — en millisecondes.
+ *
+ * ⚠️ INTERDIT DE DEVINER UN CHIFFRE ICI. Toute valeur se source dans la documentation de la venue, et la source
+ * s'écrit dans ce commentaire. Un throttle inventé se paie en bannissement d'IP, pas en lenteur.
+ *
+ * Ces cadences sont un PLANCHER : si la venue répond plus lentement que son throttle, c'est sa latence qui
+ * commande. Trois d'entre elles ont été corrigées PAR LA MESURE, jamais par confort — deux tours complets du
+ * 2026-08-02 ayant compté les refus venue par venue :
+ *
+ *     venue          avant  →  après    refus au 1er tour       refus au 2e
+ *     pacifica       2 500  →  4 000    51 / 525    (9,7 %)     0
+ *     lighter          600  →  1 200    126 / 1 218 (10,3 %)    0
+ *     hyperliquid      200  →    500    17 / 1 239  (1,4 %)     39 / 708 (5,5 %) à 300 ms
+ *
+ * ⚠️ LEÇON DU CAS HYPERLIQUID : un premier réglage à 300 ms reposait sur un poids de requête SUPPOSÉ, et il a
+ * EMPIRÉ la situation. Une cadence ne se déduit pas d'une hypothèse sur ce que coûte un appel — elle se dérive du
+ * budget documenté, puis se vérifie au tour suivant.
+ *
+ * Détail des budgets :
+ *
+ *   binance      weight 2 par kline, budget IP 6 000 weight/min → ~3 000 req/min ; 150 ms est très en dessous.
+ *                429 et 418 (ban d'IP) remontés par la venue.
+ *   bybit        600 req / 5 s en public → 150 ms reste prudent.
+ *   hyperliquid  1 200 weight/min par IP. À 387 ms réels on tirait 155 req/min en se faisant encore refouler :
+ *                la requête pèse donc ~8 weight et le budget est atteint vers 150 req/min. 500 ms garde 20 % de
+ *                marge, la même que celle qui a ramené lighter et pacifica à zéro refus.
+ *   blofin       500 req/min ET 1 500 req/5 min (docs.blofin.com). C'EST LA SECONDE QUI MORD : 300 req/min, deux
+ *                fois plus strict — et sa sanction est d'UNE HEURE contre cinq minutes. 250 ms tient 240 req/min.
+ *   pacifica     125 crédits / 60 s sur IP non identifiée, une kline étant un GET lourd à 3-12 crédits. La plus
+ *                contraignante de loin, et sa pénalité s'ALLONGE si on insiste. À 4 000 ms on tire 15 req/min,
+ *                soit 45 à 180 crédits — sous le budget pour tout coût jusqu'à 8.
+ *   lighter      ~60 requêtes pondérées/min (palier Standard), les endpoints pesant ~300. Le budget donne
+ *                1 000 ms tout juste ; 1 200 parce qu'un réglage COLLÉ au budget laisse un résidu de refus.
+ *   aster        2 400 weight/min, une kline au-delà de 1 000 bougies coûtant 10 → ~240 req/min.
+ *   paradex      1 500 req/min par IP.
+ *   extended     API lente (2 à 4 s par requête observées) — le throttle ne mord jamais.
+ */
+declare const REST_THROTTLE_MS: Partial<Record<XgateEx, number>>;
+/**
+ * La cadence documentée d'une venue, ou `undefined` si personne ne l'a publiée.
+ *
+ * ⚠️ LE BUDGET EST CELUI DE LA VENUE, PAS DU MARCHÉ. Une IP qui interroge le comptant ET le perpétuel de binance
+ * consomme UN SEUL budget : un appelant qui traite les deux en parallèle, chacun à cette cadence, tire deux fois
+ * plus vite que ce que la table annonce. C'est à lui de sérialiser par venue.
+ */
+declare function restThrottleOf(xex: XgateEx): number | undefined;
+
 /**
  * UNE COTATION, TELLE QU'XGATE LA REND — quelle que soit la venue d'où elle vient.
  *
@@ -1729,4 +1815,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 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 };
+export { CANDLES_PER_CALL, 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, REST_THROTTLE_MS, 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, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };

package/dist/index.d.ts

@@ -461,6 +461,92 @@ declare const WS_SUBSCRIPTION_LIMITS: Partial<Record<XgateEx, number>>;
  */
 declare function subscriptionLimitOf(xex: XgateEx): number | undefined;
 
+/**
+ * COMBIEN DE BOUGIES UNE VENUE SERT PAR APPEL — uniquement ce qu'une documentation ou un SDK affirme.
+ *
+ * Le budget d'une venue se compte en APPELS, pas en bougies : dix fois plus de barres par appel, c'est dix fois
+ * moins d'appels ET dix fois moins d'attente cumulée. C'est le seul levier qui décide de la durée d'un backfill.
+ *
+ * **binance** — « `limit` est plafonné à 1500 par la venue **sur les deux marchés** ; au-delà, elle refuse la
+ * requête au lieu de tronquer » (`binance-sdk`, docblock de `getCandles`). Le plafond vaut donc pour le comptant
+ * comme pour le perpétuel.
+ *
+ * **bybit** — `limit [1, 1000]`, défaut **200** (doc officielle v5, `/v5/market/kline`). C'est `category` qui
+ * distingue comptant et perpétuel chez elle, pas la limite. ⚠️ SANS `limit` EXPLICITE, BYBIT EN REND 200, quelle
+ * que soit la fenêtre demandée — mesuré le 2026-08-16 : 197 bougies par appel sur les six intervalles, les
+ * huit cents manquantes n'étant jamais redemandées puisque le curseur avance de la fenêtre entière.
+ *
+ * **blofin** — 1440 ; la venue clampe EN SILENCE et le SDK lève au-delà (`blofin-sdk`, `getCandles`).
+ *
+ * **aster** — 1500 ; non documenté, API de forme binance.
+ *
+ * **hyperliquid** et **pacifica** n'acceptent AUCUN `limit` : leurs SDK n'envoient que `startTime`/`endTime`
+ * (`get-candle-snapshot.ts`, `get-candle-data.ts`). Le nombre sert alors à dimensionner la FENÊTRE demandée, pas
+ * à remplir un paramètre. Pour hyperliquid, la venue borne d'elle-même à ~5 000 bougies par (coin, intervalle) —
+ * et l'horizon que ça couvre dépend de l'activité du coin, ce n'est donc pas une durée fixe.
+ *
+ * ⚠️ UNE VENUE ABSENTE DE CETTE TABLE N'A PAS DE PLAFOND DOCUMENTÉ — ce qui n'est pas « 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 CANDLES_PER_CALL: Partial<Record<XgateEx, number>>;
+/**
+ * Combien de bougies demander à une venue en un appel, ou `undefined` si personne ne l'a publié.
+ *
+ * ⚠️ LA CLÉ EST LA VENUE, PAS LA LIGNE DE CATALOGUE DE L'APPELANT. Un consommateur qui distingue le comptant du
+ * perpétuel par deux identifiants à lui (`binance` / `binance-spot`) doit résoudre vers la venue avant de
+ * demander : le plafond appartient à binance, pas à l'un de ses marchés. Interroger cette table avec un
+ * identifiant maison rendait `undefined` et faisait retomber l'appelant sur une valeur de repli — trois fois trop
+ * petite pour binance, deux fois pour bybit.
+ */
+declare function candlesPerCallOf(xex: XgateEx): number | undefined;
+/**
+ * LA CADENCE MINIMALE ENTRE DEUX APPELS, PAR VENUE — en millisecondes.
+ *
+ * ⚠️ INTERDIT DE DEVINER UN CHIFFRE ICI. Toute valeur se source dans la documentation de la venue, et la source
+ * s'écrit dans ce commentaire. Un throttle inventé se paie en bannissement d'IP, pas en lenteur.
+ *
+ * Ces cadences sont un PLANCHER : si la venue répond plus lentement que son throttle, c'est sa latence qui
+ * commande. Trois d'entre elles ont été corrigées PAR LA MESURE, jamais par confort — deux tours complets du
+ * 2026-08-02 ayant compté les refus venue par venue :
+ *
+ *     venue          avant  →  après    refus au 1er tour       refus au 2e
+ *     pacifica       2 500  →  4 000    51 / 525    (9,7 %)     0
+ *     lighter          600  →  1 200    126 / 1 218 (10,3 %)    0
+ *     hyperliquid      200  →    500    17 / 1 239  (1,4 %)     39 / 708 (5,5 %) à 300 ms
+ *
+ * ⚠️ LEÇON DU CAS HYPERLIQUID : un premier réglage à 300 ms reposait sur un poids de requête SUPPOSÉ, et il a
+ * EMPIRÉ la situation. Une cadence ne se déduit pas d'une hypothèse sur ce que coûte un appel — elle se dérive du
+ * budget documenté, puis se vérifie au tour suivant.
+ *
+ * Détail des budgets :
+ *
+ *   binance      weight 2 par kline, budget IP 6 000 weight/min → ~3 000 req/min ; 150 ms est très en dessous.
+ *                429 et 418 (ban d'IP) remontés par la venue.
+ *   bybit        600 req / 5 s en public → 150 ms reste prudent.
+ *   hyperliquid  1 200 weight/min par IP. À 387 ms réels on tirait 155 req/min en se faisant encore refouler :
+ *                la requête pèse donc ~8 weight et le budget est atteint vers 150 req/min. 500 ms garde 20 % de
+ *                marge, la même que celle qui a ramené lighter et pacifica à zéro refus.
+ *   blofin       500 req/min ET 1 500 req/5 min (docs.blofin.com). C'EST LA SECONDE QUI MORD : 300 req/min, deux
+ *                fois plus strict — et sa sanction est d'UNE HEURE contre cinq minutes. 250 ms tient 240 req/min.
+ *   pacifica     125 crédits / 60 s sur IP non identifiée, une kline étant un GET lourd à 3-12 crédits. La plus
+ *                contraignante de loin, et sa pénalité s'ALLONGE si on insiste. À 4 000 ms on tire 15 req/min,
+ *                soit 45 à 180 crédits — sous le budget pour tout coût jusqu'à 8.
+ *   lighter      ~60 requêtes pondérées/min (palier Standard), les endpoints pesant ~300. Le budget donne
+ *                1 000 ms tout juste ; 1 200 parce qu'un réglage COLLÉ au budget laisse un résidu de refus.
+ *   aster        2 400 weight/min, une kline au-delà de 1 000 bougies coûtant 10 → ~240 req/min.
+ *   paradex      1 500 req/min par IP.
+ *   extended     API lente (2 à 4 s par requête observées) — le throttle ne mord jamais.
+ */
+declare const REST_THROTTLE_MS: Partial<Record<XgateEx, number>>;
+/**
+ * La cadence documentée d'une venue, ou `undefined` si personne ne l'a publiée.
+ *
+ * ⚠️ LE BUDGET EST CELUI DE LA VENUE, PAS DU MARCHÉ. Une IP qui interroge le comptant ET le perpétuel de binance
+ * consomme UN SEUL budget : un appelant qui traite les deux en parallèle, chacun à cette cadence, tire deux fois
+ * plus vite que ce que la table annonce. C'est à lui de sérialiser par venue.
+ */
+declare function restThrottleOf(xex: XgateEx): number | undefined;
+
 /**
  * UNE COTATION, TELLE QU'XGATE LA REND — quelle que soit la venue d'où elle vient.
  *
@@ -1729,4 +1815,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 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 };
+export { CANDLES_PER_CALL, 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, REST_THROTTLE_MS, 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, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };

package/dist/index.js

@@ -2130,6 +2130,33 @@ XgateModule = __decorateClass([
   })
 ], XgateModule);
 
-export { CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, ORDER_STATUSES, PricesService, SPOT_XEXES, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, Timeframe, TradingService, 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 };
+// src/helpers/rest-limits.ts
+var CANDLES_PER_CALL = {
+  binance: 1500,
+  bybit: 1e3,
+  blofin: 1440,
+  aster: 1500,
+  hyperliquid: 5e3,
+  pacifica: 500
+};
+function candlesPerCallOf(xex) {
+  return CANDLES_PER_CALL[xex];
+}
+var REST_THROTTLE_MS = {
+  binance: 150,
+  bybit: 150,
+  hyperliquid: 500,
+  extended: 200,
+  paradex: 200,
+  aster: 400,
+  lighter: 1200,
+  blofin: 250,
+  pacifica: 4e3
+};
+function restThrottleOf(xex) {
+  return REST_THROTTLE_MS[xex];
+}
+
+export { CANDLES_PER_CALL, CandlesService, CandlesStreamRegistry, CandlesStreamService, CatalogService, ORDER_STATUSES, PricesService, REST_THROTTLE_MS, SPOT_XEXES, SpotCandlesService, SpotCatalogService, SpotPricesService, SpotWsCandlesService, TIMEFRAME_MINUTES, Timeframe, TradingService, WALLET_XEXES, WS_SUBSCRIPTION_LIMITS, WalletService, WsCandlesService, WsTradesService, XGATE_EXCHANGES, XgateEx, XgateModule, buildLevels, buildProtection, candlesPerCallOf, canonicalFromBase, canonicalFromXex, expiryOf, isDated, multiplierFromXex, restThrottleOf, roundPrice, roundToStep, servesNatively, servesSpot, sourceFor, subscriptionLimitOf, timeframeMs };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map