@blackcube/xgate-sdk 0.23.0 → 0.25.0

package/README.md

@@ -22,7 +22,7 @@ une capacité n'est comptée que si un test réel l'a exercée.
 |---|:---:|:---:|:---:|:---:|
 | **hyperliquid** | ✔ | ✔ | ✔ | ✔ **prouvée** |
 | **pacifica** | ✔ | ✔ | ✔ | ✔ **prouvée** |
-| **aster** | ✔ | ✔ | ✔ | ⚠ **à valider** |
+| **aster** | ✔ | ✔ | ✔ | ✔ **prouvée** *(voir la fenêtre d'1 s)* |
 | lighter | ✔ | ✔ *(sans clé)* | — | — |
 | extended | ✔ | — | — | — |
 | paradex | ✔ | — | — | — |
@@ -34,12 +34,25 @@ une capacité n'est comptée que si un test réel l'a exercée.
 **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.
 
-**aster est complète mais non validée**, et le refus est délibéré. Son `/fapi/v3/batchOrders` coupe
-à ~3,26 s en répondant « The request has timed out. » *alors que la venue a déjà créé une partie des
-ordres* : deux exécutions identiques ont produit deux sous-ensembles différents. Un statut inconnu
-sur une ouverture protégée, c'est la position nue que ce paquet existe pour rendre impossible — donc
-`openWithProtection` y **lève** tant que la preuve manque. Tout le reste (positions, ordres,
-historique, clôture) fonctionne. Détail complet dans le backlog.
+**aster ouvre en SÉQUENTIEL, avec une fenêtre d'environ une seconde.** Son lot atomique
+(`/fapi/v3/batchOrders`) coupe systématiquement à ~3,26 s — chaque leg s'y écrit on-chain — et
+laissait des orphelins non déterministes : une fois l'entrée seule, une fois le stop seul. XGate y
+pose donc l'entrée, **puis** le stop, **puis** les take-profits.
+
+⚠️ **Entre l'entrée remplie et le stop posé, la position est nue pendant ~1,1 s** (mesuré :
+entrée 1 041 ms, stop 1 078 ms plus tard). Si le marché s'effondre dans cet intervalle, rien ne
+protège. C'est un compromis assumé — l'alternative était une venue inutilisable.
+
+Poser le stop **en premier** supprimerait la fenêtre, mais aster **accepte un `reduceOnly` sans
+position puis l'annule** : vérifié, il a disparu du carnet une seconde plus tard.
+
+**Filet de sécurité** : si le stop échoue alors que l'entrée a rempli, la position est **soldée au
+marché** et l'erreur remonte. Une position sans stop ne survit pas à `openWithProtection`.
+
+> **Un mot sur les timeouts d'aster.** Sa documentation annonce un `HTTP 503` pour un timeout, « à
+> ne **PAS** traiter comme un échec ; le statut d'exécution est **INCONNU** ». Elle renvoie en
+> réalité un **`400`** — « requête malformée » — alors que les ordres sont bel et bien créés. XGate
+> reconnaît donc le message, relit le carnet, et lève sur position nue ou balaie les orphelins.
 
 **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,
@@ -67,12 +80,21 @@ Chacun est un `@Injectable()` NestJS, utilisable seul ou via `XgateModule`.
 | 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')` |
