@lifi/perps-sdk-provider-lighter 33.0.0 → 35.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"settlementPool.d.ts","sourceRoot":"","sources":["../../../src/utils/settlementPool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,QAAQ,CAAA;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGzD,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,GAAI,OAAO,cAAc,KAAG,GAG3D,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO,cAAc,EACrB,kBAAkB,GAAG,KACpB,GAKF,CAAA;AAED,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,cAAc,EAAE,EACjC,sBAAsB,MAAM,KAC3B,MAKF,CAAA"}

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

@@ -1,4 +1,4 @@
-import { type Position } from '@lifi/perps-types';
+import { type DecimalString, type Position } from '@lifi/perps-types';
 /**
  * Lighter removable isolated margin:
  * `allocated_margin + unrealized PnL − initial margin requirement`. Lighter
@@ -13,5 +13,5 @@ import { type Position } from '@lifi/perps-types';
  * @see https://docs.lighter.xyz/trading/liquidations-and-llp-insurance-fund
  * @public
  */
-export declare function positionRemovableMargin(position: Position): string | undefined;
+export declare function positionRemovableMargin(position: Position): DecimalString | undefined;
 //# sourceMappingURL=transferMargin.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,mBAAmB,CAAA;AA2B1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,SAAS,CAmBpB"}
