@lifi/perps-sdk 23.1.0 → 25.0.0

package/dist/types/math/order.d.ts

@@ -1,41 +1,47 @@
 /**
- * Display-tier order formulas. Every function takes and gives `number`;
- * exact decimal arithmetic happens internally with `DivBig`.
+ * Display-tier order formulas. Every function takes and gives decimal
+ * strings; arithmetic is exact Big.js, with division to 40 decimal places.
+ * Each formula throws `ValidationError` on an input that does not match the
+ * decimal pattern and has a `safe*` pair that gives `undefined` in place of the throw.
  */
 import { type FeeTier, type Market, type MarketContext, type Order, type OrderbookLevel, type Position, type Quote, type QuoteSide, type TradeType } from '@lifi/perps-types';
 /**
- * Calculate position size in asset units from margin.
+ * Position size in asset units from margin: `marginUsd × leverage ÷ price`.
  *
- * @param marginUsd - Margin amount in USD
- * @param leverage - Position leverage
- * @param price - Current asset price
- * @returns Position size in asset units
  * @example
  * ```ts
- * calculateSize(100, 10, 2000) // 0.5 (ETH at $2000)
+ * calculateSize('100', '10', '2000') // '0.5' (ETH at $2000)
  * ```
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern
+ *   or `price` is zero.
  * @public
  */
-export declare function calculateSize(marginUsd: number, leverage: number, price: number): number;
+export declare function calculateSize(marginUsd: string, leverage: string, price: string): string;
+/** @public */
+export declare const safeCalculateSize: (marginUsd: string, leverage: string, price: string) => string | undefined;
 /**
- * Estimate trading fees.
+ * Estimated trading fee in USD: `sizeUsd × feeRate`.
  *
- * @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
+ * @param feeRate - Fee rate as a fraction (`'0.00035'` for 0.035%).
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function estimateFees(sizeUsd: number, feeRate: number): number;
+export declare function estimateFees(sizeUsd: string, feeRate: string): string;
+/** @public */
+export declare const safeEstimateFees: (sizeUsd: string, feeRate: string) => string | undefined;
 /**
- * Apply slippage to a price for order execution.
+ * Apply slippage to an order-entry price with exact decimal math: a buy
+ * multiplies by `1 + slippagePercent / 100`, a sell divides by it. The result
+ * is not rounded; snap it to the market tick before it goes to a venue.
  *
- * @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
+ * @param slippagePercent - Slippage tolerance as a percentage (`'0.5'` is 0.5%).
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, or `slippagePercent` is -100 or less.
  * @public
  */
-export declare function applySlippage(price: number, slippagePercent: number, isBuy: boolean): number;
+export declare function applySlippageToPrice(price: string, slippagePercent: string, isBuy: boolean): string;
+/** @public */
+export declare const safeApplySlippageToPrice: (price: string, slippagePercent: string, isBuy: boolean) => string | undefined;
 /**
  * Signed expected PnL for a trigger price — see {@link calculateExpectedPnl}.
  *
@@ -43,61 +49,63 @@ export declare function applySlippage(price: number, slippagePercent: number, is
  */
 export interface ExpectedPnl {
     /** Signed expected profit/loss in USD. */
-    amount: number;
-    /** Signed expected return as a percentage (10 means 10%). */
-    percent: number;
+    amount: string;
+    /** Signed expected return as a percentage (`'10'` means 10%). */
+    percent: string;
 }
 /**
- * Calculate expected gain/loss for a TP or SL trigger price.
- * Returns signed values — positive means profit, negative means loss.
+ * Expected gain or loss for a TP or SL trigger price. Positive is a profit,
+ * negative a 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
+ * @param entryPrice - Position entry or current market price.
+ * @param margin - Margin amount in USD.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, or `triggerPrice`, `entryPrice` or `margin` is zero.
  * @public
  */