+| temps réel — **plusieurs marchés** | `CandlesStreamRegistry` | `CandlesStreamRegistry.of(xex, 'spot')` |
+| temps réel — **un seul marché** | `WsCandlesService` | `SpotWsCandlesService` |
+
+`candlesOf([...venues], query)` interroge le **même marché chez plusieurs venues** en une liste —
+chaque bougie porte son `xex`. Une venue en échec parmi d'autres est journalisée et ignorée ; seule,
+son échec est celui de l'appel.
 
 `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 deux lignes de temps réel ne sont pas interchangeables.** `WsCandlesService` ouvre **une
+socket par souscription** : suivre 50 marchés y ouvre 50 connexions, quand hyperliquid n'en accepte
+que 10 par IP. Le registre, lui, les fait toutes passer par **une seule**. En cas de doute, prends
+le registre — `WsCandlesService` ne se justifie que pour un ou deux marchés.
+
 ### ⚠️ Les sockets réagissent MAL à un symbole invalide
 
 **À lire avant d'ouvrir un flux.** Aucune des venues ne rejette proprement un marché inconnu : elles
@@ -113,12 +135,22 @@ flux.maxSubscriptions;      // 1000 — plafond documenté, null si la venue n'e
 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.
+`of(xex, kind?)` rend **toujours la même instance** pour une venue et un marché : 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.
+**Deux classes, deux rôles.** `CandlesStreamRegistry` tient la table des flux ; `CandlesStreamService`
+est le flux lui-même, celui que `of()` rend. Les deux sont exportés, mais on n'instancie normalement
+que le registre — construire un `CandlesStreamService` à la main revient à tenir soi-même la table,
+donc à risquer plusieurs sockets pour la même venue.
+
+| | `CandlesStreamRegistry` | `CandlesStreamService` |
+|---|---|---|
+| `of(xex, kind?)` | le flux d'une venue, créé une fois | — |
+| `start(symbols, interval, onCandle)` | — | ouvre les souscriptions |
+| `stop()` / `stopAll()` | coupe tous les flux | coupe ce flux |
+| `subscriptionCount()` / `counts()` | par venue | pour ce flux |
+| `maxSubscriptions` | — | plafond documenté, ou `null` |
 
 > **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
@@ -149,12 +181,14 @@ marchés.
 |---|---|
 | `WalletService` | soldes, mouvements, historique d'équité |
 | `TradingService` | positions, ordres, exécutions — et le cycle **ouvrir → gérer → fermer** |
+| `WsTradesService` | les flux du compte : **exécutions**, **ordres**, et transactions **publiques** |
 
 Le cycle de vie d'une position tient en trois gestes, et chacun préserve le même invariant : la
 position n'est jamais sans stop.
 
 | geste | méthode | venues |
 |---|---|---|
+| régler le levier | `setLeverage` | toutes sauf bullet |
 | ouvrir avec sa protection | `openWithProtection` | hyperliquid, pacifica |
 | déplacer le stop | `moveStop` | hyperliquid, pacifica, aster |
 | fermer sans reliquat | `closePosition` | toutes celles qui tradent |
@@ -162,6 +196,16 @@ position n'est jamais sans stop.
 
 ## Le portefeuille
 
+```typescript
+await wallet.balances(access);                    // comptant + collatéral, chaque ligne marquée
+await wallet.movements(access);                   // dépôts, retraits, transferts — montants signés
+await wallet.equityHistory(access);               // la courbe d'équité du compte
+```
+
+`movements` **lève** si la venue ne les sert pas, plutôt que de rendre une liste vide : « cette
+venue n'expose pas son historique » et « ce compte n'a jamais bougé » appellent des suites très
+différentes. `equityHistory` n'est publié que par hyperliquid et pacifica.
+
 `balances()` rend **le comptant et le collatéral**, chaque ligne portant sa nature :
 
 ```typescript
@@ -186,12 +230,28 @@ venues.
 ## Le trading
 
 **Jamais un ordre sans stop.** `openWithProtection` est la seule façon d'ouvrir une position, et
-elle exige un `slPct`. La protection part **avec** l'entrée, en un geste que la venue traite
+elle exige un `sl`. La protection part **avec** l'entrée, en un geste que la venue traite
 atomiquement : si l'entrée ne remplit pas, la protection ne naît jamais.
 