+{"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAA;AA2B1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,GACjB,aAAa,GAAG,SAAS,CAmB3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "33.0.0",
+  "version": "35.0.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -44,10 +44,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^19.0.0"
+    "@lifi/perps-types": "^20.1.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^21.1.0"
+    "@lifi/perps-sdk": "^23.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -9,7 +9,9 @@ import {
   getMarketsContext,
   getProviders,
   isActiveOrderStatus,
+  isDecimalString,
   localStorageAdapter,
+  numberToDecimalString,
   PerpsError,
   type PerpsProviderPlugin,
   type PerpsSDKClient,
@@ -65,7 +67,6 @@ import type {
 import {
   ActionType,
   ActivityType,
-  isDecimalString,
   MarginMode,
   PerpsErrorCode,
 } from '@lifi/perps-types'
@@ -124,6 +125,7 @@ import type {
 } from './types/index.js'
 import {
   LT_ACCOUNT_TRADING_MODE_SIMPLE,
+  LT_ACCOUNT_TRADING_MODE_UNIFIED,
   LT_MARGIN_MODE_CROSS,
   LT_MARGIN_MODE_ISOLATED,
 } from './types/index.js'
@@ -161,6 +163,11 @@ import {
   fetchRegisteredApiKey,
   normalizeLighterPublicKey,
 } from './utils/registeredApiKey.js'
+import {
+  collateralSpotBalance,
+  pooledSettlementSpendable,
+  pooledSettlementUnits,
+} from './utils/settlementPool.js'
 import { spotPriceByAssetId, spotValuation } from './utils/spotPrice.js'
 import { isPlaceholderTxHash } from './utils/txHash.js'
 import { wireList } from './utils/wireList.js'
@@ -168,7 +175,7 @@ import { wireList } from './utils/wireList.js'
 const ZERO_FEE_TIER = { maker: '0', taker: '0' }
 
 const tickToFeeString = (tick: number): string =>
-  String(tick / LIGHTER_FEE_TICK_SCALE)
+  numberToDecimalString(tick / LIGHTER_FEE_TICK_SCALE)
 
 const projectFeeTier = (
   limits: LtAccountLimits
@@ -268,11 +275,9 @@ interface ReadOnlyCreationBackoff {
  * manager are created per plugin instance.
  *
  * Auth-token resolution order for the auth-gated reads:
- *   1. Per-call `options.lighterAuthToken`
- *   2. Constructor `authToken` (string or async factory)
- *   3. Persisted long-lived read-only token, keyed on the resolved Lighter
+ *   1. Persisted long-lived read-only token, keyed on the resolved Lighter
  *      `accountIndex`
- *   4. Fresh 1h create via this instance's WASM signer + the user's registered
+ *   2. Fresh 1h create via this instance's WASM signer + the user's registered
  *      API key
  *
  * Status reads report the account's state and do not throw for a missing
@@ -286,9 +291,9 @@ interface ReadOnlyCreationBackoff {
  *   - `SetupRequired` when none of these sources yields a token. The SDK
  *     sends no venue request. `getOrders`, `getOrder`, `getFills`,
  *     `getPortfolioHistory` and `getActivity` need a token.
- *   - `Unauthorized` when Lighter rejects the token that was sent. An
- *     SDK-owned read-only token that Lighter reports as revoked is replaced
- *     and the read retried once first.
+ *   - `Unauthorized` when Lighter rejects the token that was sent. A
+ *     read-only token that Lighter reports as revoked is replaced and the
+ *     read retried once first.
  *   - `AccountNotFound` when the wallet has no Lighter account. This also
  *     applies to `getPositions`, `getWithdrawableBalances` and
  *     `getAvailableToTrade`, which need no token. `getAvailableToTrade`
@@ -311,8 +316,6 @@ export interface LighterProviderOptions {
    * instance's signer and read-only token manager follow this URL.
    */
   restUrl?: string
-  /** Pre-created Lighter read-only bearer, bypassing SDK token resolution. */
-  authToken?: string | (() => string | Promise<string>)
   /** Token lifetime for on-demand standard-token creates (Lighter caps at 8h). Default 1h. */
   tokenLifetimeSeconds?: number
   /** Re-create when the cached standard token's remaining life is below this. Default 60s. */
@@ -343,8 +346,8 @@ interface CachedStandardToken {
 export interface LighterPerpsProvider extends PerpsProviderPlugin {
   /**
    * Resolve a Lighter auth token for `address`, following the resolution order
-   * documented on {@link LighterProviderOptions} (the per-call override does not
-   * apply here). Returns `undefined` when no source can produce a token.
+   * documented on {@link LighterProviderOptions}. Returns `undefined` when no
+   * source can produce a token.
    */
   resolveAuthToken(address: Address): Promise<string | undefined>
 }
@@ -380,12 +383,6 @@ export const createLighterProvider = (
   const explorerTxBaseUrl = deployment.explorerTxBaseUrl
   const bridgeChainId = deployment.bridgeChainId
   const collateral = deployment.collateral
-  const authTokenSource: (() => string | Promise<string>) | undefined =
-    typeof options.authToken === 'function'
-      ? options.authToken
-      : options.authToken !== undefined
-        ? () => options.authToken as string
-        : undefined
   const storage = options.storage ?? localStorageAdapter
   const signer = new LighterSigner({
     apiUrl: restUrl,
@@ -459,32 +456,20 @@ export const createLighterProvider = (
 
   /**
    * Resolve the bearer token for auth-gated reads. Priority:
-   *   1. Per-call override (`options.lighterAuthToken`).
-   *   2. Constructor-supplied token source.
-   *   3. A stored read-only token — preferred for reads: it is read-only, so
+   *   1. A stored read-only token — preferred for reads: it is read-only, so
    *      forwarding it (incl. to the backend) cannot authorise writes.
-   *   4. A read-only token created on first use (via signer + registered API
+   *   2. A read-only token created on first use (via signer + registered API
    *      key) and persisted for reuse.
-   *   5. A standard auth token (read+write, 8h max) as a last resort — used
+   *   3. A standard auth token (read+write, 8h max) as a last resort — used
    *      as the credential that authorises read-only token creation, and as
    *      the fallback while creation is failing, bounded by the
    *      creation-retry backoff.
    * Returns `undefined` when no source can produce a token.
    */
   const resolveAuthToken = async (
-    opts: SDKRequestOptions | undefined,
-    address?: Address,
+    address: Address,
     knownApiKey?: LighterApiKey
   ): Promise<string | undefined> => {
-    if (opts?.lighterAuthToken !== undefined) {
-      return opts.lighterAuthToken
-    }
-    if (authTokenSource !== undefined) {
-      return authTokenSource()
-    }
-    if (address === undefined) {
-      return undefined
-    }
     const apiKey = knownApiKey ?? (await keyStore.get(address))
     if (apiKey === null) {
       return undefined
@@ -566,17 +551,15 @@ export const createLighterProvider = (
   /** {@link resolveAuthToken}, throwing `SetupRequired` when no source yields a token. */
   const requireAuthToken = async (
     read: string,
-    opts: SDKRequestOptions | undefined,
     address: Address,
     knownApiKey?: LighterApiKey
   ): Promise<string> => {
-    const token = await resolveAuthToken(opts, address, knownApiKey)
+    const token = await resolveAuthToken(address, knownApiKey)
     if (token === undefined) {
       throw new PerpsError(
         PerpsErrorCode.SetupRequired,
-        `Lighter ${read} requires an auth token. Pass \`authToken\` to ` +
-          'lighterProvider, register an API key + signer for on-demand creation, or ' +
-          'forward `options.lighterAuthToken` on the call.'
+        `Lighter ${read} requires an auth token. Register an API key + signer ` +
+          'for on-demand creation.'
       )
     }
     return token
@@ -637,7 +620,6 @@ export const createLighterProvider = (
   }
 
   const retryOnRevoked = async <T>(
-    opts: SDKRequestOptions | undefined,
     address: Address,
     token: string,
     run: (token: string) => Promise<T>
@@ -645,9 +627,7 @@ export const createLighterProvider = (
     try {
       return await run(token)
     } catch (err) {
-      const sdkOwnsToken =
-        opts?.lighterAuthToken === undefined && authTokenSource === undefined
-      if (!(err instanceof LighterTokenRevokedError) || !sdkOwnsToken) {
+      if (!(err instanceof LighterTokenRevokedError)) {
         throw err
       }
       const fresh = await replaceRevokedReadOnlyToken(address, token)
@@ -878,6 +858,20 @@ export const createLighterProvider = (
     return setup.find((descriptor) => descriptor.type === action)
   }
 
+  /**
+   * Refuse a SEND_ASSET for a unified account. Its settlement asset is one pool
+   * across both routes, so a perps↔spot transfer has nothing to move.
+   */
+  const assertSendAssetMode = async (address: Address): Promise<void> => {
+    const account = await fetchDetailedAccount(apiClient(), address)
+    if (account.account_trading_mode === LT_ACCOUNT_TRADING_MODE_UNIFIED) {
+      throw new PerpsError(
+        PerpsErrorCode.PooledCategoryTransfer,
+        'Lighter unified accounts pool the settlement asset across perps and spot; a transfer between them has nothing to move'
+      )
+    }
+  }
+
   /**
    * Refuse an order signature for a tier no ACCOUNT_TYPE option binds. An
    * unreadable descriptor or tier fails open: the venue itself
@@ -907,11 +901,11 @@ export const createLighterProvider = (
     }
     let userTierName: string | undefined
     try {
-      const token = await resolveAuthToken(undefined, address, localKey)
+      const token = await resolveAuthToken(address, localKey)
       const limits =
         token === undefined
           ? undefined
-          : await retryOnRevoked(undefined, address, token, (resolvedToken) =>
+          : await retryOnRevoked(address, token, (resolvedToken) =>
               fetchAccountLimits(
                 apiClient(),
                 localKey.accountIndex,
@@ -950,7 +944,7 @@ export const createLighterProvider = (
     },
 
     resolveAuthToken(address: Address): Promise<string | undefined> {
-      return resolveAuthToken(undefined, address)
+      return resolveAuthToken(address)
     },
 
     async getAccount(
@@ -980,7 +974,7 @@ export const createLighterProvider = (
           normalizeLighterPublicKey(registeredKey.public_key)
       // Status read: a missing or stale credential reports `apiKeyRegistered: false`, not a throw.
       const token = apiKeyRegistered
-        ? await resolveAuthToken(opts, params.address, localKey)
+        ? await resolveAuthToken(params.address, localKey)
         : undefined
 
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -993,7 +987,7 @@ export const createLighterProvider = (
           getMarketsContext(requireClient(), { provider: providerKey }, opts),
           token === undefined
             ? Promise.resolve(undefined)
-            : retryOnRevoked(opts, params.address, token, (resolvedToken) =>
+            : retryOnRevoked(params.address, token, (resolvedToken) =>
                 fetchAccountLimits(client, account.index, resolvedToken)
               ),
           apiKeyRegistered
@@ -1023,12 +1017,21 @@ export const createLighterProvider = (
       )
       // Each asset has a spot route (`balance`) and a perps route
       // (`margin_balance`). The instance's settlement asset is valued 1:1; an
-      // asset no spot market prices keeps a zero USD value.
+      // asset no spot market prices keeps a zero USD value. A unified account
+      // pools both settlement routes into one spot row.
+      const isPooled = (asset: LtAccountAsset): boolean =>
+        account.account_trading_mode === LT_ACCOUNT_TRADING_MODE_UNIFIED &&
+        asset.asset_id === collateral.assetIndex
       const heldAssets = account.assets.filter((asset) =>
-        toRequiredBig(asset.balance, 'balance').gt(0)
+        (isPooled(asset)
+          ? pooledSettlementUnits(asset)
+          : toRequiredBig(asset.balance, 'balance')
+        ).gt(0)
       )
-      const marginAssets = account.assets.filter((asset) =>
-        toRequiredBig(asset.margin_balance, 'margin_balance').gt(0)
+      const marginAssets = account.assets.filter(
+        (asset) =>
+          !isPooled(asset) &&
+          toRequiredBig(asset.margin_balance, 'margin_balance').gt(0)
       )
       const spotPrices = spotPriceByAssetId(
         registry.markets,
@@ -1093,6 +1096,16 @@ export const createLighterProvider = (
         }
       })
       const balances: Balance[] = heldAssets.map((a) => {
+        if (isPooled(a)) {
+          const units = pooledSettlementUnits(a).toFixed()
+          return {
+            ...toBalance(a, LIGHTER_SPOT_CATEGORY_ID, registryAsset(a), units),
+            transferable: calculateTransferable(
+              pooledSettlementSpendable(a, availableBalance).toFixed(),
+              units
+            ),
+          }
+        }
         const balance = toRequiredBig(a.balance, 'balance')
         return {
           ...toBalance(
@@ -1131,6 +1144,10 @@ export const createLighterProvider = (
         crossAssetValue: account.cross_asset_value,
         crossInitialMarginRequirement: account.cross_initial_margin_requirement,
         totalAssetValue: account.total_asset_value,
+        collateralSpotBalance: collateralSpotBalance(
+          account.assets,
+          collateral.assetIndex
+        ),
         userTierName: limitsResult?.user_tier_name,
         accountTradingMode:
           account.account_trading_mode ?? LT_ACCOUNT_TRADING_MODE_SIMPLE,
@@ -1304,7 +1321,7 @@ export const createLighterProvider = (
       if (statuses.size === 0) {
         return empty
       }
-      const token = await requireAuthToken('orders read', opts, params.address)
+      const token = await requireAuthToken('orders read', params.address)
 
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -1326,7 +1343,6 @@ export const createLighterProvider = (
         }
       }
       const [activeResponse, inactiveResponse] = await retryOnRevoked(
-        opts,
         params.address,
         token,
         (t) =>
@@ -1393,7 +1409,7 @@ export const createLighterProvider = (
       params: ProviderGetOrderParams,
       opts?: SDKRequestOptions
     ): Promise<Order> {
-      const token = await requireAuthToken('order lookup', opts, params.address)
+      const token = await requireAuthToken('order lookup', params.address)
 
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -1436,7 +1452,7 @@ export const createLighterProvider = (
               `"${clientOrderIndex}" is not a decimal integer.`
           )
         }
-        const orders = await retryOnRevoked(opts, params.address, token, (t) =>
+        const orders = await retryOnRevoked(params.address, token, (t) =>
           fetchOrdersByClientOrderIndex(
             client,
             t,
@@ -1460,7 +1476,7 @@ export const createLighterProvider = (
       const byOrderIndex = (o: LtOrder): boolean =>
         String(o.order_index) === params.id
 
-      const active = await retryOnRevoked(opts, params.address, token, (t) =>
+      const active = await retryOnRevoked(params.address, token, (t) =>
         fetchActiveOrders(
           client,
           t,
@@ -1473,7 +1489,7 @@ export const createLighterProvider = (
         return detail(activeHit)
       }
 
-      const inactive = await retryOnRevoked(opts, params.address, token, (t) =>
+      const inactive = await retryOnRevoked(params.address, token, (t) =>
         client.getAuthed<LtOrdersResponse>('/api/v1/accountInactiveOrders', t, {
           account_index: account.index,
           market_id: LIGHTER_ALL_MARKETS_WILDCARD,
@@ -1491,7 +1507,7 @@ export const createLighterProvider = (
       params: ProviderGetFillsParams,
       opts?: SDKRequestOptions
     ): Promise<FillsResponse> {
-      const token = await requireAuthToken('fills read', opts, params.address)
+      const token = await requireAuthToken('fills read', params.address)
 
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -1510,12 +1526,8 @@ export const createLighterProvider = (
         queryParams.cursor = params.cursor
       }
 
-      const response = await retryOnRevoked(
-        opts,
-        params.address,
-        token,
-        (tok) =>
-          client.getAuthed<LtTradesResponse>('/api/v1/trades', tok, queryParams)
+      const response = await retryOnRevoked(params.address, token, (tok) =>
+        client.getAuthed<LtTradesResponse>('/api/v1/trades', tok, queryParams)
       )
 
       // `get`, not `require`: a market id the backend list no longer carries
@@ -1545,12 +1557,9 @@ export const createLighterProvider = (
       params: ProviderGetPortfolioHistoryParams,
       opts?: SDKRequestOptions
     ): Promise<PortfolioHistoryResponse> {
-      const sdkOwnsToken =
-        opts?.lighterAuthToken === undefined && authTokenSource === undefined
-      const apiKey = sdkOwnsToken ? await keyStore.get(params.address) : null
+      const apiKey = await keyStore.get(params.address)
       const token = await requireAuthToken(
         'portfolio history read',
-        opts,
         params.address,
         apiKey ?? undefined
       )
@@ -1579,23 +1588,24 @@ export const createLighterProvider = (
       // fallback sits outside `retryOnRevoked`, so a revocation the standard
       // token reports never replaces the read-only one. The key is re-read at
       // retry time because `REGISTER_API_KEY` can rotate it.
-      const response = await retryOnRevoked(
-        opts,
-        params.address,
-        token,
-        read
-      ).catch(async (err: unknown) => {
-        if (!(err instanceof LighterAuthRejectedError) || apiKey === null) {
-          throw err
+      const response = await retryOnRevoked(params.address, token, read).catch(
+        async (err: unknown) => {
+          if (!(err instanceof LighterAuthRejectedError) || apiKey === null) {
+            throw err
+          }
+          const current = (await keyStore.get(params.address)) ?? apiKey
+          return read(
+            await getStandardAuthToken(
+              params.address,
+              current.apiKeyPrivateKey,
+              {
+                apiKeyIndex: current.apiKeyIndex,
+                accountIndex: current.accountIndex,
+              }
+            )
+          )
         }
-        const current = (await keyStore.get(params.address)) ?? apiKey
-        return read(
-          await getStandardAuthToken(params.address, current.apiKeyPrivateKey, {
-            apiKeyIndex: current.apiKeyIndex,
-            accountIndex: current.accountIndex,
-          })
-        )
-      })
+      )
 
       return mapPortfolioHistory(
         params.range,
@@ -1608,11 +1618,7 @@ export const createLighterProvider = (
       params: ProviderGetActivityParams,
       opts?: SDKRequestOptions
     ): Promise<ActivitiesResponse> {
-      const token = await requireAuthToken(
-        'activity read',
-        opts,
-        params.address
-      )
+      const token = await requireAuthToken('activity read', params.address)
 
       const inputCursor = decodeActivityCursor(params.cursor)
       const client = apiClient(opts)
@@ -1622,7 +1628,7 @@ export const createLighterProvider = (
       // Markets identify funding and liquidation rows; assets identify ledger
       // rows. A request for one surface must not pull the other's registry.
       const [history] = await Promise.all([
-        retryOnRevoked(opts, params.address, token, (t) =>
+        retryOnRevoked(params.address, token, (t) =>
           fetchAllHistory(
             client,
             t,
@@ -1874,6 +1880,9 @@ export const createLighterProvider = (
       if (steps.some((step) => ORDER_PLACEMENT_ACTIONS.has(step.action))) {
         await assertOrderTier(address)
       }
+      if (steps.some((step) => step.action === ActionType.SEND_ASSET)) {
+        await assertSendAssetMode(address)
+      }
       return lighterSignActions(
         {
           signer,

package/src/accountSummary.ts

@@ -50,7 +50,8 @@ export const lighterPortfolioValue = (
 
 /**
  * Roll up settlement equity, spot holdings and non-settlement margin holdings.
- * Settlement margin is already included in `totalAssetValue`.
+ * The settlement asset counts as `totalAssetValue` plus its spot-route balance,
+ * so a row that pools both routes is not counted again.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
@@ -61,14 +62,11 @@ export function getAccountSummary(
 ): AccountSummary {
   const config = lighterConfig(account)
   const settlement = LIGHTER_COLLATERAL_ASSETS[config.provider]
-  const holdings = [
-    ...account.balances,
-    ...account.collateralBalances.filter(
-      ({ asset }) =>
-        asset.id !== String(settlement.assetIndex) &&
-        asset.id !== settlement.displaySymbol
-    ),
-  ]
+  const holdings = [...account.balances, ...account.collateralBalances].filter(
+    ({ asset }) =>
+      asset.id !== String(settlement.assetIndex) &&
+      asset.id !== settlement.displaySymbol
+  )
 
   let marginUsed = new Big(0)
   let unrealizedPnl = new Big(0)
@@ -79,7 +77,9 @@ export function getAccountSummary(
 
   return {
     portfolioValue: lighterPortfolioValue(
-      toRequiredBig(config.totalAssetValue, 'totalAssetValue'),
+      toRequiredBig(config.totalAssetValue, 'totalAssetValue').plus(
+        toRequiredBig(config.collateralSpotBalance, 'collateralSpotBalance')
+      ),
       holdings.map((balance) => balance.valueUsd)
     ).toFixed(),
     availableMargin: atLeastZero(

package/src/signers/createAuthToken.ts

@@ -33,8 +33,7 @@ export interface CreateAuthTokenInputs {
  * endpoints (`getOrders`, `getOrder`, `getActivity`, etc.).
  *
  * This utility carries no SDK-wide coupling — pass an explicit `signer` +
- * `apiKey` and consume the returned bearer however the caller likes
- * (per-call `options.lighterAuthToken`, persisted cache, etc.).
+ * `apiKey` and consume the returned bearer however the caller likes.
  * @public
  */
 export async function createAuthToken(

package/src/utils/liquidation.ts

@@ -8,7 +8,7 @@
  */
 
 import {
-  estimateLiquidationPrice as estimateIsolatedLiquidationPrice,
+  estimateLiquidationPrice as estimateLiquidationPriceAtRate,
   type LiquidationEstimateParams,
 } from '@lifi/perps-sdk'
 import type { PerpsMarket } from '@lifi/perps-types'
@@ -30,7 +30,7 @@ export function estimateLiquidationPrice(
   if (market.maintenanceMarginRate === undefined) {
     return undefined
   }
-  return estimateIsolatedLiquidationPrice({
+  return estimateLiquidationPriceAtRate({
     entryPrice: params.entryPrice,
     leverage: params.leverage,
     isLong: params.isLong,

package/src/utils/mapFill.ts

@@ -76,7 +76,7 @@ const deriveRealizedPnl = (
   const pnl = isLong
     ? price.minus(avgEntry).times(closedSize)
     : avgEntry.minus(price).times(closedSize)
-  return pnl.eq(0) ? null : pnl.toString()
+  return pnl.eq(0) ? null : pnl.toFixed()
 }
 
 /**

package/src/utils/mapOrder.ts

@@ -118,7 +118,7 @@ export const mapOrder = (order: LtOrder, market: MarketDisplay): Order => {
       ? {
           averagePrice: new Big(order.filled_quote_amount)
             .div(filledSize)
-            .toString(),
+            .toFixed(),
         }
       : {}),
     reduceOnly: order.reduce_only,

package/src/utils/settlementPool.ts

@@ -0,0 +1,36 @@
+import type Big from 'big.js'
+import type { LtAccountAsset } from '../types/account.js'
+import { toRequiredBig } from './decimal.js'
+
+/** Both routes of a unified account's settlement asset, as one holding. */
+export const pooledSettlementUnits = (asset: LtAccountAsset): Big =>
+  toRequiredBig(asset.balance, 'balance').plus(
+    toRequiredBig(asset.margin_balance, 'margin_balance')
+  )
+
+/**
+ * Spot units a unified account can spend from its settlement pool: the free
+ * spot route plus the margin route up to the account's `available_balance`.
+ * This is `computeSpotAvailableToTradeMarket` in Lighter's `lighter-ts` for an
+ * asset priced 1:1 with a `loan_to_value` of 1. The result can be negative.
+ */
+export const pooledSettlementSpendable = (
+  asset: LtAccountAsset,
+  availableBalance: Big
+): Big => {
+  const marginBalance = toRequiredBig(asset.margin_balance, 'margin_balance')
+  return toRequiredBig(asset.balance, 'balance')
+    .minus(toRequiredBig(asset.locked_balance, 'locked_balance'))
+    .plus(marginBalance.lt(availableBalance) ? marginBalance : availableBalance)
+}
+
+/** Spot-route `balance` of the collateral asset; `'0'` when the account holds none. */
+export const collateralSpotBalance = (
+  assets: readonly LtAccountAsset[],
+  settlementAssetIndex: number
+): string => {
+  const asset = assets.find((a) => a.asset_id === settlementAssetIndex)
+  return asset === undefined
+    ? '0'
+    : toRequiredBig(asset.balance, 'balance').toFixed()
+}

package/src/utils/transferMargin.ts

@@ -1,9 +1,12 @@
-import { PerpsError } from '@lifi/perps-sdk'
 import {
-  PerpsErrorCode,
-  type Position,
+  PerpsError,
   positionSupportsMarginAdjustment,
   positionSupportsMarginRemoval,
+} from '@lifi/perps-sdk'
+import {
+  type DecimalString,
+  PerpsErrorCode,
+  type Position,
 } from '@lifi/perps-types'
 import Big from 'big.js'
 
@@ -47,7 +50,7 @@ function positivePositionAmount(value: string, field: string): Big {
  */
 export function positionRemovableMargin(
   position: Position
-): string | undefined {
+): DecimalString | undefined {
   if (!positionSupportsMarginAdjustment(position)) {
     return undefined
   }