@lifi/perps-sdk 20.1.1 → 21.1.0

package/dist/types/types/withdrawal.d.ts

@@ -13,6 +13,12 @@ export interface ProviderWithdrawableBalance {
     route: WithdrawalRoute;
     /** Withdrawable amount in the asset's own units. Always greater than zero. */
     available: DecimalString;
+    /**
+     * Largest `amount` the row can fund: `available` when the fee is deducted
+     * from the amount or absent; `available − withdrawalFee` floored at zero
+     * when the venue charges the fee on top (`isFeeDeducted === false`).
+     */
+    max: DecimalString;
     /**
      * Flat venue fee on a withdrawal from this row, in the asset's own units.
      * Absent when the venue publishes no fee for the asset. The client rejects
@@ -38,6 +44,12 @@ export interface WithdrawableBalance {
     route: WithdrawalRoute;
     /** Withdrawable amount in the asset's own units. */
     available: DecimalString;
+    /**
+     * Largest `amount` the row can fund: `available` when the fee is deducted
+     * from the amount or absent; `available − withdrawalFee` floored at zero
+     * when the venue charges the fee on top (`isFeeDeducted === false`).
+     */
+    max: DecimalString;
     /**
      * Flat venue fee on a withdrawal from this row, in the asset's own units.
      * Absent when the venue publishes no fee for the asset. With

package/dist/types/types/withdrawal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../../../src/types/withdrawal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,KAAK,EACL,aAAa,EACb,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,eAAe,CAAA;IACtB,8EAA8E;IAC9E,SAAS,EAAE,aAAa,CAAA;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAA;IACZ,KAAK,EAAE,eAAe,CAAA;IACtB,oDAAoD;IACpD,SAAS,EAAE,aAAa,CAAA;IACxB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,eAAe,CAAA;IACrB,qEAAqE;IACrE,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,yBAAyB,CAAA"}
+{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../../../src/types/withdrawal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,KAAK,EACL,aAAa,EACb,eAAe,EAChB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,eAAe,CAAA;IACtB,8EAA8E;IAC9E,SAAS,EAAE,aAAa,CAAA;IACxB;;;;OAIG;IACH,GAAG,EAAE,aAAa,CAAA;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAA;IACZ,KAAK,EAAE,eAAe,CAAA;IACtB,oDAAoD;IACpD,SAAS,EAAE,aAAa,CAAA;IACxB;;;;OAIG;IACH,GAAG,EAAE,aAAa,CAAA;IAClB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,eAAe,CAAA;IACrB,qEAAqE;IACrE,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,yBAAyB,CAAA"}

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

@@ -1,11 +1,5 @@
 import type { Order, RegularOrder, TriggerOrder, TwapOrder } from '@lifi/perps-types';
-import { FillClassification, OrderSide, OrderStatus, TriggerCondition } from '@lifi/perps-types';
-/**
- * Re-exported fill taxonomy used by {@link classifyFillFromPosition}.
- *
- * @public
- */
-export { FillClassification };
+import { OrderSide, OrderStatus, TriggerCondition } from '@lifi/perps-types';
 /**
  * Check if an open order is a Take Profit trigger order.
  * @public
@@ -37,11 +31,4 @@ export declare const ACTIVE_ORDER_STATUSES: ReadonlySet<OrderStatus>;
  * @public
  */
 export declare function isActiveOrderStatus(status: OrderStatus): 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.
- * @public
- */
-export declare function classifyFill(side: OrderSide, realizedPnl: string | null | undefined): FillClassification;
 //# sourceMappingURL=orderClassification.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"orderClassification.d.ts","sourceRoot":"","sources":["../../../src/utils/orderClassification.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,WAAW,EAEX,gBAAgB,EACjB,MAAM,mBAAmB,CAAA;AAG1B;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAY7B;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAErE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAEnE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAE/D;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,YAAY,CAElE;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,YAAY,CAElE;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,SAAS,CAE5D;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,SAAS,GACd,gBAAgB,CAKlB;AAED,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,WAAW,CAMzD,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,kBAAkB,CAUpB"}
+{"version":3,"file":"orderClassification.d.ts","sourceRoot":"","sources":["../../../src/utils/orderClassification.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,SAAS,EACT,WAAW,EAEX,gBAAgB,EACjB,MAAM,mBAAmB,CAAA;AAY1B;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAErE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAEnE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAE/D;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,YAAY,CAElE;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,YAAY,CAElE;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,SAAS,CAE5D;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,SAAS,GACd,gBAAgB,CAKlB;AAED,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,WAAW,CAMzD,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEhE"}

package/dist/types/version.d.ts

@@ -9,5 +9,5 @@ export declare const name = "@lifi/perps-sdk";
  *
  * @public
  */
-export declare const version = "20.1.1";
+export declare const version = "21.1.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/types/wire/orderAmounts.d.ts

@@ -0,0 +1,55 @@
+import { type DecimalString, type Market } from '@lifi/perps-types';
+import type { PerpsSDKClient } from '../types/provider.js';
+/** @public */
+export interface OrderAmountsInput {
+    sdk: PerpsSDKClient;
+    market: Market;
+    /** The field the user typed; the other two are calculated from it. */
+    held: 'margin' | 'size' | 'notional';
+    amount: DecimalString;
+    leverage: number;
+    price: DecimalString;
+    /** Decimals for the quote-asset amounts (margin, notional). Default 2. */
+    quoteDecimals?: number;
+}
+/** @public */
+export interface OrderAmounts {
+    /**
+     * On the `quoteDecimals` grid: rounded up when derived, so it funds `size`
+     * at the requested leverage, and truncated when the user holds it.
+     */
+    margin: DecimalString;
+    /** Snapped onto the venue lot grid. */
+    size: DecimalString;
+    /** Truncated to `quoteDecimals`. */
+    notional: DecimalString;
+}
+/**
+ * The three order-entry amounts, derived from whichever one the user typed.
+ *
+ * The held field is normalised first — truncated to `quoteDecimals` for a
+ * margin or notional, snapped onto the venue lot grid for a size — and the
+ * other two are then derived from that normalised value, so the three agree
+ * with each other rather than with an input the user cannot see.
+ *
+ * Rounding is directional, so the result always funds itself:
+ * `size × price ≤ margin × leverage`. A derived size truncates onto the lot
+ * grid and a derived notional truncates onto the quote grid, but a derived
+ * margin rounds **up** onto the quote grid, because it is the one amount that
+ * has to cover the others rather than cap them.
+ *
+ * Formulas: `size = margin × leverage ÷ price`,
+ * `margin = size × price ÷ leverage`, `notional = size × price`
+ * (or `margin × leverage` when the margin is held).
+ *
+ * @returns `null` when `amount` or `price` is not a positive decimal string,
+ *   when `leverage` is not a positive finite number, or when the venue and
+ *   quote grids snap the result to a non-positive amount — a sub-lot size or
+ *   a sub-cent quote amount describes no order a venue can take.
+ * @throws {PerpsError} `ValidationError` when `quoteDecimals` is not a
+ *   non-negative integer, or `SDKError` when `market.providerId` names no
+ *   registered provider plugin.
+ * @public
+ */
+export declare function calculateOrderAmounts(input: OrderAmountsInput): OrderAmounts | null;
+//# sourceMappingURL=orderAmounts.d.ts.map

package/dist/types/wire/orderAmounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderAmounts.d.ts","sourceRoot":"","sources":["../../../src/wire/orderAmounts.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,MAAM,EAEZ,MAAM,mBAAmB,CAAA;AAI1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1D,cAAc;AACd,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;IACpC,MAAM,EAAE,aAAa,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,aAAa,CAAA;IACpB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,cAAc;AACd,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,aAAa,CAAA;IACrB,uCAAuC;IACvC,IAAI,EAAE,aAAa,CAAA;IACnB,oCAAoC;IACpC,QAAQ,EAAE,aAAa,CAAA;CACxB;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,GACvB,YAAY,GAAG,IAAI,CAqDrB"}

package/dist/types/wire/refuel.d.ts

@@ -0,0 +1,28 @@
+import { type DecimalString } from '@lifi/perps-types';
+/** @public */
+export interface RefuelAmountInput {
+    /** USD value of the gas the route recommends. */
+    gasUsd: DecimalString;
+    /** USD price of one whole source token. */
+    priceUsd: DecimalString;
+    /** Decimals of the source token, which the result is spelled to exactly. */
+    decimals: number;
+}
+/**
+ * Source-token amount whose USD value covers `gasUsd`, rounded **up** onto
+ * the token's decimal grid so a refuel never lands short of the
+ * recommendation. The result keeps trailing zeros to `decimals`, so it seeds
+ * an amount input at the token's own precision.
+ *
+ * The quotient does not terminate for most prices, which is why this is a
+ * big.js primitive: an 18-decimal token needs a ceiling at 10^-18, far past
+ * what a `number` can carry.
+ *
+ * @returns `undefined` when `gasUsd` or `priceUsd` is not greater than zero,
+ *   which is a route with nothing to refuel rather than a failure.
+ * @throws {PerpsError} `ValidationError` when `gasUsd` or `priceUsd` is not a
+ *   {@link DecimalString}, or when `decimals` is not a non-negative integer.
+ * @public
+ */
+export declare function calculateRefuelAmount(input: RefuelAmountInput): DecimalString | undefined;
+//# sourceMappingURL=refuel.d.ts.map

package/dist/types/wire/refuel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refuel.d.ts","sourceRoot":"","sources":["../../../src/wire/refuel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,mBAAmB,CAAA;AAKtE,cAAc;AACd,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,MAAM,EAAE,aAAa,CAAA;IACrB,2CAA2C;IAC3C,QAAQ,EAAE,aAAa,CAAA;IACvB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,GACvB,aAAa,GAAG,SAAS,CAiB3B"}

package/dist/types/wire/requireDecimal.d.ts

@@ -0,0 +1,11 @@
+import { type DecimalString } from '@lifi/perps-types';
+import Big from 'big.js';
+/**
+ * Parse a wire-tier decimal input, naming the field it came from when the
+ * value breaks the {@link DecimalString} contract, so a malformed amount
+ * fails at the SDK boundary instead of inside big.js.
+ *
+ * @throws {PerpsError} `ValidationError` naming `field`.
+ */
+export declare function requireDecimal(value: DecimalString, field: string): Big;
+//# sourceMappingURL=requireDecimal.d.ts.map

package/dist/types/wire/requireDecimal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/wire/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,GAAG,MAAM,QAAQ,CAAA;AAGxB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAQvE"}

package/dist/types/wire/snap.d.ts

@@ -0,0 +1,24 @@
+import type { DecimalString, Market } from '@lifi/perps-types';
+import type { PerpsSDKClient } from '../types/provider.js';
+/**
+ * Snap `size` onto the lot grid of `market`'s venue, truncating toward zero,
+ * through the market's own provider. Takes and gives a {@link DecimalString},
+ * so a caller never converts an order size to a `number`.
+ *
+ * @throws {PerpsError} `SDKError` when `market.providerId` names no registered
+ *   provider plugin.
+ * @public
+ */
+export declare function snapOrderSize(sdk: PerpsSDKClient, market: Market, size: DecimalString): DecimalString;
+/**
+ * Snap `price` onto the tick grid of `market`'s venue, rounding half-up,
+ * through the market's own provider. Takes and gives a {@link DecimalString},
+ * so a caller never converts an order price to a `number`.
+ *
+ * @throws {PerpsError} `SDKError` when `market.providerId` names no registered
+ *   provider plugin, or `ValidationError` when the market lacks the tick
+ *   metadata the venue's rules need.
+ * @public
+ */
+export declare function snapOrderPrice(sdk: PerpsSDKClient, market: Market, price: DecimalString): DecimalString;
+//# sourceMappingURL=snap.d.ts.map

package/dist/types/wire/snap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snap.d.ts","sourceRoot":"","sources":["../../../src/wire/snap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAClB,aAAa,CAEf;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,GACnB,aAAa,CAEf"}

package/dist/types/wire/transferable.d.ts

@@ -0,0 +1,15 @@
+import type { DecimalString } from '@lifi/perps-types';
+/**
+ * The part of `units` that a venue-wide free figure releases: never below
+ * zero, never above the units held. `Balance.transferable` on every provider
+ * is this clamp over the venue's own free-margin or unlocked-balance figure.
+ *
+ * @param venueFigure - The venue's free figure for the category, which can
+ *   exceed `units` or fall below zero.
+ * @param units - Units held in the category, the upper bound of the clamp.
+ * @throws {PerpsError} `ValidationError` when either input is not a
+ *   {@link DecimalString}, naming the field.
+ * @public
+ */
+export declare function calculateTransferable(venueFigure: DecimalString, units: DecimalString): DecimalString;
+//# sourceMappingURL=transferable.d.ts.map

package/dist/types/wire/transferable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferable.d.ts","sourceRoot":"","sources":["../../../src/wire/transferable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,aAAa,EAC1B,KAAK,EAAE,aAAa,GACnB,aAAa,CAOf"}

package/dist/types/wire/withdraw.d.ts

@@ -0,0 +1,14 @@
+import type { DecimalString } from '@lifi/perps-types';
+import type { WithdrawableBalance } from '../types/withdrawal.js';
+/**
+ * Largest `amount` a withdrawable row can fund: `available` when the venue
+ * deducts the fee from the amount or publishes no fee, and
+ * `available − withdrawalFee` floored at zero when the venue charges the fee
+ * on top (`isFeeDeducted === false`).
+ *
+ * @throws {PerpsError} `ValidationError` when `available` or `withdrawalFee`
+ *   is not a {@link DecimalString}, naming the field.
+ * @public
+ */
+export declare function calculateWithdrawMax(row: Pick<WithdrawableBalance, 'available' | 'withdrawalFee' | 'isFeeDeducted'>): DecimalString;
+//# sourceMappingURL=withdraw.d.ts.map

package/dist/types/wire/withdraw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withdraw.d.ts","sourceRoot":"","sources":["../../../src/wire/withdraw.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAGjE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,IAAI,CACP,mBAAmB,EACnB,WAAW,GAAG,eAAe,GAAG,eAAe,CAChD,GACA,aAAa,CASf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "20.1.1",
+  "version": "21.1.0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -46,7 +46,7 @@
     "big.js": "^7.0.1",
     "partysocket": "^1.1.19",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^18.1.0"
+    "@lifi/perps-types": "^19.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/PerpsClient.ts

@@ -360,7 +360,14 @@ export class PerpsClient {
     return resolveProvider(this.sdkClient, provider)
   }
 
-  /** Read active or historical orders from the selected venue. */
+  /**
+   * Read active or historical orders from the selected venue.
+   *
+   * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+   *   Lighter auth token or an Ondo session) and none is stored.
+   * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+   * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
+   */
   async getOrders(
     params: GetOrdersParams,
     options?: SDKRequestOptions
@@ -368,7 +375,14 @@ export class PerpsClient {
     return fetchOrders(this.sdkClient, params, options)
   }
 
-  /** Read one venue order through the provider's unified mapper. */
+  /**
+   * Read one venue order through the provider's unified mapper.
+   *
+   * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+   *   Lighter auth token or an Ondo session) and none is stored.
+   * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+   * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
+   */
   async getOrder(
     params: GetOrderParams,
     options?: SDKRequestOptions
@@ -654,6 +668,9 @@ export class PerpsClient {
    * @throws {PerpsError} When the provider plugin is not registered,
    *   `ValidationError` for a spot market, or any other `PerpsError` when the
    *   venue read fails or carries no usable value.
+   * @throws {PerpsError} `SetupRequired` when the venue needs a credential (an
+   *   Ondo session) and none is stored.
+   * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
    * @public
    */
   async getMarketSettings(params: {
@@ -674,12 +691,19 @@ export class PerpsClient {
    * account displays read the account-scoped
    * {@link AccountSummary.availableMargin} instead.
    *
-   * Providers that read a per-market figure answer it directly. For every
-   * other provider this falls back to the account summary, so both sides
-   * equal `availableMargin` and the asset is the market's quote asset.
+   * Providers that read a per-market figure answer it directly. A provider
+   * that has no per-market figure for the market (a Hyperliquid or Lighter
+   * spot market) resolves `undefined`, and this falls back to the account
+   * summary, so both sides equal `availableMargin` and the asset is the
+   * market's quote asset. A provider read that throws propagates and never
+   * falls back.
    *
    * @throws {PerpsError} When the provider plugin is not registered, or the
    *   market is unknown to the provider's market registry.
+   * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+   *   Lighter auth token or an Ondo session) and none is stored.
+   * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+   * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
    * @public
    */
   async getAvailableToTrade(
@@ -813,6 +837,10 @@ export class PerpsClient {
    * @throws {PerpsError} When the provider plugin is not registered, when
    *   either the plugin read or the asset sync fails, when a row's
    *   `withdrawalFee` is not a non-negative decimal.
+   * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+   *   Lighter auth token or an Ondo session) and none is stored.
+   * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+   * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
    * @public
    */
   async getWithdrawableBalances(
@@ -849,7 +877,9 @@ export class PerpsClient {
         }
       }
       if (row.withdrawalFee === undefined) {
-        return [{ asset, route: row.route, available: row.available }]
+        return [
+          { asset, route: row.route, available: row.available, max: row.max },
+        ]
       }
       if (!isNonNegativeDecimal(row.withdrawalFee)) {
         throw new PerpsError(
@@ -862,6 +892,7 @@ export class PerpsClient {
           asset,
           route: row.route,
           available: row.available,
+          max: row.max,
           withdrawalFee: row.withdrawalFee,
           ...(row.isFeeDeducted === undefined
             ? {}
@@ -877,6 +908,10 @@ export class PerpsClient {
    *
    * @throws {PerpsError} When the provider plugin is not registered, when it
    *   declares no portfolio history read, or when the venue read fails.
+   * @throws {PerpsError} `SetupRequired` when the venue needs a credential (a
+   *   Lighter auth token or an Ondo session) and none is stored.
+   * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
+   * @throws {PerpsError} `AccountNotFound` when the wallet has no venue account.
    * @public
    */
   async getPortfolioHistory(

package/src/decimal/convert.ts

@@ -0,0 +1,164 @@
+import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+import { formatUnits } from 'viem'
+import { PerpsError } from '../errors/PerpsError.js'
+import { parseDecimal } from './parse.js'
+
+/**
+ * Off-grid resolution for {@link decimalToBaseUnits}:
+ * - `truncate` — toward zero, for sizes and collateral amounts. The wire
+ *   value never exceeds the caller's intent.
+ * - `round` — half away from zero, for prices, which snap to the nearest
+ *   tick.
+ * @public
+ */
+export type BaseUnitsRounding = 'truncate' | 'round'
+
+/**
+ * @deprecated Use `BaseUnitsRounding`. Removed in the next major.
+ */
+export type ScaleToIntegerPolicy = BaseUnitsRounding
+
+/**
+ * Scale a decimal string to a scaled integer in exact decimal arithmetic — an
+ * on-grid input maps to its exact scaled integer with no binary float
+ * artifacts (`'0.29'` at 2 decimals is 29, never 28). Off-grid input resolves
+ * per `rounding`; there is no silent default.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is not a decimal
+ *   numeric string, `decimals` is not a non-negative integer, or the scaled
+ *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export const decimalToBaseUnits = (
+  value: DecimalString,
+  decimals: number,
+  rounding: BaseUnitsRounding
+): number => {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimals for integer scaling: ${decimals}`
+    )
+  }
+  let parsed: Big
+  try {
+    parsed = new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string for integer scaling: '${value}'`
+    )
+  }
+  const scaled = parsed
+    .times(new Big(10).pow(decimals))
+    .round(0, rounding === 'truncate' ? Big.roundDown : Big.roundHalfUp)
+  if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Scaled value ${scaled.toFixed()} exceeds Number.MAX_SAFE_INTEGER and cannot be encoded exactly.`
+    )
+  }
+  return scaled.toNumber()
+}
+
+/**
+ * @deprecated Use `decimalToBaseUnits`. Removed in the next major.
+ */
+export const scaleToInteger = decimalToBaseUnits
+
+/**
+ * Convert a base-unit amount (bigint string) to a decimal string.
+ *
+ * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
+ * @param decimals - Token decimals (e.g. 6 for USDC)
+ * @returns Decimal string; `"0"` when `amount` is not a valid bigint
+ * @example
+ * ```ts
+ * baseUnitsToDecimal('1000000', 6) // '1'
+ * ```
+ * @public
+ */
+export function baseUnitsToDecimal(
+  amount: string,
+  decimals: number
+): DecimalString {
+  try {
+    return formatUnits(BigInt(amount), decimals)
+  } catch {
+    return '0'
+  }
+}
+
+/**
+ * @deprecated Use `baseUnitsToDecimal`. Removed in the next major.
+ */
+export const fromBaseUnits = baseUnitsToDecimal
+
+/**
+ * @deprecated Compose `parseDecimal(baseUnitsToDecimal(...))`. Removed in the
+ * next major.
+ */
+export function fromBaseUnitsNumber(amount: string, decimals: number): number {
+  return parseDecimal(baseUnitsToDecimal(amount, decimals)) ?? 0
+}
+
+/**
+ * Round `value` down to `decimals` and pad the result to exactly that many
+ * decimal places. The padding is the point: this seeds a fixed-decimal input,
+ * where `'500.00'` and `'500'` are two renderings of one amount and the field
+ * wants the first. For a canonical wire amount with no trailing zeros, read
+ * the amount off `calculateOrderAmounts` or a provider snap instead.
+ *
+ * Exact decimal arithmetic throughout, so there is no 2^53 ceiling and no
+ * float artifact: `'0.01'` at 18 decimals gives
+ * `'0.010000000000000000'`, which `Number#toFixed` cannot.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is not a decimal
+ *   numeric string, or `decimals` is not a non-negative integer.
+ * @public
+ */
+export function truncateDecimal(
+  value: DecimalString,
+  decimals: number
+): DecimalString {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimals for truncation: ${decimals}`
+    )
+  }
+  let parsed: Big
+  try {
+    parsed = new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string for truncation: '${value}'`
+    )
+  }
+  const truncated = parsed.round(decimals, Big.roundDown)
+  // big.js carries the sign through a round to zero; '-0.00' is not a spelling.
+  return (truncated.eq(0) ? new Big(0) : truncated).toFixed(decimals)
+}
+
+/**
+ * Spell a `number` as a {@link DecimalString} in plain notation: `1e-7`
+ * becomes `'0.0000001'`, never `'1e-7'`. The boundary helper for a venue or
+ * browser API that hands out numbers; a value already spelled as a decimal
+ * string must not round-trip through here, because above 15 significant
+ * digits the `number` has already lost digits.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is `NaN` or infinite.
+ * @public
+ */
+export function numberToDecimalString(value: number): DecimalString {
+  if (!Number.isFinite(value)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid number for decimal conversion: ${value}`
+    )
+  }
+  const parsed = new Big(value)
+  return (parsed.eq(0) ? new Big(0) : parsed).toFixed()
+}

package/src/{utils → decimal}/parse.ts

@@ -1,3 +1,5 @@
+import type { DecimalString } from '@lifi/perps-types'
+
 /**
  * Parse a string to a float, stripping common formatting artefacts.
  *
@@ -10,14 +12,8 @@
  *
  * @returns Parsed number; `0` for empty/blank input, `NaN` when a non-empty
  *   string contains no parseable number
- * @example
- * ```ts
- * stringToFloat('$1,234.50') // 1234.5
- * stringToFloat('') // 0
- * ```
- * @public
  */
-export function stringToFloat(value: string): number {
+function toFloat(value: string): number {
   if (!value) {
     return 0
   }
@@ -28,27 +24,33 @@ export function stringToFloat(value: string): number {
   return parseFloat(cleaned)
 }
 
+/**
+ * @deprecated Use `parseDecimal`. Removed in the next major.
+ */
+export const stringToFloat = toFloat
+
 const FORMATTED_NUMBER =
   /^(?:[+-]\s*)?(?:\$\s*)?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?(?:\s*(?:%|USD))?$/i
 
 /**
- * Parse an optional decimal field, with the same formatting tolerance as {@link stringToFloat}.
+ * Parse an optional decimal field, tolerating currency symbols, grouping
+ * separators and a percentage suffix around the number.
  * Gives back `undefined` for a missing, malformed or non-finite value, and `0` for an empty string.
  *
  * @public
  */
 export function parseDecimal(
-  value: string | null | undefined
+  value: DecimalString | string | null | undefined
 ): number | undefined {
   if (value == null) {
     return undefined
   }
   if (value.trim() === '') {
-    return stringToFloat(value)
+    return toFloat(value)
   }
   if (!FORMATTED_NUMBER.test(value.trim())) {
     return undefined
   }
-  const parsed = stringToFloat(value)
+  const parsed = toFloat(value)
   return Number.isFinite(parsed) ? parsed : undefined
 }