@lifi/perps-sdk 0.1.1-alpha.8 → 0.2.0-alpha.0

package/dist/esm/utils/hyperliquid/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/hyperliquid/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACpB,MAAM,sBAAsB,CAAA"}

package/dist/esm/utils/hyperliquid/liquidation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hyperliquid-specific liquidation price calculation.
+ *
+ * Uses the exact formula from Hyperliquid docs:
+ * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/liquidations
+ *
+ * liq_price = price - side * margin_available / position_size / (1 - l * side)
+ *
+ * Where:
+ * - l = 1 / (2 * maxLeverage) (maintenance margin fraction)
+ * - side = 1 (long) or -1 (short)
+ * - margin_available = isolated_margin - maintenance_margin_required
+ */
+/**
+ * Calculate the maintenance margin fraction for a Hyperliquid asset.
+ *
+ * Maintenance margin is half of the initial margin at max leverage.
+ *
+ * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
+ * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
+ *   or undefined if maxLeverage is zero
+ */
+export declare function calculateMaintenanceMarginRate(maxLeverage: number): number | undefined;
+/**
+ * Calculate liquidation price using the exact Hyperliquid formula.
+ *
+ * For isolated margin, new position prediction. For existing positions,
+ * prefer Position.liquidationPrice from the API.
+ *
+ * Formula derivation (isolated margin, single position):
+ *   margin_per_unit        = entryPrice / leverage
+ *   maintenance_per_unit   = entryPrice * mmr
+ *   margin_available       = margin_per_unit - maintenance_per_unit
+ *   liq_price              = entryPrice - side * margin_available / (1 - mmr * side)
+ *
+ * Where mmr = 1 / (2 * maxLeverage).
+ *
+ * @param entryPrice - Position entry price
+ * @param leverage - User-selected leverage (e.g., 10)
+ * @param isLong - True if long position, false if short
+ * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
+ *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
+ * @returns Estimated liquidation price, or undefined if inputs are invalid
+ */
+export declare function calculateLiquidationPrice(entryPrice: number, leverage: number, isLong: boolean, maxLeverage: number): number | undefined;
+//# sourceMappingURL=liquidation.d.ts.map

package/dist/esm/utils/hyperliquid/liquidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidation.d.ts","sourceRoot":"","sources":["../../../../src/utils/hyperliquid/liquidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAYpB"}

package/dist/esm/utils/hyperliquid/liquidation.js

@@ -0,0 +1,63 @@
+/**
+ * Hyperliquid-specific liquidation price calculation.
+ *
+ * Uses the exact formula from Hyperliquid docs:
+ * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/liquidations
+ *
+ * liq_price = price - side * margin_available / position_size / (1 - l * side)
+ *
+ * Where:
+ * - l = 1 / (2 * maxLeverage) (maintenance margin fraction)
+ * - side = 1 (long) or -1 (short)
+ * - margin_available = isolated_margin - maintenance_margin_required
+ */
+/**
+ * Calculate the maintenance margin fraction for a Hyperliquid asset.
+ *
+ * Maintenance margin is half of the initial margin at max leverage.
+ *
+ * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
+ * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
+ *   or undefined if maxLeverage is zero
+ */
+export function calculateMaintenanceMarginRate(maxLeverage) {
+    if (maxLeverage === 0) {
+        return undefined;
+    }
+    return 1 / (2 * maxLeverage);
+}
+/**
+ * Calculate liquidation price using the exact Hyperliquid formula.
+ *
+ * For isolated margin, new position prediction. For existing positions,
+ * prefer Position.liquidationPrice from the API.
+ *
+ * Formula derivation (isolated margin, single position):
+ *   margin_per_unit        = entryPrice / leverage
+ *   maintenance_per_unit   = entryPrice * mmr
+ *   margin_available       = margin_per_unit - maintenance_per_unit
+ *   liq_price              = entryPrice - side * margin_available / (1 - mmr * side)
+ *
+ * Where mmr = 1 / (2 * maxLeverage).
+ *
+ * @param entryPrice - Position entry price
+ * @param leverage - User-selected leverage (e.g., 10)
+ * @param isLong - True if long position, false if short
+ * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
+ *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
+ * @returns Estimated liquidation price, or undefined if inputs are invalid
+ */
+export function calculateLiquidationPrice(entryPrice, leverage, isLong, maxLeverage) {
+    if (leverage === 0 || maxLeverage === 0) {
+        return undefined;
+    }
+    const mmr = 1 / (2 * maxLeverage);
+    const side = isLong ? 1 : -1;
+    const denominator = 1 - mmr * side;
+    if (denominator === 0) {
+        return undefined;
+    }
+    const marginAvailable = entryPrice * (1 / leverage - mmr);
+    return entryPrice - (side * marginAvailable) / denominator;
+}
+//# sourceMappingURL=liquidation.js.map

