@pear-protocol/exchanges-sdk 0.3.0 → 0.4.0

package/dist/tracker/bybit/tracker.test.js

@@ -0,0 +1,145 @@
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+import { BybitAccountTracker } from './tracker';
+
+const { fetchWalletBalanceMock, fetchPositionsMock, fetchAccountInfoMock, fetchPositionLeverageMock } = vi.hoisted(
+  () => ({
+    fetchWalletBalanceMock: vi.fn(),
+    fetchPositionsMock: vi.fn(),
+    fetchAccountInfoMock: vi.fn(),
+    fetchPositionLeverageMock: vi.fn()
+  })
+);
+vi.mock("../../client/bybit/rest", () => ({
+  fetchWalletBalance: fetchWalletBalanceMock,
+  fetchPositions: fetchPositionsMock,
+  fetchAccountInfo: fetchAccountInfoMock,
+  fetchPositionLeverage: fetchPositionLeverageMock
+}));
+const creds = { api_key: "k", api_secret: "s" };
+function buildTracker() {
+  return new BybitAccountTracker({ demo: true, credentials: creds });
+}
+describe("BybitAccountTracker.snapshot", () => {
+  beforeEach(() => {
+    fetchWalletBalanceMock.mockReset();
+    fetchPositionsMock.mockReset();
+    fetchAccountInfoMock.mockReset();
+  });
+  it("returns mapped balance + positions across USDT and USDC settle coins with no socket opened", async () => {
+    fetchWalletBalanceMock.mockResolvedValue({
+      totalEquity: "2000",
+      totalWalletBalance: "2000",
+      totalMarginBalance: "2000",
+      totalAvailableBalance: "1800",
+      totalPerpUPL: "50",
+      totalInitialMargin: "100",
+      totalMaintenanceMargin: "20",
+      accountMMRate: "0.0100",
+      coin: [
+        {
+          coin: "USDT",
+          equity: "2000",
+          usdValue: "2000",
+          walletBalance: "2000",
+          unrealisedPnl: "50",
+          totalPositionIM: "100",
+          totalPositionMM: "20",
+          totalOrderIM: "0",
+          locked: "0",
+          borrowAmount: "0",
+          marginCollateral: true,
+          collateralSwitch: true
+        }
+      ]
+    });
+    fetchPositionsMock.mockImplementation(async (_creds, settleCoin) => {
+      if (settleCoin === "USDT") {
+        return [
+          {
+            symbol: "BTCUSDT",
+            side: "Buy",
+            size: "1",
+            avgPrice: "50000",
+            unrealisedPnl: "10",
+            leverage: "5",
+            tradeMode: "0",
+            liqPrice: "40000"
+          }
+        ];
+      }
+      return [];
+    });
+    fetchAccountInfoMock.mockResolvedValue({ marginMode: "REGULAR_MARGIN", updatedTime: "0" });
+    const snapshot = await buildTracker().snapshot();
+    expect(snapshot.balance).toMatchObject({
+      accountType: "REGULAR_MARGIN",
+      totalEquity: "2000",
+      availableToTrade: "1800",
+      maintenanceMargin: "20",
+      marginRatio: "0.0100"
+    });
+    expect(snapshot.positions).toHaveLength(1);
+    expect(snapshot.positions[0]).toMatchObject({
+      symbol: "BTCUSDT",
+      side: "long",
+      leverage: "5",
+      marginType: "cross",
+      liquidationPrice: "40000"
+    });
+    expect(fetchPositionsMock).toHaveBeenCalledWith(creds, "USDT", true);
+    expect(fetchPositionsMock).toHaveBeenCalledWith(creds, "USDC", true);
+    expect(fetchPositionLeverageMock).not.toHaveBeenCalled();
+  });
+  it("returns a null balance when the wallet fetch is empty", async () => {
+    fetchWalletBalanceMock.mockResolvedValue(void 0);
+    fetchPositionsMock.mockResolvedValue([]);
+    fetchAccountInfoMock.mockResolvedValue({ marginMode: "REGULAR_MARGIN", updatedTime: "0" });
+    const snapshot = await buildTracker().snapshot();
+    expect(snapshot.balance).toBeNull();
+    expect(snapshot.positions).toEqual([]);
+  });
+});
+describe("BybitAccountTracker.snapshotAssets", () => {
+  beforeEach(() => {
+    fetchPositionsMock.mockReset();
+    fetchPositionLeverageMock.mockReset();
+  });
+  it(">2 symbols: resolves positioned symbols from the two settleCoin reads and fills in the rest per symbol", async () => {
+    fetchPositionsMock.mockImplementation(
+      async (_creds, settleCoin) => settleCoin === "USDT" ? [
+        { symbol: "BTCUSDT", size: "1", leverage: "10", tradeMode: "0" },
+        { symbol: "ETHUSDT", size: "2", leverage: "5", tradeMode: "1" }
+      ] : []
+    );
+    fetchPositionLeverageMock.mockResolvedValue({ symbol: "DOGEUSDT", size: "0", leverage: "3", tradeMode: "0" });
+    const result = await buildTracker().snapshotAssets(["BTCUSDT", "ETHUSDT", "DOGEUSDT"]);
+    expect(fetchPositionsMock).toHaveBeenCalledTimes(2);
+    expect(fetchPositionLeverageMock).toHaveBeenCalledTimes(1);
+    expect(fetchPositionLeverageMock).toHaveBeenCalledWith(creds, "DOGEUSDT", true);
+    expect(result).toEqual({
+      BTCUSDT: { coin: "BTCUSDT", leverage: "10", marginType: "cross" },
+      ETHUSDT: { coin: "ETHUSDT", leverage: "5", marginType: "isolated" },
+      DOGEUSDT: { coin: "DOGEUSDT", leverage: "3", marginType: "cross" }
+    });
+  });
+  it("\u22642 symbols: skips the settleCoin batch and reads per symbol directly", async () => {
+    fetchPositionLeverageMock.mockResolvedValue({ symbol: "BTCUSDT", size: "0", leverage: "10", tradeMode: "0" });
+    const result = await buildTracker().snapshotAssets(["BTCUSDT"]);
+    expect(fetchPositionsMock).not.toHaveBeenCalled();
+    expect(fetchPositionLeverageMock).toHaveBeenCalledTimes(1);
+    expect(result.BTCUSDT).toEqual({ coin: "BTCUSDT", leverage: "10", marginType: "cross" });
+  });
+  it("maps a failed fill-in to null while the others succeed", async () => {
+    fetchPositionLeverageMock.mockImplementation(async (_creds, symbol) => {
+      if (symbol === "NOPEUSDT") throw new Error("10001");
+      return { symbol, size: "0", leverage: "10", tradeMode: "0" };
+    });
+    const result = await buildTracker().snapshotAssets(["BTCUSDT", "NOPEUSDT"]);
+    expect(result.BTCUSDT).toMatchObject({ leverage: "10", marginType: "cross" });
+    expect(result.NOPEUSDT).toBeNull();
+  });
+  it("throws when every per-symbol read fails", async () => {
+    fetchPositionLeverageMock.mockRejectedValue(new Error("down"));
+    await expect(buildTracker().snapshotAssets(["BTCUSDT", "ETHUSDT"])).rejects.toThrow("every position read failed");
+  });
+});

