@pear-protocol/exchanges-sdk 0.17.0 → 0.18.0

package/README.md

@@ -2,6 +2,30 @@
 
 Unified SDK for account state (balance, positions, per-asset leverage) across supported derivative exchanges — as a live WebSocket subscription or a stateless one-shot snapshot.
 
+## Public trading equity
+
+```typescript
+const trader = await sdk.core.traders.public(tradeAccountId);
+const equity = await exchanges.tradingEquity(trader);
+console.log(equity.tradingEquityUsd, equity.timestamp);
+```
+
+Pass the returned public identity directly; only `connector` and `exchangeIdentifier` are used.
+This read supports Hyperliquid, Lighter, and Lighter RHC without credentials or starting a stream.
+It includes unrealized PnL and spot holdings, excludes staking and vault deposits, and rejects
+failed reads or unpriceable holdings. Equity refreshes do not reload the public trader resources.
+
+The same public identity can create a tracker for explicit REST snapshots:
+
+```typescript
+const tracker = exchanges.createTracker(trader, { access: 'public' });
+const snapshot = await tracker.snapshot();
+const equity = await tracker.tradingEquity();
+```
+
+Public Lighter trackers support REST reads only. Private account streams and tier reads still
+require an authenticated connection. Existing `createTracker(connection)` calls keep their behavior.
+
 ## Supported Exchanges
 
 | Exchange | Connector | Market |
