@pear-protocol/exchanges-sdk 0.12.2 → 0.14.0

package/README.md

@@ -291,6 +291,7 @@ tracker.trackPosition((positions) => {
     p.size;
     p.entryPrice;
     p.unrealizedPnl;
+    p.marginUsed;       // string | null — null where the venue publishes none
     p.leverage;
     p.marginType;       // "cross" | "isolated"
     p.liquidationPrice; // string | null

package/dist/client/hyperliquid/rest.js

@@ -6,6 +6,16 @@ const HL_INFO_URLS = {
   mainnet: "https://api.hyperliquid.xyz/info",
   testnet: "https://api.hyperliquid-testnet.xyz/info"
 };
+class HyperliquidInfoRequestError extends Error {
+  static {
+    __name(this, "HyperliquidInfoRequestError");
+  }
+  status;
+  constructor(status) {
+    super(`Hyperliquid info request failed: ${status}`);
+    this.status = status;
+  }
+}
 async function fetchInfo(body, demo = false) {
   const url = demo ? HL_INFO_URLS.testnet : HL_INFO_URLS.mainnet;
   const res = await proxyFetch(url, {
@@ -16,7 +26,7 @@ async function fetchInfo(body, demo = false) {
     body: JSON.stringify(body)
   });
   if (!res.ok) {
-    throw new Error(`Hyperliquid info request failed: ${res.status}`);
+    throw new HyperliquidInfoRequestError(res.status);
   }
   return res.json();
 }
@@ -85,4 +95,4 @@ async function fetchActiveAssetData(user, coin, demo = false) {
 }
 __name(fetchActiveAssetData, "fetchActiveAssetData");
 
-export { fetchActiveAssetData, fetchAllMids, fetchClearinghouseState, fetchDelegatorSummary, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole, fetchUserVaultEquities };
+export { HyperliquidInfoRequestError, fetchActiveAssetData, fetchAllMids, fetchClearinghouseState, fetchDelegatorSummary, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole, fetchUserVaultEquities };

package/dist/client/lighter/rest.js

@@ -3,6 +3,17 @@ import { getLighterBaseUrl } from './constants';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+class LighterRequestError extends Error {
+  static {
+    __name(this, "LighterRequestError");
+  }
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "LighterRequestError";
+    this.status = status;
+  }
+}
 const INTENT_REQUEST_ATTEMPTS = 3;
 const INTENT_RETRY_BASE_DELAY_MS = 500;
 const RETRYABLE_INTENT_STATUSES = /* @__PURE__ */ new Set([
@@ -176,9 +187,11 @@ async function fetchAccountsByL1Address(l1Address, demo = false) {
   };
 }
 __name(fetchAccountsByL1Address, "fetchAccountsByL1Address");
-async function fetchAccount(accountIndex, authToken, demo = false) {
-  const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/account?by=index&value=${accountIndex}`, authToken);
-  return readLighterResponse(response, "/account");
+async function fetchAccount(accountIndex, authToken, demo = false, throttle) {
+  return gatedLighterRead(throttle, "account", async () => {
+    const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/account?by=index&value=${accountIndex}`, authToken);
+    return readLighterResponse(response, "/account");
+  }, () => 0);
 }
 __name(fetchAccount, "fetchAccount");
 async function fetchPublicAccount(accountIndex, demo = false) {
@@ -232,7 +245,7 @@ async function fetchAssetDetails(demo) {
   return data.asset_details;
 }
 __name(fetchAssetDetails, "fetchAssetDetails");
-async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
+async function fetchTradesSince(accountIndex, authToken, since, demo = false, throttle) {
   const results = [];
   const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
@@ -251,8 +264,10 @@ async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
         cursor
       } : {}
     });
-    const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/trades?${params.toString()}`, authToken);
-    const data = await readLighterResponse(response, "/trades");
+    const data = await gatedLighterRead(throttle, "trades", async () => {
+      const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/trades?${params.toString()}`, authToken);
+      return readLighterResponse(response, "/trades");
+    }, (page2) => (page2.trades ?? []).length);
     const page = data.trades ?? [];
     results.push(...page.filter((trade) => trade.timestamp >= since.getTime()));
     const reachedSince = page.some((trade) => trade.timestamp < since.getTime());
@@ -269,7 +284,7 @@ async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
   return Array.from(byId.values());
 }
 __name(fetchTradesSince, "fetchTradesSince");
-async function fetchPositionFundingSince(accountIndex, authToken, since, demo = false) {
+async function fetchPositionFundingSince(accountIndex, authToken, since, demo = false, throttle) {
   const results = /* @__PURE__ */ new Map();
   const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
@@ -284,8 +299,10 @@ async function fetchPositionFundingSince(accountIndex, authToken, since, demo =
         cursor
       } : {}
     });
