@pear-protocol/exchanges-sdk 0.6.6 → 0.7.0

package/dist/tracker/hyperliquid/balance.js

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { DecimalString, AccountBalanceCore, SignedDecimalString } from '../balance-core';
+
+const HyperliquidDexState = z.object({
+  dex: z.string(),
+  collateralToken: z.number().int().nullable(),
+  accountValue: DecimalString,
+  crossNotional: DecimalString,
+  crossMaintenanceMargin: DecimalString,
+  withdrawable: DecimalString
+});
+const HyperliquidStandardBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("hyperliquid:standard"),
+  /**
+  * Spot holdings valued in USD.
+  *
+  * Null when a NON-ZERO holding cannot be priced — a balance carries only a token index, so its
+  * mid is reached through a USDC-quoted pair or through one pair quoted in a token that has one,
+  * and some tokens are beyond both. Counting an unpriceable holding as zero would report a number
+  * the venue never stated.
+  */
+  spotEquity: DecimalString.nullable(),
+  /**
+  * The perps wallet as CASH: transfers + realized + funding, i.e. Σ `marginSummary.accountValue`
+  * with `unrealizedPnl` taken back out. This is the venue's own `Perps` figure, reproduced inside
+  * 0.08% on all nine Standard accounts captured 2026-08-18 and in both directions of PnL, and it
+  * is the perps term the venue's Total Equity adds — which is why `totalEquity` is exactly
+  * `spotEquity + perpsEquity + vaultEquity + stakedEquity` and stays that way.
+  *
+  * SIGNED, because an account whose unrealized profit exceeds its account value carries negative
+  * cash — measured at −230.12 on `0x5b43…92ab`. It replaced a separate `balance` field carrying
+  * this same quantity under a second name; the account value that field was subtracted FROM is
+  * `perpsEquity + unrealizedPnl`, and is published per dex in `perDexState[].accountValue`.
+  */
+  perpsEquity: SignedDecimalString,
+  vaultEquity: DecimalString,
+  /**
+  * The whole staking account — delegated HYPE plus undelegated — valued at its spot mid.
+  *
+  * Null when a NON-ZERO staking balance cannot be priced — the HYPE mid needs both `spotMeta` and
+  * `allMids`, so it is absent until each has arrived, and counting staked HYPE as zero would
+  * report a number the venue never stated. An empty staking account is worth zero at any price and
+  * still reads `0`.
+  */
+  stakedEquity: DecimalString.nullable(),
+  unrealizedPnl: SignedDecimalString,
+  maintenanceMargin: DecimalString,
+  /**
+  * The cross pool's own utilisation: Σ `crossMaintenanceMarginUsed` over Σ `crossMarginSummary
+  * .accountValue`, aggregated across every dex before the single division.
+  *
+  * Isolated legs are excluded for the same reason `maintenanceMargin` above excludes them: they
+  * carry their own margin and liquidate independently of the cross pool, so a field named for the
+  * cross pool reports the cross pool. Measured against the venue's own badge on
+  * `0x17c3…a868`: 109,558.03 / 7,510,025.45 = 1.46%, where that account's worst isolated leg reads
+  * 16.11% and its worst single dex 5.07%. Neither of those is the account's cross risk.
+  *
+  * THE VENUE IS INTERNALLY INCONSISTENT HERE, and both spellings below match it deliberately. Its
+  * ratio badge and its Cross Account Leverage divide by cross ACCOUNT VALUE — unrealized PnL
+  * included — while the `Perps` figure `perpsEquity` reproduces is that account value net of the
+  * same PnL. Neither is wrong; they are two different questions, and aligning one to the other
+  * would break its own verified match against the venue.
+  */
+  crossMarginRatio: DecimalString,
+  crossAccountLeverage: DecimalString,
+  /** Kept per dex — the aggregate hides HIP-3 positions entirely. */
+  perDexState: z.array(HyperliquidDexState)
+});
+const HyperliquidUnifiedBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("hyperliquid:unified"),
+  /**
+  * The whole spot wallet at mid, since spot IS the collateral in this mode.
+  *
+  * Null when a NON-ZERO holding cannot be priced, for the reason Standard's `spotEquity` is: no
+  * route to USDC reaches every token, and counting an unpriceable holding as zero would report a
+  * number the venue never stated.
+  */
+  tradingEquity: DecimalString.nullable(),
+  vaultEquity: DecimalString,
+  /**
+  * The whole staking account — delegated HYPE plus undelegated — valued at its spot mid. Null when
+  * a NON-ZERO staking balance cannot be priced.
+  */
+  stakedEquity: DecimalString.nullable(),
+  /**
+  * Trading equity plus what sits outside trading. Null whenever either term is — one unknown term
+  * makes the sum unknown.
+  */
+  portfolioValue: DecimalString.nullable(),
+  unrealizedPnl: SignedDecimalString,
+  /** Cross maintenance only — isolated legs carry their own margin. */
+  perpsMaintenanceMargin: DecimalString,
+  unifiedAccountRatio: DecimalString,
+  /**
+  * Cross notional over the COLLATERAL backing it — the spot holdings of the dex collateral tokens,
+  * at their own mids — and NOT over `portfolioValue`.
+  *
+  * Staking, vault deposits and non-collateral spot coins are outside the denominator: the venue
+  * renders 0.28x on `0x8fec806c…`, where the portfolio-value spelling reads 0.0211 because 89% of
+  * that wallet sits in HYPE, staking and a vault.
+  *
+  * Null when a NON-ZERO collateral holding cannot be priced: a denominator nobody could state
+  * leaves the quotient unknown, where a zero would claim the account carries no leverage at all.
+  */
+  unifiedAccountLeverage: DecimalString.nullable(),
+  perDexState: z.array(HyperliquidDexState)
+});
+const HyperliquidPortfolioMarginCollateral = z.object({
+  asset: z.string(),
+  /** Net Balance: the venue's `total`, in the coin's own units, negative on a borrowed coin. */
+  equity: SignedDecimalString,
+  /** The per-pool floor of `activeAssetData.availableToTrade`; null where nothing was measured. */
+  availableMargin: DecimalString.nullable(),
+  /**
+  * Available Balance: `total − hold`, UNFLOORED and signed.
+  *
+  * In PM the `hold` is net of borrowing headroom, so this is free balance PLUS what the account
+  * may still borrow of the coin — which is why the venue labels it Available Balance and renders
+  * the 999,999.99999999 USDT0 case verbatim. Flooring the hold at zero would delete the borrow
+  * term and turn a borrowing account's spendable balance into its debt.
+  */
+  withdrawable: SignedDecimalString,
+  /**
+  * The coin's initial LTV, and `null` where the wire publishes no `ltv` key.
+  *
+  * `null` is the venue's `--`: the coin is not collateral and contributes nothing to the leverage
+  * denominator. `"0"` is the venue's `N/A`: a stablecoin at full weight. The two are opposite
+  * ends of the scale, so a consumer must not read the absent key as a zero weight.
+  */
+  ltv: DecimalString.nullable(),
+  /**
+  * `borrowed / borrow cap` for this coin, and `null` where the venue renders `--` — no borrow.
+  * NOT clipped at one: `0x0871deb3…` reports 1.0081 on USDT0.
+  */
+  borrowCapUsed: DecimalString.nullable()
+});
+const HyperliquidPortfolioMarginBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("hyperliquid:portfolioMargin"),
+  /**
+  * One row per spot holding the venue lists — every balance where `total ≠ 0` OR `hold ≠ 0`, not
+  * one row per dex collateral token. In PM every spot holding is potentially collateral, and the
+  * collateral-token spelling hid $14.57M of HYPE behind a single USDC row on `0x0871deb3…`.
+  */
+  perCollateral: z.array(HyperliquidPortfolioMarginCollateral),
+  /** The whole spot wallet at mid. Null when a NON-ZERO holding has no route to USDC to price it. */
+  tradingEquity: DecimalString.nullable(),
+  vaultEquity: DecimalString,
+  /**
+  * The whole staking account — delegated HYPE plus undelegated — valued at its spot mid. Null when
+  * a NON-ZERO staking balance cannot be priced.
+  */
+  stakedEquity: DecimalString.nullable(),
+  /**
+  * The venue's Portfolio Value, which is Trading Equity under its other name: Σ spot × mid, with
+  * staking and vault deposits EXCLUDED. Both labels appear on the venue's own screens for the
+  * same quantity, and `totalEquity` is the one that adds the two outside balances back.
+  */
+  portfolioValue: DecimalString.nullable(),
+  unrealizedPnl: SignedDecimalString,
+  perpsMaintenanceMargin: DecimalString,
+  /**
+  * The venue's own `spotClearinghouseState.portfolioMarginRatio`, clipped at `1.0000` by the
+  * venue itself. Null when the wire states none.
+  *
+  * Read, never derived. The closed form behind it was solved to 0.4% on the seven debt-free
+  * accounts measured — `Σ crossMaintenanceMarginUsed` over capped collateral weighted
+  * `(1 + ltv) / 2`, less isolated margin — and does NOT extend to the seven carrying debt, where
+  * five candidate debt terms were each ruled out on at least three accounts.
+  */
+  portfolioMarginRatio: DecimalString.nullable(),
+  /**
+  * Cross notional over LTV-haircut collateral. Null when a holding that carries an `ltv` weight
+  * cannot be priced, since the denominator is then unknown rather than smaller.
+  */
+  portfolioAccountLeverage: DecimalString.nullable(),
+  /**
+  * Borrow Capacity Used: the WORST `tokenToPortfolioBorrowRatio` across coins, null when the
+  * account borrows nothing. Not clipped at one, and never the USDC entry alone.
+  */
+  borrowCapUsed: DecimalString.nullable(),
+  perDexState: z.array(HyperliquidDexState)
+});
+
+export { HyperliquidDexState, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance };

package/dist/tracker/hyperliquid/basket-size.js

@@ -0,0 +1,93 @@
+import BigNumber from 'bignumber.js';
+import { splitDexCoin } from './coin-name';
+import { toDecimal } from './decimal';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const UNRESOLVED_POOL = "";
+function buildCappedLegs(legs, markets) {
+  return legs.map((leg) => {
+    const market = markets.get(leg.asset) ?? null;
+    const leverage = effectiveLeverage(leg.leverage, market);
+    return {
+      asset: leg.asset,
+      pool: market?.pool ?? UNRESOLVED_POOL,
+      weight: leg.weight,
+      effectiveLeverage: leverage,
+      marginMode: leg.marginMode,
+      maxNotional: tierBoundaryNotional(market?.marginTiers ?? null, leverage)
+    };
+  });
+}
+__name(buildCappedLegs, "buildCappedLegs");
+function buildPoolBudgets(legs, markets, assetData) {
+  const dataByPool = /* @__PURE__ */ new Map();
+  for (const leg of legs) {
+    const pool = markets.get(leg.asset)?.pool ?? null;
+    const data = assetData.get(leg.asset);
+    if (pool === null || data === void 0) {
+      continue;
+    }
+    const bucket = dataByPool.get(pool) ?? [];
+    bucket.push(data);
+    dataByPool.set(pool, bucket);
+  }
+  const budgets = {};
+  for (const [pool, data] of dataByPool) {
+    const floor = minimumAvailableToTrade(data);
+    if (floor !== null) {
+      budgets[pool] = floor;
+    }
+  }
+  return budgets;
+}
+__name(buildPoolBudgets, "buildPoolBudgets");
+function effectiveLeverage(requestedLeverage, market) {
+  let leverage = toDecimal(requestedLeverage);
+  if (market?.venueMaxLeverage !== null && market?.venueMaxLeverage !== void 0) {
+    leverage = BigNumber.min(leverage, market.venueMaxLeverage);
+  }
+  if (market?.accountLeverage !== null && market?.accountLeverage !== void 0) {
+    leverage = BigNumber.min(leverage, market.accountLeverage);
+  }
+  return BigNumber.max(leverage, 1).toFixed();
+}
+__name(effectiveLeverage, "effectiveLeverage");
+function tierBoundaryNotional(marginTiers, effectiveLeverage2) {
+  if (!marginTiers) {
+    return null;
+  }
+  const leverage = toDecimal(effectiveLeverage2);
+  const boundary = marginTiers.find((tier) => leverage.isGreaterThan(tier.maxLeverage));
+  return boundary ? boundary.lowerBound : null;
+}
+__name(tierBoundaryNotional, "tierBoundaryNotional");
+function minimumAvailableToTrade(assetData) {
+  let floor = null;
+  for (const data of assetData) {
+    for (const available of data.availableToTrade ?? []) {
+      const value = toDecimal(available);
+      if (floor === null || value.isLessThan(floor)) {
+        floor = value;
+      }
+    }
+  }
+  return floor === null ? null : floor.toFixed();
+}
+__name(minimumAvailableToTrade, "minimumAvailableToTrade");
+function findLegMarket(dexToMeta, tokenNames, coin, accountLeverage) {
+  const { dex, bareCoin } = splitDexCoin(coin);
+  const meta = dexToMeta.get(dex);
+  const asset = meta?.universe.find((candidate) => candidate.name === coin || candidate.name === bareCoin);
+  const marginTiers = meta?.marginTables.find(([id]) => id === asset?.marginTableId)?.[1].marginTiers;
+  const collateralToken = meta?.collateralToken;
+  return {
+    pool: collateralToken === void 0 ? null : tokenNames.get(collateralToken) ?? null,
+    venueMaxLeverage: asset?.maxLeverage ?? null,
+    accountLeverage,
+    marginTiers: marginTiers?.length ? marginTiers : null
+  };
+}
+__name(findLegMarket, "findLegMarket");
+
+export { buildCappedLegs, buildPoolBudgets, effectiveLeverage, findLegMarket, minimumAvailableToTrade, tierBoundaryNotional };