@@ -279,6 +303,8 @@ tracker.trackBalance((balance) => {
 
 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.
 
+**Hyperliquid also lists the whole spot wallet.** Every Hyperliquid variant carries `spotHoldings`: one row per coin the venue lists, in every mode, including coins no perp dex settles in (which `perCollateral` leaves out in Standard and Unified). A row carries `asset`, `token`, and the venue's signed `total`, `hold` and `entryNotional`. `entryNotional` is what the holding cost, not what it is worth, and is `null` when the venue sends none. Rows are never priced: value the wallet with the variant's equity scalar.
+
 #### 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`.
@@ -386,3 +412,7 @@ await tracker.disconnect(); // closes the WebSocket opened by start()
 ```
 
 Credentials and the trade account are fetched automatically on `connect`; Hyperliquid and Lighter account identifiers come from `connection.account.exchangeIdentifier`.
+
+Pear returns the public trader identity only while its owner enables `sharingEnabled` in
+trade account settings. Disabling it hides future Pear reads; the exchange public APIs
+remain address-based and independent of Pear consent.

package/dist/client/lighter/rest.js

@@ -221,6 +221,17 @@ async function fetchAccountMetadata(accountIndex, authToken, connector, demo = f
   }
 }
 __name(fetchAccountMetadata, "fetchAccountMetadata");
+async function fetchAccountMetadataByL1Address(l1Address, authToken, demo = false, connector = "lighter") {
+  const response = await proxyFetch(`${getLighterBaseUrl(connector, demo)}/api/v1/accountMetadata?by=l1_address&value=${encodeURIComponent(l1Address)}`, {
+    headers: {
+      accept: "application/json",
+      authorization: authToken
+    }
+  });
+  const data = await readLighterResponse(response, "/accountMetadata");
+  return data.account_metadatas ?? [];
+}
+__name(fetchAccountMetadataByL1Address, "fetchAccountMetadataByL1Address");
 async function fetchOrderBookDetails(authToken, connector, demo = false) {
   const response = await authenticatedLighterFetch(`${getLighterBaseUrl(connector, demo)}/api/v1/orderBookDetails`, authToken);
   const data = await readLighterResponse(response, "/orderBookDetails");
@@ -525,4 +536,4 @@ function readReferralAmount(value) {
 }
 __name(readReferralAmount, "readReferralAmount");
 
-export { LighterRequestError, createDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchPublicAccount, fetchPublicOrderBookDetails, fetchTradesSince, fetchUserReferrals, fetchWithdrawHistory, submitReferralCode };
+export { LighterRequestError, createDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountMetadataByL1Address, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchPublicAccount, fetchPublicOrderBookDetails, fetchTradesSince, fetchUserReferrals, fetchWithdrawHistory, submitReferralCode };

package/dist/helper/hyperliquid/helper.js

@@ -1,4 +1,7 @@
+import { HttpTransport } from '@nktkas/hyperliquid';
+import { subAccountTransfer, createSubAccount } from '@nktkas/hyperliquid/api/exchange';
 import { fetchInfo, fetchUserRole } from '../../client/hyperliquid/rest';
+import { parseCollateralAmount } from '../subaccount.helper';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -14,14 +17,63 @@ function createHyperliquidHelper(demo = false) {
       const role = await fetchUserRole(userAddress, demo);
       return role.role !== "missing";
     },
-    /** Checks that the requested API wallet exists and has not expired. */
+    /**
+    * Creates a named subaccount under the signer's main account. This is an L1 action pinned to
+    * chainId 1337, which browser wallets reject, so the signer is normally the approved agent key.
+    */
+    async createSubAccount(wallet, params) {
+      const transport = new HttpTransport({
+        isTestnet: demo
+      });
+      const response = await createSubAccount({
+        transport,
+        wallet
+      }, params);
+      return {
+        subAccountAddress: response.response.data
+      };
+    },
+    /** Moves perpetual USDC between a main account and one of its subaccounts. */
+    async transferSubAccount(wallet, params) {
+      const usd = parseCollateralAmount(params.amount, "USDC");
+      const transport = new HttpTransport({
+        isTestnet: demo
+      });
+      await subAccountTransfer({
+        transport,
+        wallet
+      }, {
+        subAccountUser: params.subAccountAddress,
+        isDeposit: isMainToSubAccount(params.direction),
+        usd
+      });
+    },
+    /** Lists a main account's existing subaccounts for transfer-destination selection. */
+    async listSubAccounts(userAddress) {
+      const subAccounts = await fetchInfo({
+        type: "subAccounts",
+        user: userAddress
+      }, demo);
+      return (subAccounts ?? []).map((subAccount) => ({
+        name: subAccount.name,
+        subAccountUser: subAccount.subAccountUser
+      }));
+    },
+    /** Checks ownership and expiry for named and unnamed API wallets. */
     async checkApiWallet(params) {
       const agents = await fetchInfo({
         type: "extraAgents",
         user: params.userAddress
       }, demo);
-      const now = Date.now();
-      return agents.some((agent) => agent.address.toLowerCase() === params.agentWalletAddress.toLowerCase() && (agent.validUntil === null || agent.validUntil > now));
+      const matchingAgent = agents.find((candidate) => candidate.address.toLowerCase() === params.agentWalletAddress.toLowerCase());
+      if (matchingAgent) {
+        return matchingAgent.validUntil === null || matchingAgent.validUntil > Date.now();
+      }
+      const { userState } = await fetchInfo({
+        type: "webData3",
+        user: params.userAddress
+      }, demo);
+      return userState.agentAddress?.toLowerCase() === params.agentWalletAddress.toLowerCase() && (userState.agentValidUntil === null || userState.agentValidUntil > Date.now());
     },
     /** Checks that the approval covers the exact builder fee requested by orders. */
     async checkBuilderFeeApproval(userAddress, builderAddress, requiredFeeTenthsBps) {
@@ -39,5 +91,14 @@ function createHyperliquidHelper(demo = false) {
   };
 }
 __name(createHyperliquidHelper, "createHyperliquidHelper");
+function isMainToSubAccount(direction) {
+  switch (direction) {
+    case "main-to-subaccount":
+      return true;
+    case "subaccount-to-main":
+      return false;
+  }
+}
+__name(isMainToSubAccount, "isMainToSubAccount");
 
 export { createHyperliquidHelper };

package/dist/helper/index.js

@@ -1,3 +1,5 @@
 export * from './hyperliquid';
 export * from './lighter';
+export * from './subaccount.helper';
+export * from './subaccount.types';
 export * from './types';

package/dist/helper/lighter/helper.js

@@ -1,5 +1,5 @@
 import { isAddress, parseUnits } from 'viem';
-import { fetchApiKeys, fetchAccount, fetchPublicAccount, fetchAccountsByL1Address } from '../../client/lighter/rest';
+import { fetchApiKeys, fetchAccount, fetchPublicAccount, fetchAccountMetadataByL1Address } from '../../client/lighter/rest';
 import { LIGHTER_QUOTE_ASSETS } from '../../tracker/lighter/const';
 import { parseCollateralAmount } from '../subaccount.helper';
 import { resolveAssetDecimals } from './asset-decimals.helper';
@@ -8,9 +8,10 @@ import { createDepositAddressForRoute, depositThroughRoute } from './deposit.hel
 import { writeWithdraw } from './ethereum';
 import { readWithdrawHistory, readDepositHistory } from './history.helper';
 import { selectLighterMiscRoutes } from './misc-routes.helper';
-import { LIGHTER_ACCOUNT_NOT_REGISTERED_CODE, readOnboardingStatus } from './onboarding.helper';
+import { readOnboardingStatus } from './onboarding.helper';
 import { readUserReferrals, applyReferralCode } from './referral.helper';
 import { depositUsdgOnRobinhoodChain, createRhcDepositAddress } from './rhc-deposit.helper';
+import { lookupLighterAccount, transferLighterSubAccount, setLighterSubAccountMetadata, createNamedLighterSubAccount, createLighterSubAccount } from './subaccount.helper';
 import { MIN_LIGHTER_FAST_WITHDRAW_COLLATERAL } from './types';
 
 var __defProp = Object.defineProperty;
@@ -84,6 +85,40 @@ function buildSharedLighterHelper(sdk, connector, demo) {
   const collateralSymbol = LIGHTER_QUOTE_ASSETS[connector];
   const minFastWithdraw = MIN_LIGHTER_FAST_WITHDRAW_COLLATERAL[connector];
   return {
+    /** Fetches full account metadata across an L1 address's account family, keyed by account index. */
+    async fetchAccountMetadata(params) {
+      if (demo) {
+        throw new Error("Lighter demo account metadata is unavailable because backend signing is mainnet-only");
+      }
+      const { token } = await misc.createAuthToken({
+        accountIndex: params.accountIndex,
+        apiKeyIndex: params.apiKeyIndex,
+        apiPrivateKey: params.apiPrivateKey
+      });
+      const metadatas = await fetchAccountMetadataByL1Address(params.l1Address, token, demo, connector);
+      return {
+        accounts: Object.fromEntries(metadatas.map((metadata) => [
+          metadata.account_index,
+          metadata
+        ]))
+      };
+    },
+    /** Creates a Lighter subaccount from the main account's API credentials. */
+    async createSubAccount(params) {
+      return createLighterSubAccount(sdk, params, connector, demo);
+    },
+    /** Creates, discovers, and names a Lighter subaccount before reporting completion. */
+    async createNamedSubAccount(params) {
+      return createNamedLighterSubAccount(sdk, params, connector, demo);
+    },
+    /** Sets a Lighter subaccount's display name and description. */
+    async setSubAccountMetadata(params) {
+      return setLighterSubAccountMetadata(sdk, params, connector, demo);
+    },
+    /** Moves perpetual collateral between a Lighter main account and one of its subaccounts. */
+    async transferSubAccount(params) {
+      return transferLighterSubAccount(sdk, params, connector, demo);
+    },
     /** Reports whether an L1 address still needs its first deposit before it owns a Lighter account. */
     async checkOnboarding(l1Address) {
       if (!isAddress(l1Address)) {
@@ -91,20 +126,9 @@ function buildSharedLighterHelper(sdk, connector, demo) {
       }
       return readOnboardingStatus(l1Address, connector, demo);
     },
+    /** Reads the selected deployment's account family. */
     async lookupAccount(l1Address) {
-      const data = await fetchAccountsByL1Address(l1Address, connector, demo);
-      if (data.code === LIGHTER_ACCOUNT_NOT_REGISTERED_CODE) {
-        throw new Error("Account not registered on Lighter");
-      }
-      const accounts = data.sub_accounts ?? [];
-      const main = accounts.find((s) => s.account_type === 0);
-      if (!main) {
-        throw new Error("Main account not found for this address");
-      }
-      return {
-        mainAccountIndex: main.index,
-        subAccountIndexes: accounts.filter((s) => s.account_type !== 0).map((s) => s.index)
-      };
+      return lookupLighterAccount(l1Address, connector, demo);
     },
     async checkIntegratorApproval(accountIndex, integratorAccountIndex, requirements, authToken) {
       if (requirements) validateApprovalRequirements(requirements);

package/dist/helper/lighter/subaccount.helper.js

@@ -0,0 +1,118 @@
+import { fetchAccountsByL1Address } from '../../client/lighter/rest';
+import { LIGHTER_QUOTE_ASSETS } from '../../tracker/lighter/const';
+import { parseCollateralAmount } from '../subaccount.helper';
+import { selectLighterMiscRoutes } from './misc-routes.helper';
+import { LIGHTER_ACCOUNT_NOT_REGISTERED_CODE } from './onboarding.helper';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const NEW_SUBACCOUNT_POLL_INTERVAL_MS = 1500;
+const NEW_SUBACCOUNT_POLL_ATTEMPTS = 8;
+async function createNamedLighterSubAccount(sdk, params, connector, demo) {
+  if (demo) {
+    throw new Error("Lighter demo subaccount creation is unavailable because backend signing is mainnet-only");
+  }
+  const family = await lookupLighterAccount(params.l1Address, connector, demo);
+  const knownIndexes = new Set(family.subAccountIndexes);
+  const result = await createLighterSubAccount(sdk, params, connector, demo);
+  const subAccountIndex = await resolveNewLighterSubAccountIndex(params.l1Address, knownIndexes, connector, demo);
+  await setLighterSubAccountMetadata(sdk, {
+    ...params,
+    subAccountIndex
+  }, connector, demo);
+  return {
+    ...result,
+    subAccountIndex
+  };
+}
+__name(createNamedLighterSubAccount, "createNamedLighterSubAccount");
+async function createLighterSubAccount(sdk, params, connector, demo) {
+  if (demo) {
+    throw new Error("Lighter demo subaccount creation is unavailable because backend signing is mainnet-only");
+  }
+  return selectLighterMiscRoutes(sdk, connector).createSubAccount({
+    accountIndex: params.mainAccountIndex,
+    apiKeyIndex: params.apiKeyIndex,
+    apiPrivateKey: params.apiPrivateKey
+  });
+}
+__name(createLighterSubAccount, "createLighterSubAccount");
+async function setLighterSubAccountMetadata(sdk, params, connector, demo) {
+  if (demo) {
+    throw new Error("Lighter demo subaccount metadata is unavailable because backend signing is mainnet-only");
+  }
+  await selectLighterMiscRoutes(sdk, connector).setSubAccountMetadata({
+    mainAccountIndex: params.mainAccountIndex,
+    subAccountIndex: params.subAccountIndex,
+    apiKeyIndex: params.apiKeyIndex,
+    apiPrivateKey: params.apiPrivateKey,
+    name: params.name,
+    description: params.description
+  });
+}
+__name(setLighterSubAccountMetadata, "setLighterSubAccountMetadata");
+async function transferLighterSubAccount(sdk, params, connector, demo) {
+  if (demo) {
+    throw new Error("Lighter demo subaccount transfers are unavailable because backend signing is mainnet-only");
+  }
+  const accounts = resolveTransferAccounts(params.mainAccountIndex, params.subAccountIndex, params.direction);
+  const amount = parseCollateralAmount(params.amount, LIGHTER_QUOTE_ASSETS[connector]);
+  return selectLighterMiscRoutes(sdk, connector).transferSubAccount({
+    l1Address: params.l1Address,
+    fromAccountIndex: accounts.fromAccountIndex,
+    toAccountIndex: accounts.toAccountIndex,
+    amount,
+    apiKeyIndex: params.apiKeyIndex,
+    apiPrivateKey: params.apiPrivateKey
+  });
+}
+__name(transferLighterSubAccount, "transferLighterSubAccount");
+async function lookupLighterAccount(l1Address, connector, demo) {
+  const data = await fetchAccountsByL1Address(l1Address, connector, demo);
+  if (data.code === LIGHTER_ACCOUNT_NOT_REGISTERED_CODE) {
+    throw new Error("Account not registered on Lighter");
+  }
+  const accounts = data.sub_accounts ?? [];
+  const main = accounts.find((account) => account.account_type === 0);
+  if (!main) {
+    throw new Error("Main account not found for this address");
+  }
+  return {
+    mainAccountIndex: main.index,
+    subAccountIndexes: accounts.filter((account) => account.account_type === 1).map((account) => account.index)
+  };
+}
+__name(lookupLighterAccount, "lookupLighterAccount");
+function resolveTransferAccounts(mainAccountIndex, subAccountIndex, direction) {
+  switch (direction) {
+    case "main-to-subaccount":
+      return {
+        fromAccountIndex: mainAccountIndex,
+        toAccountIndex: subAccountIndex
+      };
+    case "subaccount-to-main":
+      return {
+        fromAccountIndex: subAccountIndex,
+        toAccountIndex: mainAccountIndex
+      };
+  }
+}
+__name(resolveTransferAccounts, "resolveTransferAccounts");
+async function resolveNewLighterSubAccountIndex(l1Address, knownIndexes, connector, demo) {
+  for (let attempt = 0; attempt < NEW_SUBACCOUNT_POLL_ATTEMPTS; attempt += 1) {
+    const lookup = await lookupLighterAccount(l1Address, connector, demo);
+    const newIndexes = lookup.subAccountIndexes.filter((index) => !knownIndexes.has(index));
+    if (newIndexes.length > 1) {
+      throw new Error("Subaccount created, but multiple new accounts appeared. Refresh and set its name manually.");
+    }
+    const [newIndex] = newIndexes;
+    if (newIndex !== void 0) {
+      return newIndex;
+    }
+    await new Promise((resolve) => setTimeout(resolve, NEW_SUBACCOUNT_POLL_INTERVAL_MS));
+  }
+  throw new Error("Subaccount created, but its index is not visible yet. Refresh and set its name shortly.");
+}
+__name(resolveNewLighterSubAccountIndex, "resolveNewLighterSubAccountIndex");
+
+export { createLighterSubAccount, createNamedLighterSubAccount, lookupLighterAccount, setLighterSubAccountMetadata, transferLighterSubAccount };

package/dist/helper/subaccount.types.js

@@ -0,0 +1 @@
+