-**L'appelant donne des pourcentages, jamais des prix.** XGate calcule les niveaux depuis le prix
-d'entrée, les arrondit à la grille de la paire, et garantit qu'au-delà de 80 % de parts cumulées la
-position ferme entièrement — sans reliquat de 0,01 qui traîne.
+### Un niveau se dit en écart OU en prix
+
+```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
+```
+
+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 reviendrait à faire calculer l'appelant, donc à déplacer l'erreur chez
+lui. Les deux modes se mélangent librement dans le même appel.
+
+**`part` reste toujours une fraction de la POSITION** — les deux modes ne portent que sur le niveau.
+
+Le type rend l'ambiguïté impossible : `ITarget` est une union **exclusive**, donc
+`{ pct: 0.1, price: 62500 }` **ne compile pas**, et `{}` non plus.
+
+**XGate arrondit les niveaux à la grille de la paire** et garantit qu'au-delà de 80 % de parts
+cumulées la position ferme entièrement — sans reliquat de 0,01 qui traîne.
 
 ```typescript
 import { TradingService, XgateEx } from '@blackcube/xgate-sdk';
@@ -210,9 +270,9 @@ const orders = await trading.openWithProtection(access, {
   direction: 'long',
   size: 0.02,
   entry: 3120,
-  slPct: 0.02,                              // stop à 2 % sous l'entrée
+  sl: { pct: 0.02 },                        // stop à 2 % sous l'entrée
   tps: [{ pct: 0.03, part: 0.5 },           // 50 % à +3 %
-        { pct: 0.06, part: 0.5 }],          // 50 % à +6 % → somme 100 %, clôture intégrale
+        { price: 62500, part: 0.5 }],       // 50 % si le prix touche 62 500
   tif: 'ioc',
 });
 ```
@@ -251,6 +311,89 @@ l'erreur ne se voit qu'une fois l'argent parti. Le prix courant est donc un argu
 > une chaîne nue, sans identifiant — pour un stop groupé sous son entrée. Il se retrouve au carnet,
 > où `reduceOnly === true` le distingue.
 
+### Savoir ce qui s'est rempli : `WsTradesService`
+
+Le flux des exécutions du compte, en temps réel. C'est ce qui permet de connaître son état **exact**
+sans sonder : entre deux interrogations, un take-profit partiel a pu changer la taille de la
+position, et toute décision prise sur l'ancienne valeur est fausse.
+
+```typescript
+const stop = wsTrades.subscribe(access, (trade) => {
+  // trade.price est le prix RÉELLEMENT obtenu, pas celui demandé
+});
+```
+
+**Seules les exécutions survenues après l'abonnement sont transmises.** Les venues rejouent leur
+historique à la souscription — mesuré sur hyperliquid : 30 exécutions dans les six premières
+secondes, toutes antérieures, la plus ancienne de plus de deux jours. XGate les écarte, sans quoi
+chaque reconnexion rejouerait deux jours de trades et ferait compter deux fois les mêmes
+remplissages. Pour l'historique, `TradingService.trades()` est fait pour ça.
+
+`subscribeAll([...accès], handler)` suit plusieurs comptes avec un seul handler. **blofin ne diffuse
+pas ses exécutions** et lève ; les sept autres venues les servent.
+
+**Trois flux, trois usages** :
+
+```typescript
+wsTrades.subscribe(access, (trade) => { … });                    // MES exécutions : à quel prix
+wsTrades.subscribeOrders(access, (order) => { … });              // MES ordres : leur cycle de vie
+wsTrades.subscribePublicTrades(access, 'ETH', (trade) => { … }); // le marché : ce qui se négocie
+```
+
+`subscribeOrders` voit l'ordre **naître et changer d'état** (`open` → `filled`, ou `canceled`) —
+c'est là qu'on apprend qu'un stop vient de se déclencher. `subscribe` dit à quel prix. Les deux
+écartent le rejeu d'historique ; `subscribePublicTrades` n'en a pas à écarter.
+
+### La marge : mode, renfort, allègement
+
+```typescript
+await trading.setMarginMode(access, 'ETH', true);   // true = isolée, false = croisée
+await trading.addMargin(access, 'ETH', '2');        // éloigne la liquidation
+await trading.removeMargin(access, 'ETH', '1');     // libère du capital
+```
+
+**Le mode se règle AVANT d'ouvrir.** En **croisée**, tout le solde 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, la liquidation arrive plus tôt.
+
+`addMargin` renforce une position sous pression **sans la réduire** — vérifié en réel : marge 38,45
+→ 40,46 après `+2`, puis 39,46 après `−1`. N'a de sens qu'en isolée ; en croisée le solde entier
+garantit déjà la position.
+
+⚠️ **pacifica ne retire pas de marge** et `removeMargin` y lève : fermer partiellement la position
+est alors la façon de libérer du capital.
+
+### Le coupe-circuit : `cancelAll`
+
+Annule **tous** les ordres d'une paire d'un geste — pour reprendre la main sans discuter : état
+incohérent, arrêt d'urgence, reprise après incident. Annuler un par un laisse une fenêtre pendant
+laquelle certains vivent encore.
+
+```typescript
+const annules = await trading.cancelAll(access, 'ETH');   // nombre annulé, ou null
+```
+
+⚠️ **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. XGate le journalise en `warn` s'il détecte
+une position, mais ne refuse pas — c'est un coupe-circuit, il doit couper. À n'employer que si la
+position est fermée, ou en reposant une protection dans la foulée.
+
+### Ne jamais annuler pour reposer
+
+**Annuler une protection pour la recréer est une aberration**, et XGate n'expose délibérément ni
+`cancelProtection` ni `createProtection`. Entre l'annulation et la nouvelle pose, la position est
+**nue** — et cette fenêtre s'ouvre précisément quand ça va mal : marché rapide, latence réseau,
+serveur qui redémarre. C'est le scénario que tout ce paquet existe pour rendre impossible.
+
+Le stop se **déplace** : `moveStop` pose le nouveau **avant** d'annuler l'ancien, du côté du SDK de
+la venue. À aucun instant la position n'est sans protection.
+
+```typescript
+await trading.moveStop(access, { …, stopId: stop.id, triggerPrice: 3120, size: 0.02 }, markPrice);
+```
+
+Si tu te surprends à vouloir annuler puis reposer, c'est un déplacement que tu cherches.
+
 ### Fermer
 
 `closePosition` relit la position **sur la venue** avant de la fermer, et sort la taille que la venue