package/dist/esm/utils/hyperliquid/liquidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidation.js","sourceRoot":"","sources":["../../../../src/utils/hyperliquid/liquidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAmB;IAEnB,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAA;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,QAAgB,EAChB,MAAe,EACf,WAAmB;IAEnB,IAAI,QAAQ,KAAK,CAAC,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAA;IACjC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5B,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,IAAI,CAAA;IAClC,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,eAAe,GAAG,UAAU,GAAG,CAAC,CAAC,GAAG,QAAQ,GAAG,GAAG,CAAC,CAAA;IACzD,OAAO,UAAU,GAAG,CAAC,IAAI,GAAG,eAAe,CAAC,GAAG,WAAW,CAAA;AAC5D,CAAC"}

package/dist/esm/utils/hyperliquid/orderFormatting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hyperliquid order size and price formatting for exchange submission.
+ *
+ * These encode Hyperliquid-specific order submission rules. Getting size/price
+ * formatting wrong causes rejected orders.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ */
+/**
+ * Derive the maximum number of price decimal places for a given asset.
+ *
+ * @param szDecimals - The asset's szDecimals (from market meta)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Maximum allowed price decimals
+ */
+export declare function getMaxPriceDecimals(szDecimals: number, market?: string): number;
+/**
+ * Format a size value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Size must be rounded to the asset's szDecimals
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param size - The size value to format
+ * @param szDecimals - Number of decimal places allowed for this asset (from meta)
+ * @returns Size as a string with correct precision, no trailing zeros
+ */
+export declare function formatOrderSize(size: number, szDecimals: number): string;
+/**
+ * Format a price value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Maximum 5 significant figures
+ * - Max decimals = MAX_DECIMALS - szDecimals (6 for perps, 8 for spot)
+ * - Integer prices always allowed regardless of significant figures
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param price - The price value to format
+ * @param szDecimals - The asset's szDecimals (affects max price decimals)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Price as a string with correct precision, no trailing zeros
+ */
+export declare function formatOrderPrice(price: number, szDecimals: number, market?: string): string;
+//# sourceMappingURL=orderFormatting.d.ts.map

package/dist/esm/utils/hyperliquid/orderFormatting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderFormatting.d.ts","sourceRoot":"","sources":["../../../../src/utils/hyperliquid/orderFormatting.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAsBR"}

package/dist/esm/utils/hyperliquid/orderFormatting.js

