@pear-protocol/exchanges-sdk 0.6.6 → 0.7.0

package/dist/sdk.js

@@ -42,6 +42,14 @@ class ExchangesSDK {
     const connection = await this.fetchCredentials(tradeAccountId);
     return this.buildTracker(connection).snapshot();
   }
+  /**
+  * Sizes a basket in one shot. Routed to the tracker's REST path on purpose: this entry point
+  * builds a throwaway tracker per call, so it must open no socket.
+  */
+  async maxBasketSize(tradeAccountId, input) {
+    const connection = await this.fetchCredentials(tradeAccountId);
+    return this.buildTracker(connection).snapshotMaxBasketSize(input);
+  }
   async snapshotAssets(tradeAccountId, coins) {
     const connection = await this.fetchCredentials(tradeAccountId);
     return this.buildTracker(connection).snapshotAssets(coins);
@@ -74,8 +82,7 @@ class ExchangesSDK {
     return createAccountTracker(connection.connector, {
       demo: this.demo,
       account: connection.account,
-      credentials: connection.credentials,
-      sdk: this.sdk
+      credentials: connection.credentials
     });
   }
   async fetchCredentials(tradeAccountId) {

package/dist/tracker/balance-core.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+
+const DecimalString = z.string().regex(/^\d+(\.\d+)?$/);
+const SignedDecimalString = z.string().regex(/^[+-]\d+(\.\d+)?$/);
+const MarginMode = z.enum([
+  "cross",
+  "isolated"
+]);
+const Side = z.enum([
+  "BUY",
+  "SELL"
+]);
+const AccountMode = z.enum([
+  "hyperliquid:standard",
+  "hyperliquid:unified",
+  "hyperliquid:portfolioMargin",
+  "lighter:classic",
+  "lighter:unified",
+  "binance:singleAsset",
+  "binance:multiAsset",
+  "bybit:isolatedMargin",
+  "bybit:regularMargin",
+  "bybit:portfolioMargin",
+  "okx:spot",
+  "okx:futures",
+  "okx:multiCurrencyMargin",
+  "okx:portfolioMargin"
+]);
+const CollateralBalance = z.object({
+  asset: z.string(),
+  equity: DecimalString,
+  availableMargin: DecimalString.nullable(),
+  withdrawable: DecimalString.nullable()
+});
+const AccountBalanceCore = z.object({
+  /**
+  * The account's whole equity in USD, and `null` when the venue cannot state ONE spendable figure.
+  * The reasons are per-venue, and `perCollateral` is where the truth lives in every one of them:
+  *
+  * - a holding the venue cannot price — Lighter spot needs a last trade and an inactive book has
+  *   none; Hyperliquid spot needs a USDC-quoted pair and the venue lists none for every token.
+  *   Reporting the rest would understate the account by exactly the part we could not value.
+  * - two funded pools that cannot fund each other — `binance:singleAsset`, `okx:spot` and
+  *   `okx:futures` run one collateral pool per settlement currency, so once a second pool holds
+  *   value no single number is spendable across both.
+  * - a figure the venue left blank — CEX account endpoints blank their account-level fields per
+  *   mode, and a blank is "not stated", never a zero.
+  *
+  * Nullable on EVERY variant on purpose: a consumer that narrows to one mode handles the same
+  * `string | null` it would have handled without narrowing, so no variant can quietly stop being
+  * safe when a venue starts blanking a field it used to fill.
+  */
+  totalEquity: DecimalString.nullable(),
+  /** What can leave the trading account right now. */
+  withdrawableBalance: DecimalString.nullable(),
+  /**
+  * Collateral guaranteed usable as margin for EVERY asset in the tracked set — a floor, not a
+  * per-asset figure. On venues where headroom varies by asset (Hyperliquid), this is the minimum
+  * across that set, so it is only meaningful relative to the assets it was computed over.
+  */
+  availableMargin: DecimalString.nullable(),
+  /**
+  * Whether ONE pool funds every position. `false` means the rows are separate budgets that
+  * cannot fund each other; `true` means they are holdings inside one shared pool, where only
+  * the scalars are spendable.
+  */
+  poolsShared: z.boolean(),
+  /** Per-collateral rows in each asset's own units. Empty when the venue publishes none. */
+  perCollateral: z.array(CollateralBalance),
+  timestamp: z.number().int()
+});
+const ACCOUNT_MODE_LABELS = {
+  "hyperliquid:standard": "Standard",
+  "hyperliquid:unified": "Unified Account",
+  "hyperliquid:portfolioMargin": "Portfolio Margin",
+  "lighter:classic": "Classic",
+  "lighter:unified": "Unified",
+  "binance:singleAsset": "Single-Asset Mode",
+  "binance:multiAsset": "Multi-Asset Mode",
+  "bybit:isolatedMargin": "Isolated Margin",
+  "bybit:regularMargin": "Cross Margin",
+  "bybit:portfolioMargin": "Portfolio Margin",
+  "okx:spot": "Spot Mode",
+  "okx:futures": "Futures Mode",
+  "okx:multiCurrencyMargin": "Multi-Currency Margin",
+  "okx:portfolioMargin": "Portfolio Margin"
+};
+
+export { ACCOUNT_MODE_LABELS, AccountBalanceCore, AccountMode, CollateralBalance, DecimalString, MarginMode, Side, SignedDecimalString };

package/dist/tracker/balance.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { BinanceSingleAssetBalance, BinanceMultiAssetBalance } from './binance/balance';
+import { BybitIsolatedMarginBalance, BybitRegularMarginBalance, BybitPortfolioMarginBalance } from './bybit/balance';
+import { HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidPortfolioMarginBalance } from './hyperliquid/balance';
+import { LighterClassicBalance, LighterUnifiedBalance } from './lighter/balance';
+import { OkxSpotBalance, OkxFuturesBalance, OkxMultiCurrencyMarginBalance, OkxPortfolioMarginBalance } from './okx/balance';
+
+const AccountBalance = z.discriminatedUnion("accountMode", [
+  HyperliquidStandardBalance,
+  HyperliquidUnifiedBalance,
+  HyperliquidPortfolioMarginBalance,
+  LighterClassicBalance,
+  LighterUnifiedBalance,
+  BinanceSingleAssetBalance,
+  BinanceMultiAssetBalance,
+  BybitIsolatedMarginBalance,
+  BybitRegularMarginBalance,
+  BybitPortfolioMarginBalance,
+  OkxSpotBalance,
+  OkxFuturesBalance,
+  OkxMultiCurrencyMarginBalance,
+  OkxPortfolioMarginBalance
+]);
+
+export { AccountBalance };

package/dist/tracker/basket-size.js

@@ -0,0 +1,194 @@
+import BigNumber from 'bignumber.js';
+import { z } from 'zod';
+import { Side, DecimalString, MarginMode } from './balance-core';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const BasketLeg = z.object({
+  asset: z.string(),
+  marginMode: MarginMode,
+  leverage: DecimalString,
+  side: Side,
+  /** Unsigned percentage. The set sums to 100. */
+  weight: z.number().positive()
+});
+const MaxBasketSizeInput = z.object({
+  legs: z.array(BasketLeg).min(1)
+});
+const MaxBasketSizeResult = z.object({
+  /**
+  * The whole basket's max GROSS notional in USD — Σ leg notional, not per-side and not per-asset.
+  * The basket is atomic, so this is one ceiling for the entire structure.
+  * Null when the venue cannot supply a per-asset max leverage (all three CEXs in v1), and null
+  * when any leg draws on a pool the caller could not value.
+  */
+  maxNotional: DecimalString.nullable(),
+  /** Derived from maxNotional — each leg's notional at that basket size. NOT a per-leg maximum. */
+  legs: z.array(z.object({
+    asset: z.string(),
+    notional: DecimalString,
+    marginRequired: DecimalString
+  })),
+  /** Which pool or leg ran out first. */
+  bindingConstraint: z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("cross-pool"),
+      pool: z.string()
+    }),
+    z.object({
+      kind: z.literal("isolated-leg"),
+      asset: z.string()
+    })
+  ]).nullable()
+});
+function computeMaxBasketSize(input) {
+  if (!isSizeableInput(input)) {
+    return unsizedResult();
+  }
+  const budgets = new Map(Object.entries(input.budgets));
+  const weightSum = sumWeights(input.legs);
+  if (weightSum.isZero()) {
+    return unsizedResult();
+  }
+  const shares = input.legs.map((leg) => toLegShare(leg, weightSum));
+  const demandByPool = marginPerUnitNotionalByPool(shares);
+  const tightestPool = tightestPoolCeiling(demandByPool, budgets);
+  if (tightestPool === null) {
+    return unsizedResult();
+  }
+  const tightestCap = tightestLegCap(shares);
+  if (tightestCap === null || tightestPool.size.isLessThanOrEqualTo(tightestCap.size)) {
+    return buildResult(tightestPool.size, shares, {
+      kind: "cross-pool",
+      pool: tightestPool.pool
+    });
+  }
+  return buildResult(tightestCap.size, shares, {
+    kind: "isolated-leg",
+    asset: tightestCap.asset
+  });
+}
+__name(computeMaxBasketSize, "computeMaxBasketSize");
+function isSizeableInput(input) {
+  for (const budget of Object.values(input.budgets)) {
+    if (!isUnsignedDecimal(budget)) {
+      return false;
+    }
+  }
+  for (const leg of input.legs) {
+    if (!isPositiveFinite(leg.weight)) {
+      return false;
+    }
+    if (!isUsableLeverage(leg.effectiveLeverage)) {
+      return false;
+    }
+    if (leg.maxNotional !== null && !isUnsignedDecimal(leg.maxNotional)) {
+      return false;
+    }
+  }
+  return true;
+}
+__name(isSizeableInput, "isSizeableInput");
+function isUnsignedDecimal(value) {
+  return DecimalString.safeParse(value).success;
+}
+__name(isUnsignedDecimal, "isUnsignedDecimal");
+function isPositiveFinite(weight) {
+  return Number.isFinite(weight) && weight > 0;
+}
+__name(isPositiveFinite, "isPositiveFinite");
+function isUsableLeverage(effectiveLeverage) {
+  if (!isUnsignedDecimal(effectiveLeverage)) {
+    return false;
+  }
+  return !new BigNumber(effectiveLeverage).isZero();
+}
+__name(isUsableLeverage, "isUsableLeverage");
+function sumWeights(legs) {
+  let total = new BigNumber(0);
+  for (const leg of legs) {
+    total = total.plus(String(leg.weight));
+  }
+  return total;
+}
+__name(sumWeights, "sumWeights");
+function unsizedResult() {
+  return {
+    maxNotional: null,
+    legs: [],
+    bindingConstraint: null
+  };
+}
+__name(unsizedResult, "unsizedResult");
+function toLegShare(leg, weightSum) {
+  return {
+    asset: leg.asset,
+    pool: leg.pool,
+    share: new BigNumber(String(leg.weight)).div(weightSum),
+    imr: new BigNumber(1).div(leg.effectiveLeverage),
+    maxNotional: leg.maxNotional === null ? null : new BigNumber(leg.maxNotional)
+  };
+}
+__name(toLegShare, "toLegShare");
+function marginPerUnitNotionalByPool(shares) {
+  const demandByPool = /* @__PURE__ */ new Map();
+  for (const leg of shares) {
+    const running = demandByPool.get(leg.pool) ?? new BigNumber(0);
+    demandByPool.set(leg.pool, running.plus(leg.share.times(leg.imr)));
+  }
+  return demandByPool;
+}
+__name(marginPerUnitNotionalByPool, "marginPerUnitNotionalByPool");
+function tightestPoolCeiling(demandByPool, budgets) {
+  let tightest = null;
+  for (const [pool, marginPerUnitNotional] of demandByPool) {
+    const budget = budgets.get(pool);
+    if (budget === void 0) {
+      return null;
+    }
+    const size = new BigNumber(budget).div(marginPerUnitNotional);
+    if (tightest === null || size.isLessThan(tightest.size)) {
+      tightest = {
+        pool,
+        size
+      };
+    }
+  }
+  return tightest;
+}
+__name(tightestPoolCeiling, "tightestPoolCeiling");
+function tightestLegCap(shares) {
+  let tightest = null;
+  for (const leg of shares) {
+    if (leg.maxNotional === null) {
+      continue;
+    }
+    const size = leg.maxNotional.div(leg.share);
+    if (tightest === null || size.isLessThan(tightest.size)) {
+      tightest = {
+        asset: leg.asset,
+        size
+      };
+    }
+  }
+  return tightest;
+}
+__name(tightestLegCap, "tightestLegCap");
+function buildResult(size, shares, bindingConstraint) {
+  const legs = shares.map((leg) => {
+    const notional = size.times(leg.share);
+    return {
+      asset: leg.asset,
+      notional: notional.toFixed(),
+      marginRequired: notional.times(leg.imr).toFixed()
+    };
+  });
+  return {
+    maxNotional: size.toFixed(),
+    legs,
+    bindingConstraint
+  };
+}
+__name(buildResult, "buildResult");
+
+export { BasketLeg, MaxBasketSizeInput, MaxBasketSizeResult, computeMaxBasketSize };