-export declare function calculateExpectedPnl(triggerPrice: number, entryPrice: number, leverage: number, isLong: boolean, margin: number): ExpectedPnl | null;
+export declare function calculateExpectedPnl(triggerPrice: string, entryPrice: string, leverage: string, isLong: boolean, margin: string): ExpectedPnl;
+/** @public */
+export declare const safeCalculateExpectedPnl: (triggerPrice: string, entryPrice: string, leverage: string, isLong: boolean, margin: string) => ExpectedPnl | undefined;
 /**
- * Calculate the trigger price that realises a percentage gain/loss.
+ * Trigger price that realises a percentage gain or loss.
  *
- * @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
+ * @param percent - Target gain or loss percentage (positive = profitable
+ *   direction).
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function calculateTriggerPrice(percent: number, entryPrice: number, leverage: number, isLong: boolean): number;
+export declare function calculateTriggerPrice(percent: string, entryPrice: string, leverage: string, isLong: boolean): string;
+/** @public */
+export declare const safeCalculateTriggerPrice: (percent: string, entryPrice: string, leverage: string, isLong: boolean) => string | undefined;
 /**
- * Calculate the percentage gain/loss a trigger price realises.
+ * Percentage gain or loss that a trigger price realises.
  *
- * @param price - Target price
- * @param entryPrice - Position entry price
- * @param leverage - Position leverage multiplier
- * @param isLong - True for long positions, false for short
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function calculateTriggerPercent(price: number, entryPrice: number, leverage: number, isLong: boolean): number;
+export declare function calculateTriggerPercent(price: string, entryPrice: string, leverage: string, isLong: boolean): string;
+/** @public */
+export declare const safeCalculateTriggerPercent: (price: string, entryPrice: string, leverage: string, isLong: boolean) => string | undefined;
 /**
- * Calculate realized PnL as a percentage of position value at close.
+ * Realized PnL as a percentage of the position value at close:
+ * `realizedPnl ÷ (|size| × price) × 100`.
  *
- * @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
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `size × price` is zero.
  * @public
  */
-export declare function calculateRealizedPnlPercent(realizedPnl: number, size: number, price: number): number;
+export declare function calculateRealizedPnlPercent(realizedPnl: string, size: string, price: string): string;
+/** @public */
+export declare const safeCalculateRealizedPnlPercent: (realizedPnl: string, size: string, price: string) => string | undefined;
 /** Result of {@link walkOrderbook} — the fill obtained for a USD-notional walk. */
 interface BookWalk {
     /** Base amount filled. */
-    baseSize: number;
+    baseSize: string;
     /** Notional actually filled in USD (equals the requested size unless the book ran dry). */
-    filledNotional: number;
-    /** Volume-weighted average fill price, or 0 when the book is empty. */
-    vwap: number;
-    /** True when the levels could not absorb the requested notional, and for a non-finite notional. */
+    filledNotional: string;
+    /** Volume-weighted average fill price, or `'0'` when the book is empty. */
+    vwap: string;
+    /** True when the levels could not absorb the requested notional. */
     insufficientLiquidity: boolean;
 }
 /**
@@ -106,21 +114,22 @@ interface BookWalk {
  * in array order — the caller passes asks for a buy and bids for a sell, each
  * already ordered best-price-first. When the book cannot absorb the full
  * notional, the walk stops at the last level and flags `insufficientLiquidity`,
- * returning the best obtainable fill. A non-finite `sizeUsd` gives NaN fill
- * fields with `insufficientLiquidity` set.
+ * returning the best obtainable fill.
  *
- * @throws {PerpsError} `ValidationError` when a level's `price` or `size`
- *   does not parse to a finite number.
+ * @throws {PerpsError} `ValidationError` when `sizeUsd` or a level's `price`
+ *   or `size` does not match the decimal pattern.
  * @public
  */