-    const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/positionFunding?${params.toString()}`, authToken);
-    const data = await readLighterResponse(response, "/positionFunding");
+    const data = await gatedLighterRead(throttle, "positionFunding", async () => {
+      const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/positionFunding?${params.toString()}`, authToken);
+      return readLighterResponse(response, "/positionFunding");
+    }, (page) => (page.position_fundings ?? []).length);
     for (const funding of data.position_fundings ?? []) {
       if (funding.timestamp >= sinceSeconds) {
         results.set(`${funding.market_id}:${funding.funding_id}`, funding);
@@ -374,6 +391,21 @@ async function fetchUserReferrals(params, demo = false) {
   };
 }
 __name(fetchUserReferrals, "fetchUserReferrals");
+async function gatedLighterRead(throttle, requestType, run, countItems) {
+  if (!throttle) {
+    return run();
+  }
+  await throttle.beforeRequest(requestType);
+  try {
+    const result = await run();
+    throttle.afterRequest(requestType, countItems(result));
+    return result;
+  } catch (error) {
+    throttle.afterRequestError(requestType, error);
+    throw error;
+  }
+}
+__name(gatedLighterRead, "gatedLighterRead");
 async function authenticatedLighterFetch(url, authToken, init) {
   const headers = new Headers(init?.headers);
   headers.set("authorization", authToken);
@@ -440,10 +472,10 @@ async function readLighterResponse(response, endpoint, acceptedCodes = [
     data = void 0;
   }
   if (!data) {
-    throw new Error(`Lighter ${endpoint} returned ${response.status}`);
+    throw new LighterRequestError(`Lighter ${endpoint} returned ${response.status}`, response.status);
   }
   if (!acceptedCodes.includes(data.code)) {
-    throw new Error(`Lighter ${endpoint} returned ${data.code}: ${data.message ?? `HTTP ${response.status}`}`);
+    throw new LighterRequestError(`Lighter ${endpoint} returned ${data.code}: ${data.message ?? `HTTP ${response.status}`}`, response.status);
   }
   return data;
 }
@@ -493,4 +525,4 @@ function readReferralAmount(value) {
 }
 __name(readReferralAmount, "readReferralAmount");
 
-export { createCctpDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchPublicAccount, fetchPublicOrderBookDetails, fetchTradesSince, fetchUserReferrals, fetchWithdrawHistory, submitReferralCode };
+export { LighterRequestError, createCctpDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchPublicAccount, fetchPublicOrderBookDetails, fetchTradesSince, fetchUserReferrals, fetchWithdrawHistory, submitReferralCode };

package/dist/index.d.ts

@@ -6,9 +6,30 @@ import { WalletClient, Transport, Chain, Account } from 'viem';
 import { z } from 'zod';
 
 type SupportedCredentials = HttpTypes.ExchangeCredentialsResponse['credentials'];
+/**
+ * Optional pacing seam around the syncer's exchange info requests. The SDK stays
+ * rate-limit-agnostic: it only exposes when a request starts, what it returned,
+ * and when it failed — the caller owns all budget math and waiting.
+ */
+type SyncerThrottle = {
+    /** Awaited before the request fires; the caller blocks here until its budget allows the call. */
+    beforeRequest(requestType: string): Promise<void>;
+    /** Called after a successful response; `itemCount` is the response array length (0 for object responses). */
+    afterRequest(requestType: string, itemCount: number): void;
+    /** Called when the request threw, before the error propagates; lets the caller inspect rate-limit rejections. */
+    afterRequestError(requestType: string, error: unknown): void;
+};
 type ExchangesSDKConfig = {
     sdk: PearSDK;
     demo?: boolean;
+    /** Optional pacing seam around the syncer's exchange info requests; absent = unthrottled (current behavior). */
+    throttle?: SyncerThrottle;
+    /**
+     * Optional pre-fetched Hyperliquid perp-dex names ('' = the main dex). The list is
+     * global (identical for every account), so a batch caller fetches it once per run and
+     * passes it here; absent = the syncer fetches it per sync (current behavior).
+     */
+    hyperliquidPerpDexNames?: string[];
     /**
      * Optional forward-proxy for the exchange REST calls. When enabled, requests are re-pointed at
      * `proxy.url` with the original venue host in `X-Proxy-Target`. Injected here because the SDK
@@ -918,6 +939,10 @@ interface AccountSyncerConfig {
     account: TradeAccount;
     credentials: SupportedCredentials;
     demo: boolean;
+    /** Optional pacing seam around the exchange info requests; absent = unthrottled (current behavior). */
+    throttle?: SyncerThrottle;
+    /** Optional pre-fetched Hyperliquid perp-dex names ('' = the main dex); absent = fetched per sync. */
+    hyperliquidPerpDexNames?: string[];
 }
 /**
  * Outcome of one fill sync cycle, so batch/cron callers can tell a completed
@@ -959,6 +984,7 @@ declare abstract class BaseAccountSyncer<ExternalFill> implements AccountSyncer
     protected account: TradeAccount;
     protected credentials: SupportedCredentials;
     protected demo: boolean;
+    protected throttle: SyncerThrottle | undefined;
     constructor(config: AccountSyncerConfig);
     /**
      * Fetch the account's currently-open positions from the exchange, normalized
@@ -1125,11 +1151,19 @@ type UserFillsByTimeResponse = {
 type HyperliquidRawFill = UserFillsByTimeResponse;
 declare class HyperliquidAccountSyncer extends BaseAccountSyncer<HyperliquidRawFill> {
     private readonly address;
+    private readonly perpDexNames;
     constructor(config: AccountSyncerConfig);
     protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
     protected listExternalFunding({ since, instruments, }: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
     protected isReduceOnly(rawFill: HyperliquidRawFill): boolean;
+    /** Fetch the perp-dex descriptors and reduce them to unique dex names ('' = the main dex). */
+    private fetchPerpDexNames;
+    /**
+     * Route one info request through the optional throttle seam: gate before the
+     * call, report the response size after, surface a failure before it propagates.
+     */
+    private fetchInfoGated;
 }
 
 type RawFill$1 = LighterRawTrade;
@@ -1211,6 +1245,7 @@ declare const AccountBalance: z.ZodDiscriminatedUnion<[z.ZodObject<{
     stakedEquity: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodString;
     maintenanceMargin: z.ZodString;
+    marginUsed: z.ZodString;
     crossMarginRatio: z.ZodString;
     crossAccountLeverage: z.ZodString;
     perDexState: z.ZodArray<z.ZodObject<{
@@ -1240,6 +1275,7 @@ declare const AccountBalance: z.ZodDiscriminatedUnion<[z.ZodObject<{
     portfolioValue: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodString;
     perpsMaintenanceMargin: z.ZodString;
+    marginUsed: z.ZodString;
     unifiedAccountRatio: z.ZodString;
     unifiedAccountLeverage: z.ZodNullable<z.ZodString>;
     perDexState: z.ZodArray<z.ZodObject<{
@@ -1271,6 +1307,7 @@ declare const AccountBalance: z.ZodDiscriminatedUnion<[z.ZodObject<{
     portfolioValue: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodString;
     perpsMaintenanceMargin: z.ZodString;
+    marginUsed: z.ZodString;
     portfolioMarginRatio: z.ZodNullable<z.ZodString>;
     portfolioAccountLeverage: z.ZodNullable<z.ZodString>;
     borrowCapUsed: z.ZodNullable<z.ZodString>;
@@ -1301,6 +1338,7 @@ declare const AccountBalance: z.ZodDiscriminatedUnion<[z.ZodObject<{
     stakingEquity: z.ZodNullable<z.ZodString>;
     creditedInLit: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodNullable<z.ZodString>;
+    marginUsed: z.ZodNullable<z.ZodString>;
     crossLeverage: z.ZodNullable<z.ZodString>;
     maintenanceMargin: z.ZodNullable<z.ZodString>;
     crossMarginUsage: z.ZodNullable<z.ZodString>;
@@ -1326,6 +1364,7 @@ declare const AccountBalance: z.ZodDiscriminatedUnion<[z.ZodObject<{
     stakingEquity: z.ZodNullable<z.ZodString>;
     creditedInLit: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodNullable<z.ZodString>;
+    marginUsed: z.ZodNullable<z.ZodString>;
     crossLeverage: z.ZodNullable<z.ZodString>;
     maintenanceMargin: z.ZodNullable<z.ZodString>;
     crossMarginUsage: z.ZodNullable<z.ZodString>;
@@ -1532,6 +1571,20 @@ interface AccountPosition {
     size: string;
     entryPrice: string;
     unrealizedPnl: string;
+    /**
+     * The margin this one position holds, in the account's quote currency.
+     *
+     * The meaning is the venue's own, and the two margin modes state different things: an isolated
+     * leg holds collateral of its own, while a cross position holds the initial margin its market
+     * demands out of the shared pool.
+     *
+     * `null` where the venue publishes no per-position figure and none can be derived from what it
+     * does publish — the margin is then unknown, which is not the same as a position holding none.
+     *
+     * The currency is the one that position's own venue settles in, and no field states which: a
+     * Hyperliquid position on a non-USDC HIP-3 dex holds margin in that dex's collateral token.
+     */
+    marginUsed: string | null;
     leverage: string;
     marginType: MarginMode;
     liquidationPrice: string | null;
@@ -1919,6 +1972,7 @@ declare const HyperliquidStandardBalance: z.ZodObject<{
     stakedEquity: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodString;
     maintenanceMargin: z.ZodString;
+    marginUsed: z.ZodString;
     crossMarginRatio: z.ZodString;
     crossAccountLeverage: z.ZodString;
     perDexState: z.ZodArray<z.ZodObject<{
@@ -1950,6 +2004,7 @@ declare const HyperliquidUnifiedBalance: z.ZodObject<{
     portfolioValue: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodString;
     perpsMaintenanceMargin: z.ZodString;
+    marginUsed: z.ZodString;
     unifiedAccountRatio: z.ZodString;
     unifiedAccountLeverage: z.ZodNullable<z.ZodString>;
     perDexState: z.ZodArray<z.ZodObject<{
@@ -2009,6 +2064,7 @@ declare const HyperliquidPortfolioMarginBalance: z.ZodObject<{
     portfolioValue: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodString;
     perpsMaintenanceMargin: z.ZodString;
+    marginUsed: z.ZodString;
     portfolioMarginRatio: z.ZodNullable<z.ZodString>;
     portfolioAccountLeverage: z.ZodNullable<z.ZodString>;
     borrowCapUsed: z.ZodNullable<z.ZodString>;
@@ -2143,6 +2199,7 @@ declare const LighterClassicBalance: z.ZodObject<{
     stakingEquity: z.ZodNullable<z.ZodString>;
     creditedInLit: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodNullable<z.ZodString>;
+    marginUsed: z.ZodNullable<z.ZodString>;
     crossLeverage: z.ZodNullable<z.ZodString>;
     maintenanceMargin: z.ZodNullable<z.ZodString>;
     crossMarginUsage: z.ZodNullable<z.ZodString>;
@@ -2170,6 +2227,7 @@ declare const LighterUnifiedBalance: z.ZodObject<{
     stakingEquity: z.ZodNullable<z.ZodString>;
     creditedInLit: z.ZodNullable<z.ZodString>;
     unrealizedPnl: z.ZodNullable<z.ZodString>;
+    marginUsed: z.ZodNullable<z.ZodString>;
     crossLeverage: z.ZodNullable<z.ZodString>;
     maintenanceMargin: z.ZodNullable<z.ZodString>;
     crossMarginUsage: z.ZodNullable<z.ZodString>;
@@ -2202,9 +2260,9 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     private startInFlight;
     private lifecycleVersion;
     private wsConnectionVersion;
-    private stateVersion;
+    private positionStateVersion;
     private assetsByAssetId;
-    private wsPositionsByMarketId;
+    private positionsByMarketId;
     private marketsByMarketId;
     private marketsBySymbol;
     private spotPriceBySymbol;
@@ -2253,10 +2311,10 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     /**
      * Subscribes this socket epoch's account channels, and keeps trying until one attempt lands.
      *
-     * This is the sole subscriber of `account_all` and `user_stats`, and the live balance is built
-     * from those two channels alone — see `buildBalance`. A mint that failed once and was never
-     * retried therefore left the tracker connected but permanently unsubscribed: the 2s REST poll
-     * kept positions moving while the balance silently froze until some incidental reconnect.
+     * This is the sole subscriber of `account_all` and `user_stats`, and no balance exists without
+     * both — see `buildBalance`. A mint that failed once and was never retried therefore left the
+     * tracker connected but permanently unsubscribed: the 2s REST poll kept positions moving while
+     * the balance stayed null until some incidental reconnect.
      *
      * The wait doubles up to a ceiling, and only a new connection epoch or teardown ends it.
      */
@@ -2271,13 +2329,15 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     /** Keeps both published scopes: cross drives every "Cross" field, total drives the account ones. */
     private onUserStats;
     /**
-     * The account's balance, built from websocket state alone.
+     * The account's balance, from the freshest state each of its parts has.
      *
-     * Every input is websocket-sourced — `user_stats` for the two account scopes, `account_all` for
-     * the assets and positions — except the market context, which is venue-wide metadata this
-     * tracker re-reads on its own timer. This is the ONLY producer of the value `getBalance()`
-     * returns while the tracker is running; `snapshot()` is the separate REST path and never writes
-     * here.
+     * The two account scopes come from `user_stats` and the assets from `account_all`, both
+     * websocket-only. The positions come from whichever source read the account last — a frame, or
+     * the REST poll that keeps them moving while the socket says nothing (see
+     * `performPositionPoll`). The market context is venue-wide metadata on its own timer.
+     *
+     * This is the ONLY producer of the value `getBalance()` returns while the tracker is running;
+     * `snapshot()` is the separate one-shot path and never writes here.
      *
      * Null until both channels have delivered a frame, because a balance built from one of them
      * would be missing half the account.
@@ -2295,16 +2355,27 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     private retrieveRequiredAuthToken;
     private pollPositions;
     /**
-     * Republishes positions and per-market settings from REST.
+     * Republishes positions, per-market settings, and the balance those positions move.
+     *
+     * This is what keeps the account's open result alive. Lighter republishes `account_all` when the
+     * account itself changes and not when the mark moves, so between fills the position rows hold
+     * whatever the last frame left them at. A balance built on those rows stated a dead unrealized
+     * PnL and a dead maintenance margin beside the live `user_stats` figures — and restated them on
+     * every frame under a current timestamp, so nothing marked them as old. The venue's own account
+     * read is the only source that carries the new figures, so the poll adopts it wholesale.
+     *
+     * The rows land in the same store `account_all` writes, which is what keeps `getPositions()` and
+     * the balance's `unrealizedPnl` stating one account rather than two.
      *
-     * Deliberately publishes NO balance. Every field of both Lighter variants comes off the two
-     * websocket channels — `user_stats` carries both account scopes and `account_all` carries the
-     * assets and positions behind them — so a REST balance here would only overwrite a live value
-     * with an equal one, while making `getBalance()` REST-derived most of the time.
+     * A read is dropped whole when a frame moved the position state while it was in flight: that
+     * frame is the newer account. `user_stats` deliberately does not invalidate one — it carries the
+     * account scopes and no positions at all, and a venue publishing it every tick would otherwise
+     * cancel every poll and freeze the very figures this read exists to move.
      *
-     * It also leaves `wsPositionsByMarketId` alone. That store feeds the live balance's unrealized
-     * PnL and maintenance margin, so writing REST rows into it would make a balance labelled live
-     * partly REST-derived without any reader being able to tell.
+     * No balance leaves here while the socket is down. The account scopes and the assets are dropped
+     * on the next open rather than on the drop, so a balance published mid-outage would pair these
+     * fresh positions with figures frozen at the drop — worst of it a cross margin ratio measured
+     * against a portfolio value the account no longer has. Positions still publish: they are whole.
      */
     private performPositionPoll;
     /**
@@ -2531,6 +2602,8 @@ declare function createAccountTracker(exchange: Connector, config: CreateAccount
 declare class ExchangesSDK {
     private sdk;
     private demo;
+    private throttle;
+    private hyperliquidPerpDexNames;
     constructor(config: ExchangesSDKConfig);
     connect(tradeAccountId: string): Promise<ExchangeConnection>;
     /**
@@ -2548,4 +2621,4 @@ declare class ExchangesSDK {
     private fetchCredentials;
 }
 
-export { ACCOUNT_MODE_LABELS, ASSET_DECIMALS, AccountBalance, AccountBalanceCore, type AccountHealthStatus, AccountMode, type AccountPosition, type AccountSnapshot, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTierCallback, type AccountTracker, type AccountTrackerConfig, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, AssetId, type AssetSnapshotMap, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceExchangeWs, BinanceMultiAssetBalance, BinanceSingleAssetBalance, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitExchangeWs, BybitIsolatedMarginBalance, BybitPortfolioMarginBalance, BybitRegularMarginBalance, BybitWs, type BybitWsConfig, type CctpDepositAddressParams, type CctpDepositAddressResult, type CctpDepositHistorySettlement, type CctpDepositParams, type CctpDepositRegistrationSettlement, type CctpDepositResult, type CctpDepositSettlement, type ChangeAccountTierParams, type ChangeAccountTierResult, type CheckApiWalletParams, CollateralBalance, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, DecimalString, type EthereumDepositParams, type EthereumDepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, FUNXYZ_DEPOSIT_MINIMUMS_USD, FUNXYZ_ETHEREUM_MAINNET_CHAIN_ID, FUNXYZ_EVM_CHAIN_NAMES, type FastWithdrawParams, type FastWithdrawResult, type FillSyncOutcome, type FundingSyncOutcome, type FunxyzAccountState, type FunxyzAsset, type FunxyzDepositAddressParams, type FunxyzDepositAddressResult, type FunxyzDepositCredit, type FunxyzDepositParams, type FunxyzDepositResult, type FunxyzDepositSettlement, type FunxyzDepositSource, type FunxyzMarket, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidDexState, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LIGHTER_NATIVE_USDC_ADDRESSES, LIGHTER_USDC_DECIMALS, LighterAccountSyncer, type LighterAccountTier, LighterAccountTracker, type LighterAccountTrackerConfig, type LighterApplyReferralCodeParams, type LighterAuthCredentials, LighterClassicBalance, type LighterDeposit, type LighterDepositAddressParams, type LighterDepositAddressResult, type LighterDepositCredit, type LighterDepositHistoryParams, type LighterDepositNetwork, type LighterDepositPage, type LighterDepositParams, type LighterDepositProgress, type LighterDepositResult, type LighterDepositStatus, type LighterDepositWalletAdapter, LighterExchangeWs, type LighterHelper, type LighterLookupResult, type LighterOnboardingStatus, type LighterReferral, type LighterReferralTotals, type LighterReferralTradeStats, LighterUnifiedBalance, type LighterUserReferrals, type LighterUserReferralsParams, type LighterWithdraw, type LighterWithdrawHistoryParams, type LighterWithdrawPage, type LighterWithdrawStatus, type LighterWithdrawType, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_LIGHTER_CCTP_DEPOSIT_USDC, MIN_LIGHTER_FAST_WITHDRAW_USDC, MIN_USER_API_KEY_INDEX, MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxExchangeWs, OkxFuturesBalance, OkxMultiCurrencyMarginBalance, OkxPortfolioMarginBalance, OkxSpotBalance, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, Side, SignedDecimalString, type StateUpdate, type SupportedCredentials, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, findAvailableApiKeyIndex, getAssetDecimals, getLighterNativeUsdcAddress, listFunxyzTransferableChains, readFunxyzChainSource, readFunxyzMinimumUsd, retrieveLighterAuthToken, usdcAbi };
+export { ACCOUNT_MODE_LABELS, ASSET_DECIMALS, AccountBalance, AccountBalanceCore, type AccountHealthStatus, AccountMode, type AccountPosition, type AccountSnapshot, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTierCallback, type AccountTracker, type AccountTrackerConfig, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, AssetId, type AssetSnapshotMap, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceExchangeWs, BinanceMultiAssetBalance, BinanceSingleAssetBalance, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitExchangeWs, BybitIsolatedMarginBalance, BybitPortfolioMarginBalance, BybitRegularMarginBalance, BybitWs, type BybitWsConfig, type CctpDepositAddressParams, type CctpDepositAddressResult, type CctpDepositHistorySettlement, type CctpDepositParams, type CctpDepositRegistrationSettlement, type CctpDepositResult, type CctpDepositSettlement, type ChangeAccountTierParams, type ChangeAccountTierResult, type CheckApiWalletParams, CollateralBalance, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, DecimalString, type EthereumDepositParams, type EthereumDepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, FUNXYZ_DEPOSIT_MINIMUMS_USD, FUNXYZ_ETHEREUM_MAINNET_CHAIN_ID, FUNXYZ_EVM_CHAIN_NAMES, type FastWithdrawParams, type FastWithdrawResult, type FillSyncOutcome, type FundingSyncOutcome, type FunxyzAccountState, type FunxyzAsset, type FunxyzDepositAddressParams, type FunxyzDepositAddressResult, type FunxyzDepositCredit, type FunxyzDepositParams, type FunxyzDepositResult, type FunxyzDepositSettlement, type FunxyzDepositSource, type FunxyzMarket, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidDexState, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LIGHTER_NATIVE_USDC_ADDRESSES, LIGHTER_USDC_DECIMALS, LighterAccountSyncer, type LighterAccountTier, LighterAccountTracker, type LighterAccountTrackerConfig, type LighterApplyReferralCodeParams, type LighterAuthCredentials, LighterClassicBalance, type LighterDeposit, type LighterDepositAddressParams, type LighterDepositAddressResult, type LighterDepositCredit, type LighterDepositHistoryParams, type LighterDepositNetwork, type LighterDepositPage, type LighterDepositParams, type LighterDepositProgress, type LighterDepositResult, type LighterDepositStatus, type LighterDepositWalletAdapter, LighterExchangeWs, type LighterHelper, type LighterLookupResult, type LighterOnboardingStatus, type LighterReferral, type LighterReferralTotals, type LighterReferralTradeStats, LighterUnifiedBalance, type LighterUserReferrals, type LighterUserReferralsParams, type LighterWithdraw, type LighterWithdrawHistoryParams, type LighterWithdrawPage, type LighterWithdrawStatus, type LighterWithdrawType, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_LIGHTER_CCTP_DEPOSIT_USDC, MIN_LIGHTER_FAST_WITHDRAW_USDC, MIN_USER_API_KEY_INDEX, MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxExchangeWs, OkxFuturesBalance, OkxMultiCurrencyMarginBalance, OkxPortfolioMarginBalance, OkxSpotBalance, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, Side, SignedDecimalString, type StateUpdate, type SupportedCredentials, type SyncerThrottle, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, findAvailableApiKeyIndex, getAssetDecimals, getLighterNativeUsdcAddress, listFunxyzTransferableChains, readFunxyzChainSource, readFunxyzMinimumUsd, retrieveLighterAuthToken, usdcAbi };

package/dist/sdk.js

@@ -12,9 +12,13 @@ class ExchangesSDK {
   }
   sdk;
   demo;
+  throttle;
+  hyperliquidPerpDexNames;
   constructor(config) {
     this.sdk = config.sdk;
     this.demo = config.demo ?? false;
+    this.throttle = config.throttle;
+    this.hyperliquidPerpDexNames = config.hyperliquidPerpDexNames;
     if (config.proxy) configureProxy(config.proxy);
   }
   async connect(tradeAccountId) {
@@ -67,7 +71,9 @@ class ExchangesSDK {
       connector: connection.connector,
       account: connection.account,
       credentials: connection.credentials,
-      demo: this.demo
+      demo: this.demo,
+      throttle: this.throttle,
+      hyperliquidPerpDexNames: this.hyperliquidPerpDexNames
     });
   }
   buildTracker(connection) {

package/dist/syncer/base.js

@@ -12,12 +12,14 @@ class BaseAccountSyncer {
   account;
   credentials;
   demo;
+  throttle;
   constructor(config) {
     this.sdk = config.sdk;
     this.connector = config.connector;
     this.account = config.account;
     this.credentials = config.credentials;
     this.demo = config.demo;
+    this.throttle = config.throttle;
   }
   // Phase A: Load current Pear state (positions, fills, instruments, watermark).
   async loadPearState() {

package/dist/syncer/hyperliquid/syncer.js

@@ -11,9 +11,11 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     __name(this, "HyperliquidAccountSyncer");
   }
   address;
+  perpDexNames;
   constructor(config) {
     super(config);
     this.address = config.account.exchangeIdentifier;
+    this.perpDexNames = config.hyperliquidPerpDexNames;
   }
   async listExternalPositions({ instruments }) {
     const instrumentByBase = new Map(instruments.map((instrument) => [
@@ -23,17 +25,12 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
         contractSize: instrument.precision.quantity.contractSize
       }
     ]));
-    const perpDexs = await fetchInfo({
-      type: "perpDexs"
-    }, this.demo);
-    const dexNames = [
-      ...new Set(perpDexs.map((perpDex) => perpDex?.name ?? ""))
-    ];
-    const states = await Promise.all(dexNames.map((dex) => fetchInfo({
+    const dexNames = this.perpDexNames ?? await this.fetchPerpDexNames();
+    const states = await Promise.all(dexNames.map((dex) => this.fetchInfoGated({
       type: "clearinghouseState",
       user: this.address,
       dex
-    }, this.demo)));
+    })));
     const assetPositions = states.flatMap((state) => state.assetPositions);
     return assetPositions.reduce((positions, { position: rawPosition }) => {
       const szi = new BigNumber(rawPosition.szi);
@@ -72,12 +69,12 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     let cursor = since.getTime();
     let batchSize;
     do {
-      const batch = await fetchInfo({
+      const batch = await this.fetchInfoGated({
         type: "userFillsByTime",
         user: this.address,
         startTime: cursor,
         aggregateByTime: true
-      }, this.demo);
+      });
       batchSize = batch.length;
       for (const rawFill of batch) {
         addFill(rawFill);
@@ -93,12 +90,12 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     } while (batchSize === HYPERLIQUID_FILL_PAGE_LIMIT);
     cursor = since.getTime();
     do {
-      const twapBatch = await fetchInfo({
+      const twapBatch = await this.fetchInfoGated({
         type: "userTwapSliceFillsByTime",
         user: this.address,
         startTime: cursor,
         aggregateByTime: true
-      }, this.demo);
+      });
       batchSize = twapBatch.length;
       for (const item of twapBatch) {
         addFill(item.fill);
@@ -149,11 +146,11 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     let cursor = since.getTime();
     let batchSize;
     do {
-      const batch = await fetchInfo({
+      const batch = await this.fetchInfoGated({
         type: "userFunding",
         user: this.address,
         startTime: cursor
-      }, this.demo);
+      });
       batchSize = batch.length;
       for (const event of batch) {
         allEvents.set(`${event.time}:${event.delta.coin}:${event.hash}`, event);
@@ -174,6 +171,33 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
   isReduceOnly(rawFill) {
     return rawFill.dir.includes("Close");
   }
+  /** Fetch the perp-dex descriptors and reduce them to unique dex names ('' = the main dex). */
+  async fetchPerpDexNames() {
+    const perpDexs = await this.fetchInfoGated({
+      type: "perpDexs"
+    });
+    return [
+      ...new Set(perpDexs.map((perpDex) => perpDex?.name ?? ""))
+    ];
+  }
+  /**
+  * Route one info request through the optional throttle seam: gate before the
+  * call, report the response size after, surface a failure before it propagates.
+  */
+  async fetchInfoGated(body) {
+    if (!this.throttle) {
+      return fetchInfo(body, this.demo);
+    }
+    await this.throttle.beforeRequest(body.type);
+    try {
+      const response = await fetchInfo(body, this.demo);
+      this.throttle.afterRequest(body.type, Array.isArray(response) ? response.length : 0);
+      return response;
+    } catch (error) {
+      this.throttle.afterRequestError(body.type, error);
+      throw error;
+    }
+  }
 }
 function warnStalledPagination(stream, cursor) {
   console.warn(`Hyperliquid ${stream} pagination stalled at timestamp ${cursor}; returned history may be incomplete.`);

package/dist/syncer/lighter/syncer.js

@@ -36,7 +36,7 @@ class LighterAccountSyncer extends BaseAccountSyncer {
       instrument.precision.quantity.contractSize
     ]));
     const token = await this.retrieveAuthToken();
-    const response = await fetchAccount(this.accountIndex, token, this.demo);
+    const response = await fetchAccount(this.accountIndex, token, this.demo, this.throttle);
     const rawPositions = response.accounts?.[0]?.positions ?? [];
     return rawPositions.reduce((positions, rawPosition) => {
       const instrumentId = rawPosition.market_id.toString();
@@ -59,7 +59,7 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   async listExternalFills({ since, instruments }) {
     this.assertAuthenticatedSyncAvailable();
     const token = await this.retrieveAuthToken();
-    const trades = await fetchTradesSince(this.accountIndex, token, since, this.demo);
+    const trades = await fetchTradesSince(this.accountIndex, token, since, this.demo, this.throttle);
     const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
     return trades.toSorted((a, b) => a.timestamp - b.timestamp).reduce((fills, rawFill) => {
       const instrumentId = rawFill.market_id.toString();
@@ -92,7 +92,7 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   async listExternalFunding({ since, instruments }) {
     this.assertAuthenticatedSyncAvailable();
     const token = await this.retrieveAuthToken();
-    const fundingEvents = await fetchPositionFundingSince(this.accountIndex, token, since, this.demo);
+    const fundingEvents = await fetchPositionFundingSince(this.accountIndex, token, since, this.demo, this.throttle);
     const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
     return toFundingPaymentEntries(fundingEvents, instrumentIds);
   }

package/dist/tracker/binance/mapper.js

@@ -54,6 +54,8 @@ function mapPositions(raw) {
       size: amt,
       entryPrice: p.entryPrice ?? "0",
       unrealizedPnl: p.unRealizedProfit ?? "0",
+      // Binance states `initialMargin` per position; mapping it is left to its own change.
+      marginUsed: null,
       leverage: p.leverage ?? "0",
       marginType: p.marginType,
       liquidationPrice: p.liquidationPrice || null

package/dist/tracker/binance/tracker.js

@@ -214,6 +214,8 @@ class BinanceAccountTracker extends BaseAccountTracker {
           size: amt,
           entryPrice: risk.entryPrice ?? "0",
           unrealizedPnl: risk.unRealizedProfit ?? "0",
+          // Mapped nowhere on Binance yet — see `mapPositions`.
+          marginUsed: null,
           leverage: risk.leverage ?? "0",
           marginType: risk.marginType,
           liquidationPrice: risk.liquidationPrice || null

package/dist/tracker/bybit/mapper.js

@@ -71,6 +71,8 @@ function mapSinglePosition(p, size) {
     size: size === "0" || size === "" ? "0" : side === "short" ? `-${size}` : size,
     entryPrice: p.avgPrice ?? "0",
     unrealizedPnl: p.unrealisedPnl ?? "0",
+    // Bybit states `positionIM` per position; mapping it is left to its own change.
+    marginUsed: null,
     leverage: p.leverage ?? "0",
     marginType: p.tradeMode === "1" ? "isolated" : "cross",
     liquidationPrice: p.liqPrice || null

package/dist/tracker/hyperliquid/balance.js

@@ -46,6 +46,18 @@ const HyperliquidStandardBalance = AccountBalanceCore.extend({
   unrealizedPnl: SignedDecimalString,
   maintenanceMargin: DecimalString,
   /**
+  * Margin held across every open position, both margin modes together.
+  *
+  * Read from the positions, never derived: `positionValue / leverage` reproduces a cross
+  * position's margin exactly, and misses an isolated one — measured across 683 live positions, all
+  * 662 cross matched and all 21 isolated drifted, because an isolated leg can be topped up and
+  * accrues its own PnL. The venue states each position's figure outright, so this sums those.
+  *
+  * Adds across collateral tokens, so an account holding a non-USDC HIP-3 dex reads a total in no
+  * single currency — the same limit `accountValue` and `unrealizedPnl` carry on this variant.
+  */
+  marginUsed: DecimalString,
+  /**
   * The cross pool's own utilisation: Σ `crossMaintenanceMarginUsed` over Σ `crossMarginSummary
   * .accountValue`, aggregated across every dex before the single division.
   *
@@ -90,6 +102,8 @@ const HyperliquidUnifiedBalance = AccountBalanceCore.extend({
   unrealizedPnl: SignedDecimalString,
   /** Cross maintenance only — isolated legs carry their own margin. */
   perpsMaintenanceMargin: DecimalString,
+  /** Margin held across every open position, both modes — read per position, never derived. */
+  marginUsed: DecimalString,
   unifiedAccountRatio: DecimalString,
   /**
   * Cross notional over the COLLATERAL backing it — the spot holdings of the dex collateral tokens,
@@ -158,6 +172,8 @@ const HyperliquidPortfolioMarginBalance = AccountBalanceCore.extend({
   portfolioValue: DecimalString.nullable(),
   unrealizedPnl: SignedDecimalString,
   perpsMaintenanceMargin: DecimalString,
+  /** Margin held across every open position, both modes — read per position, never derived. */
+  marginUsed: DecimalString,
   /**
   * The venue's own `spotClearinghouseState.portfolioMarginRatio`, clipped at `1.0000` by the
   * venue itself. Null when the wire states none.

package/dist/tracker/hyperliquid/mapper.js

@@ -29,12 +29,14 @@ function aggregateClearinghouseStates(states) {
         position.position.marginUsed
       ];
     })).toFixed();
+    const marginUsed = sum(positions.map((position) => position.position.marginUsed)).toFixed();
     summary.accountValue = add(summary.accountValue, state.marginSummary.accountValue);
     summary.crossAccountValue = add(summary.crossAccountValue, state.crossMarginSummary.accountValue);
     summary.crossNotional = add(summary.crossNotional, state.crossMarginSummary.totalNtlPos);
     summary.crossMaintenanceMarginUsed = add(summary.crossMaintenanceMarginUsed, state.crossMaintenanceMarginUsed);
     summary.withdrawable = add(summary.withdrawable, state.withdrawable);
     summary.totalUnrealizedPnl = add(summary.totalUnrealizedPnl, unrealizedPnl);
+    summary.totalMarginUsed = add(summary.totalMarginUsed, marginUsed);
     assetPositions.push(...positions);
     summary.perDexState.push({
       dex: dexState.dex,
@@ -77,6 +79,7 @@ function emptyClearinghouseSummary() {
     crossMaintenanceMarginUsed: "0",
     withdrawable: "0",
     totalUnrealizedPnl: "0",
+    totalMarginUsed: "0",
     byCollateralToken: /* @__PURE__ */ new Map(),
     perDexState: []
   };
@@ -115,6 +118,8 @@ function mapPositions(raw) {
       size: size.toFixed(),
       entryPrice: position.entryPx || "0",
       unrealizedPnl: position.unrealizedPnl || "0",
+      // Read, never derived: an isolated leg can be topped up, so its margin outruns value/leverage.
+      marginUsed: position.marginUsed || null,
       leverage: position.leverage.value.toString(),
       marginType: position.leverage.type,
       liquidationPrice: position.liquidationPx || null
@@ -157,6 +162,8 @@ function mapStandardBalance(context) {
     unrealizedPnl: signed(context.summary.totalUnrealizedPnl),
     // Cross-only: isolated legs carry their own margin and liquidate independently.
     maintenanceMargin: context.summary.crossMaintenanceMarginUsed,
+    // Both modes, unlike the maintenance figure above: every position's margin is margin committed.
+    marginUsed: context.summary.totalMarginUsed,
     // Risk levers against ACCOUNT VALUE, not the cash above: one pool, one quotient, one division.
     crossMarginRatio: ratio(context.summary.crossMaintenanceMarginUsed, context.summary.crossAccountValue),
     crossAccountLeverage: accountLeverage(context.summary.crossNotional, context.summary.crossAccountValue),
@@ -189,6 +196,8 @@ function mapUnifiedBalance(context) {
     unrealizedPnl: signed(context.summary.totalUnrealizedPnl),
     // Cross-only: adding isolated maintenance overstated the figure by 2x against the venue's UI.
     perpsMaintenanceMargin: context.summary.crossMaintenanceMarginUsed,
+    // Both modes, unlike the maintenance figure above: every position's margin is margin committed.
+    marginUsed: context.summary.totalMarginUsed,
     unifiedAccountRatio: crossRatioAgainstFreeSpot(context),
     unifiedAccountLeverage: unifiedAccountLeverage(context),
     perDexState: context.summary.perDexState,
@@ -218,6 +227,8 @@ function mapPortfolioMarginBalance(context) {
     portfolioValue: tradingEquity,
     unrealizedPnl: signed(context.summary.totalUnrealizedPnl),
     perpsMaintenanceMargin: context.summary.crossMaintenanceMarginUsed,
+    // Both modes, unlike the maintenance figure above: every position's margin is margin committed.
+    marginUsed: context.summary.totalMarginUsed,
     portfolioMarginRatio: wireMarginRatio(context),
     portfolioAccountLeverage: portfolioAccountLeverage(context),
     borrowCapUsed: worstBorrowCapUsed(context),

package/dist/tracker/lighter/balance.js

@@ -34,6 +34,22 @@ const lighterShared = {
   */
   unrealizedPnl: SignedDecimalString.nullable(),
   /**
+  * Margin held across every open position, both margin modes together.
+  *
+  * Summed from the positions, because the venue publishes no one field for it: `/account` states
+  * the cross requirement alone and `user_stats` states neither. Over cross positions the sum
+  * reproduces the venue's own `cross_initial_margin_requirement` exactly — rounded half-up at six
+  * decimals, the way the venue states a requirement — and an isolated leg adds the collateral it
+  * holds on top, the same both-modes reading `maintenanceMargin` takes.
+  *
+  * Rounded once, over the exact total: the per-position figures round individually, so adding
+  * those up can miss this by a decimal's last place. This is the figure that matches the venue.
+  *
+  * Null when ANY position's own margin is unreadable, for the reason `unrealizedPnl` is: a total
+  * missing one term is not a smaller version of the answer.
+  */
+  marginUsed: DecimalString.nullable(),
+  /**
   * Cross exposure over cross equity.
   *
   * A MULTIPLE, not a ratio: `0.72` reads 0.72x, and the venue publishes it that way in both

package/dist/tracker/lighter/mapper.js

@@ -28,6 +28,7 @@ function mapLiveBalance(stats, assets, positions, markets, timestamp) {
     equity,
     perCollateral,
     unrealizedPnl: signed(sumUnrealizedPnl(openPositions)),
+    marginUsed: usdOrNull(asMarginRequirement(sumMarginUsed(risks))),
     // The venue states leverage and usage outright here and REST derives them, so each pair meets
     // at one formatter — otherwise the paths would agree only while the venue kept its precision.
     // Usage arrives in percent points and leaves as a fraction, which is the venue's scale changed.
@@ -57,6 +58,7 @@ function mapRestBalance(account, markets, timestamp) {
     equity,
     perCollateral,
     unrealizedPnl: signed(sumUnrealizedPnl(positions)),
+    marginUsed: usdOrNull(asMarginRequirement(sumMarginUsed(risks))),
     crossLeverage: multipleOf(sumNotional(risks, "cross"), crossEquity),
     crossMarginUsage: fractionOf(toDecimal(account.cross_initial_margin_requirement), crossEquity),
     crossMarginRatio: fractionOf(crossMaintenance, crossEquity),
@@ -91,6 +93,7 @@ function mapPositions(raw, includeZeroPositions = false) {
       size: size.isFinite() && !size.isZero() ? size.toFixed() : "0",
       entryPrice: rawPosition.avg_entry_price || "0",
       unrealizedPnl: rawPosition.unrealized_pnl || "0",
+      marginUsed: usdOrNull(asMarginRequirement(positionMarginUsed(rawPosition))),
       leverage,
       marginType,
       liquidationPrice: rawPosition.liquidation_price && rawPosition.liquidation_price !== "0" ? rawPosition.liquidation_price : null
@@ -181,6 +184,7 @@ function toLighterBalance(figures) {
     stakingEquity: null,
     creditedInLit: null,
     unrealizedPnl: figures.unrealizedPnl,
+    marginUsed: figures.marginUsed,
     crossLeverage: figures.crossLeverage,
     maintenanceMargin: figures.maintenanceMargin,
     crossMarginUsage: figures.crossMarginUsage,
@@ -301,12 +305,29 @@ function toPositionRisks(positions, perpByMarketId) {
     risks.push({
       marginMode: position.margin_mode === 1 ? "isolated" : "cross",
       notional,
+      marginUsed: positionMarginUsed(position),
       maintenance: notional === null || maintenanceFraction === null ? null : notional.times(maintenanceFraction).div(MARGIN_FRACTION_SCALE)
     });
   }
   return risks;
 }
 __name(toPositionRisks, "toPositionRisks");
+function positionMarginUsed(position) {
+  if (position.margin_mode === 1) {
+    return toDecimal(position.allocated_margin);
+  }
+  const positionValue = toDecimal(position.position_value);
+  const initialMarginFraction = toDecimal(position.initial_margin_fraction);
+  if (positionValue === null || initialMarginFraction === null || initialMarginFraction.lte(0)) {
+    return null;
+  }
+  return positionValue.abs().times(initialMarginFraction).div(PERCENT_SCALE);
+}
+__name(positionMarginUsed, "positionMarginUsed");
+function sumMarginUsed(risks) {
+  return sumOf(risks.map((risk) => risk.marginUsed));
+}
+__name(sumMarginUsed, "sumMarginUsed");
 function sumMaintenance(risks, marginMode) {
   return sumOf(risks.filter((risk) => risk.marginMode === marginMode).map((risk) => risk.maintenance));
 }

package/dist/tracker/lighter/tracker.js

@@ -46,11 +46,13 @@ class LighterAccountTracker extends BaseAccountTracker {
   startInFlight = null;
   lifecycleVersion = 0;
   wsConnectionVersion = 0;
-  stateVersion = 0;
+  // Bumped only where position state actually moves, so an in-flight REST read is invalidated by
+  // a frame that carries positions and never by one that carries the account figures alone.
+  positionStateVersion = 0;
   assetsByAssetId = /* @__PURE__ */ new Map();
-  // Written only by `account_all`. The live balance reads its unrealized PnL and maintenance
-  // margin from here, so keeping REST out of it is what makes that balance wholly websocket-derived.
-  wsPositionsByMarketId = /* @__PURE__ */ new Map();
+  // Written by `account_all` and by the REST poll, whichever read the account last. The live
+  // balance takes its unrealized PnL and its maintenance margin from here.
+  positionsByMarketId = /* @__PURE__ */ new Map();
   marketsByMarketId = /* @__PURE__ */ new Map();
   marketsBySymbol = /* @__PURE__ */ new Map();
   // Seeded empty, which still prices the quote asset — spot dollars are dollars before any
@@ -222,9 +224,9 @@ class LighterAccountTracker extends BaseAccountTracker {
   handleWsOpen() {
     const wsConnectionVersion = ++this.wsConnectionVersion;
     this.clearSubscribeRetry();
-    this.stateVersion += 1;
+    this.positionStateVersion += 1;
     this.assetsByAssetId.clear();
-    this.wsPositionsByMarketId.clear();
+    this.positionsByMarketId.clear();
     this.stats = null;
     this.hasAssets = false;
     this.resetAccountState();
@@ -240,10 +242,10 @@ class LighterAccountTracker extends BaseAccountTracker {
   /**
   * Subscribes this socket epoch's account channels, and keeps trying until one attempt lands.
   *
-  * This is the sole subscriber of `account_all` and `user_stats`, and the live balance is built
-  * from those two channels alone — see `buildBalance`. A mint that failed once and was never
-  * retried therefore left the tracker connected but permanently unsubscribed: the 2s REST poll
-  * kept positions moving while the balance silently froze until some incidental reconnect.
+  * This is the sole subscriber of `account_all` and `user_stats`, and no balance exists without
+  * both — see `buildBalance`. A mint that failed once and was never retried therefore left the
+  * tracker connected but permanently unsubscribed: the 2s REST poll kept positions moving while
+  * the balance stayed null until some incidental reconnect.
   *
   * The wait doubles up to a ceiling, and only a new connection epoch or teardown ends it.
   */
@@ -303,7 +305,7 @@ class LighterAccountTracker extends BaseAccountTracker {
     }
   }
   onAccountAll(data) {
-    this.stateVersion += 1;
+    this.positionStateVersion += 1;
     const update = {};
     const isSnapshot = data.type === "subscribed/account_all";
     if (data.assets) {
@@ -320,20 +322,20 @@ class LighterAccountTracker extends BaseAccountTracker {
         ...data.positions
       };
       if (isSnapshot) {
-        this.wsPositionsByMarketId.clear();
+        this.positionsByMarketId.clear();
       }
       for (const [marketId, position] of Object.entries(data.positions)) {
         if (isZeroSize(position.position)) {
-          const previousPosition = this.wsPositionsByMarketId.get(marketId);
+          const previousPosition = this.positionsByMarketId.get(marketId);
           if (previousPosition) {
             positionsForMapping[marketId] = {
               ...position,
               sign: previousPosition.sign
             };
           }
-          this.wsPositionsByMarketId.delete(marketId);
+          this.positionsByMarketId.delete(marketId);
         } else {
-          this.wsPositionsByMarketId.set(marketId, position);
+          this.positionsByMarketId.set(marketId, position);
         }
       }
       const { positions, trackedAssets } = mapPositions(positionsForMapping, !isSnapshot);
@@ -347,7 +349,6 @@ class LighterAccountTracker extends BaseAccountTracker {
   }
   /** Keeps both published scopes: cross drives every "Cross" field, total drives the account ones. */
   onUserStats(data) {
-    this.stateVersion += 1;
     const stats = data.stats;
     this.stats = {
       accountType: toLighterAccountType(stats.account_trading_mode),
@@ -360,20 +361,22 @@ class LighterAccountTracker extends BaseAccountTracker {
     });
   }
   /**
-  * The account's balance, built from websocket state alone.
+  * The account's balance, from the freshest state each of its parts has.
   *
-  * Every input is websocket-sourced — `user_stats` for the two account scopes, `account_all` for
-  * the assets and positions — except the market context, which is venue-wide metadata this
-  * tracker re-reads on its own timer. This is the ONLY producer of the value `getBalance()`
-  * returns while the tracker is running; `snapshot()` is the separate REST path and never writes
-  * here.
+  * The two account scopes come from `user_stats` and the assets from `account_all`, both
+  * websocket-only. The positions come from whichever source read the account last — a frame, or
+  * the REST poll that keeps them moving while the socket says nothing (see
+  * `performPositionPoll`). The market context is venue-wide metadata on its own timer.
+  *
+  * This is the ONLY producer of the value `getBalance()` returns while the tracker is running;
+  * `snapshot()` is the separate one-shot path and never writes here.
   *
   * Null until both channels have delivered a frame, because a balance built from one of them
   * would be missing half the account.
   */
   buildBalance() {
     if (!this.stats || !this.hasAssets) return null;
-    return mapLiveBalance(this.stats, this.assetsByAssetId.values(), this.wsPositionsByMarketId.values(), this.marketContext(), Date.now());
+    return mapLiveBalance(this.stats, this.assetsByAssetId.values(), this.positionsByMarketId.values(), this.marketContext(), Date.now());
   }
   /** The market data both read paths join account state against, as the latest read left it. */
   marketContext() {
@@ -419,8 +422,8 @@ class LighterAccountTracker extends BaseAccountTracker {
   pollPositions() {
     if (this.positionPollInFlight) return this.positionPollInFlight;
     const lifecycleVersion = this.lifecycleVersion;
-    const stateVersion = this.stateVersion;
-    const poll = this.performPositionPoll(lifecycleVersion, stateVersion).finally(() => {
+    const positionStateVersion = this.positionStateVersion;
+    const poll = this.performPositionPoll(lifecycleVersion, positionStateVersion).finally(() => {
       if (this.positionPollInFlight === poll) {
         this.positionPollInFlight = null;
       }
@@ -429,28 +432,52 @@ class LighterAccountTracker extends BaseAccountTracker {
     return poll;
   }
   /**
-  * Republishes positions and per-market settings from REST.
+  * Republishes positions, per-market settings, and the balance those positions move.
+  *
+  * This is what keeps the account's open result alive. Lighter republishes `account_all` when the
+  * account itself changes and not when the mark moves, so between fills the position rows hold
+  * whatever the last frame left them at. A balance built on those rows stated a dead unrealized
+  * PnL and a dead maintenance margin beside the live `user_stats` figures — and restated them on
+  * every frame under a current timestamp, so nothing marked them as old. The venue's own account
+  * read is the only source that carries the new figures, so the poll adopts it wholesale.
+  *
+  * The rows land in the same store `account_all` writes, which is what keeps `getPositions()` and
+  * the balance's `unrealizedPnl` stating one account rather than two.
   *
-  * Deliberately publishes NO balance. Every field of both Lighter variants comes off the two
-  * websocket channels — `user_stats` carries both account scopes and `account_all` carries the
-  * assets and positions behind them — so a REST balance here would only overwrite a live value
-  * with an equal one, while making `getBalance()` REST-derived most of the time.
+  * A read is dropped whole when a frame moved the position state while it was in flight: that
+  * frame is the newer account. `user_stats` deliberately does not invalidate one — it carries the
+  * account scopes and no positions at all, and a venue publishing it every tick would otherwise
+  * cancel every poll and freeze the very figures this read exists to move.
   *
-  * It also leaves `wsPositionsByMarketId` alone. That store feeds the live balance's unrealized
-  * PnL and maintenance margin, so writing REST rows into it would make a balance labelled live
-  * partly REST-derived without any reader being able to tell.
+  * No balance leaves here while the socket is down. The account scopes and the assets are dropped
+  * on the next open rather than on the drop, so a balance published mid-outage would pair these
+  * fresh positions with figures frozen at the drop — worst of it a cross margin ratio measured
+  * against a portfolio value the account no longer has. Positions still publish: they are whole.
   */
-  async performPositionPoll(lifecycleVersion, stateVersion) {
+  async performPositionPoll(lifecycleVersion, positionStateVersion) {
     try {
       const account = await this.fetchPrimaryAccount();
       if (lifecycleVersion !== this.lifecycleVersion) return;
-      if (!account || stateVersion !== this.stateVersion) return;
-      const { positions, trackedAssets } = mapPositions(toPosRecord(account.positions ?? []), true);
-      this.onStateUpdate({
+      if (!account || positionStateVersion !== this.positionStateVersion) return;
+      const rawPositions = account.positions ?? [];
+      this.positionsByMarketId.clear();
+      for (const position of rawPositions) {
+        if (isZeroSize(position.position)) {
+          continue;
+        }
+        this.positionsByMarketId.set(String(position.market_id), position);
+      }
+      const { positions, trackedAssets } = mapPositions(toPosRecord(rawPositions), true);
+      const update = {
         positions,
         positionsMode: "replace",
         trackedAssets
-      });
+      };
+      const balance = this.isConnected ? this.buildBalance() : null;
+      if (balance) {
+        update.balance = balance;
+      }
+      this.onStateUpdate(update);
     } catch (err) {
       if (lifecycleVersion === this.lifecycleVersion) {
         this.onError(err instanceof Error ? err : new Error(String(err)));

package/dist/tracker/okx/mapper.js

@@ -88,6 +88,8 @@ function mapSinglePosition(p) {
     size,
     entryPrice: p.avgPx ?? "0",
     unrealizedPnl: p.upl ?? "0",
+    // OKX states `imr` per position; mapping it is left to its own change.
+    marginUsed: null,
     leverage: p.lever ?? "0",
     marginType,
     liquidationPrice: p.liqPx || null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -27,9 +27,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@pear-protocol/core-sdk": "^1.19.3",
-    "@pear-protocol/types": "^1.31.0",
-    "@pear-protocol/utils": "^0.8.0",
+    "@pear-protocol/core-sdk": "^1.20.0",
+    "@pear-protocol/types": "^1.32.0",
+    "@pear-protocol/utils": "^0.8.1",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8",