@lifi/perps-sdk 0.0.0-preview-697b8c5 → 0.0.0-preview-1edeff0

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

@@ -0,0 +1,46 @@
+import type { DeclaredDepositAsset } from '../types/deposit.js';
+/**
+ * USDC on Ethereum mainnet — the collateral leg of Lighter's first-deposit
+ * pipeline, and the token Ondo's provisioned deposit address is funded in.
+ *
+ * @public
+ */
+export declare const ETHEREUM_USDC: DeclaredDepositAsset;
+/**
+ * Ether on Ethereum mainnet, to broadcast the first-deposit pipeline's legs
+ * with.
+ *
+ * @public
+ */
+export declare const ETHEREUM_NATIVE_GAS: DeclaredDepositAsset;
+/**
+ * USDC on the Hyperliquid venue chain: the 6-decimal perps contract. The same
+ * chain also lists an 8-decimal spot `USDC` at
+ * `0x6d1e7cde53bA9467B783Cb7c530CE05400000000`, so a deposit destination
+ * resolved by symbol lands on the wrong token and the wrong scale.
+ *
+ * @public
+ */
+export declare const HYPERLIQUID_USDC: DeclaredDepositAsset;
+/**
+ * USDC on the Lighter venue chain. The venue chain reuses the mainnet USDC
+ * address, so `chainId` is what distinguishes it from {@link ETHEREUM_USDC}.
+ *
+ * @public
+ */
+export declare const LIGHTER_USDC: DeclaredDepositAsset;
+/**
+ * USDG on Robinhood Chain — the collateral the Lighter Robinhood instance is
+ * funded in.
+ *
+ * @public
+ */
+export declare const ROBINHOOD_USDG: DeclaredDepositAsset;
+/**
+ * Ether on Robinhood Chain, to broadcast the Robinhood first-deposit pipeline's
+ * legs with.
+ *
+ * @public
+ */
+export declare const ROBINHOOD_NATIVE_GAS: DeclaredDepositAsset;
+//# sourceMappingURL=depositAssets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"depositAssets.d.ts","sourceRoot":"","sources":["../../../src/utils/depositAssets.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,oBAI3B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,oBAIjC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,oBAI9B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,oBAI1B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,oBAI5B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,oBAIlC,CAAA"}

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

@@ -0,0 +1,22 @@
+/**
+ * Off-grid resolution for {@link scaleToInteger}:
+ * - `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 ScaleToIntegerPolicy = 'truncate' | 'round';
+/**
+ * Scale a human-readable 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 `policy`; 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 declare const scaleToInteger: (value: string, decimals: number, policy: ScaleToIntegerPolicy) => number;
+//# sourceMappingURL=scaleToInteger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaleToInteger.d.ts","sourceRoot":"","sources":["../../../src/utils/scaleToInteger.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,EACb,UAAU,MAAM,EAChB,QAAQ,oBAAoB,KAC3B,MA0BF,CAAA"}

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

@@ -0,0 +1,17 @@
+import type { ProviderAction } from '@lifi/perps-types';
+/**
+ * Select the `Provider.setup` descriptors a user is responsible for satisfying:
+ * those whose `signers` include {@link PerpsSigner.USER}. Descriptors the SDK
+ * signs on its own (no `USER` signer) are held back — `checkSetup` completes
+ * them inline, so surfacing them would render inert cards the user can't act on.
+ *
+ * Membership is a property of the descriptor's `signers` alone, independent of
+ * any account: use this to build the onboarding list, then layer each entry's
+ * satisfied/unsatisfied state on top from a live `checkSetup` so the tick never
+ * goes stale.
+ *
+ * @param setup The provider's `setup` descriptors, in their declared order.
+ * @public
+ */
+export declare function selectUserSetupActions(setup: ProviderAction[]): ProviderAction[];
+//# sourceMappingURL=setupActions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setupActions.d.ts","sourceRoot":"","sources":["../../../src/utils/setupActions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,GACtB,cAAc,EAAE,CAIlB"}

