@pear-protocol/exchanges-sdk 0.17.1 → 0.19.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,50 @@ 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.
+
+## Hyperliquid subaccount funding
+
+```typescript
+import { createHyperliquidHelper } from '@pear-protocol/exchanges-sdk';
+
+const helper = createHyperliquidHelper();
+await helper.transferSubAccount(ownerWallet, {
+  subAccountAddress: '0x...',
+  direction: 'main-to-subaccount', // use 'subaccount-to-main' to return USDC
+  amount: '1.25',
+});
+```
+
+Supply the owning main account's wallet (a viem wallet client/account or an ethers signer) in both
+directions. Every transfer uses owner-signed `sendAsset` with `sourceDex: "spot"` and
+`destinationDex: "spot"`. An approved API agent cannot sign this action. Browser wallet clients use
+their connected chain for EIP-712 signing.
+
+For standard accounts, this moves the separate spot USDC balance and does not fund perpetual
+collateral. Unified and portfolio-margin accounts use their shared spot balance. The helper checks
+subaccount ownership before signing. It does not read or change either account's mode.
+
+A newly created standard subaccount receives USDC in spot and cannot use that balance as perpetual
+margin. Before trading perps, make a separate owner-signed
+[`usdClassTransfer`](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#transfer-from-spot-account-to-perp-account-and-vice-versa)
+with `toPerp: true` and `subaccount:<address>` appended to the amount. The funding helper does not
+submit this second action. A standard main account with USDC in perps must first move the intended
+amount to spot before calling this helper.
+
+The helper uses a fixed USDC token ID for the selected network without a metadata lookup, and the
+amount stays an exact decimal string. Each successful transfer makes two information reads: the
+signer's role and the subaccount's role and ownership. It then submits one transfer action.
+
+Amounts must be positive decimal strings with at most six fractional digits and must fit the
+existing safe integer micro-USDC limit (`9007199254.740991` USDC). The helper never rounds an amount.
+
+Failures reach the caller without retries or fallback actions. After a timeout or connection loss,
+check transfer history and balances before making another call; submission may have succeeded.
+
+The routing and signing follow Hyperliquid's [Send Asset API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#send-asset),
+[account modes](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/account-abstraction-modes),
+and [official signing implementation](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/hyperliquid/utils/signing.py).

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,7 +1,16 @@
+import { HttpTransport } from '@nktkas/hyperliquid';
+import { sendAsset, createSubAccount } from '@nktkas/hyperliquid/api/exchange';
+import { getWalletAddress } from '@nktkas/hyperliquid/signing';
+import { formatUnits } from 'viem';
 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 });
+const USDC_TOKENS = {
+  mainnet: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054",
+  testnet: "USDC:0xeb62eee3685fc4c43992febcd9e75443"
+};
 function createHyperliquidHelper(demo = false) {
   return {
     /**
@@ -14,6 +23,64 @@ function createHyperliquidHelper(demo = false) {
       const role = await fetchUserRole(userAddress, demo);
       return role.role !== "missing";
     },
+    /**
+    * 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 spot USDC between owned accounts using the owning main wallet. */
+    async transferSubAccount(wallet, params) {
+      const usd = parseCollateralAmount(params.amount, "USDC");
+      const ownerAddress = await getWalletAddress(wallet);
+      const signerRole = await fetchUserRole(ownerAddress, demo);
+      if (signerRole.role === "agent") {
+        throw new Error("Spot subaccount transfers require the owner wallet; an approved agent cannot sign");
+      }
+      if (signerRole.role !== "user") {
+        throw new Error("Spot subaccount transfers require the owner wallet");
+      }
+      const subAccountRole = await fetchUserRole(params.subAccountAddress, demo);
+      if (subAccountRole.role !== "subAccount" || subAccountRole.data.master.toLowerCase() !== ownerAddress.toLowerCase()) {
+        throw new Error("Subaccount does not belong to the signing main account");
+      }
+      const isDeposit = isMainToSubAccount(params.direction);
+      const transport = new HttpTransport({
+        isTestnet: demo
+      });
+      await sendAsset({
+        transport,
+        wallet
+      }, {
+        destination: isDeposit ? params.subAccountAddress : ownerAddress,
+        sourceDex: "spot",
+        destinationDex: "spot",
+        token: demo ? USDC_TOKENS.testnet : USDC_TOKENS.mainnet,
+        amount: formatUnits(BigInt(usd), 6),
+        fromSubAccount: isDeposit ? "" : params.subAccountAddress
+      });
+    },
+    /** 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({
@@ -46,5 +113,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 @@
+