@@ -0,0 +1,79 @@
+/**
+ * Hyperliquid order size and price formatting for exchange submission.
+ *
+ * These encode Hyperliquid-specific order submission rules. Getting size/price
+ * formatting wrong causes rejected orders.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ */
+import { stringToFloat } from '../parse.js';
+/**
+ * Max combined decimals (size + price) enforced by Hyperliquid.
+ * Perps: 6, Spot: 8
+ */
+const MAX_DECIMALS_PERPS = 6;
+const MAX_DECIMALS_SPOT = 8;
+function getMaxDecimals(market) {
+    return market === 'spot' ? MAX_DECIMALS_SPOT : MAX_DECIMALS_PERPS;
+}
+/**
+ * Derive the maximum number of price decimal places for a given asset.
+ *
+ * @param szDecimals - The asset's szDecimals (from market meta)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Maximum allowed price decimals
+ */
+export function getMaxPriceDecimals(szDecimals, market) {
+    return Math.max(0, getMaxDecimals(market) - szDecimals);
+}
+/**
+ * Format a size value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Size must be rounded to the asset's szDecimals
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param size - The size value to format
+ * @param szDecimals - Number of decimal places allowed for this asset (from meta)
+ * @returns Size as a string with correct precision, no trailing zeros
+ */
+export function formatOrderSize(size, szDecimals) {
+    // Truncate (don't round up) to avoid exceeding available balance
+    const multiplier = 10 ** szDecimals;
+    const truncated = Math.floor(size * multiplier) / multiplier;
+    // Remove trailing zeros by round-tripping through stringToFloat
+    return stringToFloat(truncated.toFixed(szDecimals)).toString();
+}
+/**
+ * Format a price value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Maximum 5 significant figures
+ * - Max decimals = MAX_DECIMALS - szDecimals (6 for perps, 8 for spot)
+ * - Integer prices always allowed regardless of significant figures
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param price - The price value to format
+ * @param szDecimals - The asset's szDecimals (affects max price decimals)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Price as a string with correct precision, no trailing zeros
+ */
+export function formatOrderPrice(price, szDecimals, market) {
+    const maxPriceDecimals = getMaxPriceDecimals(szDecimals, market);
+    // Round to max allowed decimals
+    let rounded = stringToFloat(price.toFixed(maxPriceDecimals));
+    // Integer prices are always allowed regardless of significant figures
+    if (Number.isInteger(rounded)) {
+        return rounded.toString();
+    }
+    // Count significant figures (digits excluding leading zeros)
+    const absStr = Math.abs(rounded).toString().replace('.', '');
+    const sigFigs = absStr.replace(/^0+/, '').length;
+    // If more than 5 significant figures, round to 5
+    if (sigFigs > 5) {
+        rounded = stringToFloat(rounded.toPrecision(5));
+    }
+    // Return without trailing zeros
+    return rounded.toString();
+}
+//# sourceMappingURL=orderFormatting.js.map

package/dist/esm/utils/hyperliquid/orderFormatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderFormatting.js","sourceRoot":"","sources":["../../../../src/utils/hyperliquid/orderFormatting.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAC5B,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAE3B,SAAS,cAAc,CAAC,MAAe;IACrC,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,CAAA;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAkB,EAClB,MAAe;IAEf,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAA;AACzD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,UAAkB;IAC9D,iEAAiE;IACjE,MAAM,UAAU,GAAG,EAAE,IAAI,UAAU,CAAA;IACnC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,UAAU,CAAC,GAAG,UAAU,CAAA;IAC5D,gEAAgE;IAChE,OAAO,aAAa,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;AAChE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAa,EACb,UAAkB,EAClB,MAAe;IAEf,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IAEhE,gCAAgC;IAChC,IAAI,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAA;IAE5D,sEAAsE;IACtE,IAAI,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAA;IAC3B,CAAC;IAED,6DAA6D;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAA;IAEhD,iDAAiD;IACjD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IACjD,CAAC;IAED,gCAAgC;IAChC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAA;AAC3B,CAAC"}