@@ -261,6 +404,39 @@ fill a différé du plan, et ce reliquat reste ouvert, sans stop.
 await trading.closePosition(access, 'ETH');   // null s'il n'y avait rien à fermer
 ```
 
+### Lire l'état et l'historique
+
+```typescript
+await trading.orderHistory(access, 'ETH');          // les ordres : soumis, remplis, annulés
+await trading.accountInfo(access);                  // équité, marge, ratio de maintenance (brut)
+await trading.fundingHistory(access, 'ETH', { limit: 100 });   // le funding RÉELLEMENT payé
+trading.newClientOrderId(XgateEx.Hyperliquid);      // au format que la venue accepte
+```
+
+**`accountInfo` est unifié** — équité, disponible, marge immobilisée, marge de maintenance, PnL
+latent. Les venues rangent ces valeurs sous des noms sans rapport, mais elles disent la même chose :
+
+| | hyperliquid | pacifica | aster |
+|---|---|---|---|
+| équité | `marginSummary.accountValue` | `accountEquity` | `totalMarginBalance` |
+| disponible | `withdrawable` | `availableToSpend` | `availableBalance` |
+| marge utilisée | `marginSummary.totalMarginUsed` | `totalMarginUsed` | `totalInitialMargin` |
+| maintenance | `crossMaintenanceMarginUsed` | `crossMmr` | `totalMaintMargin` |
+
+La forme native complète reste dans `xtras` — rien n'est perdu. `unrealizedPnl` vaut `null` là où la
+venue ne le publie pas au niveau du compte (hyperliquid, pacifica) : il se lit alors sur les
+positions. **blofin ne l'expose pas** et lève.
+
+**`fundingHistory` dit ce qui a été payé**, là où `PricesService` annonce le taux à venir. Un calcul
+de résultat qui l'ignore surestime toute position tenue longtemps.
+
+**`newClientOrderId` n'est pas un `randomUUID()` déguisé** : hyperliquid exige un hexadécimal
+préfixé `0x` (128 bits) quand les autres acceptent un UUID ordinaire. Le mauvais format fait rejeter
+l'ordre.
+
+> ⚠️ **`fundingHistory` sur le testnet aster répond `502`** — page HTML, serveur en panne sur cet
+> endpoint. Le mainnet le sert normalement. Le SDK et l'URL sont corrects.
+
 ### Le prix de sortie réel
 
 Le prix planifié ne dit pas à quel prix on est sorti : un stop se déclenche au marché, un take-profit