@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.1

package/dist/esm/types/config.d.ts

@@ -0,0 +1,70 @@
+import type { Account, WalletClient } from 'viem';
+import type { RetryConfig } from '../transport/retryPolicy.js';
+/**
+ * Viem `WalletClient` shape used by `PerpsSDKClient.userWallet`. Aliased here
+ * so provider plugins can name the type without re-deriving the viem generics.
+ *
+ * @public
+ */
+export type PerpsClientSigner = WalletClient<any, any, Account>;
+/**
+ * Per-provider config — restricts which `markets` the WS client subscribes
+ * to. Indexed by provider key.
+ *
+ * @public
+ */
+export interface ProviderConfig {
+    markets?: string[];
+}
+/**
+ * @deprecated Use {@link ProviderConfig}.
+ * @public
+ */
+export type HyperliquidConfig = ProviderConfig;
+/**
+ * Map of per-provider {@link ProviderConfig}, keyed by provider key.
+ *
+ * @public
+ */
+export interface ProviderConfigs {
+    [provider: string]: ProviderConfig | undefined;
+}
+/**
+ * Hook to rewrite each outgoing request's URL/`RequestInit` before it is sent.
+ *
+ * @public
+ */
+export type RequestInterceptor = (url: string, options: RequestInit) => RequestInit | Promise<RequestInit>;
+/**
+ * Per-call request options threaded through the service functions.
+ *
+ * @public
+ */
+export interface SDKRequestOptions {
+    signal?: AbortSignal;
+    /**
+     * Lighter auth token consumed by provider-direct venue reads (getOrders,
+     * getOrder, getActivity, getAccount). Create via
+     * `lighterSigner.createAuthToken(deadline, context)`. Sent only to Lighter
+     * venue endpoints, never to the LI.FI backend — read-only by design
+     * (8h max TTL, cannot authorize writes).
+     */
+    lighterAuthToken?: string;
+}
+/**
+ * Immutable snapshot of the resolved client configuration after defaults
+ * are applied. Exposed via {@link PerpsSDKClient.config}.
+ *
+ * @public
+ */
+export interface PerpsBaseConfig {
+    integrator: string;
+    apiKey: string;
+    apiUrl: string;
+    disableVersionCheck?: boolean;
+    requestInterceptor?: RequestInterceptor;
+    providers?: ProviderConfigs;
+    retry?: RetryConfig;
+    fetch?: typeof fetch;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/esm/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAA;AAE9C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAA;CAC/C;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,KACjB,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAEvC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB"}

package/dist/esm/types/config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.js.map

package/dist/esm/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/types/config.ts"],"names":[],"mappings":""}

package/dist/esm/types/provider.d.ts

@@ -0,0 +1,330 @@
+import type { AccountConfig, AccountConfigSetting, AccountResponse, AccountSummary, ActionStep, ActionType, ActivitiesResponse, ActivityType, FillsResponse, Market, Order, OrdersResponse, PerpsMarket, PerpsSigner, Position, PositionsResponse, ProviderAction, Quote, QuoteSide, SignedActionStep, SigningMethod, TradeType } from '@lifi/perps-types';
+import type { Address } from 'viem';
+import type { PerpsBaseConfig, PerpsClientSigner, SDKRequestOptions } from './config.js';
+/**
+ * Low-level SDK client: resolved config, the optional end-user wallet, and the
+ * registered provider plugins. Returned by {@link createPerpsClient} and
+ * consumed by every service function.
+ *
+ * @public
+ */
+export interface PerpsSDKClient {
+    readonly config: PerpsBaseConfig;
+    /** The end-user's wallet — accepts any viem WalletClient (browser, private key, mnemonic). */
+    readonly userWallet?: PerpsClientSigner;
+    /** Registered providers, bound to this client, in construction order. */
+    readonly providers: PerpsProvider[];
+    /** Look up a registered bound {@link PerpsProvider} by its `type` key. */
+    getProvider(key: string): PerpsProvider | undefined;
+}
+/**
+ * Per-call context passed by `PerpsClient` to a provider's {@link
+ * PerpsProvider.signActions} method. Carries the end-user's wallet (when
+ * configured); providers that own a session credential (e.g. the Hyperliquid
+ * agent keypair, Lighter's API key) resolve it internally.
+ *
+ * @public
+ */
+export interface SignActionsContext {
+    userWallet?: PerpsClientSigner;
+    /**
+     * The signing batch's declared signers, from the action's `ProviderAction`
+     * descriptor. The plugin branches on this to pick WHO signs (e.g.
+     * Hyperliquid: `USER` → end-user wallet, `AGENT` → session keypair). Core
+     * forwards the descriptor's `signers` as data; it does not branch on them.
+     */
+    signers?: PerpsSigner[];
+}
+/**
+ * Signer-bearing wire fields a provider plugin contributes to an action's
+ * `createAction` / `executeAction` requests — resolved by the plugin because
+ * signer identity (WHO signs) is provider-owned. Returned by
+ * {@link PerpsProviderPlugin.resolveActionRequest}.
+ *
+ * @public
+ */
+export interface ActionSignerContribution {
+    /**
+     * The on-wire `signerAddress` for an action a provider signs on the user's
+     * behalf — the address of the provider-owned session keypair (Hyperliquid's
+     * approved agent wallet). Sent on both `createAction` (so the backend builds
+     * the right typed data) and `executeAction`. Omitted when the provider signs
+     * as the user or with a non-EVM session credential (Lighter's API key).
+     */
+    signerAddress?: Address;
+    /**
+     * Extra action params the plugin injects from its own signer state — e.g.
+     * Hyperliquid's `agentAddress` for `APPROVE_AGENT`. Merged over the caller's
+     * params.
+     */
+    params?: Record<string, unknown>;
+}
+/**
+ * Inputs for {@link PerpsProviderPlugin.estimateLiquidationPrice}:
+ * `leverage` is the user-selected leverage for the new position, `isLong`
+ * carries direction.
+ *
+ * @public
+ */
+export interface LiquidationEstimateParams {
+    entryPrice: number;
+    leverage: number;
+    isLong: boolean;
+}
+/**
+ * Read-side params for {@link PerpsProvider.getAccount}. The `provider`
+ * field is implicit in the provider instance and so is not duplicated here.
+ *
+ * @public
+ */
+export interface ProviderGetAccountParams {
+    address: Address;
+}
+/**
+ * Read params for {@link PerpsProvider.getPositions}.
+ *
+ * @public
+ */
+export interface ProviderGetPositionsParams {
+    address: Address;
+    /** Optional filter — opaque `Market.id` (not `displaySymbol`). */
+    marketId?: string;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Read params for {@link PerpsProvider.getOrders}.
+ *
+ * @public
+ */
+export interface ProviderGetOrdersParams {
+    address: Address;
+    /** Optional filter — opaque `Market.id` (not `displaySymbol`). */
+    marketId?: string;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Read params for {@link PerpsProvider.getOrder}.
+ *
+ * @public
+ */
+export interface ProviderGetOrderParams {
+    address: Address;
+    id: string;
+}
+/**
+ * Read params for {@link PerpsProvider.getFills}.
+ *
+ * @public
+ */
+export interface ProviderGetFillsParams {
+    address: Address;
+    limit?: number;
+    cursor?: string;
+    startTime?: number;
+    endTime?: number;
+}
+/**
+ * Read params for {@link PerpsProvider.getActivity}.
+ *
+ * @public
+ */
+export interface ProviderGetActivityParams {
+    address: Address;
+    limit?: number;
+    cursor?: string;
+    startTime?: number;
+    endTime?: number;
+    type?: ActivityType[];
+}
+/**
+ * Read params for {@link PerpsProviderPlugin.getQuote}. `provider` is implicit
+ * in the provider instance and so is not duplicated here.
+ *
+ * @public
+ */
+export interface ProviderGetQuoteParams {
+    /** Human `displaySymbol`, e.g. `"BTC"`. Resolved against the provider's own markets, scoped by `type`. */
+    symbol: string;
+    side: QuoteSide;
+    /** USD notional to fill. */
+    size: number;
+    type: TradeType;
+}
+/**
+ * Listener invoked with each freshly computed {@link Quote} on a streaming
+ * quote subscription.
+ *
+ * @public
+ */
+export type QuoteListener = (quote: Quote) => void;
+/**
+ * Unbound provider plugin passed to {@link createPerpsClient}, modelled on
+ * `@lifi/sdk`'s `SDKProvider`. Each provider is identified by `type` (the wire
+ * key — `'hyperliquid'`, `'lighter'`, …) and implements the read-side surface
+ * area for one DEX. Read methods are clientless — `(params, options?)`; the
+ * runtime context they need is injected once via {@link bind} when
+ * {@link createPerpsClient} calls {@link bindProvider}, and captured in the
+ * factory's closure.
+ *
+ * Concrete implementations live in dedicated packages
+ * (`@lifi/perps-sdk-provider-hyperliquid`, `@lifi/perps-sdk-provider-lighter`).
+ * Consumers register providers up-front:
+ *
+ * ```ts
+ * const client = createPerpsClient({
+ *   integrator: 'my-app',
+ *   apiKey: 'key',
+ *   providers: [hyperliquidProvider(), lighterProvider()],
+ * })
+ * const account = await client.getProvider('hyperliquid')!.getAccount({ address })
+ * ```
+ *
+ * Write-side actions (`createAction`, `executeAction`) remain on the core
+ * client because they go through the LI.FI backend's generic action
+ * pipeline — they are not per-provider plugin surface.
+ *
+ * @public
+ */
+export interface PerpsProviderPlugin {
+    /**
+     * Provider key, matching `Provider.key` from the backend's
+     * `/providers` response (e.g. `'hyperliquid'`, `'lighter'`). Used to
+     * look the provider up via {@link PerpsSDKClient.getProvider}.
+     */
+    readonly type: string;
+    /**
+     * Inject the runtime {@link PerpsSDKClient} into the plugin once, during
+     * {@link createPerpsClient}. The plugin captures it (config, fetch, retry,
+     * provider registry) in its factory closure so the clientless read methods
+     * can resolve their runtime deps at call time. Called exactly once per
+     * registered plugin by {@link bindProvider}.
+     */
+    bind(client: PerpsSDKClient): void;
+    getAccount(params: ProviderGetAccountParams, options?: SDKRequestOptions): Promise<AccountResponse>;
+    getPositions(params: ProviderGetPositionsParams, options?: SDKRequestOptions): Promise<PositionsResponse>;
+    getOrders(params: ProviderGetOrdersParams, options?: SDKRequestOptions): Promise<OrdersResponse>;
+    getOrder(params: ProviderGetOrderParams, options?: SDKRequestOptions): Promise<Order>;
+    getFills(params: ProviderGetFillsParams, options?: SDKRequestOptions): Promise<FillsResponse>;
+    getActivity(params: ProviderGetActivityParams, options?: SDKRequestOptions): Promise<ActivitiesResponse>;
+    /**
+     * Produce a one-shot fill {@link Quote} for `params.symbol` at `params.size`
+     * USD notional on this venue. The provider resolves the symbol against its
+     * own markets (matching `baseAsset.displaySymbol`, scoped by `params.type`),
+     * walks its orderbook for the VWAP fill, and applies its public base fee
+     * tier. Throws when no market matches the symbol+type.
+     */
+    getQuote(params: ProviderGetQuoteParams, options?: SDKRequestOptions): Promise<Quote>;
+    /**
+     * Roll an already-fetched {@link AccountResponse} (plus its positions) up
+     * into an {@link AccountSummary}. Owned by the provider because the
+     * gross/free meaning of collateral and the margin handling are
+     * venue-specific: Hyperliquid branches on its abstraction mode (in
+     * `disabled`/`dexAbstraction` the venue equity is already free margin; in
+     * `unifiedAccount`/`portfolioMargin` spot holds the whole account), whereas
+     * Lighter has a single flat collateral model. Pure — does no I/O.
+     */
+    getAccountSummary(account: AccountResponse, positions: Position[]): AccountSummary;
+    /**
+     * Format an order price onto the venue's tick grid for `market`. This is
+     * the canonical, provider-correct formatting surface — venue tick rules
+     * differ per provider, so provider-agnostic consumers must route every
+     * order price through the market's own provider instead of applying one
+     * venue's rules to another's markets. Pure — does no I/O.
+     *
+     * @returns The price as a wire-ready decimal string, trailing zeros
+     *   stripped.
+     * @throws {PerpsError} `ValidationError` when `market` lacks the tick
+     *   metadata the venue's rules need (e.g. `Market.priceDecimals` absent).
+     */
+    formatOrderPrice(market: Market, price: number): string;
+    /**
+     * Format an order size onto the venue's lot grid for `market`. Truncates
+     * (never rounds up) so the formatted size cannot exceed the user's intended
+     * size or available balance. Pure — does no I/O.
+     *
+     * @param size - Size in base-asset units as a non-negative magnitude.
+     * @returns The size as a wire-ready decimal string, trailing zeros
+     *   stripped.
+     */
+    formatOrderSize(market: Market, size: number): string;
+    /**
+     * Estimate the liquidation price of a new isolated position on `market`
+     * using the venue's margin model. A preview helper — for existing
+     * positions, prefer `Position.liquidationPrice` from the venue. Pure —
+     * does no I/O.
+     *
+     * @returns The estimated liquidation price, or `undefined` when the venue's
+     *   model cannot be evaluated client-side (degenerate inputs, or `market`
+     *   lacks the margin metadata the model needs).
+     */
+    estimateLiquidationPrice(market: PerpsMarket, params: LiquidationEstimateParams): number | undefined;
+    /**
+     * Project a typed {@link AccountConfig} against the provider's `setup`
+     * + `options` descriptors into `AccountConfigSetting[]`. Used by
+     * `PerpsClient.getAccount` to attach a `settings` array to the response —
+     * one entry per descriptor, in `setup`-then-`options` order.
+     *
+     * Implementations receive the union-typed `AccountConfig` and narrow on
+     * `config.provider` themselves; the dispatcher in `PerpsClient` does not
+     * narrow before calling.
+     */
+    projectConfig(config: AccountConfig, setup: ProviderAction[], options: ProviderAction[]): AccountConfigSetting[];
+    /**
+     * Per-setup-action params the SDK should inject into `createAction` calls
+     * when staging the provider setup. Used for plugin-side state the backend
+     * needs to make a correct idempotency decision (e.g. Lighter's known local
+     * API public key). Returns an empty object when the plugin has no params
+     * to contribute for the action. Optional — providers without local state
+     * can omit it entirely.
+     */
+    resolveSetupParams?(action: ActionType, address: Address): Promise<Record<string, unknown>>;
+    /**
+     * Contribute the signer-bearing wire fields for an action — the plugin owns
+     * signer identity (WHO signs), so core asks the plugin rather than resolving
+     * a `signerAddress` itself. The descriptor's `signers` are forwarded so the
+     * plugin can branch on signer role: a provider that signs on the user's
+     * behalf with a session keypair (Hyperliquid's agent) resolves — provisioning
+     * one if needed — and returns the agent address as `signerAddress`; for
+     * `APPROVE_AGENT` (user-signed) it returns the agent address only as the
+     * `agentAddress` param. The agent address must be known pre-build so the
+     * backend builds the right typed data, so core calls this before
+     * `createAction` and threads the same result into `executeAction`.
+     *
+     * Optional: providers that sign as the user or with a non-EVM session
+     * credential (Lighter's API key) omit it — core then sends no `signerAddress`
+     * and no injected params.
+     */
+    resolveActionRequest?(action: ActionType, address: Address, signers: PerpsSigner[]): Promise<ActionSignerContribution>;
+    /**
+     * Sign a batch of unsigned {@link ActionStep}s belonging to one
+     * `SigningMethod` arm. Returns the matching {@link SignedActionStep}s in
+     * the same order — the core `PerpsClient.execute` then forwards them to
+     * `/executeAction`.
+     *
+     * Optional: providers that do not implement write actions (read-only
+     * plugins) may omit it. `PerpsClient.execute` throws `PerpsErrorCode.SDKError`
+     * when an action requires a delegated signing method but the resolved
+     * provider has no `signActions`.
+     *
+     * `method` mirrors the descriptor's `signingMethod`. The plugin owns every
+     * arm, branching on the descriptor's `signers` internally: the EIP712 arm
+     * signs with the user's wallet (read from `ctx.userWallet`) or the provider's
+     * session keypair (Hyperliquid's agent), and `WASM_BLOB` / `EVM_TX` sign with
+     * the provider's local credential (Lighter).
+     */
+    signActions?(method: SigningMethod, steps: ActionStep[], address: Address, ctx?: SignActionsContext): Promise<SignedActionStep[]>;
+}
+/**
+ * Runtime provider returned by {@link PerpsSDKClient.getProvider} and
+ * {@link requireProvider}: a {@link PerpsProviderPlugin} that has been bound to
+ * its client via {@link bindProvider}. The read methods are already clientless
+ * on the plugin (`getX(params, options?)`); binding only drops the one-shot
+ * {@link PerpsProviderPlugin.bind} hook so consumers cannot re-bind a live
+ * provider.
+ *
+ * @public
+ */
+export type PerpsProvider = Omit<PerpsProviderPlugin, 'bind'>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/esm/types/provider.d.ts.map

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

package/dist/esm/types/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/esm/types/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../src/types/provider.ts"],"names":[],"mappings":""}

package/dist/esm/utils/accountSummary.d.ts

@@ -1,13 +1,13 @@
-import type { AccountResponse, Asset, Position } from '@lifi/perps-types';
-export interface AccountSummary {
-    /** Total portfolio value in USD */
-    portfolioValue: number;
-    /** Collateral available for new positions */
-    availableMargin: number;
-    /** Margin locked in open positions */
-    marginUsed: number;
-    /** Unrealized PnL across all positions */
-    unrealizedPnl: number;
-}
-export declare function calculateAccountSummary(account: AccountResponse, positions: Position[], prices: Record<string, string>, assets?: Asset[], collateralCurrencies?: ReadonlySet<string>): AccountSummary;
+import type { AccountResponse, AccountSummary, Position } from '@lifi/perps-types';
+/**
+ * Roll an {@link AccountResponse} and its open positions up into an
+ * {@link AccountSummary}.
+ *
+ * @param collateralIsGross - `true` when the collateral rows already include
+ * margin locked in positions, so free margin is collateral minus
+ * `marginUsed`. `false` when the collateral rows hold free margin only and
+ * the locked portion is carried by the positions' `marginUsed`.
+ * @public
+ */
+export declare function summarizeAccount(account: AccountResponse, positions: Position[], collateralIsGross: boolean): AccountSummary;
 //# sourceMappingURL=accountSummary.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"accountSummary.d.ts","sourceRoot":"","sources":["../../../src/utils/accountSummary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAIzE,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAA;IACtB,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAA;CACtB;AAwDD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,QAAQ,EAAE,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,CAAC,EAAE,KAAK,EAAE,EAChB,oBAAoB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACzC,cAAc,CAsDhB"}
+{"version":3,"file":"accountSummary.d.ts","sourceRoot":"","sources":["../../../src/utils/accountSummary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,mBAAmB,CAAA;AAM1B;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,QAAQ,EAAE,EACrB,iBAAiB,EAAE,OAAO,GACzB,cAAc,CAqBhB"}

package/dist/esm/utils/accountSummary.js

@@ -1,97 +1,32 @@
-import { HlAbstractionMode } from '@lifi/perps-types/providers/hyperliquid';
 import { stringToFloat } from './parse.js';
+const sumValueUsd = (balances) => balances.reduce((sum, b) => sum + stringToFloat(b.valueUsd), 0);
 /**
- * Build a map of coin name → USD price from spot assets and allMids.
- * Spot assets have displaySymbol "BASE/QUOTE" and assetId "@N" which keys into prices.
- */
-function buildSpotCoinPrices(assets, prices) {
-    const map = new Map();
-    for (const asset of assets) {
-        if (asset.market !== 'spot') {
-            continue;
-        }
-        const price = prices[asset.assetId];
-        if (!price) {
-            continue;
-        }
-        const slashIdx = asset.displaySymbol.indexOf('/');
-        if (slashIdx < 0) {
-            continue;
-        }
-        const base = asset.displaySymbol.slice(0, slashIdx);
-        map.set(base, stringToFloat(price));
-    }
-    return map;
-}
-/**
- * Resolve the USD price of a spot balance currency.
+ * Roll an {@link AccountResponse} and its open positions up into an
+ * {@link AccountSummary}.
  *
- * Looks up the coin in the spot mid prices map first, then tries an exact
- * match in allMids (e.g. a perps-listed stablecoin). Falls back to $1 for
- * stablecoins with no market price entry.
+ * @param collateralIsGross - `true` when the collateral rows already include
+ * margin locked in positions, so free margin is collateral minus
+ * `marginUsed`. `false` when the collateral rows hold free margin only and
+ * the locked portion is carried by the positions' `marginUsed`.
+ * @public
  */
-function getSpotPrice(currency, prices, spotCoinPrices) {
-    const spotPrice = spotCoinPrices.get(currency);
-    if (spotPrice !== undefined) {
-        return spotPrice;
-    }
-    if (prices[currency] !== undefined) {
-        return stringToFloat(prices[currency]);
-    }
-    return 1;
-}
-const UNIFIED_STATUSES = new Set([
-    HlAbstractionMode.UNIFIED_ACCOUNT,
-    HlAbstractionMode.PORTFOLIO_MARGIN,
-]);
-export function calculateAccountSummary(account, positions, prices, assets, collateralCurrencies) {
+export function summarizeAccount(account, positions, collateralIsGross) {
     let marginUsed = 0;
     let unrealizedPnl = 0;
     for (const p of positions) {
         marginUsed += stringToFloat(p.marginUsed);
         unrealizedPnl += stringToFloat(p.unrealizedPnl);
     }
-    const spotCoinPrices = buildSpotCoinPrices(assets ?? [], prices);
-    // Split spot into margin-eligible (quote assets) and non-margin (HYPE, PURR etc.)
-    let spotMarginValue = 0;
-    let spotNonMarginValue = 0;
-    let perpsBalance = 0;
-    for (const [key, entries] of Object.entries(account.balances)) {
-        if (key === 'spot') {
-            for (const b of entries) {
-                const value = stringToFloat(b.amount) *
-                    getSpotPrice(b.currency, prices, spotCoinPrices);
-                if (!collateralCurrencies || collateralCurrencies.has(b.currency)) {
-                    spotMarginValue += value;
-                }
-                else {
-                    spotNonMarginValue += value;
-                }
-            }
-        }
-        else {
-            for (const b of entries) {
-                perpsBalance += stringToFloat(b.amount);
-            }
-        }
-    }
-    // `abstractionMode` is HL-only; for any other provider variant (today
-    // Lighter) the unified-collateral semantics don't apply, so fall back
-    // to `undefined` and let the non-unified branch below run.
-    const status = account.config.provider === 'hyperliquid'
-        ? (account.config.abstractionMode ?? undefined)
-        : undefined;
-    const isUnified = UNIFIED_STATUSES.has(status ?? '');
-    // Unified: spot balances are total token holdings (margin is NOT subtracted).
-    // Disabled: perps venue balances are free margin (margin IS already subtracted).
-    const marginCollateral = isUnified
-        ? spotMarginValue + perpsBalance
-        : spotMarginValue + perpsBalance + marginUsed;
+    const collateral = sumValueUsd(account.collateralBalances);
+    const balances = sumValueUsd(account.balances);
+    const grossCollateral = collateralIsGross
+        ? collateral
+        : collateral + marginUsed;
     return {
-        portfolioValue: marginCollateral + spotNonMarginValue + unrealizedPnl,
-        availableMargin: marginCollateral - marginUsed,
-        marginUsed,
-        unrealizedPnl,
+        portfolioValue: (balances + grossCollateral + unrealizedPnl).toString(),
+        availableMargin: (grossCollateral - marginUsed).toString(),
+        marginUsed: marginUsed.toString(),
+        unrealizedPnl: unrealizedPnl.toString(),
     };
 }
 //# sourceMappingURL=accountSummary.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"accountSummary.js","sourceRoot":"","sources":["../../../src/utils/accountSummary.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"accountSummary.js","sourceRoot":"","sources":["../../../src/utils/accountSummary.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,MAAM,WAAW,GAAG,CAAC,QAAqC,EAAU,EAAE,CACpE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAA;AAEjE;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAwB,EACxB,SAAqB,EACrB,iBAA0B;IAE1B,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,IAAI,aAAa,GAAG,CAAC,CAAA;IACrB,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,UAAU,IAAI,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;QACzC,aAAa,IAAI,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAA;IACjD,CAAC;IAED,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC1D,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE9C,MAAM,eAAe,GAAG,iBAAiB;QACvC,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,GAAG,UAAU,CAAA;IAE3B,OAAO;QACL,cAAc,EAAE,CAAC,QAAQ,GAAG,eAAe,GAAG,aAAa,CAAC,CAAC,QAAQ,EAAE;QACvE,eAAe,EAAE,CAAC,eAAe,GAAG,UAAU,CAAC,CAAC,QAAQ,EAAE;QAC1D,UAAU,EAAE,UAAU,CAAC,QAAQ,EAAE;QACjC,aAAa,EAAE,aAAa,CAAC,QAAQ,EAAE;KACxC,CAAA;AACH,CAAC"}

package/dist/esm/utils/assertNever.d.ts

@@ -14,6 +14,7 @@
  *     case 'lighter': return projectLighter(config)
  *     default: return assertNever(config)
  *   }
+ * @internal
  */
 export declare function assertNever(value: never): never;
 //# sourceMappingURL=assertNever.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"assertNever.d.ts","sourceRoot":"","sources":["../../../src/utils/assertNever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAI/C"}
+{"version":3,"file":"assertNever.d.ts","sourceRoot":"","sources":["../../../src/utils/assertNever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAI/C"}

package/dist/esm/utils/assertNever.js

@@ -14,6 +14,7 @@
  *     case 'lighter': return projectLighter(config)
  *     default: return assertNever(config)
  *   }
+ * @internal
  */
 export function assertNever(value) {
     throw new Error(`Unreachable: exhaustiveness check failed for value ${JSON.stringify(value)}`);

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

@@ -1 +1 @@
-{"version":3,"file":"assertNever.js","sourceRoot":"","sources":["../../../src/utils/assertNever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,MAAM,IAAI,KAAK,CACb,sDAAsD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAC9E,CAAA;AACH,CAAC"}
+{"version":3,"file":"assertNever.js","sourceRoot":"","sources":["../../../src/utils/assertNever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,MAAM,IAAI,KAAK,CACb,sDAAsD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAC9E,CAAA;AACH,CAAC"}