package/dist/tracker/hyperliquid/coin-name.js

@@ -0,0 +1,18 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function splitDexCoin(coin) {
+  const separator = coin.indexOf(":");
+  if (separator === -1) {
+    return {
+      dex: "",
+      bareCoin: coin
+    };
+  }
+  return {
+    dex: coin.slice(0, separator),
+    bareCoin: coin.slice(separator + 1)
+  };
+}
+__name(splitDexCoin, "splitDexCoin");
+
+export { splitDexCoin };

package/dist/tracker/hyperliquid/collateral.js

@@ -0,0 +1,48 @@
+import { minimumAvailableToTrade } from './basket-size';
+import { splitDexCoin } from './coin-name';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function buildCollateralTokenNames(spotMeta) {
+  const names = /* @__PURE__ */ new Map();
+  for (const token of spotMeta.tokens ?? []) {
+    names.set(token.index, token.name);
+  }
+  return names;
+}
+__name(buildCollateralTokenNames, "buildCollateralTokenNames");
+function buildAvailableMarginByToken(perDexState, assetData) {
+  const tokenByDex = collateralTokenByDex(perDexState);
+  const assetsByToken = /* @__PURE__ */ new Map();
+  for (const data of assetData) {
+    const token = tokenByDex.get(splitDexCoin(data.coin).dex);
+    if (token === void 0) {
+      continue;
+    }
+    const bucket = assetsByToken.get(token) ?? [];
+    bucket.push(data);
+    assetsByToken.set(token, bucket);
+  }
+  const floors = /* @__PURE__ */ new Map();
+  for (const [token, assets] of assetsByToken) {
+    const floor = minimumAvailableToTrade(assets);
+    if (floor !== null) {
+      floors.set(token, floor);
+    }
+  }
+  return floors;
+}
+__name(buildAvailableMarginByToken, "buildAvailableMarginByToken");
+function collateralTokenByDex(perDexState) {
+  const tokenByDex = /* @__PURE__ */ new Map();
+  for (const entry of perDexState) {
+    if (entry.collateralToken === null) {
+      continue;
+    }
+    tokenByDex.set(entry.dex, entry.collateralToken);
+  }
+  return tokenByDex;
+}
+__name(collateralTokenByDex, "collateralTokenByDex");
+
+export { buildAvailableMarginByToken, buildCollateralTokenNames };

package/dist/tracker/hyperliquid/decimal.js

@@ -0,0 +1,28 @@
+import BigNumber from 'bignumber.js';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const ZERO = new BigNumber(0);
+const ONE = new BigNumber(1);
+const WIRE_DECIMAL = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+function toPrice(value) {
+  const price = toDecimal(value);
+  if (!price.isGreaterThan(ZERO)) {
+    return null;
+  }
+  return price;
+}
+__name(toPrice, "toPrice");
+function toDecimal(value) {
+  if (value === null || value === void 0) {
+    return ZERO;
+  }
+  const trimmed = value.trim();
+  if (!WIRE_DECIMAL.test(trimmed)) {
+    return ZERO;
+  }
+  return new BigNumber(trimmed);
+}
+__name(toDecimal, "toDecimal");
+
+export { ONE, ZERO, toDecimal, toPrice };