-export declare function walkOrderbook(levels: OrderbookLevel[], sizeUsd: number): BookWalk;
+export declare function walkOrderbook(levels: OrderbookLevel[], sizeUsd: string): BookWalk;
+/** @public */
+export declare const safeWalkOrderbook: (levels: OrderbookLevel[], sizeUsd: string) => BookWalk | undefined;
 /** Inputs to {@link buildQuote} — the resolved market, its live price, its book, and the trade ask. */
 interface BuildQuoteInput {
     provider: string;
     symbol: string;
     type: TradeType;
     side: QuoteSide;
-    sizeUsd: number;
+    sizeUsd: string;
     market: Market;
     price: MarketContext;
     bids: OrderbookLevel[];
@@ -136,12 +145,13 @@ interface BuildQuoteInput {
  * versus mark, applies the base taker fee on the filled notional, and carries
  * the market's `funding` (`null` for spot, which has none).
  *
- * @throws {PerpsError} `ValidationError` when a book level does not parse to
- *   a finite number — see {@link walkOrderbook} — or when a quoted figure is
- *   not finite (a non-finite `sizeUsd`, mark price or taker fee).
+ * @throws {PerpsError} `ValidationError` when `sizeUsd`, the mark price, the
+ *   taker fee or a book level does not match the decimal pattern.
  * @public
  */
 export declare function buildQuote(input: BuildQuoteInput): Quote;
+/** @public */
+export declare const safeBuildQuote: (input: BuildQuoteInput) => Quote | undefined;
 /**
  * Pick the matching open position for an order's market, if any.
  *
@@ -158,9 +168,13 @@ export declare function findMatchingPosition(marketId: string, positions: readon
  *    position can only close what's open.
  *
  * Inputs are non-negative magnitudes.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function resolveCloseSize(orderSize: number, positionSize: number): number;
+export declare function resolveCloseSize(orderSize: string, positionSize: string): string;
+/** @public */
+export declare const safeResolveCloseSize: (orderSize: string, positionSize: string) => string | undefined;
 /**
  * Expected rPnL an unfilled order would realise against a matching position:
  * a resting limit order prices off its limit, an armed trigger off its trigger
@@ -168,9 +182,13 @@ export declare function resolveCloseSize(orderSize: number, positionSize: number
  * nothing.
  *
  * @returns Realised PnL if the order would reduce the position, otherwise
- *   `null`.
+ *   `undefined`.
+ * @throws {PerpsError} `ValidationError` when a price or size on the order or
+ *   the position does not match the decimal pattern.
  * @public
  */
-export declare function estimateRealizedPnl(order: Order, position: Position | undefined): number | null;
+export declare function estimateRealizedPnl(order: Order, position: Position | undefined): string | undefined;
+/** @public */
+export declare const safeEstimateRealizedPnl: (order: Order, position: Position | undefined) => string | undefined;
 export {};
 //# sourceMappingURL=order.d.ts.map

package/dist/types/math/order.d.ts.map

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

package/dist/types/math/position.d.ts

@@ -1,181 +1,238 @@
 /**
  * Display-tier position formulas and margin-adjustment predicates. Every
- * formula takes and gives `number`; exact decimal arithmetic happens
- * internally with `DivBig`.
+ * formula takes and gives decimal strings; arithmetic is exact Big.js, with
+ * division to 40 decimal places. Each formula throws `ValidationError` on an
+ * input that does not match the decimal pattern and has a `safe*` pair that gives
+ * `undefined` in place of the throw.
  *
  * Sign convention: long = +1, short = -1. Sizes passed to the `estimate*`
  * helpers are always non-negative magnitudes; direction is carried by
  * `isLong`.
  */
-import { type Position } from '@lifi/perps-types';
+import { type PerpsMarket, type Position } from '@lifi/perps-types';
+import type { LiquidationEstimateParams } from '../types/provider.js';
 /**
- * Calculate notional value of a position.
+ * Notional value of a position: `|size| × price`.
  *
- * @param size - Position size in asset units
- * @param price - Current asset price
- * @returns Notional value in USD
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function calculateNotionalValue(size: number, price: number): number;
+export declare function calculateNotionalValue(size: string, price: string): string;
+/** @public */
+export declare const safeCalculateNotionalValue: (size: string, price: string) => string | undefined;
 /**
- * Calculate unrealized PnL.
+ * Unrealized PnL: `(currentPrice - entryPrice) × size`, where `size` is
+ * positive for a long and negative for a short.
  *
- * @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
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
-export declare function calculateUnrealizedPnl(entryPrice: number, currentPrice: number, size: number): number;
+export declare function calculateUnrealizedPnl(entryPrice: string, currentPrice: string, size: string): string;
+/** @public */
+export declare const safeCalculateUnrealizedPnl: (entryPrice: string, currentPrice: string, size: string) => string | undefined;
 /**
- * Calculate return on equity (ROE) percentage.
+ * Return on equity as a percentage (`'10'` for 10%): `pnl ÷ margin × 100`.
  *
- * @param pnl - Profit/loss in USD
- * @param margin - Initial margin in USD
- * @returns ROE as percentage (e.g., 10 for 10%)
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `margin` is zero.
  * @public
  */
-export declare function calculateRoe(pnl: number, margin: number): number;
+export declare function calculateRoe(pnl: string, margin: string): string;
+/** @public */
+export declare const safeCalculateRoe: (pnl: string, margin: string) => string | undefined;
 /**
- * Calculate required margin for a position.
+ * Required margin: `notionalValue ÷ leverage`.
  *
- * @param notionalValue - Position notional value in USD
- * @param leverage - Position leverage
- * @returns Required margin in USD
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern
+ *   or `leverage` is zero.
  * @public
  */
-export declare function calculateRequiredMargin(notionalValue: number, leverage: number): number;
+export declare function calculateRequiredMargin(notionalValue: string, leverage: string): string;
+/** @public */
+export declare const safeCalculateRequiredMargin: (notionalValue: string, leverage: string) => string | undefined;
 /**
- * Distance from the current price to the liquidation price, as a percentage of
- * the current price.
+ * Distance from the current price to the liquidation price, as an absolute
+ * percentage of the current price.
  *
- * @param liquidationPrice - The position's liquidation price
- * @param currentPrice - Current market price
- * @returns Absolute distance as a percentage, or 0 when current price is zero
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `currentPrice` is zero.
  * @public
  */
 export declare function calculateLiquidationDistance(params: {
-    liquidationPrice: number;
-    currentPrice: number;
-}): number;
+    liquidationPrice: string;
+    currentPrice: string;
+}): string;
+/** @public */
+export declare const safeCalculateLiquidationDistance: (params: {
+    liquidationPrice: string;
+    currentPrice: string;
+}) => string | undefined;
 /**
- * Effective leverage of an open position.
+ * Effective leverage of an open position: `positionValueUsd ÷ marginUsd`.
  *
- * leverage = positionValueUsd / marginUsd
- *
- * @param positionValueUsd - Position notional value in USD
- * @param marginUsd - Margin backing the position in USD
- * @returns Effective leverage, or 0 when margin is zero
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `marginUsd` is zero.
  * @public
  */
 export declare function calculateEffectiveLeverage(params: {
-    positionValueUsd: number;
-    marginUsd: number;
-}): number;
+    positionValueUsd: string;
+    marginUsd: string;
+}): string;
+/** @public */
+export declare const safeCalculateEffectiveLeverage: (params: {
+    positionValueUsd: string;
+    marginUsd: string;
+}) => string | undefined;
 /**
  * Estimated liquidation price for an isolated-margin position, parameterised
  * by the venue's maintenance margin rate.
  *
  * Standard isolated-margin model (new position, no existing exposure):
- *   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)
+ *   margin_available = entryPrice × (1 / leverage - mmr)
+ *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
  *
  * For existing positions, prefer `Position.liquidationPrice` from the venue.
  *
  * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
- *   (e.g. 0.01 = 1%).
- * @returns Estimated liquidation price, or undefined if the inputs cannot
- *   produce one (zero leverage, degenerate denominator).
+ *   (`'0.01'` = 1%).
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, `leverage` is zero, or `maintenanceMarginRate` gives a
+ *   zero denominator (`1` for a long, `-1` for a short).
  * @public
  */
 export declare function estimateLiquidationPrice(params: {
-    entryPrice: number;
-    leverage: number;
+    entryPrice: string;
+    leverage: string;
+    isLong: boolean;
+    maintenanceMarginRate: string;
+}): string;
+/** @public */
+export declare const safeEstimateLiquidationPrice: (params: {
+    entryPrice: string;
+    leverage: string;
     isLong: boolean;
-    maintenanceMarginRate: number;
-}): number | undefined;
+    maintenanceMarginRate: string;
+}) => string | undefined;
+/**
+ * Estimate the liquidation price of a new isolated position from the flat
+ * `market.maintenanceMarginRate`.
+ *
+ * @returns The estimate, or `undefined` when the market carries no
+ *   `maintenanceMarginRate`.
+ * @throws {PerpsError} `ValidationError` on an input that
+ *   {@link estimateLiquidationPrice} rejects.
+ * @public
+ */
+export declare function estimateLiquidationPriceAtMarketRate(market: PerpsMarket, params: LiquidationEstimateParams): string | undefined;
+/** @public */
+export declare const safeEstimateLiquidationPriceAtMarketRate: (market: PerpsMarket, params: LiquidationEstimateParams) => string | undefined;
 /**
  * Whether an isolated position with this liquidation price is already past
  * liquidation at `currentPrice`: a long liquidates when the price falls to its
  * liquidation level, a short when it rises to it. A non-positive price on
  * either side counts as unknown, so the result is `false`.
  *
+ * @throws {PerpsError} `ValidationError` when a price does not match the decimal pattern.
  * @public
  */
 export declare function wouldImmediatelyLiquidate(params: {
-    liquidationPrice: number;
-    currentPrice: number;
+    liquidationPrice: string;
+    currentPrice: string;
     isLong: boolean;
 }): boolean;
