@syldel/hl-shared-types 0.0.23 → 0.0.24

package/README.md

@@ -119,10 +119,48 @@ git push origin main --follow-tags
 
 ---
 
+## 🔍 Avant de déclarer un champ : d'où vient l'information
+
+Chaque champ de ce paquet est une **affirmation sur ce que l'exchange rend**, et les trois
+dépôts la croient. Une affirmation fausse ne se voit pas : elle se paie plus loin, sur un
+dimensionnement ou un affichage. Avant d'ajouter, de resserrer ou d'élargir un type, lire
+[`nest-hyperliquid-gateway/docs/sources.md`](https://github.com/Syldel/nest-hyperliquid-gateway/blob/main/docs/sources.md).
+
+En résumé de ce document :
+
+* **La mesure** (captures du gateway, lectures `/hyperliquid/info/*`) prouve qu'une forme
+  existe, jamais qu'elle soit la seule. Un `null` vu une fois clôt la nullité d'un champ ;
+  mille valeurs présentes ne closent rien. Et un échantillon se décrit honnêtement — 22
+  instantanés d'une même position ne sont pas 22 observations.
+* **La doc officielle** fait autorité sur les noms, et tient sur **un exemple par
+  endpoint** : elle est donc muette sur ce qui varie. Un champ absent d'un exemple n'est ni
+  absent de l'API ni optionnel.
+* **Le SDK Python officiel**
+  ([hyperliquid-dex/hyperliquid-python-sdk](https://github.com/hyperliquid-dex/hyperliquid-python-sdk))
+  est de première partie **et typé** : il tranche les unions, les champs propres à une
+  variante et les valeurs énumérées que la prose laisse en suspens. Mais il ne type pas
+  tout, et son silence n'est pas une réponse.
+* **Les SDK communautaires ne concluent pas.** La page d'API en recommande plusieurs — un en
+  Rust, deux en TypeScript, plus CCXT — et le dit : ils sont écrits par la communauté. Être
+  lié par la doc officielle donne de la visibilité, pas de l'autorité ; ils lisent la même
+  API que nous et peuvent s'être trompés pareil. Ils servent à repérer une question, jamais
+  à la clore — et le piège est celui en TypeScript, dont on a envie de recopier une union
+  toute faite. Il n'existe **aucun SDK TypeScript de première partie**.
+
+`HLPerpLeverage` est le cas d'école : ni les captures (que du `cross`) ni l'exemple de la
+doc (que de l'`isolated`) ne pouvaient trancher, et `hyperliquid/utils/types.py` déclare les
+deux branches. Les types portent leur source et leur date en commentaire — c'est ce qui
+permet de les contredire plus tard au lieu de devoir tout remesurer.
+
+---
+
 ## 📝 Conventions de code
 
 * **Sauts de ligne** : Une ligne vide est automatiquement insérée entre chaque `interface` pour une meilleure lisibilité.
 * **Naming** : Toutes les interfaces commencent par `HL`.
 * **Types stricts** : Usage de `DecimalString` pour la précision financière.
+* **Fins de ligne** : LF partout, imposé par `.gitattributes` et non par la configuration de
+  la machine — le paquet publié embarque du code généré par `tsc`, dont les fins de ligne
+  suivent celles des sources.
 
 ---

package/dist/interfaces/perp/balance.interfaces.d.ts

@@ -25,6 +25,12 @@ import { DecimalString, Timestamp } from '../common';
  * porte `rawUsd: "-95.059824"`. Aucun des deux ne couvre l'autre branche — le
  * SDK, lui, les couvre toutes les deux.
  *
+ * ⚠️ Ce « officiel » ne se déduit **pas** du nom de l'organisation GitHub, qui
+ * n'est d'ailleurs pas vérifiée (`is_verified: false`). Il repose sur la page
+ * d'API de la documentation, qui distingue ce SDK des bibliothèques
+ * communautaires, et sur PyPI, qui le publie sous `hello@hyperliquid.xyz`. La
+ * chaîne et ses limites : `nest-hyperliquid-gateway/docs/sources.md`.
+ *
  * Pourquoi l'union et non `rawUsd?: DecimalString` : l'optionnel rendrait
  * `lev.rawUsd` lisible sans vérifier `type`, et `Number(undefined)` rend `NaN`
  * sans un mot. L'union en fait une erreur de compilation. Et si un cross

package/dist/interfaces/perp/funding.interfaces.d.ts

@@ -0,0 +1,115 @@
+import { DecimalString, Timestamp } from '../common';
+/**
+ * ============================================================================
+ * L'HISTORIQUE DE FUNDING — LE SEUL CHAMP DE CONTEXTE QUI AIT UNE VRAIE SÉRIE
+ *
+ * `fundingHistory` est, au 2026-10-06, le **seul** endpoint d'information qui
+ * rende une série temporelle d'un champ de contexte de marché. Il n'existe
+ * aucun endpoint documenté pour l'historique de l'intérêt ouvert, ni pour celui
+ * des prix d'impact : ces valeurs ne sont lisibles qu'à l'instant courant.
+ *
+ * C'est ce qui décide de ce qu'un moteur de règles peut en faire : une
+ * transformation glissante (z-score, pente, percentile) a besoin d'une série,
+ * donc elle n'est légitime que sur `fundingRate` et `premium`.
+ *
+ * ## Ce qui a été mesuré, le 2026-10-06
+ *
+ * Deux appels, sur six heures, sur `api.hyperliquid.xyz` :
+ *
+ * - **BTC** (vivant) : 6 entrées pour 6 heures — la cadence est bien horaire,
+ *   ce que la documentation confirme (« funding is paid every hour at one
+ *   eighth of the computed rate »). Quatre clés, toutes en chaîne sauf `time`.
+ *   **Aucun nul**, sur aucun champ.
+ * - **MATIC** (délisté) : 6 entrées également, avec `fundingRate: "0.0"` et
+ *   `premium: "0.0"`.
+ * - **xyz:XYZ100** (HIP-3, vivant) : 6 entrées, écarts de 3 600 000 ms ± 20 ms,
+ *   et le `coin` rendu est identique à celui demandé, préfixe compris.
+ *
+ * ⚠️ Les horodatages ne tombent **pas exactement** sur l'heure : les restes
+ * modulo une heure relevés valaient 37, 39, 27, 7, 46 et 24 ms. Aligner une
+ * fenêtre de requête sur l'heure pleine reste correct — `startTime` est
+ * inclusif, donc arrondir vers le bas attrape l'entrée — mais comparer un
+ * horodatage à une frontière d'heure par égalité ne marcherait pas.
+ *
+ * ## ⚠️ Trois pièges que ces mesures révèlent
+ *
+ * **1. `"0.0"` a trois significations différentes, et rien ne les distingue
+ * dans cette réponse.** Mesuré le 2026-10-06 via `perpDexs` :
+ *
+ * - un **marché délisté** rend `"0.0"` (MATIC) ;
+ * - un **marché vivant et sain** peut rendre `"0.0"` en permanence, parce que
+ *   son dex déclare un multiplicateur de funding nul : `assetToFundingMultiplier`
+ *   vaut `0.0` sur **tous** les actifs de `flx` et de `vntl` ;
+ * - et un financement réellement nul à cette heure-là.
+ *
+ * Une règle du genre `funding <= 0` serait donc vraie en permanence sur des
+ * marchés parfaitement vivants. Un consommateur doit croiser cette série avec
+ * `isDelisted` (voir `HLPerpMarketInfo`) **et** avec le multiplicateur du dex
+ * (voir `HLPerpDex.assetToFundingMultiplier`). L'API fournit ici elle-même la
+ * valeur de repli plausible et fausse que ce dépôt refuse d'habitude de
+ * fabriquer.
+ *
+ * **2. Un seuil de funding absolu n'est pas transposable d'un marché à
+ * l'autre.** Les multiplicateurs relevés vont de `0.0` (`flx`, `vntl`) à
+ * `0.000001` (`cash`), `0.01` à `1.0` (`hyna`, qui les fait varier **par
+ * actif** dans un même dex), `0.1` à `0.6` (`para`), `0.125` à `0.5` (`io`),
+ * `0.5` partout sur `xyz`. Trois dex n'en déclarent aucun. Un `funding >
+ * 0.00001` serait donc courant sur l'un et impossible sur l'autre : ce champ
+ * se compare **relativement** (z-score, percentile) ou normalisé par le
+ * multiplicateur, jamais à une constante écrite en dur.
+ *
+ * **3. `fundingRate` est souvent constant.** Sur BTC, les trois heures relevées
+ * valaient toutes `0.0000125`, soit exactement le plancher (un huitième de
+ * 0,01 %) ; sur `xyz:XYZ100`, toutes `0.00000625`, soit ce même plancher
+ * multiplié par le `0.5` du dex. Une transformation glissante sur un taux au
+ * plancher voit une série plate : son écart-type est nul, et un z-score n'y a
+ * aucun sens. `premium`, lui, varie en continu sur les deux marchés — c'est la
+ * série informative des deux.
+ *
+ * ## `premium` ici n'est pas `premium` dans `metaAndAssetCtxs`
+ *
+ * La documentation dit que « the premium is sampled **every 5 seconds and
+ * averaged over the hour** », et que `premium = impact_price_difference /
+ * oracle_price`. Le champ rendu ici est donc une **moyenne horaire** sur
+ * environ 720 échantillons, là où le `premium` d'un contexte d'actif est la
+ * lecture de l'instant. Les deux portent le même nom et ne sont pas la même
+ * quantité.
+ * ============================================================================
+ */
+/**
+ * Une entrée de l'historique de funding, telle que `fundingHistory` la rend.
+ *
+ * Aucun champ n'est optionnel ni nullable : mesuré sur un marché vivant **et**
+ * sur un marché délisté, l'endpoint rend toujours les quatre, et rend `"0.0"`
+ * plutôt que `null` quand il n'y a rien à payer.
+ */
+export interface HLFundingHistoryEntry {
+    /** Le marché concerné, tel que demandé (ex. `BTC`, `xyz:XYZ100`). */
+    coin: string;
+    /**
+     * Le taux **horaire** réellement appliqué, soit un huitième du taux calculé
+     * sur 8 heures. `"0.0"` sur un marché délisté — voir l'en-tête.
+     */
+    fundingRate: DecimalString;
+    /**
+     * La prime moyenne de l'heure : `impact_price_difference / oracle_price`,
+     * échantillonnée toutes les 5 secondes et moyennée. Peut être négative.
+     */
+    premium: DecimalString;
+    /** Début de l'heure de funding, en millisecondes. */
+    time: Timestamp;
+}
+/**
+ * Les paramètres de `fundingHistory`.
+ *
+ * ⚠️ À plat dans le corps de la requête, contrairement à `candleSnapshot` qui
+ * imbrique les siens sous une clé `req`. Deux endpoints voisins, deux formes :
+ * c'est le genre d'écart qui se découvre par un appel qui échoue.
+ */
+export interface HLFundingHistoryRequest {
+    coin: string;
+    /** Inclusif, en millisecondes. Requis. */
+    startTime: Timestamp;
+    /** Inclusif. Par défaut, l'instant courant. */
+    endTime?: Timestamp;
+}

package/dist/interfaces/perp/funding.interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/perp/index.d.ts

@@ -1,3 +1,4 @@
 export * from './balance.interfaces';
 export * from './meta.interfaces';
 export * from './dexs.interfaces';
+export * from './funding.interfaces';

package/dist/interfaces/perp/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./balance.interfaces"), exports);
 __exportStar(require("./meta.interfaces"), exports);
 __exportStar(require("./dexs.interfaces"), exports);
+__exportStar(require("./funding.interfaces"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syldel/hl-shared-types",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",