@syldel/hl-shared-types 0.0.7 → 0.0.9

package/dist/interfaces/infos/candle.interfaces.d.ts

@@ -1,22 +1,43 @@
 import { DecimalString, Timestamp } from '../common';
-/** Intervalles supportés pour les bougies Hyperliquid */
+/**
+ * Supported Hyperliquid candle intervals.
+ */
 export type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M';
-/** Réponse brute d'une bougie (Candle) selon l'API Hyperliquid */
+/**
+ * Raw candle data returned by the Hyperliquid `candleSnapshot` endpoint.
+ */
 export interface CandleSnapshot {
+    /** Candle open timestamp (ms). */
     t: Timestamp;
+    /** Candle close timestamp (ms). */
     T: Timestamp;
+    /** Asset symbol (e.g. BTC or xyz:XYZ100 for HIP-3 markets). */
     s: string;
+    /** Candle interval. */
     i: CandleInterval;
+    /** Open price. */
     o: DecimalString;
+    /** Close price. */
     c: DecimalString;
+    /** Highest traded price during the interval. */
     h: DecimalString;
+    /** Lowest traded price during the interval. */
     l: DecimalString;
+    /** Traded volume in base asset. */
     v: DecimalString;
+    /** Number of trades included in the candle. */
     n: number;
 }
+/**
+ * Parameters for querying historical candles.
+ */
 export interface CandleSnapshotRequest {
+    /** Asset symbol (e.g. BTC or xyz:XYZ100 for HIP-3 markets). */
     coin: string;
+    /** Candle interval. */
     interval: CandleInterval;
+    /** Start timestamp in milliseconds (inclusive). */
     startTime: Timestamp;
+    /** End timestamp in milliseconds (inclusive). Defaults to current time. */
     endTime?: Timestamp;
 }

package/dist/interfaces/infos/portfolio.interfaces.d.ts

@@ -1,15 +1,29 @@
 import { DecimalString, Timestamp } from '../common';
-/** Un point de donnée : [Timestamp, Valeur] */
+/**
+ * Time-series data point represented as [timestamp, value].
+ */
 export type PortfolioPoint = [Timestamp, DecimalString];
-/** Données de portfolio pour une période donnée */
+/**
+ * Portfolio statistics for a given time period.
+ */
 export interface PortfolioStats {
+    /** Historical account value over time. */
     accountValueHistory: PortfolioPoint[];
+    /** Historical profit and loss over time. */
     pnlHistory: PortfolioPoint[];
+    /** Total traded volume for the period. */
     vlm: DecimalString;
 }
-/** Labels de périodes supportés par Hyperliquid */
+/**
+ * Supported portfolio time ranges returned by the API.
+ */
 export type PortfolioPeriod = 'day' | 'week' | 'month' | 'allTime' | 'perpDay' | 'perpWeek' | 'perpMonth' | 'perpAllTime';
-/** * La réponse est un tableau de tuples : [Période, Stats]
- * Exemple: ["day", { accountValueHistory: [...], ... }]
+/**
+ * Portfolio response returned by the `portfolio` endpoint.
+ *
+ * Each entry is a tuple: [period, stats].
+ *
+ * Example:
+ * ["day", { accountValueHistory: [...], pnlHistory: [...], vlm: "12345.67" }]
  */
 export type PortfolioResponse = [PortfolioPeriod, PortfolioStats][];

package/dist/interfaces/orders/user-fills.interfaces.d.ts

@@ -1,26 +1,57 @@
 import { Timestamp } from '../common';
+/**
+ * User trade fill returned by the Hyperliquid `userFills` endpoints.
+ */
 export interface HLUserFill {
+    /** Asset symbol or asset id (e.g. "BTC" or "@107" for spot markets). */
     coin: string;
+    /** Execution price. */
     px: string;
+    /** Executed size (base asset). */
     sz: string;
+    /** Liquidity side: A = ask (sell), B = bid (buy). */
     side: 'A' | 'B';
+    /** Execution timestamp (ms). */
     time: Timestamp;
+    /** Order identifier. */
     oid: number;
+    /** Trade identifier. */
     tid: number;
+    /** Trade direction (e.g. "Open Long", "Close Short"). */
     dir: string;
+    /** Position size before this fill. */
     startPosition: string;
+    /** Realized PnL from the fill. */
     closedPnl: string;
+    /** Whether the trade executed via crossing order logic. */
     crossed: boolean;
+    /** Transaction hash on Hyperliquid. */
     hash: `0x${string}`;
+    /** Trading fee paid. */
     fee: string;
+    /** Token used to pay the fee. */
     feeToken: string;
+    /** Optional builder/referral fee applied to the trade. */
     builderFee?: string;
 }