+/** @public */
+export declare const safeWouldImmediatelyLiquidate: (params: {
+    liquidationPrice: string;
+    currentPrice: string;
+    isLong: boolean;
+}) => boolean | undefined;
 /**
- * Estimated 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).
+ * Estimated average entry price after adding to an existing position: the
+ * size-weighted average of the current entry and the fill price. Both legs
+ * are in the same direction (an add, not a flip).
+ *
+ * @param fillPrice - Expected fill price (mid for market, limit price for
+ *   limit orders).
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `currentSize + addSize` is not positive.
  * @public
  */
 export declare function estimateAverageEntryPrice(params: {
-    currentSize: number;
-    currentEntry: number;
-    addSize: number;
-    fillPrice: number;
-}): number | undefined;
+    currentSize: string;
+    currentEntry: string;
+    addSize: string;
+    fillPrice: string;
+}): string;
+/** @public */
+export declare const safeEstimateAverageEntryPrice: (params: {
+    currentSize: string;
+    currentEntry: string;
+    addSize: string;
+    fillPrice: string;
+}) => string | undefined;
 /**
- * Estimated effective leverage after adding margin and notional.
+ * Estimated effective leverage after adding margin and notional:
+ * `(currentNotional + addNotional) ÷ (currentMargin + addMargin)`.
  *
- * 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.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `currentMargin + addMargin` is not positive.
  * @public
  */
 export declare function estimateNewLeverage(params: {
-    currentNotional: number;
-    currentMargin: number;
-    addNotional: number;
-    addMargin: number;
-}): number | undefined;
+    currentNotional: string;
+    currentMargin: string;
+    addNotional: string;
+    addMargin: string;
+}): string;
+/** @public */
+export declare const safeEstimateNewLeverage: (params: {
+    currentNotional: string;
+    currentMargin: string;
+    addNotional: string;
+    addMargin: string;
+}) => string | undefined;
 /**
- * Estimated unrealised PnL at the current mark price.
- *
- * `pnl = (markPrice - entryPrice) * size * (isLong ? 1 : -1)`
+ * Estimated unrealised PnL at the mark price:
+ * `(markPrice - entryPrice) × size × (isLong ? 1 : -1)`.
  *
  * @param size - Position size as a non-negative magnitude.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export declare function estimateUnrealizedPnl(params: {
-    entryPrice: number;
-    markPrice: number;
-    size: number;
+    entryPrice: string;
+    markPrice: string;
+    size: string;
     isLong: boolean;
-}): number;
+}): string;
+/** @public */
+export declare const safeEstimateUnrealizedPnl: (params: {
+    entryPrice: string;
+    markPrice: string;
+    size: string;
+    isLong: boolean;
+}) => string | undefined;
 /**
- * Realised PnL on the portion of a position being closed.
- *
- * `rPnl = (closePrice - entryPrice) * closeSize * (isLong ? 1 : -1)`
+ * Realised PnL on the portion of a position being closed:
+ * `(closePrice - entryPrice) × closeSize × (isLong ? 1 : -1)`.
  *
  * @param closeSize - Size being closed as a non-negative magnitude.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export declare function calculateRealizedPnl(params: {
-    entryPrice: number;
-    closePrice: number;
-    closeSize: number;
+    entryPrice: string;
+    closePrice: string;
+    closeSize: string;
+    isLong: boolean;
+}): string;
+/** @public */
+export declare const safeCalculateRealizedPnl: (params: {
+    entryPrice: string;
+    closePrice: string;
+    closeSize: string;
     isLong: boolean;
-}): number;
+}) => string | undefined;
 /**
  * Whether this position can take a margin adjustment at all: it holds margin of
  * its own and its market exposes individual position margin.

package/dist/types/math/position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/math/position.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,mBAAmB,CAAA;AAG1B;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,MAAM,CAMT;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,CAST;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,qBAAqB,EAAE,MAAM,CAAA;CAC9B,GAAG,MAAM,GAAG,SAAS,CAqBrB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,OAAO,CAQV;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,GAAG,SAAS,CAiBrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,GAAG,SAAS,CAarB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,MAAM,CAUT;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,MAAM,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAMzE"}
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/math/position.ts"],"names":[],"mappings":"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"}

package/dist/types/services/getQuote.d.ts

@@ -13,7 +13,7 @@ export interface GetQuoteParams {
     /** Buy consumes asks; sell consumes bids. */
     side: QuoteSide;
     /** USD notional to fill. */
-    size: number;
+    size: string;
     /** Product family used to distinguish spot and perpetual markets. */
     type: TradeType;
 }
@@ -33,7 +33,7 @@ export interface GetQuoteParams {
  *   provider: 'hyperliquid',
  *   symbol: 'BTC',
  *   side: 'buy',
- *   size: 10_000,
+ *   size: '10000',
  *   type: 'perps',
  * })
  * console.log(quote.expectedFillPrice, quote.priceImpactBps)

package/dist/types/services/resolveSubscribeQuote.d.ts

@@ -29,7 +29,7 @@ export declare const QUOTE_THROTTLE_MS = 100;
  * price, a throwing `onQuote`) is logged via `wsLog.listenerFailure` and the
  * emission is skipped, on both the immediate and the trailing-timer path.
  *
- * @throws {PerpsError} `ValidationError` when `params.size` is not finite.
+ * @throws {PerpsError} `ValidationError` when `params.size` does not match the decimal pattern.
  * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
  * @internal
  */