@blackcube/xgate-sdk 0.21.1 → 0.23.0

package/README.md

@@ -23,13 +23,13 @@ une capacité n'est comptée que si un test réel l'a exercée.
 | **hyperliquid** | ✔ | ✔ | ✔ | ✔ **prouvée** |
 | **pacifica** | ✔ | ✔ | ✔ | ✔ **prouvée** |
 | **aster** | ✔ | ✔ | ✔ | ⚠ **à valider** |
-| lighter | ✔ | — | — | — |
+| lighter | ✔ | ✔ *(sans clé)* | — | — |
 | extended | ✔ | — | — | — |
 | paradex | ✔ | — | — | — |
-| bullet | ✔ | — | — | — |
+| bullet | ✔ *(bougies en WS seulement)* | — | — | — |
 | blofin | ✔ | ✔ | ✔ | — |
-| binance | ✔ *(+ comptant)* | — | — | — |
-| bybit | ✔ *(+ comptant)* | — | — | — |
+| binance | ✔ **+ comptant complet** | — | — | — |
+| bybit | ✔ **+ comptant complet** | — | — | — |
 
 **hyperliquid et pacifica sont complètes et prouvées.** Le cycle entier — ouvrir avec stop, lire la
 position, refermer sans reliquat — tourne sur leur testnet à chaque exécution de la suite de tests.
@@ -41,22 +41,112 @@ sur une ouverture protégée, c'est la position nue que ce paquet existe pour re
 `openWithProtection` y **lève** tant que la preuve manque. Tout le reste (positions, ordres,
 historique, clôture) fonctionne. Détail complet dans le backlog.
 
+**lighter se lit sans aucune clé.** Sa documentation classe `/account`, `accountsByL1Address` et
+`positions` parmi les routes **sans authentification**, et `/account` accepte « an account's index,
+**or L1 address** » : une adresse suffit, comme sur les autres DEX. Son trading, lui, demanderait
+une clé d'API — aucune n'existe aujourd'hui.
+
+**bullet ne sert aucune bougie en REST.** Sa documentation officielle ne comporte aucune section de
+données historiques, et six noms d'endpoint testés répondent tous 404 — son REST existe pourtant
+(`/fapi/v1/depth`, `trades`, `premiumIndex`, `fundingRate`, `ticker/24hr`, `openInterest`). Ses
+bougies passent donc par `WsCandlesService` ; `CandlesService` y lève.
+
 **Les autres sont en lecture.** Elles servent le catalogue, les bougies et les prix ; il leur manque