package/dist/esm/utils/orderClassification.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Order classification utilities.
+ *
+ * Type guards and classifiers that operate on SDK types to determine
+ * order categories (TP/SL, open/close). These use the OrderType enum
+ * for classification — no string matching.
+ */
+import type { OpenOrder } from '@lifi/perps-types';
+import { FillClassification, OrderSide } from '@lifi/perps-types';
+export { FillClassification };
+/**
+ * Check if an open order is a Take Profit trigger order.
+ */
+export declare function isTakeProfitOrder(order: Pick<OpenOrder, 'type'>): boolean;
+/**
+ * Check if an open order is a Stop Loss trigger order.
+ */
+export declare function isStopLossOrder(order: Pick<OpenOrder, 'type'>): boolean;
+/**
+ * Check if an open order is a TP or SL trigger order.
+ */
+export declare function isTpSlOrder(order: Pick<OpenOrder, 'type'>): boolean;
+/**
+ * Classify a fill as open or close based on realizedPnl.
+ * @deprecated Use `Fill.classification` instead — it uses startPosition
+ * for accurate open/increase/reduce/close/reverse classification.
+ */
+export declare function classifyFill(side: OrderSide, realizedPnl: string | null | undefined): FillClassification;
+//# sourceMappingURL=orderClassification.d.ts.map

package/dist/esm/utils/orderClassification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderClassification.d.ts","sourceRoot":"","sources":["../../../src/utils/orderClassification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAa,MAAM,mBAAmB,CAAA;AAG5E,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAY7B;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAEzE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAEvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,kBAAkB,CAUpB"}

package/dist/esm/utils/orderClassification.js

@@ -0,0 +1,53 @@
+/**
+ * Order classification utilities.
+ *
+ * Type guards and classifiers that operate on SDK types to determine
+ * order categories (TP/SL, open/close). These use the OrderType enum
+ * for classification — no string matching.
+ */
+import { FillClassification, OrderSide, OrderType } from '@lifi/perps-types';
+import { stringToFloat } from './parse.js';
+export { FillClassification };
+const TP_TYPES = new Set([
+    OrderType.TAKE_PROFIT_MARKET,
+    OrderType.TAKE_PROFIT_LIMIT,
+]);
+const SL_TYPES = new Set([
+    OrderType.STOP_MARKET,
+    OrderType.STOP_LIMIT,
+]);
+/**
+ * Check if an open order is a Take Profit trigger order.
+ */
+export function isTakeProfitOrder(order) {
+    return TP_TYPES.has(order.type);
+}
+/**
+ * Check if an open order is a Stop Loss trigger order.
+ */
+export function isStopLossOrder(order) {
+    return SL_TYPES.has(order.type);
+}
+/**
+ * Check if an open order is a TP or SL trigger order.
+ */
+export function isTpSlOrder(order) {
+    return TP_TYPES.has(order.type) || SL_TYPES.has(order.type);
+}
+/**
+ * Classify a fill as open or close based on realizedPnl.
+ * @deprecated Use `Fill.classification` instead — it uses startPosition
+ * for accurate open/increase/reduce/close/reverse classification.
+ */
+export function classifyFill(side, realizedPnl) {
+    const isClose = realizedPnl != null && stringToFloat(realizedPnl) !== 0;
+    if (side === OrderSide.BUY) {
+        return isClose
+            ? FillClassification.CLOSED_SHORT
+            : FillClassification.OPENED_LONG;
+    }
+    return isClose
+        ? FillClassification.CLOSED_LONG
+        : FillClassification.OPENED_SHORT;
+}
+//# sourceMappingURL=orderClassification.js.map

package/dist/esm/utils/orderClassification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderClassification.js","sourceRoot":"","sources":["../../../src/utils/orderClassification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAY;IAClC,SAAS,CAAC,kBAAkB;IAC5B,SAAS,CAAC,iBAAiB;CAC5B,CAAC,CAAA;AAEF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAY;IAClC,SAAS,CAAC,WAAW;IACrB,SAAS,CAAC,UAAU;CACrB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA8B;IAC9D,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAA8B;IAC5D,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAA8B;IACxD,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAe,EACf,WAAsC;IAEtC,MAAM,OAAO,GAAG,WAAW,IAAI,IAAI,IAAI,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;IACvE,IAAI,IAAI,KAAK,SAAS,CAAC,GAAG,EAAE,CAAC;QAC3B,OAAO,OAAO;YACZ,CAAC,CAAC,kBAAkB,CAAC,YAAY;YACjC,CAAC,CAAC,kBAAkB,CAAC,WAAW,CAAA;IACpC,CAAC;IACD,OAAO,OAAO;QACZ,CAAC,CAAC,kBAAkB,CAAC,WAAW;QAChC,CAAC,CAAC,kBAAkB,CAAC,YAAY,CAAA;AACrC,CAAC"}

