@pear-protocol/exchanges-sdk 0.13.0 → 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/index.d.ts

@@ -1245,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<{
@@ -1274,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<{
@@ -1305,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>;
@@ -1335,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>;
@@ -1360,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>;
@@ -1566,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;
@@ -1953,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<{
@@ -1984,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<{
@@ -2043,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>;
@@ -2177,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>;
@@ -2204,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>;
@@ -2236,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;
@@ -2287,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.
      */
@@ -2305,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.
+     *
+     * 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.
      *
-     * 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.
+     * 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.
@@ -2329,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;
     /**

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.13.0",
+  "version": "0.14.0",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",