@lifi/perps-sdk 0.1.1-alpha.4 → 0.1.1-alpha.40

package/dist/esm/utils/calculations.js

@@ -0,0 +1,154 @@
+/**
+ * Universal perpetual futures calculation utilities.
+ *
+ * Pure functions for computing position-related values that any consumer
+ * of the perps SDK would need. All parameters are required — no default
+ * values for critical financial parameters.
+ */
+/**
+ * Calculate position size in asset units from margin.
+ *
+ * @param marginUsd - Margin amount in USD
+ * @param leverage - Position leverage
+ * @param price - Current asset price
+ * @returns Position size in asset units
+ */
+export function calculatePositionSize(marginUsd, leverage, price) {
+    return (marginUsd * leverage) / price;
+}
+/**
+ * Calculate notional value of a position.
+ *
+ * @param size - Position size in asset units
+ * @param price - Current asset price
+ * @returns Notional value in USD
+ */
+export function calculateNotionalValue(size, price) {
+    return Math.abs(size) * price;
+}
+/**
+ * Calculate unrealized PnL.
+ *
+ * @param entryPrice - Position entry price
+ * @param currentPrice - Current market price
+ * @param size - Position size (positive for long, negative for short)
+ * @returns Unrealized PnL in USD
+ */
+export function calculateUnrealizedPnl(entryPrice, currentPrice, size) {
+    return (currentPrice - entryPrice) * size;
+}
+/**
+ * Calculate return on equity (ROE) percentage.
+ *
+ * @param pnl - Profit/loss in USD
+ * @param margin - Initial margin in USD
+ * @returns ROE as percentage (e.g., 10 for 10%)
+ */
+export function calculateRoe(pnl, margin) {
+    if (margin === 0) {
+        return 0;
+    }
+    return (pnl / margin) * 100;
+}
+/**
+ * Calculate required margin for a position.
+ *
+ * @param notionalValue - Position notional value in USD
+ * @param leverage - Position leverage
+ * @returns Required margin in USD
+ */
+export function calculateRequiredMargin(notionalValue, leverage) {
+    return notionalValue / leverage;
+}
+/**
+ * Estimate trading fees.
+ *
+ * @param sizeUsd - Position size in USD (notional value)
+ * @param feeRate - Fee rate as decimal (e.g., 0.00035 for 0.035%)
+ * @returns Estimated fee in USD
+ */
+export function estimateFees(sizeUsd, feeRate) {
+    return sizeUsd * feeRate;
+}
+/**
+ * Apply slippage to a price for order execution.
+ *
+ * @param price - Base price
+ * @param slippagePercent - Slippage tolerance as percentage (e.g., 0.5 for 0.5%)
+ * @param isBuy - True if buying (price goes up), false if selling (price goes down)
+ * @returns Price adjusted for slippage
+ */
+export function applySlippage(price, slippagePercent, isBuy) {
+    const multiplier = 1 + slippagePercent / 100;
+    return isBuy ? price * multiplier : price / multiplier;
+}
+/**
+ * Calculate expected gain/loss for a TP or SL trigger price.
+ * Returns signed values — positive means profit, negative means loss.
+ *
+ * @param triggerPrice - The TP or SL target price
+ * @param entryPrice - Position entry / current market price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ * @param margin - Margin amount in USD
+ */
+export function calculateExpectedPnl(triggerPrice, entryPrice, leverage, isLong, margin) {
+    if (!triggerPrice || entryPrice === 0 || margin === 0) {
+        return null;
+    }
+    const priceDiff = isLong
+        ? triggerPrice - entryPrice
+        : entryPrice - triggerPrice;
+    const percent = (priceDiff / entryPrice) * leverage * 100;
+    const amount = margin * (percent / 100);
+    return { amount, percent };
+}
+/**
+ * Convert a percentage gain/loss to a target price.
+ *
+ * @param percent - Target gain/loss percentage (positive = profitable direction)
+ * @param entryPrice - Position entry price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ */
+export function priceFromPercent(percent, entryPrice, leverage, isLong) {
+    if (entryPrice === 0 || leverage === 0) {
+        return 0;
+    }
+    const priceDelta = (percent / 100 / leverage) * entryPrice;
+    return isLong ? entryPrice + priceDelta : entryPrice - priceDelta;
+}
+/**
+ * Convert a target price to a percentage gain/loss.
+ *
+ * @param price - Target price
+ * @param entryPrice - Position entry price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ */
+export function percentFromPrice(price, entryPrice, leverage, isLong) {
+    if (entryPrice === 0 || leverage === 0) {
+        return 0;
+    }
+    const priceDiff = isLong ? price - entryPrice : entryPrice - price;
+    return (priceDiff / entryPrice) * leverage * 100;
+}
+// ---------------------------------------------------------------------------
+// Realized PnL percentage
+// ---------------------------------------------------------------------------
+/**
+ * Calculate realized PnL as a percentage of position value at close.
+ *
+ * @param realizedPnl - The realized profit/loss in USD
+ * @param size - Position size in asset units at close
+ * @param price - Price at close
+ * @returns PnL as a percentage of position value
+ */
+export function calculateRealizedPnlPercent(realizedPnl, size, price) {
+    const positionValue = Math.abs(size) * price;
+    if (positionValue === 0) {
+        return 0;
+    }
+    return (realizedPnl / positionValue) * 100;
+}
+//# sourceMappingURL=calculations.js.map

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

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

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