package/dist/esm/utils/orderMath.d.ts

@@ -0,0 +1,40 @@
+import { type OpenOrder, type Position, type TriggerOrder } from '@lifi/perps-types';
+/**
+ * Pick the matching open position for an order's asset, if any.
+ *
+ * @param assetId - The order's `asset.assetId`.
+ * @param positions - Open positions list (any symbol).
+ */
+export declare function findMatchingPosition(assetId: string, positions: readonly Position[]): Position | undefined;
+/**
+ * Resolve the close-size against a position, applying the spec's cap rules:
+ *  - `orderSize === 0` is the Hyperliquid convention for "close entire
+ *    position" → close the full position size.
+ *  - Otherwise cap at the absolute position size; an order larger than the
+ *    position can only close what's open.
+ *
+ * Inputs are non-negative magnitudes.
+ */
+export declare function resolveCloseSize(orderSize: number, positionSize: number): number;
+/**
+ * Expected rPnL for a resting limit order against a matching position.
+ *
+ * Reducing requires opposite sides (long position + SELL, short position +
+ * BUY). Same-side orders add to the position and have no rPnL → `null`.
+ *
+ * @returns Realised PnL if the order would reduce the position, otherwise
+ *   `null`.
+ */
+export declare function expectedRealizedPnlForOpenOrder(order: OpenOrder, position: Position | undefined): number | null;
+/**
+ * Expected rPnL for a TP/SL trigger order against a matching position.
+ *
+ * A trigger order is by construction a closing leg — its direction is the
+ * opposite of the position's. With no matching position there is nothing to
+ * close, so rPnL is `null`. The trigger price (always present on the SDK
+ * `TriggerOrder` shape) is used as the rPnL price; the optional `limitPrice`
+ * for STOP_LIMIT / TAKE_PROFIT_LIMIT is the post-trigger limit, not the rPnL
+ * price.
+ */
+export declare function expectedRealizedPnlForTriggerOrder(order: TriggerOrder, position: Position | undefined): number | null;
+//# sourceMappingURL=orderMath.d.ts.map

package/dist/esm/utils/orderMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderMath.d.ts","sourceRoot":"","sources":["../../../src/utils/orderMath.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,QAAQ,EAEb,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAA;AAG1B;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,QAAQ,GAAG,SAAS,CAEtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,CAKR;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAkCf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CA2Bf"}

package/dist/esm/utils/orderMath.js