package/dist/tracker/hyperliquid/mapper.js

@@ -1,35 +1,141 @@
 import BigNumber from 'bignumber.js';
 import { positionKey } from '../utils';
-import { COLLATERAL_TOKEN_MAP } from './types';
+import { COLLATERAL_TOKEN_MAP, HyperliquidAccountType } from './types';
 
-const COLLATERAL_COINS = new Set(Object.values(COLLATERAL_TOKEN_MAP));
-function mapBalance(summary, spotCoinBalances, accountType, availableToTradeByCollateral) {
-  if (!accountType) return null;
+const LEGACY_COLLATERAL_TOKEN_MAP = new Map(
+  Object.entries(COLLATERAL_TOKEN_MAP).map(([token, coin]) => [Number(token), coin])
+);
+const FULL_UTILIZATION_RATIO = "1.0000";
+const ZERO_COLLATERAL_SUMMARY = {
+  accountValue: "0",
+  totalMarginUsed: "0",
+  crossMaintenanceMarginUsed: "0",
+  isolatedMaintenanceMarginUsed: "0",
+  isolatedMarginUsed: "0",
+  withdrawable: "0",
+  totalUnrealizedPnl: "0"
+};
+function aggregateClearinghouseStates(states) {
+  const summary = {
+    accountValue: "0",
+    totalMarginUsed: "0",
+    totalRawUsd: "0",
+    crossMaintenanceMarginUsed: "0",
+    isolatedMaintenanceMarginUsed: "0",
+    maximumStandardMarginRatio: "0.0000",
+    withdrawable: "0",
+    totalUnrealizedPnl: "0",
+    byCollateralToken: /* @__PURE__ */ new Map()
+  };
+  const assetPositions = [];
+  for (const dexState of states) {
+    const state = dexState.state;
+    const positions = state.assetPositions ?? [];
+    const unrealizedPnl = sum(positions.map((position) => position.position.unrealizedPnl));
+    const isolatedRisks = positions.flatMap((position) => {
+      if (position.position.leverage.type !== "isolated") {
+        return [];
+      }
+      return [{ collateral: position.position.marginUsed, maintenance: isolatedMaintenanceMargin(dexState, position) }];
+    });
+    const isolatedMaintenanceMarginUsed = sum(isolatedRisks.map((risk) => risk.maintenance));
+    const isolatedMarginUsed = sum(isolatedRisks.map((risk) => risk.collateral));
+    let dexMaximumMarginRatio = ratio(state.crossMaintenanceMarginUsed, state.crossMarginSummary.accountValue);
+    for (const isolatedRisk of isolatedRisks) {
+      dexMaximumMarginRatio = BigNumber.max(
+        dexMaximumMarginRatio,
+        ratio(isolatedRisk.maintenance, isolatedRisk.collateral)
+      ).toFixed(4);
+    }
+    summary.accountValue = add(summary.accountValue, state.marginSummary.accountValue);
+    summary.totalMarginUsed = add(summary.totalMarginUsed, state.marginSummary.totalMarginUsed);
+    summary.totalRawUsd = add(summary.totalRawUsd, state.marginSummary.totalRawUsd);
+    summary.crossMaintenanceMarginUsed = add(summary.crossMaintenanceMarginUsed, state.crossMaintenanceMarginUsed);
+    summary.isolatedMaintenanceMarginUsed = add(summary.isolatedMaintenanceMarginUsed, isolatedMaintenanceMarginUsed);
+    summary.maximumStandardMarginRatio = BigNumber.max(
+      summary.maximumStandardMarginRatio,
+      dexMaximumMarginRatio
+    ).toFixed(4);
+    summary.withdrawable = add(summary.withdrawable, state.withdrawable);
+    summary.totalUnrealizedPnl = add(summary.totalUnrealizedPnl, unrealizedPnl);
+    assetPositions.push(...positions);
+    if (dexState.collateralToken === null) {
+      continue;
+    }
+    const collateral = summary.byCollateralToken.get(dexState.collateralToken) ?? ZERO_COLLATERAL_SUMMARY;
+    summary.byCollateralToken.set(dexState.collateralToken, {
+      accountValue: add(collateral.accountValue, state.marginSummary.accountValue),
+      totalMarginUsed: add(collateral.totalMarginUsed, state.marginSummary.totalMarginUsed),
+      crossMaintenanceMarginUsed: add(collateral.crossMaintenanceMarginUsed, state.crossMaintenanceMarginUsed),
+      isolatedMaintenanceMarginUsed: add(collateral.isolatedMaintenanceMarginUsed, isolatedMaintenanceMarginUsed),
+      isolatedMarginUsed: add(collateral.isolatedMarginUsed, isolatedMarginUsed),
+      withdrawable: add(collateral.withdrawable, state.withdrawable),
+      totalUnrealizedPnl: add(collateral.totalUnrealizedPnl, unrealizedPnl)
+    });
+  }
+  return { summary, assetPositions };
+}
+function mapBalance(summary, spotCoinBalances, accountType, collateralTokenMap = LEGACY_COLLATERAL_TOKEN_MAP) {
+  if (!accountType) {
+    return null;
+  }
+  switch (accountType) {
+    case HyperliquidAccountType.DEFAULT:
+    case HyperliquidAccountType.DISABLED:
+      return mapStandardBalance(summary, accountType, collateralTokenMap);
+    case HyperliquidAccountType.UNIFIED_ACCOUNT:
+      return mapUnifiedBalance(summary, spotCoinBalances, accountType, collateralTokenMap);
+    case HyperliquidAccountType.DEX_ABSTRACTION:
+    case HyperliquidAccountType.PORTFOLIO_MARGIN:
+      return null;
+  }
+}
+function mapPositions(raw) {
+  const positions = /* @__PURE__ */ new Map();
+  for (const assetPosition of raw) {
+    const position = assetPosition.position;
+    const size = new BigNumber(position.szi || "0");
+    if (size.isZero()) {
+      continue;
+    }
+    const coin = position.coin || "";
+    const side = size.isPositive() ? "long" : "short";
+    positions.set(positionKey(coin, side), {
+      symbol: coin,
+      side,
+      size: size.toFixed(),
+      entryPrice: position.entryPx || "0",
+      unrealizedPnl: position.unrealizedPnl || "0",
+      leverage: position.leverage.value.toString(),
+      marginType: position.leverage.type,
+      liquidationPrice: position.liquidationPx || null
+    });
+  }
+  return positions;
+}
+function mapStandardBalance(summary, accountType, collateralTokenMap) {
   const free = {};
   const used = {};
   const total = {};
   const assets = [];
-  for (const [, coin] of spotCoinBalances) {
-    if (!COLLATERAL_COINS.has(coin.coin)) continue;
-    const availableOverride = availableToTradeByCollateral.get(coin.coin);
-    const coinFree = availableOverride !== void 0 ? availableOverride : new BigNumber(coin.total).minus(coin.hold).toFixed();
-    const coinUsed = coin.hold;
-    const coinTotal = coin.total;
-    free[coin.coin] = coinFree;
-    used[coin.coin] = coinUsed;
-    total[coin.coin] = coinTotal;
+  for (const [token, collateral] of summary.byCollateralToken) {
+    const coin = collateralTokenMap.get(token);
+    if (!coin) {
+      continue;
+    }
+    free[coin] = collateral.withdrawable;
+    used[coin] = collateral.totalMarginUsed;
+    total[coin] = collateral.accountValue;
     assets.push({
-      asset: coin.coin,
-      free: coinFree,
-      used: coinUsed,
-      total: coinTotal,
-      walletBalance: coinTotal,
-      usdValue: coinTotal
+      asset: coin,
+      free: collateral.withdrawable,
+      used: collateral.totalMarginUsed,
+      total: collateral.accountValue,
+      walletBalance: subtract(collateral.accountValue, collateral.totalUnrealizedPnl),
+      usdValue: collateral.accountValue
     });
   }
-  const accountValueBN = new BigNumber(summary.accountValue);
-  const walletBalance = accountValueBN.minus(summary.totalUnrealizedPnl).toFixed();
-  const marginRatio = accountValueBN.gt(0) ? new BigNumber(summary.crossMaintenanceMarginUsed).div(accountValueBN).toFixed(4) : "0.0000";
+  const maintenanceMargin = add(summary.crossMaintenanceMarginUsed, summary.isolatedMaintenanceMarginUsed);
   return {
     accountType,
     free,
@@ -37,35 +143,129 @@ function mapBalance(summary, spotCoinBalances, accountType, availableToTradeByCo
     total,
     availableToTrade: summary.withdrawable,
     totalEquity: summary.accountValue,
-    walletBalance,
+    walletBalance: subtract(summary.accountValue, summary.totalUnrealizedPnl),
     unrealizedPnl: summary.totalUnrealizedPnl,
     initialMarginUsed: summary.totalMarginUsed,
-    maintenanceMargin: summary.crossMaintenanceMarginUsed,
-    marginRatio,
+    maintenanceMargin,
+    marginRatio: summary.maximumStandardMarginRatio,
     assets,
     timestamp: Date.now()
   };
 }
-function mapPositions(raw) {
-  const positions = /* @__PURE__ */ new Map();
-  for (const ap of raw) {
-    const pos = ap.position;
-    const sziBN = new BigNumber(pos.szi || "0");
-    if (sziBN.isZero()) continue;
-    const coin = pos.coin || "";
-    const side = sziBN.isPositive() ? "long" : "short";
-    positions.set(positionKey(coin, side), {
-      symbol: coin,
-      side,
-      size: sziBN.toFixed(),
-      entryPrice: pos.entryPx || "0",
-      unrealizedPnl: pos.unrealizedPnl || "0",
-      leverage: pos.leverage.value.toString(),
-      marginType: pos.leverage.type,
-      liquidationPrice: pos.liquidationPx || null
+function mapUnifiedBalance(summary, spotCoinBalances, accountType, collateralTokenMap) {
+  const free = {};
+  const used = {};
+  const total = {};
+  const assets = [];
+  let totalEquity = new BigNumber(0);
+  let availableToTrade = new BigNumber(0);
+  for (const balance of spotCoinBalances.values()) {
+    if (!collateralTokenMap.has(balance.token)) {
+      continue;
+    }
+    const collateral = summary.byCollateralToken.get(balance.token) ?? ZERO_COLLATERAL_SUMMARY;
+    const coinUsed = balance.hold;
+    const coinFree = subtract(balance.total, coinUsed);
+    const coinWalletBalance = subtract(balance.total, collateral.totalUnrealizedPnl);
+    free[balance.coin] = coinFree;
+    used[balance.coin] = coinUsed;
+    total[balance.coin] = balance.total;
+    totalEquity = totalEquity.plus(balance.total);
+    availableToTrade = availableToTrade.plus(balance.availableAfterMaintenance ?? "0");
+    assets.push({
+      asset: balance.coin,
+      free: coinFree,
+      used: coinUsed,
+      total: balance.total,
+      walletBalance: coinWalletBalance,
+      usdValue: balance.total
     });
   }
-  return positions;
+  const maintenanceMargin = add(summary.crossMaintenanceMarginUsed, summary.isolatedMaintenanceMarginUsed);
+  const totalEquityValue = totalEquity.toFixed();
+  const walletBalance = subtract(totalEquityValue, summary.totalUnrealizedPnl);
+  return {
+    accountType,
+    free,
+    used,
+    total,
+    availableToTrade: availableToTrade.toFixed(),
+    // Unified spot totals are the authoritative equity balances and already include perp PnL.
+    totalEquity: totalEquityValue,
+    walletBalance,
+    unrealizedPnl: summary.totalUnrealizedPnl,
+    initialMarginUsed: summary.totalMarginUsed,
+    maintenanceMargin,
+    marginRatio: unifiedMarginRatio(summary, spotCoinBalances),
+    assets,
+    timestamp: Date.now()
+  };
+}
+function unifiedMarginRatio(summary, spotCoinBalances) {
+  let maximumRatio = new BigNumber(0);
+  for (const [token, collateral] of summary.byCollateralToken) {
+    const spotBalance = [...spotCoinBalances.values()].find((balance) => balance.token === token);
+    const available = new BigNumber(spotBalance?.total ?? "0").minus(collateral.isolatedMarginUsed);
+    maximumRatio = BigNumber.max(maximumRatio, ratio(collateral.crossMaintenanceMarginUsed, available.toFixed()));
+  }
+  return maximumRatio.toFixed(4);
+}
+function isolatedMaintenanceMargin(dexState, assetPosition) {
+  const position = assetPosition.position;
+  if (position.leverage.type !== "isolated" || position.maxLeverage <= 0) {
+    return "0";
+  }
+  const notional = new BigNumber(position.positionValue).abs();
+  const marginTiers = findMarginTiers(dexState, position.coin);
+  const firstMarginTier = marginTiers?.[0];
+  if (!marginTiers || !firstMarginTier || marginTiers.some((tier) => tier.maxLeverage <= 0)) {
+    return notional.div(position.maxLeverage).div(2).toFixed();
+  }
+  let activeTier = firstMarginTier;
+  let maintenanceDeduction = new BigNumber(0);
+  for (const nextTier of marginTiers.slice(1)) {
+    if (notional.lt(nextTier.lowerBound)) {
+      break;
+    }
+    const previousRate = maintenanceMarginRate(activeTier.maxLeverage);
+    const nextRate = maintenanceMarginRate(nextTier.maxLeverage);
+    maintenanceDeduction = maintenanceDeduction.plus(
+      new BigNumber(nextTier.lowerBound).times(nextRate.minus(previousRate))
+    );
+    activeTier = nextTier;
+  }
+  return notional.times(maintenanceMarginRate(activeTier.maxLeverage)).minus(maintenanceDeduction).toFixed();
+}
+function findMarginTiers(dexState, coin) {
+  if (!dexState.meta) {
+    return null;
+  }
+  const unprefixedCoin = dexState.dex && coin.startsWith(`${dexState.dex}:`) ? coin.slice(dexState.dex.length + 1) : coin;
+  const asset = dexState.meta.universe.find(
+    (candidate) => candidate.name === coin || candidate.name === unprefixedCoin
+  );
+  const marginTable = dexState.meta.marginTables.find(([id]) => id === asset?.marginTableId)?.[1];
+  return marginTable?.marginTiers.length ? marginTable.marginTiers : null;
+}
+function maintenanceMarginRate(maxLeverage) {
+  return new BigNumber(1).div(maxLeverage).div(2);
+}
+function add(left, right) {
+  return new BigNumber(left || "0").plus(right || "0").toFixed();
+}
+function subtract(left, right) {
+  return new BigNumber(left || "0").minus(right || "0").toFixed();
+}
+function sum(values) {
+  return values.reduce((total, value) => total.plus(value || "0"), new BigNumber(0)).toFixed();
+}
+function ratio(numerator, denominator) {
+  const numeratorValue = new BigNumber(numerator || "0");
+  const denominatorValue = new BigNumber(denominator || "0");
+  if (denominatorValue.gt(0)) {
+    return numeratorValue.div(denominatorValue).toFixed(4);
+  }
+  return numeratorValue.gt(0) ? FULL_UTILIZATION_RATIO : "0.0000";
 }
 
-export { mapBalance, mapPositions };
+export { aggregateClearinghouseStates, mapBalance, mapPositions };