@blackcube/xgate-sdk 0.20.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Blackcube
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,142 @@
+# @blackcube/xgate-sdk
+
+La passerelle NestJS qui unifie les dix SDK d'exchange Blackcube derrière **une seule surface** :
+un catalogue, des bougies, des prix, un portefeuille et du trading — quelle que soit la venue.
+
+> **SDK communautaire / non officiel.** Non affilié aux exchanges couverts. Usage à vos risques.
+
+## Installation
+
+```bash
+pnpm add @blackcube/xgate-sdk
+```
+
+Node.js ≥ 22. Les SDK de venue sont des dépendances : on n'en installe aucun séparément.
+
+## Ce que XGate gère, venue par venue
+
+Trois niveaux, et ils ne se valent pas. **Le tableau dit ce qui est PROUVÉ, pas ce qui est écrit** :
+une capacité n'est comptée que si un test réel l'a exercée.
+
+| Venue | Catalogue · bougies · prix | Portefeuille | Trading | Ouverture protégée |
+|---|:---:|:---:|:---:|:---:|
+| **hyperliquid** | ✔ | ✔ | ✔ | ✔ **prouvée** |
+| **pacifica** | ✔ | ✔ | ✔ | ✔ **prouvée** |
+| **aster** | ✔ | ✔ | ✔ | ⚠ **à valider** |
+| lighter | ✔ | — | — | — |
+| extended | ✔ | — | — | — |
+| paradex | ✔ | — | — | — |
+| bullet | ✔ | — | — | — |
+| blofin | ✔ | ✔ | ✔ | — |
+| binance | ✔ *(+ comptant)* | — | — | — |
+| bybit | ✔ *(+ comptant)* | — | — | — |
+
+**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.
+
+**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.
+
+## Les services
+
+Chacun est un `@Injectable()` NestJS, utilisable seul ou via `XgateModule`.
+
+| 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, ouverture protégée, clôture |
+
+## 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
+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.
+
+```typescript
+import { TradingService, XgateEx } from '@blackcube/xgate-sdk';
+
+const trading = new TradingService();
+const access = {
+  xex: XgateEx.Hyperliquid,
+  address: '0x…',
+  privateKey: '0x…',
+  network: 'testnet' as const,
+};
+
+const orders = await trading.openWithProtection(access, {
+  xex: XgateEx.Hyperliquid,
+  symbolXex: 'ETH',
+  direction: 'long',
+  size: 0.02,
+  entry: 3120,
+  slPct: 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
+  tif: 'ioc',
+});
+```
+
+Le premier ordre rendu est l'entrée ; les suivants sont le stop et les take-profits.
+
+### Fermer
+
+`closePosition` relit la position **sur la venue** avant de la fermer, et sort la taille que la venue
+déclare — jamais celle qu'on avait prévue. Fermer la taille planifiée laisse un reliquat dès que le
+fill a différé du plan, et ce reliquat reste ouvert, sans stop.
+
+```typescript
+await trading.closePosition(access, 'ETH');   // null s'il n'y avait rien à fermer
+```
+
+### Le réseau est explicite
+
+`network` vaut `mainnet` par défaut. **Le préciser est la seule chose qui sépare un test d'un ordre
+réel** : sur les venues à testnet, `network: 'testnet'` fait tout basculer, signature comprise.
+
+Le vocabulaire est le même partout — `mainnet` / `testnet` — y compris chez blofin, qui appelle le
+second « demo trading ». Une clé de démo envoyée au mainnet fait répondre « Access key does not
+exist » : le message accuse la clé alors que c'est l'adresse qui est fausse.
+
+## Les statuts d'ordre
+
+Sept valeurs, **identiques à celles des SDK de venue**, orthographe comprise :
+
+```
+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.
+
+## Les conventions qui traversent tout
+
+- **Une bougie inclut sa dernière milliseconde** : 10:00:00.000 → 10:59:59.999. `closedAt` se
+  **calcule**, il ne se recopie jamais du wire.
+- **Aucun `time: number`** : chaque date dit ce qu'elle date — `openedAt`, `closedAt`, `quotedAt`,
+  `occurredAt`, `measuredAt`, `placedAt`, `filledAt`.
+- **Les montants sont des chaînes.** Un `number` sur un prix de BTC perd des décimales là où ça
+  compte.
+- **Une taille de position est toujours positive** : le sens est porté par `side`.
+- **Pas de mensuel.** Les intervalles s'arrêtent à `1w`.
+
+## Documentation
+
+Le détail par service vit dans les docblocks — ils portent le *pourquoi*, pas la paraphrase du code.