@@ -0,0 +1,99 @@
+import { OrderSide, PositionSide, } from '@lifi/perps-types';
+import { realizedPnlOnClose } from './positionMath.js';
+/**
+ * Pick the matching open position for an order's asset, if any.
+ *
+ * @param assetId - The order's `asset.assetId`.
+ * @param positions - Open positions list (any symbol).
+ */
+export function findMatchingPosition(assetId, positions) {
+    return positions.find((p) => p.asset.assetId === assetId);
+}
+/**
+ * Resolve the close-size against a position, applying the spec's cap rules:
+ *  - `orderSize === 0` is the Hyperliquid convention for "close entire
+ *    position" → close the full position size.
+ *  - Otherwise cap at the absolute position size; an order larger than the
+ *    position can only close what's open.
+ *
+ * Inputs are non-negative magnitudes.
+ */
+export function resolveCloseSize(orderSize, positionSize) {
+    if (orderSize === 0) {
+        return positionSize;
+    }
+    return Math.min(orderSize, positionSize);
+}
+/**
+ * Expected rPnL for a resting limit order against a matching position.
+ *
+ * Reducing requires opposite sides (long position + SELL, short position +
+ * BUY). Same-side orders add to the position and have no rPnL → `null`.
+ *
+ * @returns Realised PnL if the order would reduce the position, otherwise
+ *   `null`.
+ */
+export function expectedRealizedPnlForOpenOrder(order, position) {
+    if (!position) {
+        return null;
+    }
+    const isLong = position.side === PositionSide.LONG;
+    const reducesPosition = (isLong && order.side === OrderSide.SELL) ||
+        (!isLong && order.side === OrderSide.BUY);
+    if (!reducesPosition) {
+        return null;
+    }
+    const limitPrice = Number.parseFloat(order.price);
+    const entryPrice = Number.parseFloat(position.entryPrice);
+    const orderSize = Math.abs(Number.parseFloat(order.size));
+    const positionSize = Math.abs(Number.parseFloat(position.size));
+    if (!Number.isFinite(limitPrice) ||
+        !Number.isFinite(entryPrice) ||
+        !Number.isFinite(orderSize) ||
+        !Number.isFinite(positionSize) ||
+        positionSize <= 0) {
+        return null;
+    }
+    const closeSize = resolveCloseSize(orderSize, positionSize);
+    return realizedPnlOnClose({
+        entryPrice,
+        closePrice: limitPrice,
+        closeSize,
+        isLong,
+    });
+}
+/**
+ * Expected rPnL for a TP/SL trigger order against a matching position.
+ *
+ * A trigger order is by construction a closing leg — its direction is the
+ * opposite of the position's. With no matching position there is nothing to
+ * close, so rPnL is `null`. The trigger price (always present on the SDK
+ * `TriggerOrder` shape) is used as the rPnL price; the optional `limitPrice`
+ * for STOP_LIMIT / TAKE_PROFIT_LIMIT is the post-trigger limit, not the rPnL
+ * price.
+ */
+export function expectedRealizedPnlForTriggerOrder(order, position) {
+    if (!position) {
+        return null;
+    }
+    const isLong = position.side === PositionSide.LONG;
+    const triggerPrice = Number.parseFloat(order.triggerPrice);
+    const entryPrice = Number.parseFloat(position.entryPrice);
+    const orderSize = Math.abs(Number.parseFloat(order.size));
+    const positionSize = Math.abs(Number.parseFloat(position.size));
+    if (!Number.isFinite(triggerPrice) ||
+        !Number.isFinite(entryPrice) ||
+        !Number.isFinite(orderSize) ||
+        !Number.isFinite(positionSize) ||
+        positionSize <= 0) {
+        return null;
+    }
+    const closeSize = resolveCloseSize(orderSize, positionSize);
+    return realizedPnlOnClose({
+        entryPrice,
+        closePrice: triggerPrice,
+        closeSize,
+        isLong,
+    });
+}
+//# sourceMappingURL=orderMath.js.map

package/dist/esm/utils/orderMath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderMath.js","sourceRoot":"","sources":["../../../src/utils/orderMath.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/parse.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Robust string-to-number parsing utilities.
+ */
+/**
+ * Parse a string to a float, stripping common formatting artefacts.
+ *
+ * Handles:
+ * - Currency prefixes/suffixes ($, USD, etc.)
+ * - Explicit sign prefixes (+/-)
+ * - Thousands separators (commas)
+ * - Percentage suffixes (%)
+ * - Whitespace
+ *
+ * @param value - The string to parse
+ * @returns Parsed number, or NaN if the string contains no valid number
+ */
+export declare function stringToFloat(value: string): number;
+//# sourceMappingURL=parse.d.ts.map

package/dist/esm/utils/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/utils/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUnD"}

package/dist/esm/utils/parse.js