@@ -0,0 +1,3 @@
+export { calculateLiquidationPrice, calculateMaintenanceMarginRate, } from './liquidation.js';
+export { formatOrderPrice, formatOrderSize, getMaxPriceDecimals, } from './orderFormatting.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","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/index.js

@@ -0,0 +1,3 @@
+export { calculateLiquidationPrice, calculateMaintenanceMarginRate, } from './liquidation.js';
+export { formatOrderPrice, formatOrderSize, getMaxPriceDecimals, } from './orderFormatting.js';
+//# sourceMappingURL=index.js.map

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/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/request.d.ts

@@ -11,8 +11,7 @@ export interface RequestOptions extends RequestInit {
  * @param options - Fetch options plus retries
  * @param sdkOptions - SDK-specific options (signal, etc.)
  * @returns Parsed JSON response
- * @throws {HTTPError} On non-2xx responses
- * @throws {PerpsError} On network or parsing errors
+ * @throws {PerpsError} On non-2xx responses or network errors
  */
 export declare function request<T>(config: PerpsBaseConfig, url: string, options?: RequestOptions, sdkOptions?: SDKRequestOptions): Promise<T>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/utils/request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,gCAAgC,CAAA;AAMvC,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,EAC5B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,CAAC,CAAC,CA2DZ;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC5D,MAAM,CAWR"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/utils/request.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,gCAAgC,CAAA;AAKvC,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,EAC5B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,CAAC,CAAC,CA2EZ;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC5D,MAAM,CAWR"}

package/dist/esm/utils/request.js

@@ -1,5 +1,4 @@
 import { PerpsErrorCode } from '@lifi/perps-types';
-import { HTTPError } from '../errors/HTTPError.js';
 import { PerpsError } from '../errors/PerpsError.js';
 import { version } from '../version.js';
 import { sleep } from './sleep.js';
@@ -12,8 +11,7 @@ const DEFAULT_RETRIES = 1;
  * @param options - Fetch options plus retries
  * @param sdkOptions - SDK-specific options (signal, etc.)
  * @returns Parsed JSON response
- * @throws {HTTPError} On non-2xx responses
- * @throws {PerpsError} On network or parsing errors
+ * @throws {PerpsError} On non-2xx responses or network errors
  */
 export async function request(config, url, options = {}, sdkOptions) {
     const retries = options.retries ?? DEFAULT_RETRIES;
@@ -39,19 +37,34 @@ export async function request(config, url, options = {}, sdkOptions) {
     try {
         const response = await fetch(url, finalOptions);
         if (!response.ok) {
-            const error = new HTTPError(response, url);
-            await error.buildAdditionalDetails();
-            // Retry on 5xx errors
+            // Parse the backend's error body
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch { }
+            // Retry on 5xx before throwing
             if (retries > 0 && response.status >= 500) {
                 await sleep(500);
                 return request(config, url, { ...options, retries: retries - 1 }, sdkOptions);
             }
+            // Rehydrate backend error — code/message/tool come straight from the response
+            const fallbackMessage = `Request failed with status code ${response.status}`;
+            if (body &&
+                typeof body.code === 'number' &&
+                typeof body.message === 'string') {
+                const error = new PerpsError(body.code, body.message);
+                error.tool = body.tool ?? 'unknown';
+                throw error;
+            }
+            const error = new PerpsError(PerpsErrorCode.DefaultError, fallbackMessage);
+            error.tool = 'unknown';
             throw error;
         }
         return (await response.json());
     }
     catch (error) {
-        if (error instanceof HTTPError || error instanceof PerpsError) {
+        if (error instanceof PerpsError) {
             throw error;
         }
         // Network error or other fetch failure