package/dist/tracker/binance/balance.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { AccountBalanceCore } from '../balance-core';
+
+const BinanceSingleAssetBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("binance:singleAsset")
+});
+const BinanceMultiAssetBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("binance:multiAsset")
+});
+
+export { BinanceMultiAssetBalance, BinanceSingleAssetBalance };

package/dist/tracker/binance/mapper.js

@@ -3,48 +3,42 @@ import { positionKey } from '../utils';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-function mapBalance(raw) {
-  const free = {};
-  const used = {};
-  const total = {};
-  const assets = [];
-  for (const a of raw.assets ?? []) {
-    const wb = a.walletBalance ?? "0";
-    const ab = a.availableBalance ?? "0";
-    const mb = a.marginBalance ?? "0";
-    const im = a.initialMargin ?? "0";
-    if (new BigNumber(wb).isZero() && new BigNumber(ab).isZero() && new BigNumber(mb).isZero()) continue;
-    free[a.asset] = ab;
-    used[a.asset] = im;
-    total[a.asset] = mb;
-    assets.push({
-      asset: a.asset,
-      free: ab,
-      used: im,
-      total: mb,
-      walletBalance: wb,
-      usdValue: mb
-    });
+const DECIMAL_PATTERN = /^\d+(\.\d+)?$/;
+const ACCOUNT_LEVEL_ASSET = "USDT";
+const SIGNED_DECIMAL_PATTERN = /^-?\d+(\.\d+)?$/;
+function toBinanceAccountMode(multiAssetsMargin) {
+  return multiAssetsMargin ? "binance:multiAsset" : "binance:singleAsset";
+}
+__name(toBinanceAccountMode, "toBinanceAccountMode");
+function mapBalance(raw, accountMode, timestamp) {
+  const assets = raw.assets ?? [];
+  const perCollateral = toCollateralRows(assets);
+  switch (accountMode) {
+    // Multi-asset mode values the whole wallet in USD, so the account-level figures are complete.
+    case "binance:multiAsset":
+      return {
+        accountMode,
+        totalEquity: decimalOrNull(raw.totalMarginBalance),
+        withdrawableBalance: decimalOrNull(raw.maxWithdrawAmount),
+        availableMargin: decimalOrNull(raw.availableBalance),
+        poolsShared: true,
+        perCollateral,
+        timestamp
+      };
+    // Single-asset mode runs a pool per settlement currency, so its scalars need the pool test.
+    case "binance:singleAsset": {
+      const scalarsDescribeTheAccount = nothingFundedOutsideUsdt(assets);
+      return {
+        accountMode,
+        totalEquity: scalarsDescribeTheAccount ? decimalOrNull(raw.totalMarginBalance) : null,
+        withdrawableBalance: scalarsDescribeTheAccount ? decimalOrNull(raw.maxWithdrawAmount) : null,
+        availableMargin: scalarsDescribeTheAccount ? decimalOrNull(raw.availableBalance) : null,
+        poolsShared: false,
+        perCollateral,
+        timestamp
+      };
+    }
   }
-  const totalMarginBalance = raw.totalMarginBalance ?? "0";
-  const totalMaintMargin = raw.totalMaintMargin ?? "0";
-  const marginBalanceBN = new BigNumber(totalMarginBalance);
-  const maintMarginBN = new BigNumber(totalMaintMargin);
-  const marginRatio = marginBalanceBN.gt(0) ? maintMarginBN.div(marginBalanceBN).toFixed(4) : "0.0000";
-  return {
-    free,
-    used,
-    total,
-    availableToTrade: raw.availableBalance ?? "0",
-    totalEquity: totalMarginBalance,
-    walletBalance: raw.totalWalletBalance ?? "0",
-    unrealizedPnl: raw.totalUnrealizedProfit ?? "0",
-    initialMarginUsed: raw.totalInitialMargin ?? "0",
-    maintenanceMargin: totalMaintMargin,
-    marginRatio,
-    assets,
-    timestamp: Date.now()
-  };
 }
 __name(mapBalance, "mapBalance");
 function mapPositions(raw) {
@@ -86,5 +80,56 @@ function mergePositions(incoming, existing) {
   return merged;
 }
 __name(mergePositions, "mergePositions");
+function toCollateralRows(assets) {
+  const rows = [];
+  for (const asset of assets) {
+    if (!isFunded(asset.marginBalance)) {
+      continue;
+    }
+    rows.push({
+      asset: asset.asset,
+      equity: asset.marginBalance,
+      availableMargin: decimalOrNull(asset.availableBalance),
+      withdrawable: decimalOrNull(asset.maxWithdrawAmount)
+    });
+  }
+  return rows.sort(byAssetName);
+}
+__name(toCollateralRows, "toCollateralRows");
+function nothingFundedOutsideUsdt(assets) {
+  for (const asset of assets) {
+    if (asset.asset !== ACCOUNT_LEVEL_ASSET && holdsAnyBalance(asset.marginBalance)) {
+      return false;
+    }
+  }
+  return true;
+}
+__name(nothingFundedOutsideUsdt, "nothingFundedOutsideUsdt");
+function holdsAnyBalance(value) {
+  if (value === void 0 || !SIGNED_DECIMAL_PATTERN.test(value)) {
+    return false;
+  }
+  return !new BigNumber(value).isZero();
+}
+__name(holdsAnyBalance, "holdsAnyBalance");
+function isFunded(value) {
+  return isDecimal(value) && !new BigNumber(value).isZero();
+}
+__name(isFunded, "isFunded");
+function isDecimal(value) {
+  return value !== void 0 && DECIMAL_PATTERN.test(value);
+}
+__name(isDecimal, "isDecimal");
+function byAssetName(a, b) {
+  if (a.asset === b.asset) {
+    return 0;
+  }
+  return a.asset < b.asset ? -1 : 1;
+}
+__name(byAssetName, "byAssetName");
+function decimalOrNull(value) {
+  return isDecimal(value) ? value : null;
+}
+__name(decimalOrNull, "decimalOrNull");
 
-export { mapBalance, mapPositions, mergePositions };
+export { mapBalance, mapPositions, mergePositions, toBinanceAccountMode };

package/dist/tracker/binance/tracker.js

@@ -3,8 +3,7 @@ import { fetchAllPositionRisk, keepAliveListenKey, fetchAccountStatus, fetchMult
 import { BaseAccountTracker } from '../base';
 import { positionKey } from '../utils';
 import { DEFAULT_LISTEN_KEY_REFRESH_MS, DEFAULT_ACCOUNT_POLL_MS } from './const';
-import { mapBalance, mapPositions, mergePositions } from './mapper';
-import { BinanceAccountType } from './types';
+import { mapBalance, toBinanceAccountMode, mapPositions, mergePositions } from './mapper';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -22,7 +21,7 @@ class BinanceAccountTracker extends BaseAccountTracker {
   listenKeyTimer = null;
   pollTimer = null;
   currentPositions = /* @__PURE__ */ new Map();
-  accountType = BinanceAccountType.SINGLE_ASSET;
+  accountMode = null;
   trackedAssetInfos = /* @__PURE__ */ new Map();
   constructor(config) {
     super(config);
@@ -32,17 +31,26 @@ class BinanceAccountTracker extends BaseAccountTracker {
   }
   async snapshot() {
     const { snapshot, positionRisk, multiAssetsMargin } = await this.fetchSnapshotData();
-    const accountType = multiAssetsMargin ? BinanceAccountType.MULTI_ASSET : BinanceAccountType.SINGLE_ASSET;
-    const balance = {
-      ...mapBalance(snapshot),
-      accountType
-    };
+    const balance = mapBalance(snapshot, toBinanceAccountMode(multiAssetsMargin), Date.now());
     return {
       balance,
       positions: Array.from(mapPositions(positionRisk).values())
     };
   }
   /**
+  * Binance sizes no basket in v1: the SDK reads no per-asset max leverage from it, and sizing off
+  * `availableMargin` alone would ship a number no venue field backs. The missing input is
+  * `/fapi/v2/positionRisk` → `maxNotionalValue` (the account's own per-symbol ceiling), with
+  * `/fapi/v1/leverageBracket` behind it for the tier a larger size would fall into.
+  */
+  async maxBasketSize(_input) {
+    return unsizedBasket();
+  }
+  /** The REST path answers the same way — there is no size either way, not a slower one. */
+  async snapshotMaxBasketSize(_input) {
+    return unsizedBasket();
+  }
+  /**
   * Stateless one-shot per-asset settings read: `positionRisk` with no symbol returns leverage +
   * margin type for every symbol (positioned or not), so any number of assets costs one call.
   */
@@ -61,7 +69,7 @@ class BinanceAccountTracker extends BaseAccountTracker {
   }
   async start() {
     const { snapshot, positionRisk, multiAssetsMargin } = await this.fetchSnapshotData();
-    this.accountType = multiAssetsMargin ? BinanceAccountType.MULTI_ASSET : BinanceAccountType.SINGLE_ASSET;
+    this.accountMode = toBinanceAccountMode(multiAssetsMargin);
     this.handleAccountStatus(snapshot);
     this.handlePositionRisk(positionRisk, false);
     const ws = await createExchangeWs("binance", {
@@ -157,12 +165,11 @@ class BinanceAccountTracker extends BaseAccountTracker {
     }
   }
   handleAccountStatus(result) {
-    const balance = {
-      ...mapBalance(result),
-      accountType: this.accountType
-    };
+    if (this.accountMode === null) {
+      return;
+    }
     this.onStateUpdate({
-      balance
+      balance: mapBalance(result, this.accountMode, Date.now())
     });
   }
   handlePositionRisk(risk, merge) {
@@ -247,5 +254,13 @@ function toTrackedAssetInfo(coin, risk) {
   };
 }
 __name(toTrackedAssetInfo, "toTrackedAssetInfo");
+function unsizedBasket() {
+  return {
+    maxNotional: null,
+    legs: [],
+    bindingConstraint: null
+  };
+}
+__name(unsizedBasket, "unsizedBasket");
 
 export { BinanceAccountTracker };

package/dist/tracker/binance/types.js

@@ -1,7 +1 @@
-var BinanceAccountType = /* @__PURE__ */ (function(BinanceAccountType2) {
-  BinanceAccountType2["MULTI_ASSET"] = "MULTI_ASSET";
-  BinanceAccountType2["SINGLE_ASSET"] = "SINGLE_ASSET";
-  return BinanceAccountType2;
-})({});
 
-export { BinanceAccountType };

package/dist/tracker/bybit/balance.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { AccountBalanceCore } from '../balance-core';
+
+const BybitIsolatedMarginBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("bybit:isolatedMargin")
+});
+const BybitRegularMarginBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("bybit:regularMargin")
+});
+const BybitPortfolioMarginBalance = AccountBalanceCore.extend({
+  accountMode: z.literal("bybit:portfolioMargin")
+});
+
+export { BybitIsolatedMarginBalance, BybitPortfolioMarginBalance, BybitRegularMarginBalance };