package/dist/types/version.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "@lifi/perps-sdk";
-export declare const version = "0.0.0-preview-697b8c5";
+export declare const version = "0.0.0-preview-1edeff0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "0.0.0-preview-697b8c5",
+  "version": "0.0.0-preview-1edeff0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -41,10 +41,11 @@
     "!tsconfig.json"
   ],
   "dependencies": {
-    "@lifi/types": "17.82.1",
+    "@lifi/types": "17.86.0",
+    "big.js": "^7.0.1",
     "partysocket": "^1.1.19",
     "viem": "^2.48.8",
-    "@lifi/perps-types": "^0.0.0-preview-697b8c5"
+    "@lifi/perps-types": "^0.0.0-preview-1edeff0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/PerpsClient.ts

@@ -30,6 +30,7 @@ import type {
   ExecuteProviderSetupParams,
   ExecuteProviderSetupResult,
   GetAccountResult,
+  GetDepositFlowParams,
   GetSetupParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -40,6 +41,7 @@ import type {
   WithdrawParams,
 } from '../types/api.js'
 import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
+import type { DepositFlow } from '../types/deposit.js'
 import type {
   ActionSignerContribution,
   PerpsProvider,
@@ -412,6 +414,23 @@ export class PerpsClient {
     return this.requireProvider(provider).accountExists({ address })
   }
 
+  /**
+   * The deposit flow for `params.address` at `params.provider`, delegated to the
+   * provider plugin — every deposit decision (the collateral destination, the
+   * account-opening pipeline, an outstanding setup gate) is venue-owned.
+   *
+   * @returns `undefined` when the registered plugin declares no deposit flow.
+   * @throws {PerpsError} When the provider plugin is not registered, or the
+   *   plugin's flow resolution fails.
+   * @public
+   */
+  async getDepositFlow(
+    params: GetDepositFlowParams
+  ): Promise<DepositFlow | undefined> {
+    const plugin = this.requireProvider(params.provider)
+    return plugin.getDepositFlow?.({ address: params.address })
+  }
+
   /**
    * Return the unsatisfied entries on `Provider.setup` for this account as a
    * flat, self-describing list. Trading is gated on `isReady === true`.

package/src/index.ts

@@ -3,7 +3,7 @@
 
 /**
  * `@lifi/perps-sdk` — the public entry point. Exports `createPerpsClient` and
- * `PerpsClient` (the primary API), the realtime `PerpsWsClient`, the pure
+ * `PerpsClient` (the primary API), the WebSocket `PerpsWsClient`, the pure
  * calculation/parsing/order helpers, and re-exports the shared `@lifi/perps-types`.
  *
  * @packageDocumentation
@@ -22,6 +22,7 @@ export { PerpsError } from './errors/PerpsError.js'
 export { AssetRegistry, getAssetRegistry } from './registry/assetRegistry.js'
 export {
   getMarketRegistry,
+  isActiveMarket,
   MarketRegistry,
   toMarketDisplay,
 } from './registry/marketRegistry.js'
@@ -38,6 +39,11 @@ export type { GetAssetsParams } from './services/getAssets.js'
 export { getAssets } from './services/getAssets.js'
 export type { GetFillsParams } from './services/getFills.js'
 export { getFills } from './services/getFills.js'
+export type { GetGasRecommendationParams } from './services/getGasRecommendation.js'
+export {
+  getGasRecommendation,
+  LIFI_API_URL,
+} from './services/getGasRecommendation.js'
 export type { GetMarketParams } from './services/getMarket.js'
 export { getMarket } from './services/getMarket.js'
 export type { GetMarketsParams } from './services/getMarkets.js'
@@ -92,6 +98,7 @@ export type {
   BuildProviderSetupParams,
   CancelOrdersParams,
   GetAccountResult,
+  GetDepositFlowParams,
   GetSetupParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -112,6 +119,13 @@ export type {
   SDKRequestOptions,
   SwitchChainHook,
 } from './types/config.js'
+export type {
+  DeclaredDepositAsset,
+  DepositFlow,
+  DepositFlowFirstDepositPipeline,
+  DepositFlowLifiSwap,
+  DepositFlowSetupRequired,
+} from './types/deposit.js'
 export type {
   ActionSignerContribution,
   LiquidationEstimateParams,
@@ -121,6 +135,7 @@ export type {
   ProviderAccountExistsParams,
   ProviderGetAccountParams,
   ProviderGetActivityParams,
+  ProviderGetDepositFlowParams,
   ProviderGetFillsParams,
   ProviderGetOrderParams,
   ProviderGetOrdersParams,
@@ -153,11 +168,14 @@ export {
   removableMargin,
   walkOrderbook,
 } from './utils/calculations.js'
-export type { DepositProviderKey } from './utils/depositChain.js'
 export {
-  LIFI_DEPOSIT_CHAIN_BY_PROVIDER,
-  lifiDepositChainForProvider,
-} from './utils/depositChain.js'
+  ETHEREUM_NATIVE_GAS,
+  ETHEREUM_USDC,
+  HYPERLIQUID_USDC,
+  LIGHTER_USDC,
+  ROBINHOOD_NATIVE_GAS,
+  ROBINHOOD_USDG,
+} from './utils/depositAssets.js'
 export {
   ExplorerChainId,
   explorerTxUrl,
@@ -197,6 +215,9 @@ export {
   predictUnrealizedPnl,
   realizedPnlOnClose,
 } from './utils/positionMath.js'
+export type { ScaleToIntegerPolicy } from './utils/scaleToInteger.js'
+export { scaleToInteger } from './utils/scaleToInteger.js'
+export { selectUserSetupActions } from './utils/setupActions.js'
 export {
   signTypedData,
   signTypedDataWithSigner,

package/src/registry/marketRegistry.ts

@@ -23,10 +23,16 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
     return this.items
   }
 
+  /** The synced markets that are available for live and write operations. */
+  get activeMarkets(): readonly Market[] {
+    return this.items.filter(isActiveMarket)
+  }
+
   /**
    * Lookup by `Market.id`, throwing when the backend list does not know the
-   * id. The list is the source of truth for every tradable market, so an id
-   * the venue references but the backend does not know is a hard error —
+   * id. The list is the source of truth for enriched historical and live
+   * market metadata, so an id the venue references but the backend does not
+   * know is a hard error —
    * never a silent fallback to an unenriched stand-in.
    *
    * @throws {PerpsError} `MarketNotFound`.
@@ -44,6 +50,26 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
     return market
   }
 
+  /**
+   * Lookup a market for live or write use. Delisted markets remain resolvable
+   * through {@link require} for historical display mapping, but this method
+   * rejects them.
+   *
+   * @throws {PerpsError} `MarketNotFound` when the market is absent or delisted.
+   */
+  requireActive(marketId: string): Market {
+    const market = this.require(marketId)
+    if (!isActiveMarket(market)) {
+      const error = new PerpsError(
+        PerpsErrorCode.MarketNotFound,
+        `Market '${marketId}' is not available for live use`
+      )
+      error.tool = this.provider
+      throw error
+    }
+    return market
+  }
+
   protected fetchItems(): Promise<Market[]> {
     const url = buildUrl(`${this.client.config.apiUrl}/markets`, {
       provider: this.provider,
@@ -60,6 +86,10 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
 
 const registries = new WeakMap<PerpsSDKClient, Map<string, MarketRegistry>>()
 
+/** A market is active unless the provider explicitly marks it delisted. */
+export const isActiveMarket = (market: Market): boolean =>
+  market.isDelisted !== true
+
 /**
  * The stable {@link MarketRegistry} for `(client, provider)`.
  *
@@ -95,4 +125,5 @@ export const toMarketDisplay = (market: Market): MarketDisplay => ({
   categoryId: market.categoryId,
   baseAsset: market.baseAsset,
   quoteAsset: market.quoteAsset,
+  ...(market.isDelisted === undefined ? {} : { isDelisted: market.isDelisted }),
 })

package/src/registry/referenceDataRegistry.ts

@@ -7,7 +7,8 @@ import type { PerpsSDKClient } from '../types/provider.js'
  * NOT a cache: it holds no freshness policy of its own. Every {@link sync}
  * refetches through the HTTP layer, whose `cache-control` headers decide
  * whether the response comes from disk or the network. A lookup miss warns
- * once and returns `undefined`; the next {@link sync} reconciles the index.
+ * once per id and returns `undefined`; subsequent syncs reconcile the index
+ * without replaying the warning for an id that remains absent.
  *
  * @internal
  */
@@ -65,7 +66,6 @@ export abstract class ReferenceDataRegistry<T> {
     const items = await this.fetchItems()
     this.index = new Map(items.map((item) => [this.keyOf(item), item]))
     this.current = items
-    this.warnedIds.clear()
     return items
   }
 }

package/src/services/getGasRecommendation.ts

@@ -0,0 +1,45 @@
+import type { GasRecommendationResponse } from '@lifi/types'
+import { request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * LI.FI API base URL for reads the user's client makes directly, without the
+ * perps backend in the path.
+ *
+ * @public
+ */
+export const LIFI_API_URL = 'https://li.quest/v1'
+
+/**
+ * Parameters for {@link getGasRecommendation}.
+ *
+ * @public
+ */
+export interface GetGasRecommendationParams {
+  /** Chain to hold native gas on — a `firstDepositPipeline` flow's `chainId`. */
+  chainId: number
+}
+
+/**
+ * How much native gas LI.FI suggests holding on `params.chainId` to transact
+ * there, for seeding the gas leg of a first-deposit pipeline. Read straight
+ * from the LI.FI API by the user's client.
+ *
+ * @returns The suggestion, with `available: false` and no amounts on a chain
+ *   LI.FI cannot source gas for.
+ * @throws {PerpsError} On API error responses, or network/parsing errors.
+ * @public
+ */
+export async function getGasRecommendation(
+  client: PerpsSDKClient,
+  params: GetGasRecommendationParams,
+  options?: SDKRequestOptions
+): Promise<GasRecommendationResponse> {
+  return request<GasRecommendationResponse>(
+    client.config,
+    `${LIFI_API_URL}/gas/suggestion/${params.chainId}`,
+    {},
+    options
+  )
+}

package/src/services/getMarket.ts

@@ -1,6 +1,7 @@
 import type { Market, MarketsResponse } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import { PerpsError } from '../errors/PerpsError.js'
+import { isActiveMarket } from '../registry/marketRegistry.js'
 import { buildUrl, request } from '../transport/request.js'
 import type { SDKRequestOptions } from '../types/config.js'
 import type { PerpsSDKClient } from '../types/provider.js'
@@ -21,10 +22,11 @@ export interface GetMarketParams {
 }
 
 /**
- * Get a specific market by its opaque marketId. Requests the single market
- * from the backend `/markets` route (filtered by `marketIds`) and returns the
- * first match; throws a `MarketNotFound` {@link PerpsError} both when the
- * backend responds 404 and when it responds 200 with an empty list, matching
+ * Get a specific active market by its opaque marketId. Requests the single
+ * market from the backend `/markets` route (filtered by `marketIds`) and
+ * returns the first active match; throws a `MarketNotFound` {@link PerpsError}
+ * when the backend responds 404, returns an empty list, or returns a
+ * delisted market, matching
  * `MarketRegistry.require`'s miss behaviour.
  *
  * @throws {PerpsError} On backend (e.g. 404 or empty match), network, or parsing errors.
@@ -52,7 +54,7 @@ export async function getMarket(
     options
   )
   const market = markets[0]
-  if (market === undefined) {
+  if (market === undefined || !isActiveMarket(market)) {
     const error = new PerpsError(
       PerpsErrorCode.MarketNotFound,
       `No ${params.provider} market found for marketId '${params.marketId}'`

package/src/services/getMarkets.ts

@@ -1,4 +1,5 @@
 import type { MarketsResponse } from '@lifi/perps-types'
+import { isActiveMarket } from '../registry/marketRegistry.js'
 import { buildUrl, request } from '../transport/request.js'
 import type { SDKRequestOptions } from '../types/config.js'
 import type { PerpsSDKClient } from '../types/provider.js'
@@ -15,9 +16,12 @@ export interface GetMarketsParams {
 }
 
 /**
- * Get all available markets for a provider. Thin pass-through to the LI.FI
- * backend's Valkey-cached `/perps/markets` route — the canonical source of
- * public market data for widget consumers.
+ * Get active markets for a provider. Delisted entries remain available to
+ * internal registries for historical mapping, but are excluded from this
+ * public market-selection surface.
+ *
+ * Thin pass-through to the LI.FI backend's Valkey-cached `/perps/markets`
+ * route — the canonical source of public market data for widget consumers.
  *
  * @throws {PerpsError} On backend, network, or parsing errors.
  * @example
@@ -36,5 +40,11 @@ export async function getMarkets(
     provider: params.provider,
     marketIds: params.marketIds?.join(','),
   })
-  return request<MarketsResponse>(client.config, url, {}, options)
+  const response = await request<MarketsResponse>(
+    client.config,
+    url,
+    {},
+    options
+  )
+  return { markets: response.markets.filter(isActiveMarket) }
 }

package/src/types/api.ts

@@ -209,6 +209,16 @@ export interface GetSetupParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getDepositFlow}.
+ *
+ * @public
+ */
+export interface GetDepositFlowParams {
+  provider: string
+  address: Address
+}
+
 /**
  * Result from {@link PerpsClient.checkSetup}.
  *

package/src/types/deposit.ts

@@ -0,0 +1,75 @@
+import type { ActionType } from '@lifi/perps-types'
+import type { Address } from 'viem'
+
+/**
+ * A token the SDK declares as part of a deposit flow, by full on-chain
+ * identity. Matched by `chainId` + `address`: a symbol is not identity — the
+ * Hyperliquid venue chain lists two `USDC` contracts with different decimals.
+ *
+ * @public
+ */
+export interface DeclaredDepositAsset {
+  chainId: number
+  /** EIP-55 checksummed address; the zero address denotes the chain's native gas token. */
+  address: Address
+  decimals: number
+}
+
+/**
+ * Fund the account by swapping whatever the user holds into `destination`
+ * through the LI.FI surface. The source token is picked inside that surface, so
+ * it is not part of the flow; LI.FI routing owns whether that resolves to a
+ * same-chain swap or a bridge.
+ *
+ * @public
+ */
+export interface DepositFlowLifiSwap {
+  kind: 'lifiSwap'
+  destination: DeclaredDepositAsset
+  /**
+   * Credited address when it is not the user's own — a venue-provisioned
+   * deposit address. Absent means the user's address receives the deposit.
+   */
+  toAddress?: Address
+}
+
+/**
+ * Fund an address that has no venue account yet. Collateral and the native gas
+ * to broadcast with are both needed on `chainId`, where the venue's
+ * {@link ActionType.DEPOSIT} action stages the on-chain legs that open the
+ * account.
+ *
+ * @public
+ */
+export interface DepositFlowFirstDepositPipeline {
+  kind: 'firstDepositPipeline'
+  /** Chain the deposit legs broadcast on; the user's wallet must be switched to it. */
+  chainId: number
+  gasAsset: DeclaredDepositAsset
+  collateral: DeclaredDepositAsset
+  bridgeAction: ActionType.DEPOSIT
+}
+
+/**
+ * The venue cannot name a deposit destination until the listed setup actions
+ * are satisfied — Ondo provisions its deposit address behind a signed-in
+ * session.
+ *
+ * @public
+ */
+export interface DepositFlowSetupRequired {
+  kind: 'setupRequired'
+  /** Outstanding `Provider.setup` action types, in the order they must be run. */
+  setup: ActionType[]
+}
+
+/**
+ * The single deposit flow a venue offers one address, resolved from the venue's
+ * account and setup state.
+ *
+ * @public
+ */
+export type DepositFlow =
+  | DepositFlowLifiSwap
+  | DepositFlowFirstDepositPipeline
+  | DepositFlowSetupRequired

package/src/types/provider.ts

@@ -29,6 +29,7 @@ import type {
   PerpsClientSigner,
   SDKRequestOptions,
 } from './config.js'
+import type { DepositFlow } from './deposit.js'
 
 /**
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -162,6 +163,15 @@ export interface ProviderAccountExistsParams {
   address: Address
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getDepositFlow}.
+ *
+ * @public
+ */
+export interface ProviderGetDepositFlowParams {
+  address: Address
+}
+
 /**
  * Read params for {@link PerpsProvider.getPositions}.
  *
@@ -321,6 +331,20 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<boolean>
 
+  /**
+   * The deposit flow this venue offers `params.address`, resolved from the
+   * venue's own account and setup state — which collateral token a deposit must
+   * land in, whether the address first needs the account-opening pipeline, and
+   * whether venue setup gates naming a destination at all.
+   *
+   * Optional: a provider that cannot be funded through the SDK omits it, and
+   * `PerpsClient.getDepositFlow` then resolves `undefined`.
+   */
+  getDepositFlow?(
+    params: ProviderGetDepositFlowParams,
+    options?: SDKRequestOptions
+  ): Promise<DepositFlow>
+
   getPositions(
     params: ProviderGetPositionsParams,
     options?: SDKRequestOptions

package/src/utils/accountSummary.ts

@@ -8,6 +8,12 @@ import { stringToFloat } from './parse.js'
 const sumValueUsd = (balances: AccountResponse['balances']): number =>
   balances.reduce((sum, b) => sum + stringToFloat(b.valueUsd), 0)
 
+const sumMarginUsd = (balances: AccountResponse['balances']): number =>
+  balances.reduce(
+    (sum, b) => sum + stringToFloat(b.valueUsd) * (b.collateralWeight ?? 1),
+    0
+  )
+
 /**
  * What the summed `collateralBalances` rows already contain, relative to the
  * positions' locked margin and unrealized PnL:
@@ -51,12 +57,17 @@ export function summarizeAccount(
   }
 
   const collateral = sumValueUsd(account.collateralBalances)
+  // Margin-eligible collateral: each row's value scaled by its loan-to-value
+  // weight (1 when unset), so a haircut asset backs buying power at less than
+  // face while `portfolioValue` still reflects its full value.
+  const marginCollateral = sumMarginUsd(account.collateralBalances)
   const balances = sumValueUsd(account.balances)
 
-  const grossCollateral =
-    semantics === 'free' || semantics === 'net'
-      ? collateral + marginUsed
-      : collateral
+  const withLocked = semantics === 'free' || semantics === 'net'
+  const grossCollateral = withLocked ? collateral + marginUsed : collateral
+  const grossMarginCollateral = withLocked
+    ? marginCollateral + marginUsed
+    : marginCollateral
   const equity =
     semantics === 'equity' || semantics === 'net'
       ? grossCollateral
@@ -66,7 +77,9 @@ export function summarizeAccount(
   // toward it. The `'free'` rows exclude uPnL from available margin, holding
   // it purely as free collateral.
   const availableMargin =
-    semantics === 'free' ? grossCollateral - marginUsed : equity - marginUsed
+    grossMarginCollateral +
+    (semantics === 'gross' ? unrealizedPnl : 0) -
+    marginUsed
 
   return {
     portfolioValue: (balances + equity).toString(),