@blackcube/xgate-sdk 0.22.0 → 0.23.0

package/README.md

@@ -28,8 +28,8 @@ une capacité n'est comptée que si un test réel l'a exercée.
 | paradex | ✔ | — | — | — |
 | 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.
@@ -53,21 +53,100 @@ 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 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.
+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 **perpétuelles**, avec agrégation quand la venue ne sert pas l'intervalle |
-| `SpotCandlesService` | les bougies REST **comptant** — binance et bybit |
-| `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** |
 
@@ -215,19 +294,50 @@ 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.
 
-## Comptant et perpétuel ne se mélangent pas
+## Le comptant, au même niveau que le perpétuel
 
-Deux services, jamais un drapeau : `CandlesService` sert le perpétuel, `SpotCandlesService` le
-comptant.
+**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 spotCandles.candlesOf([XgateEx.Binance, XgateEx.Bybit], { symbol: 'BTCUSDT', interval: '1h' });
+await spotPrices.prices(XgateEx.Binance, XgateEx.Bybit);
+spotWs.subscribe(XgateEx.Binance, { symbol: 'BTCUSDT', interval: '1m' }, (candle) => { … });
 ```
 
-Ce n'est pas de la coquetterie d'API : **les échelles de cotation diffèrent entre les deux
-marchés**. `SATSUSDT` au comptant chez bybit cote ×1 quand son perpétuel cote ×10000 — mélanger les
-deux séries fabrique un graphe qui saute d'un facteur 10 000. Une venue sans comptant lève.
+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
 
@@ -267,6 +377,56 @@ L'échéance est dérivée du **type de contrat**, jamais de la date de livraiso
 `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