-un accès de compte (clé d'API pour bullet, adresse active pour lighter, extended et paradex) ou la
-partie signée n'est pas câblée. Binance et bybit sont volontairement limitées au **public** : leurs
-SDK ne couvrent que catalogue, bougies et prix, et toute route signée y lève.
+un accès de compte (clé d'API pour bullet, adresse active pour extended et paradex) ou la partie
+signée n'est pas câblée. Binance et bybit sont volontairement limitées au **public**, mais y servent les deux marchés :
+perpétuel ET comptant, chacun avec ses quatre services. Toute route signée y lève.
 
 ## Les services
 
 Chacun est un `@Injectable()` NestJS, utilisable seul ou via `XgateModule`.
 
+**Les marchés se lisent par paires de services** : le nom de la classe dit lequel on interroge.
+
+| Ce qu'on lit | Perpétuel — 10 venues | Comptant — binance, bybit |
+|---|---|---|
+| catalogue | `CatalogService` | `SpotCatalogService` |
+| bougies REST | `CandlesService` | `SpotCandlesService` |
+| prix | `PricesService` | `SpotPricesService` |
+| bougies temps réel | `WsCandlesService` | `SpotWsCandlesService` |
+| **flux multi-marchés** | `CandlesStreamRegistry` | `CandlesStreamRegistry.of(xex, 'spot')` |
+
+`CandlesService` agrège quand la venue ne sert pas l'intervalle demandé ; les autres servent ce que
+la venue publie. Un `Spot*` appelé sur une venue sans comptant **lève**.
+
+### ⚠️ Les sockets réagissent MAL à un symbole invalide
+
+**À lire avant d'ouvrir un flux.** Aucune des venues ne rejette proprement un marché inconnu : elles
+l'acceptent, puis se comportent mal — chacune à sa façon, et deux d'entre elles **en silence**.
+
+| venue | ce qu'elle fait d'un symbole inconnu | XGate le voit ? |
+|---|---|---|
+| hyperliquid | ferme la connexion et reconnecte **en boucle** | ✔ coupe tout et lève |
+| binance | l'ignore, les autres marchés continuent | sans objet |
+| **bybit** | **fait taire TOUT le flux**, socket ouverte, sans erreur | ✘ **indétectable** |
+
+Le cas bybit est le plus grave : `['BTCUSDT', 'INCONNU']` ne rend **aucune** bougie — pas même pour
+`BTCUSDT` — alors que `['BTCUSDT', 'ETHUSDT']` fonctionne. Pas de fermeture, pas d'erreur, pas de
+reconnexion. C'est un **silence**, pas un incident : aucun canal ne peut le remonter, et rien dans
+XGate ne le détectera jamais.
+
+Le cas hyperliquid était le même silence avant que XGate ne coupe : cinq reconnexions en douze
+secondes pendant lesquelles les marchés **valides** du même socket se taisaient aussi.
+
+**La seule protection : souscrire depuis le catalogue**, jamais depuis une liste écrite à la main.
+
+```typescript
+const paires = await catalog.catalog(XgateEx.Bybit);
+const symboles = paires.filter((p) => /* ta sélection */).map((p) => p.symbolXex);
+registry.of(XgateEx.Bybit).start(symboles, Timeframe.M1, (candle) => { … });
+```
+
+### Suivre plusieurs marchés : `CandlesStreamRegistry`
+
+**Une socket par venue, quel que soit le nombre de marchés.** Porté de Blips, où il tourne en
+production.
+
+```typescript
+const flux = registry.of(XgateEx.Hyperliquid);
+flux.start(['BTC', 'ETH', 'SOL'], Timeframe.M1, (candle) => { … });
+flux.subscriptionCount();   // 3
+flux.maxSubscriptions;      // 1000 — plafond documenté, null si la venue n'en publie pas
+registry.stopAll();
+```
+
+`of(xex)` rend **toujours la même instance** pour une venue : deux appels, deux `start()`, une seule
+connexion. C'est ce qui rend tenable de suivre 200 marchés — hyperliquid n'accepte que 10 connexions
+par IP.
+
+`WsCandlesService`, lui, ouvre **une socket par souscription** : à réserver au suivi d'un ou deux
+marchés.
+
+> **Une erreur de flux coupe tout, puis lève.** Un symbole invalide n'échoue pas à la
+> souscription : la venue l'accepte, puis ferme la connexion en le découvrant — cinq cycles de
+> reconnexion en douze secondes, mesurés le 2026-08-07 sur hyperliquid, pendant lesquels **tous**
+> les marchés valides du même socket cessent de recevoir, en silence.
+>
+> À la première erreur, XGate coupe les souscriptions, journalise en `error`, et lève. L'exception
+> naît dans un rappel de socket : elle ne remonte pas à l'appelant de `start()`, elle sort en
+> erreur non capturée — délibérément, pour être impossible à ignorer.
+>
+> Souscris depuis le catalogue, pas depuis une liste écrite à la main.
+>
+> **Les trois venues ne réagissent pas pareil à un symbole invalide** — mesuré le 2026-08-07 :
+>
+> | venue | ce qu'elle fait | détecté ? |
+> |---|---|---|
+> | hyperliquid | ferme la connexion, reconnecte en boucle | ✔ coupe et lève |
+> | binance | l'ignore, les autres marchés continuent | sans objet |
+> | **bybit** | **tout le flux se tait**, sans fermeture ni erreur | ✘ **rien ne le signale** |
+>
+> ⚠️ **bybit est le cas dangereux** : `['BTCUSDT', 'INCONNU']` ne rend **aucune** bougie, pas même
+> pour `BTCUSDT`, et la socket reste ouverte sans erreur. Aucun canal ne peut le détecter — c'est
+> un silence, pas un incident. La seule protection est de **souscrire depuis le catalogue**.
+
+**Deux services sans équivalent comptant**, parce que binance et bybit sont bornées au public :
+
 | Service | Ce qu'il rend |
 |---|---|
-| `CatalogService` | les paires perpétuelles de toutes les venues, normalisées |
-| `SpotCatalogService` | les paires **comptant** — binance et bybit uniquement |
-| `CandlesService` | les bougies REST, avec agrégation quand la venue ne sert pas l'intervalle |
-| `WsCandlesService` | les bougies en temps réel, un handler pour N venues |
-| `PricesService` | mark, oracle, mid, bid/ask, funding, open interest |
 | `WalletService` | soldes, mouvements, historique d'équité |
 | `TradingService` | positions, ordres, exécutions — et le cycle **ouvrir → gérer → fermer** |
 
@@ -204,6 +294,139 @@ open · partiallyFilled · filled · canceled · rejected · expired · other
 `canceled` prend **un seul L**. Un statut inconnu retombe sur `other` plutôt que de traverser la
 passerelle tel quel : `ORDER_STATUSES` est exporté pour valider plutôt que caster.
 
+## Le comptant, au même niveau que le perpétuel
+
+**Quatre services de chaque côté**, jamais un drapeau. Le nom de la classe dit quel marché on lit.
+
+| | perpétuel | comptant |
+|---|---|---|
+| catalogue | `CatalogService` | `SpotCatalogService` |
+| bougies REST | `CandlesService` | `SpotCandlesService` |
+| prix | `PricesService` | `SpotPricesService` |
+| temps réel | `WsCandlesService` | `SpotWsCandlesService` |
+
+```typescript
+await spotCatalog.catalog(XgateEx.Binance, XgateEx.Bybit);
+await spotCandles.candles(XgateEx.Binance, { symbol: 'BTCUSDT', interval: '1h', limit: 100 });
+await spotPrices.prices(XgateEx.Binance, XgateEx.Bybit);
+spotWs.subscribe(XgateEx.Binance, { symbol: 'BTCUSDT', interval: '1m' }, (candle) => { … });
+```
+
+Le comptant est servi par **binance et bybit** ; toute autre venue lève.
+
+**Pourquoi deux jeux de services et non un paramètre** : ce sont deux marchés, pas deux vues du
+même. Le perpétuel porte un funding et s'écarte du comptant — c'est cet écart que certaines
+stratégies exploitent, et le confondre le rendrait invisible. Un `candles(xex, { spot: true })`
+laisserait croire qu'on regarde la même chose sous un autre angle.
+
+**Ce qui change concrètement quand on passe au comptant :**
+
+- **La cotation n'est plus toujours un dollar.** En perpétuel, tout est en USDT/USDC. Au comptant,
+  495 paires sont cotées en BTC, 375 en BNB, 370 en TRY, 230 en ETH — le champ `quote` devient
+  indispensable, et le « prix » d'`ETHBTC` est un ratio, pas des dollars.
+- **`mark`, `oracle`, `funding` et `openInterest` valent `null`** : ils n'existent que sur un
+  contrat. Les voir renseignés signalerait qu'on lit en réalité du perpétuel.
+
+> Les échelles de cotation, elles, ne posent **aucun** problème entre les deux marchés :
+> `SATSUSDT` (×1) et `10000SATSUSDT` (×10000) sont **deux paires distinctes**, chacune portant son
+> `multiplier` au catalogue. Une bougie ou un prix appartient à une paire, identifiée par
+> `xex` + `symbolXex` + `kind` — il n'y a rien à réconcilier.
+
+**419 actifs n'existent qu'au comptant** — le perpétuel en couvre 887, le comptant 962, dont 419
+sans aucun perpétuel nulle part.
+
+> Sur `SpotPricesService`, `symbol` est dérivé du symbole concaténé : `BTCUSDT` → `BTC`. Les paires
+> cotées hors dollar gardent leur nom entier (`ETHBTC`), les prix ne portant pas la base déclarée.
+> Pour un `symbol`/`quote` justes sur ces paires, passer par `SpotCatalogService`.
+
+## La semaine s'ouvre le lundi, partout
+
+`hyperliquid` sert des bougies `1w` **alignées sur jeudi** (elle aligne ses seaux sur l'epoch Unix,
+qui tombe un jeudi), là où binance et pacifica ouvrent le lundi. XGate ne les prend donc pas : il
+**reconstruit sa semaine depuis le journalier**, et les bougies rendues portent `derived: true`.
+
+```
+hyperliquid  lun 2026-06-01*  lun 2026-06-08*  lun 2026-06-15*     ← reconstruites
+binance      lun 2026-06-01   lun 2026-06-08   lun 2026-06-15      ← natives
+```
+
+Sans cela, deux séries portant le même intervalle `1w` couvriraient des jours différents et se
+compareraient silencieusement.
+
+## Le catalogue : deux pièges que les venues ne signalent pas
+
+**Le multiplicateur de cotation.** Aucune venue ne le publie — il n'existe que dans le préfixe du
+nom, que le canonique fait disparaître. `IPair.multiplier` le conserve :
+
+```
+SATS   binance:1000SATSUSDT = ×1000   bybit:10000SATSUSDT = ×10000   bybit-spot:SATSUSDT = ×1
+```
+
+Trois échelles pour le même actif sur trois sources. **Une médiane calculée sur ces prix bruts ne
+veut rien dire** ; divisés par `multiplier`, ils redeviennent comparables. 98 lignes du catalogue
+sont concernées.
+
+**Les contrats à échéance.** 44 lignes portent `kind: 'perp'` alors qu'elles expirent, dont neuf
+sur le seul BTC chez bybit. `IPair.expiresAt` les distingue — `undefined` pour un perpétuel.
+
+```typescript
+pairs.filter((pair) => pair.expiresAt === undefined);   // les vrais perpétuels
+```
+
+L'échéance est dérivée du **type de contrat**, jamais de la date de livraison : binance publie
+`deliveryDate: 4133404800000` — le 1ᵉʳ janvier 2100 — sur **tous** ses perpétuels. S'y fier
+marquerait le catalogue entier comme daté.
+
+## Les actifs non-crypto du catalogue
+
+**Extraction du 2026-08-07, et rien de plus.** Cette liste n'est pas un contrat : elle a été
+relevée un jour donné sur les dix venues, et elle bougera au prochain listing sans que ce fichier
+le sache. Ne l'utilise pas comme référence figée — refais l'extraction quand la question compte.
+
+164 actifs du catalogue perpétuel ne sont pas de la crypto. Ils s'y mélangent sans distinction :
+un balayage qui ramène « les paires BTC-like » y ramasse de l'or, du pétrole et des actions Tesla,
+alors que **ni les horaires de cotation, ni la volatilité, ni la dynamique de funding** ne s'y
+comportent pareil — les actions et indices ne cotent pas 24/7.
+
+**forex (7)**
+`AUDUSD EURUSD GBPUSD NZDUSD USDCAD USDCHF USDJPY`
+
+**matières premières (11)**
+`BZ CL COPPER GOLD NG SILVER WTIOIL XAG XAU XPD XPT`
+
+**indices et ETF (36)** — dont des ETF à effet de levier (`SOXL` ×3, `SQQQ` inverse ×3, `UVXY`)
+`BBX BITO BNC BOT BSP EWJ EWT EWY EWZ FWDI INTW IWM KORU KSTR MUU MVLL QNTX QQQ SHAZ SMH SNXX SOXL
+SOXS SP500 SPY SQQQ STXX TBT TMF TQQQ TZA URNM US100 UVXY XBI XLE`
+
+**hors-US et pré-IPO (29)** — `OPENAI`, `ANTHROPIC`, `SPCX`, `ZHIPU`, `MINIMAX` sont des sociétés
+**non cotées** : des marchés sur valorisation privée
+`AAOI ANTHROPIC ARM ASML AXTI BABA BMNR CBRS CRWV DRAM GIGADEV HK0700 HK1810 HYUNDAI MINIMAX NBIS
+NVO OPENAI PENG POPMART SAMSUNG SKHY SKHYNIX SONY SPCX TENCENT TSM USAR ZHIPU`
+
+**actions US (81)**
+`AAPL ADBE ALAB AMAT AMD AMZN APP ASTS AVGO BE BRKB BX CAT CIEN COHR COIN COST CRCL CRDO CRM CRWD
+CSCO DELL DIS DKNG EBAY FLEX FLNC GEV GLW GME GOOGL GS HD HIMS HOOD HPE IBM INTC IREN JPM KLAC KO
+LITE LLY LRCX META MRVL MSFT MSTR MU NFLX NOK NOW NVDA ONDS ORCL PANW PAYP PLTR PYPL QCOM RDDT
+RIVN RKLB SMCI SNDK SNOW SOFI STRC TER TSLA TTWO TXN UBER V VRT WDC WEN WMT ZM`
+
+### Ce que cette liste vaut, et ce qu'elle ne vaut pas
+
+**Deux venues seulement les déclarent** : extended (`contractType: 'TRADIFI_PERPETUAL'`, 153
+marchés) et bullet (`RwaPerpUsEquity`, `RwaPerpCommodities`, `RwaPerpKrEquity`,
+`RwaPerpUsEquityIndices`, 10 marchés). Les **huit autres n'en disent rien** — bybit en cote 131,
+aster 108, blofin 74, lighter 66, pacifica 20, paradex 19, sans aucun champ pour les distinguer.
+La liste ne tient donc que parce qu'un actif déclaré quelque part se reconnaît ailleurs à son
+symbole canonique.
+
+**Le sous-classement est une interprétation**, pas une donnée de venue. Le forex se reconnaît à sa
+forme (six lettres, deux codes ISO) ; le reste vient d'un rangement fait à la main sur les tickers.
+Ce qui est solide, c'est **l'appartenance à la liste** — pas la catégorie.
+
+**Aucun champ `assetType` n'existe dans `IPair`**, et c'est délibéré tant qu'aucune source
+d'autorité ne couvre les dix venues. La documentation officielle de pacifica le confirme : son
+`/api/v1/info` ne publie que `instrument_type`, qui vaut `perpetual` aussi bien pour `BTC` que pour
+`TSLA`, `XAU` ou `EURUSD`.
+
 ## Les conventions qui traversent tout
 
 - **Une bougie inclut sa dernière milliseconde** : 10:00:00.000 → 10:59:59.999. `closedAt` se
@@ -214,6 +437,10 @@ passerelle tel quel : `ORDER_STATUSES` est exporté pour valider plutôt que cas
   compte.
 - **Une taille de position est toujours positive** : le sens est porté par `side`.
 - **Pas de mensuel.** Les intervalles s'arrêtent à `1w`.
+- **Le suffixe d'un symbole n'est pas sa cotation.** bybit nomme ses perpétuels USDC avec `PERP`
+  (`1000BONKPERP` → `BONK`/`USDC`), binance suffixe ses trimestriels par leur date
+  (`BTCUSDT_260925`). XGate lit ce que la venue **déclare** (`baseAsset`, `baseCoin`) plutôt que de
+  re-parser le nom.
 
 ## Versions