+/**
+ * List of fills returned by the `userFills` endpoints.
+ */
 export type HLUserFillsResponse = HLUserFill[];
 export interface HLUserFillsRequest {
+    /**
+     * Whether to aggregate partial fills by block/time.
+     */
     aggregateByTime?: boolean;
 }
 export interface HLUserFillsByTimeRequest extends HLUserFillsRequest {
+    /**
+     * Start timestamp in milliseconds (inclusive).
+     */
     startTime: Timestamp;
+    /**
+     * End timestamp in milliseconds (inclusive).
+     * Defaults to the current time if omitted.
+     */
     endTime?: Timestamp;
 }

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

@@ -1,42 +1,89 @@
 import { DecimalString, Timestamp } from '../common';
+/**
+ * Leverage configuration for a perpetual position.
+ */
 export interface HLPerpLeverage {
+    /** Notional value in USD used for leverage calculation. */
     rawUsd: DecimalString;
+    /** Margin mode used for the position. */
     type: 'isolated' | 'cross';
+    /** Current leverage multiplier. */
     value: number;
 }
+/**
+ * Funding payments accumulated for a perpetual position.
+ */
 export interface HLPerpCumFunding {
+    /** Total funding paid or received since account creation. */
     allTime: DecimalString;
+    /** Funding accumulated since the last position change. */
     sinceChange: DecimalString;
+    /** Funding accumulated since the position was opened. */
     sinceOpen: DecimalString;
 }
+/**
+ * Detailed information about a perpetual position.
+ */
 export interface HLPerpPositionDetail {
+    /** Asset symbol (e.g. BTC, ETH). */
     coin: string;
+    /** Funding payments history. */
     cumFunding: HLPerpCumFunding;
+    /** Average entry price of the position. */
     entryPx: DecimalString;
+    /** Leverage configuration. */
     leverage: HLPerpLeverage;
+    /** Estimated liquidation price. */
     liquidationPx: DecimalString;
+    /** Margin currently used by the position. */
     marginUsed: DecimalString;
+    /** Maximum allowed leverage for this market. */
     maxLeverage: number;
+    /** Notional value of the position. */
     positionValue: DecimalString;
+    /** Return on equity (ROE). */
     returnOnEquity: DecimalString;
+    /** Position size (positive = long, negative = short). */
     szi: DecimalString;
+    /** Unrealized profit or loss. */
     unrealizedPnl: DecimalString;
 }
+/**
+ * Wrapper describing a perpetual asset position.
+ */
 export interface HLPerpAssetPosition {
+    /** Position details (null if no active position). */
     position: HLPerpPositionDetail | null;
+    /** Position mode configuration. */
     type: 'oneWay' | 'hedged';
 }
+/**
+ * Margin summary for a perpetual account.
+ */
 export interface HLPerpMarginSummary {
+    /** Total account value. */
     accountValue: DecimalString;
+    /** Margin currently used by open positions. */
     totalMarginUsed: DecimalString;
+    /** Total notional position value. */
     totalNtlPos: DecimalString;
+    /** Raw USD balance before adjustments. */
     totalRawUsd: DecimalString;
 }
+/**
+ * Clearinghouse state for a perpetual trading account.
+ */
 export interface HLClearinghouseState {
+    /** List of perpetual positions. */
     assetPositions: HLPerpAssetPosition[];
+    /** Cross maintenance margin currently required. */
     crossMaintenanceMarginUsed: DecimalString;
+    /** Cross margin account summary. */
     crossMarginSummary: HLPerpMarginSummary;
+    /** Global margin summary. */
     marginSummary: HLPerpMarginSummary;
+    /** Timestamp of the snapshot. */
     time: Timestamp;
+    /** Amount available for withdrawal. */
     withdrawable: DecimalString;
 }

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

@@ -1,50 +1,108 @@
 import { DecimalString } from '../common';
+/**
+ * Metadata describing a perpetual market.
+ */
 export interface HLPerpMarketInfo {
+    /** Market symbol (e.g. BTC, ETH). */
     name: string;
+    /** Number of decimals used for order size. */
     szDecimals: number;
+    /** Maximum leverage allowed. */
     maxLeverage: number;
+    /** Whether the market only supports isolated margin. */
     onlyIsolated?: boolean;
+    /** Whether the market has been delisted. */
     isDelisted?: boolean;
+    /** Optional margin mode restriction. */
     marginMode?: 'strictIsolated' | 'noCross';
 }
+/**
+ * Margin tier defining leverage limits for a position size range.
+ */
 export interface HLPerpMarginTier {
+    /** Minimum notional value for the tier. */
     lowerBound: string;
+    /** Maximum leverage allowed in this tier. */
     maxLeverage: number;
 }
+/**
+ * Margin configuration table for a perpetual market.
+ */
 export interface HLPerpMarginTable {
+    /** Human-readable description. */
     description: string;
+    /** Margin tiers applied to this market. */
     marginTiers: HLPerpMarginTier[];
 }