@@ -0,0 +1,28 @@
+/**
+ * Robust string-to-number parsing utilities.
+ */
+/**
+ * Parse a string to a float, stripping common formatting artefacts.
+ *
+ * Handles:
+ * - Currency prefixes/suffixes ($, USD, etc.)
+ * - Explicit sign prefixes (+/-)
+ * - Thousands separators (commas)
+ * - Percentage suffixes (%)
+ * - Whitespace
+ *
+ * @param value - The string to parse
+ * @returns Parsed number, or NaN if the string contains no valid number
+ */
+export function stringToFloat(value) {
+    if (!value) {
+        return 0;
+    }
+    // Strip whitespace, currency symbols, thousands commas, and % suffix
+    const cleaned = value.trim().replace(/[$%]/g, '').replace(/,/g, '').trim();
+    if (!cleaned) {
+        return 0;
+    }
+    return parseFloat(cleaned);
+}
+//# sourceMappingURL=parse.js.map

package/dist/esm/utils/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/utils/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,CAAA;IACV,CAAC;IACD,qEAAqE;IACrE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAA;AAC5B,CAAC"}

package/dist/esm/utils/positionMath.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure-function helpers for predicting how a perp position changes after a
+ * fill.
+ *
+ * Sign convention: long = +1, short = -1. Sizes passed to these helpers are
+ * always non-negative magnitudes; direction is carried by `isLong`.
+ */
+/**
+ * Direction sign for a position.
+ *
+ * @param isLong - True for long positions, false for short.
+ * @returns +1 for long, -1 for short.
+ */
+export declare function directionSign(isLong: boolean): 1 | -1;
+/**
+ * Predicted average entry price after adding to an existing position.
+ *
+ * Weighted average of the current entry and the new fill price, weighted by
+ * the size of each leg in coin units. Both legs assumed in the same direction
+ * (this helper is for adding to, not flipping, a position).
+ *
+ * @param currentSize - Existing position size in coin units (>= 0).
+ * @param currentEntry - Existing position's average entry price.
+ * @param addSize - Size being added in coin units (>= 0).
+ * @param fillPrice - Price the new size is expected to fill at (mid for
+ *   market, limitPrice for limit orders).
+ * @returns The new weighted-average entry price, or undefined if the inputs
+ *   cannot produce a valid average (zero combined size, non-finite values).
+ */
+export declare function predictAverageEntryPrice(params: {
+    currentSize: number;
+    currentEntry: number;
+    addSize: number;
+    fillPrice: number;
+}): number | undefined;
+/**
+ * Predicted effective leverage after adding margin and notional.
+ *
+ * leverage = totalNotional / totalMargin. The caller computes notional from
+ * size and price (`calculateNotionalValue`) and supplies the additional
+ * margin the user is about to put up.
+ *
+ * @returns The new effective leverage, or undefined if total margin is
+ *   non-positive.
+ */
+export declare function predictNewLeverage(params: {
+    currentNotional: number;
+    currentMargin: number;
+    addNotional: number;
+    addMargin: number;
+}): number | undefined;
+/**
+ * Predicted unrealised PnL at the current mark price.
+ *
+ * `pnl = (markPrice - entryPrice) * size * directionSign(isLong)`
+ *
+ * @param size - Position size as a non-negative magnitude.
+ */
+export declare function predictUnrealizedPnl(params: {
+    entryPrice: number;
+    markPrice: number;
+    size: number;
+    isLong: boolean;
+}): number;
+/**
+ * Realised PnL on the portion of a position being closed.
+ *
+ * `rPnl = (closePrice - entryPrice) * closeSize * directionSign(isLong)`
+ *
+ * @param closeSize - Size being closed as a non-negative magnitude.
+ */
+export declare function realizedPnlOnClose(params: {
+    entryPrice: number;
+    closePrice: number;
+    closeSize: number;
+    isLong: boolean;
+}): number;
+//# sourceMappingURL=positionMath.d.ts.map

package/dist/esm/utils/positionMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positionMath.d.ts","sourceRoot":"","sources":["../../../src/utils/positionMath.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAErD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,GAAG,SAAS,CAUrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,GAAG,SAAS,CAOrB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,MAAM,CAGT;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,MAAM,CAGT"}