@pear-protocol/exchanges-sdk 0.6.7 → 0.8.0

package/README.md

@@ -49,7 +49,7 @@ await tracker.start();
 
 const offBalance = tracker.trackBalance((balance) => {
   if (!balance) return; // unsupported/unrepresentable account mode
-  console.log(balance.totalEquity, balance.unrealizedPnl);
+  console.log(balance.accountMode, balance.totalEquity);
 });
 
 const offPositions = tracker.trackPosition((positions) => {
@@ -68,7 +68,7 @@ Pass `demo: true` to target each exchange's test or simulated-trading environmen
 const exchanges = new ExchangesSDK({ sdk, demo: true });
 ```
 
-Hyperliquid and Lighter public REST/WebSocket reads are routed to testnet. Lighter operations that require a backend-generated auth token or signature currently fail closed in demo mode because the existing supporting API signs for mainnet only; public snapshots and tracking remain available, without authenticated account-tier enrichment.
+Hyperliquid and Lighter public REST/WebSocket reads are routed to testnet. Lighter operations that require a backend-generated auth token or signature currently fail closed in demo mode because the existing supporting API signs for mainnet only; public snapshots and tracking remain available.
 
 ## Connection
 
@@ -125,7 +125,7 @@ Possible warning reasons:
 | `hyperliquid_api_wallet_invalid` | Hyperliquid agent wallet is missing or invalid |
 | `hyperliquid_builder_fee_not_approved` | Hyperliquid builder fee approval is missing |
 | `hyperliquid_account_mode_check_failed` | Hyperliquid account mode could not be read |
-| `hyperliquid_account_mode_unsupported` | Portfolio Margin or deprecated DEX Abstraction cannot be valued safely |
+| `hyperliquid_account_mode_unsupported` | Hyperliquid reports an account mode this SDK does not model |
 | `lighter_api_key_invalid` | Lighter API key cannot create an auth token |
 | `lighter_integrator_not_approved` | Lighter integrator approval is missing |
 
@@ -136,14 +136,15 @@ When you only need the current balance and positions once — a request/response
 ```typescript
 const { balance, positions } = await exchanges.snapshot(tradeAccountId);
 
+balance?.accountMode;
 balance?.totalEquity;
-balance?.availableToTrade;
+balance?.availableMargin;
 for (const p of positions) {
   console.log(p.symbol, p.side, p.leverage, p.liquidationPrice);
 }
 ```
 
-`snapshot()` returns the same `AccountBalance` / `AccountPosition` shapes the live tracker produces — `{ balance: AccountBalance | null; positions: AccountPosition[] }` — so either path can feed the same consumer. `balance` is `null` when the account type cannot be represented safely. Hyperliquid currently supports Standard and Unified calculations; Portfolio Margin and deprecated DEX Abstraction fail closed and are surfaced by account status.
+`snapshot()` returns the same `AccountBalance` / `AccountPosition` shapes the live tracker produces — `{ balance: AccountBalance | null; positions: AccountPosition[] }` — so either path can feed the same consumer. `balance` is `null` when the account mode cannot be represented safely. Hyperliquid Standard, Unified and Portfolio Margin each have their own calculation; an abstraction string this SDK does not model fails closed and is surfaced by account status.
 
 There is nothing to tear down: no `disconnect()`, no socket. This is the read a stateless caller (such as an MCP tool) wants.
 
@@ -176,35 +177,110 @@ The read is batch-first: each connector services the whole list with as few requ
 
 > For Lighter, a custom margin setting on a market with **no open position** is not exposed by the REST account read, so it reports the market default — the same figure the live path shows before a position exists.
 
+## Basket Sizing
+
+`maxBasketSize()` answers "how large can this basket be opened on this account". A basket is atomic — every leg executes or none do — so the answer is **one** gross notional for the whole structure, and the per-leg figures are that number spread back over the weights, never independently reachable maxima.
+
+```typescript
+const sized = await exchanges.maxBasketSize(tradeAccountId, {
+  legs: [
+    { asset: 'BTC', side: 'BUY', weight: 60, leverage: '10', marginMode: 'cross' },
+    { asset: 'ETH', side: 'SELL', weight: 40, leverage: '10', marginMode: 'cross' },
+  ],
+});
+
+sized.maxNotional;       // string | null — the whole basket's max GROSS notional in USD
+sized.bindingConstraint; // which pool or leg ran out first
+for (const leg of sized.legs) {
+  console.log(leg.asset, leg.notional, leg.marginRequired);
+}
+```
+
+`weight` is unsigned and the set sums to 100; `side` does not enter the maths, because a margin requirement does not depend on direction.
+
+The same call is on a running tracker, over either read path:
+
+```typescript
+await tracker.maxBasketSize(input);         // live path
+await tracker.snapshotMaxBasketSize(input); // REST only, no socket
+```
+
+Sizing charges each leg's margin to the collateral pool it actually draws on, and the basket stops at whichever pool runs out first. `bindingConstraint` names it: `{ kind: 'cross-pool', pool }` when a pool's budget bound the basket, `{ kind: 'isolated-leg', asset }` when one leg reached its own venue ceiling first.
+
+A leg's margin fraction is `1 / min(requestedLeverage, venueMaxLeverage, currentAccountLeverage)`. The account's current leverage is in that minimum on purpose: the open path never sets leverage, so a requested leverage the venue has not been told about would overstate the size. On Hyperliquid each leg is additionally capped at its asset's next margin-tier boundary — a single-leg basket then reproduces the venue's own published `maxTradeSzs` exactly.
+
+`maxNotional` is `null` rather than zero in two cases: the venue publishes no per-asset maximum leverage the SDK reads today (Binance, Bybit and OKX all return `null`), or a leg draws on a collateral pool the SDK could not value. Sizing a basket against a pool it cannot value is exactly the guess this call exists to remove.
+
 ## Tracking
 
 Each `track*` method returns an unsubscribe function. Callbacks fire with the current snapshot on subscribe (if available) and on every update.
 
 ### Balance
 
+`AccountBalance` is a discriminated union tagged by `accountMode` — venue and mode in one literal, so narrowing needs no separate venue check. Every variant carries the same core; the tag adds the fields that venue and mode actually publish, and no others.
+
 ```typescript
 tracker.trackBalance((balance) => {
   if (!balance) return; // a live mode change can explicitly invalidate the cached balance
-  balance.totalEquity;
-  balance.walletBalance;
-  balance.unrealizedPnl;
-  balance.availableToTrade;
-  balance.initialMarginUsed;
-  balance.maintenanceMargin;
-  balance.marginRatio;
-  balance.accountType;
-  balance.accountTier; // Lighter account tier when reported
-
-  for (const a of balance.assets) {
-    a.asset;         // "USDT", "USDC", ...
-    a.free;
-    a.used;
-    a.total;
-    a.usdValue;
+
+  balance.accountMode;         // "hyperliquid:unified" | "binance:singleAsset" | ...
+  balance.totalEquity;         // string | null
+  balance.withdrawableBalance; // string | null — what can leave the account right now
+  balance.availableMargin;     // string | null — a floor across the tracked assets, not a per-asset figure
+  balance.poolsShared;         // boolean
+  balance.timestamp;
+
+  for (const pool of balance.perCollateral) {
+    pool.asset;           // "USDT", "USDC", "HYPE", ...
+    pool.equity;          // in THAT asset's own units
+    pool.availableMargin; // string | null
+    pool.withdrawable;    // string | null
   }
 });
 ```
 
+**`null` means "this venue cannot tell us" — never zero.** Every nullable field follows that one rule: a figure the venue does not publish, or one that cannot be derived without guessing, is `null`. A zero is a zero, and the two are never interchangeable.
+
+**`perCollateral` rows are in each asset's own units, never converted.** A row is never turned into USD and two rows are never added together — a USDC row and an ETH row share a column and nothing else. The only USD figures in a variant are the scalars.
+
+**`poolsShared` says what those rows mean.** `true`: one pool funds every position, so the rows are holdings inside it and only the scalars are spendable. `false`: the rows are separate budgets that cannot fund each other — on Binance single-asset a USDT-settled contract draws USDT margin and a USDC-settled one draws USDC, and neither can pay for the other.
+
+On the three venues whose pools are separate *and* whose account-level figures cover one currency only — Binance single-asset, OKX Spot and OKX Futures — the core scalars carry the venue's own figure when exactly one pool holds a non-zero balance, and `null` once two or more do. They are never summed across pools. Hyperliquid splits by mode: Standard and Unified report `poolsShared: false` with one row per collateral token, while Portfolio Margin reports `true` — it lends against every holding at that coin's LTV, so the rows are holdings in one pool. All three keep their scalars in every case: `availableMargin` is already a per-asset floor.
+
+#### Narrowing on `accountMode`
+
+Fields beyond the core belong to a variant. Switch on the tag to reach them, and write no `default:` clause — then a mode added in a later release fails the build here instead of silently returning `undefined`.
+
+```typescript
+import type { AccountBalance } from '@pear-protocol/exchanges-sdk';
+
+function unrealizedPnlOf(balance: AccountBalance): string | null {
+  switch (balance.accountMode) {
+    // Hyperliquid and Lighter carry full per-mode detail.
+    case 'hyperliquid:standard':
+    case 'hyperliquid:unified':
+    case 'hyperliquid:portfolioMargin':
+    case 'lighter:classic':
+    case 'lighter:unified':
+      return balance.unrealizedPnl;
+
+    // The three CEXs carry the core only, so there is no figure to return.
+    case 'binance:singleAsset':
+    case 'binance:multiAsset':
+    case 'bybit:isolatedMargin':
+    case 'bybit:regularMargin':
+    case 'bybit:portfolioMargin':
+    case 'okx:spot':
+    case 'okx:futures':
+    case 'okx:multiCurrencyMargin':
+    case 'okx:portfolioMargin':
+      return null;
+  }
+}
+```
+
+Each variant is exported as both a zod schema and its inferred type — `HyperliquidStandardBalance`, `HyperliquidUnifiedBalance`, `HyperliquidPortfolioMarginBalance`, `LighterClassicBalance`, `LighterUnifiedBalance`, `BinanceSingleAssetBalance`, `BinanceMultiAssetBalance`, `BybitIsolatedMarginBalance`, `BybitRegularMarginBalance`, `BybitPortfolioMarginBalance`, `OkxSpotBalance`, `OkxFuturesBalance`, `OkxMultiCurrencyMarginBalance`, `OkxPortfolioMarginBalance` — alongside `AccountBalanceCore` and `CollateralBalance`.
+
 ### Positions
 
 ```typescript
@@ -256,16 +332,20 @@ tracker.isConnected;
 tracker.isInitialized;           // true after first balance/position state (asset metadata alone does not count)
 ```
 
-## Account Type Labels
+## Account Mode Labels
 
-`balance.accountType` is an exchange-specific enum. Render with:
+`balance.accountMode` names the venue and the mode together. Render it with the label the venue's own account page uses:
 
 ```typescript
-import { ACCOUNT_TYPE_LABELS } from '@pear-protocol/exchanges-sdk';
+import { ACCOUNT_MODE_LABELS } from '@pear-protocol/exchanges-sdk';
 
-ACCOUNT_TYPE_LABELS[balance.accountType]; // "Cross Margin", "Portfolio Margin", ...
+ACCOUNT_MODE_LABELS['hyperliquid:unified']; // "Unified Account"
+ACCOUNT_MODE_LABELS['binance:singleAsset']; // "Single-Asset Mode"
+ACCOUNT_MODE_LABELS[balance.accountMode];
 ```
 
+The map covers every member of `AccountMode`, so a mode added later cannot leave a gap.
+
 ## Cleanup
 
 ```typescript

package/dist/client/bybit/rest.js

@@ -57,6 +57,13 @@ async function fetchAccountInfo(creds, demo) {
   return signedGet(creds, "/v5/account/info", {}, demo);
 }
 __name(fetchAccountInfo, "fetchAccountInfo");
+const TRANSFERABLE_MAX_COINS = 20;
+async function fetchTransferableAmount(creds, coins, demo) {
+  return signedGet(creds, "/v5/account/withdrawal", {
+    coinName: coins.slice(0, TRANSFERABLE_MAX_COINS).join(",")
+  }, demo);
+}
+__name(fetchTransferableAmount, "fetchTransferableAmount");
 async function fetchCollateralRatios(creds, demo) {
   const result = await signedGet(creds, "/v5/spot-margin-uta/tier-collateral-ratio", {}, demo);
   const ratios = /* @__PURE__ */ new Map();
@@ -101,4 +108,4 @@ async function fetchExecutionsSince(creds, since, demo) {
 }
 __name(fetchExecutionsSince, "fetchExecutionsSince");
 
-export { fetchAccountInfo, fetchCollateralRatios, fetchExecutionsSince, fetchPositionLeverage, fetchPositions, fetchWalletBalance };
+export { fetchAccountInfo, fetchCollateralRatios, fetchExecutionsSince, fetchPositionLeverage, fetchPositions, fetchTransferableAmount, fetchWalletBalance };

package/dist/client/hyperliquid/rest.js

@@ -56,6 +56,26 @@ async function fetchSpotClearinghouseState(user, demo = false) {
   }, demo);
 }
 __name(fetchSpotClearinghouseState, "fetchSpotClearinghouseState");
+async function fetchAllMids(demo = false) {
+  return fetchInfo({
+    type: "allMids"
+  }, demo);
+}
+__name(fetchAllMids, "fetchAllMids");
+async function fetchDelegatorSummary(user, demo = false) {
+  return fetchInfo({
+    type: "delegatorSummary",
+    user
+  }, demo);
+}
+__name(fetchDelegatorSummary, "fetchDelegatorSummary");
+async function fetchUserVaultEquities(user, demo = false) {
+  return fetchInfo({
+    type: "userVaultEquities",
+    user
+  }, demo);
+}
+__name(fetchUserVaultEquities, "fetchUserVaultEquities");
 async function fetchActiveAssetData(user, coin, demo = false) {
   return fetchInfo({
     type: "activeAssetData",
@@ -65,4 +85,4 @@ async function fetchActiveAssetData(user, coin, demo = false) {
 }
 __name(fetchActiveAssetData, "fetchActiveAssetData");
 
-export { fetchActiveAssetData, fetchClearinghouseState, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole };
+export { fetchActiveAssetData, fetchAllMids, fetchClearinghouseState, fetchDelegatorSummary, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole, fetchUserVaultEquities };

package/dist/client/lighter/rest.js

@@ -144,15 +144,6 @@ async function fetchAccount(accountIndex, demo = false) {
   return readLighterResponse(response, "/account");
 }
 __name(fetchAccount, "fetchAccount");
-async function fetchAccountLimits(accountIndex, authToken, demo = false) {
-  const response = await proxyFetch(`${getLighterBaseUrl(demo)}/api/v1/accountLimits?account_index=${accountIndex}`, {
-    headers: {
-      authorization: authToken
-    }
-  });
-  return readLighterResponse(response, "/accountLimits");
-}
-__name(fetchAccountLimits, "fetchAccountLimits");
 async function fetchAccountMetadata(accountIndex, authToken, demo = false) {
   const response = await proxyFetch(`${getLighterBaseUrl(demo)}/api/v1/accountMetadata?by=index&value=${accountIndex}`, {
     headers: {
@@ -168,9 +159,12 @@ async function fetchAccountMetadata(accountIndex, authToken, demo = false) {
 }
 __name(fetchAccountMetadata, "fetchAccountMetadata");
 async function fetchOrderBookDetails(demo = false) {
-  const response = await proxyFetch(`${getLighterBaseUrl(demo)}/api/v1/orderBookDetails?filter=perp`);
+  const response = await proxyFetch(`${getLighterBaseUrl(demo)}/api/v1/orderBookDetails`);
   const data = await readLighterResponse(response, "/orderBookDetails");
-  return data.order_book_details;
+  return {
+    perp: data.order_book_details ?? [],
+    spot: data.spot_order_book_details ?? []
+  };
 }
 __name(fetchOrderBookDetails, "fetchOrderBookDetails");
 async function fetchAssetDetails(demo) {
@@ -289,4 +283,4 @@ async function readLighterResponse(response, endpoint, acceptedCodes = [
 }
 __name(readLighterResponse, "readLighterResponse");
 
-export { createCctpDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchTradesSince };
+export { createCctpDepositIntentAddress, fetchAccount, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchTradesSince };

package/dist/client/okx/rest.js

@@ -49,6 +49,10 @@ async function fetchBalance(creds, demo) {
   return data[0];
 }
 __name(fetchBalance, "fetchBalance");
+async function fetchMaxWithdrawals(creds, demo) {
+  return signedGet(creds, "/api/v5/account/max-withdrawal", {}, demo);
+}
+__name(fetchMaxWithdrawals, "fetchMaxWithdrawals");
 async function fetchPositions(creds, demo) {
   return signedGet(creds, "/api/v5/account/positions", {
     instType: "SWAP"
@@ -94,4 +98,4 @@ async function fetchFillsHistorySince(creds, since, demo) {
 }
 __name(fetchFillsHistorySince, "fetchFillsHistorySince");
 
-export { fetchAccountConfig, fetchBalance, fetchFillsHistorySince, fetchLeverageInfos, fetchPositions };
+export { fetchAccountConfig, fetchBalance, fetchFillsHistorySince, fetchLeverageInfos, fetchMaxWithdrawals, fetchPositions };