+/**
+ * Entry linking a margin table ID to its configuration.
+ */
 export type HLPerpMarginTableEntry = [number, HLPerpMarginTable];
+/**
+ * Metadata returned by the `meta` endpoint.
+ */
 export interface HLPerpMeta {
+    /** List of available perpetual markets. */
     universe: HLPerpMarketInfo[];
+    /** Margin configuration tables. */
     marginTables: HLPerpMarginTableEntry[];
 }
+/**
+ * Market metadata including its index in the universe list.
+ */
 export interface HLPerpMarketUniverse extends HLPerpMarketInfo {
+    /** Market index in the universe array. */
     index: number;
 }
+/**
+ * Runtime market data for a perpetual asset.
+ */
 export interface HLPerpAssetCtx {
+    /** Daily notional trading volume. */
     dayNtlVlm: string;
+    /** Current funding rate. */
     funding: string;
+    /** Impact price levels used for slippage estimation. */
     impactPxs: string[];
+    /** Mark price used for PnL calculations. */
     markPx: string;
+    /** Mid price between best bid and ask. */
     midPx: string;
+    /** Total open interest. */
     openInterest: string;
+    /** Oracle price reference. */
     oraclePx: string;
+    /** Price premium relative to the oracle. */
     premium: string;
+    /** Previous day's closing price. */
     prevDayPx: string;
 }
+/**
+ * Response combining market metadata and runtime context.
+ */
 export type HLPerpMetaAndCtx = [{
     universe: HLPerpMarketInfo[];
 }, HLPerpAssetCtx[]];
+/**
+ * Normalized representation of a perpetual market used by the SDK.
+ */
 export interface HLPerpMarket {
+    /** Market index in the universe list. */
     index: number;
+    /** Market symbol (e.g. BTC). */
     name: string;
+    /** Size precision for orders. */
     szDecimals: number;
+    /** Maximum leverage allowed. */
     maxLeverage: number;
+    /** Margin table identifier. */
     marginTableId?: number;
+    /** Current mark price. */
     markPrice?: DecimalString;
+    /** Current mid price. */
     midPrice?: DecimalString;
+    /** Current funding rate. */
     funding?: DecimalString;
+    /** Current open interest. */
     openInterest?: DecimalString;
 }

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

@@ -1,11 +1,23 @@
 import { DecimalString } from '../common';
+/**
+ * User's balance for a spot asset.
+ */
 export interface HLSpotBalance {
+    /** Asset symbol, e.g. "USDC" or "ETH". */
     coin: string;
+    /** Token index in Hyperliquid's system. */
     token: number;
+    /** Amount currently on hold / reserved. */
     hold: DecimalString;
+    /** Total amount owned (available + hold). */
     total: DecimalString;
+    /** Entry notional for the position. */
     entryNtl: DecimalString;
 }
+/**
+ * Spot clearinghouse state containing all balances.
+ */
 export interface HLSpotClearinghouseState {
+    /** Array of spot balances for this user. */
     balances: HLSpotBalance[];
 }

package/dist/interfaces/spot/meta.interfaces.d.ts

@@ -1,23 +1,50 @@
+/**
+ * Metadata for a spot token.
+ */
 export interface HLSpotTokenMeta {
+    /** Token symbol, e.g. "USDC". */
     name: string;
+    /** Number of decimals for display purposes. */
     szDecimals: number;
+    /** Number of decimals used on-chain (wei). */
     weiDecimals: number;
+    /** Token index in Hyperliquid system. */
     index: number;
+    /** Unique token identifier. */
     tokenId: string;
+    /** Whether this is the canonical token in the system. */
     isCanonical: boolean;
+    /** EVM contract address (if applicable). */
     evmContract: string | null;
+    /** Full token name, optional. */
     fullName: string | null;
 }
+/**
+ * Metadata for a spot market.
+ */
 export interface HLSpotMarketMeta {
+    /** Market symbol, e.g. "ETH/USDC". */
     name: string;
+    /** Indexes of the base and quote tokens. */
     tokens: [number, number];
+    /** Market index in Hyperliquid system. */
     index: number;
+    /** Whether the market uses canonical tokens. */
     isCanonical: boolean;
 }
+/**
+ * Complete spot metadata including tokens and markets.
+ */
 export interface HLSpotMeta {
+    /** All spot tokens. */
     tokens: HLSpotTokenMeta[];
+    /** All spot markets (universe). */
     universe: HLSpotMarketMeta[];
 }
+/**
+ * Summary of a spot asset, extending market metadata.
+ */
 export interface HLSpotAssetSummary extends HLSpotMarketMeta {
+    /** Optional: number of decimals for size/amount display. */
     szDecimals?: number;
 }

package/package.json

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