@pear-protocol/exchanges-sdk 0.16.0 → 0.17.0

package/README.md

@@ -103,6 +103,38 @@ Hyperliquid status requires the builder address and the minimum approved fee in
 
 Historical Hyperliquid fill synchronization identifies fills by bare `tid` and requests them aggregated by time, so partial fills of one crossing order arrive as a single fill. Consumers that persisted composite `time:coin:tid` identifiers must account for the transition overlap. Hyperliquid serves only the 10,000 most recent fills; an account with a longer history imports from that boundary forward, and the snapshot-alignment synthetics cover the residual gap. Synchronization fails closed when the exchange reports a maker rebate: the current core external-fill contract accepts only non-negative fees, so the SDK will not silently turn a rebate into a cost or advance the synchronization watermark past it.
 
+## Public Tracker (address only)
+
+Hyperliquid answers account state for any address with no key, so an account the caller does not own, such as a vault's agent, can be tracked without `connect()`. `createPublicTracker` fetches no credentials and needs no trade account:
+
+```typescript
+const tracker = exchanges.createPublicTracker({
+  connector: 'hyperliquid',
+  address: '0x...',
+  onError: (error) => console.warn(error),
+});
+
+await tracker.start(); // rejects if the venue reads or the socket fail
+const offPositions = tracker.trackPosition((positions) => {
+  // Main-dex and HIP-3 positions together, e.g. `BTC` and `xyz:TSLA`
+});
+
+const { balance, positions } = await tracker.snapshot(); // REST, every perp dex, no socket
+
+offPositions();
+await tracker.disconnect();
+```
+
+It is the same `HyperliquidAccountTracker` the trade-account path builds, so live updates, reconnects, snapshots and cleanup behave identically. It only reads: nothing on it can trade.
+
+A read that has not landed never looks like an empty account. `trackPosition` first fires once the first `allDexsClearinghouseState` frame arrives, and `isInitialized` stays `false` until then. When the socket drops, the tracker clears its live state (`isInitialized` turns `false`, `getPositions()` returns `[]`) and reports the outage to `onError` once, however many reconnect attempts fail; listeners are not sent an empty list. Once the socket reopens it resubscribes, and `isInitialized` turns `true` again with the first fresh frame. A subscription the venue refuses, and a frame that cannot be mapped, also reach `onError`.
+
+To build one directly, `HyperliquidAccountTracker` now takes the address itself:
+
+```typescript
+new HyperliquidAccountTracker({ demo: false, address: '0x...', onError });
+```
+
 ## Account Status
 
 Use `status(connection)` to check whether the account is ready for trading through PEAR.

package/dist/client/base-ws.js

@@ -10,6 +10,7 @@ class BaseWs {
   pingTimer = null;
   messageListeners = /* @__PURE__ */ new Map();
   openListeners = /* @__PURE__ */ new Map();
+  closeListeners = /* @__PURE__ */ new Map();
   nextListenerId = 0;
   async connect() {
     if (this.ws) return;
@@ -42,6 +43,13 @@ class BaseWs {
     });
     ws.addEventListener("close", () => {
       this.stopPing();
+      for (const listener of this.closeListeners.values()) {
+        try {
+          listener();
+        } catch (error) {
+          console.warn("Error in ws close listener", error);
+        }
+      }
     });
     ws.addEventListener("error", () => {
     });
@@ -57,6 +65,7 @@ class BaseWs {
       }, "onOpen");
       const onError = /* @__PURE__ */ __name(() => {
         ws.removeEventListener("open", onOpen);
+        this.disconnect();
         reject(new Error("WebSocket connection failed"));
       }, "onError");
       ws.addEventListener("open", onOpen, {
@@ -98,10 +107,19 @@ class BaseWs {
   removeOpenListener(id) {
     this.openListeners.delete(id);
   }
+  addCloseListener(listener) {
+    const id = String(++this.nextListenerId);
+    this.closeListeners.set(id, listener);
+    return id;
+  }
+  removeCloseListener(id) {
+    this.closeListeners.delete(id);
+  }
   destroy() {
     this.disconnect();
     this.messageListeners.clear();
     this.openListeners.clear();
+    this.closeListeners.clear();
   }
   startPing() {
     this.stopPing();

package/dist/index.d.ts

@@ -54,17 +54,28 @@ type ConnectOptions = {
     integratorMinPerpsTakerFee?: number;
 };
 type ExchangeConnection = HttpTypes.ExchangeCredentialsResponse;
+/**
+ * A read-only tracker for an address the caller need not own, such as a vault's agent. Only
+ * Hyperliquid publishes account state by address, so it is the only connector here.
+ */
+type PublicTrackerConfig = {
+    connector: 'hyperliquid';
+    address: `0x${string}`;
+    onError?: (error: Error) => void;
+};
 
 interface WsMessage {
     [key: string]: unknown;
 }
 type MessageListener = (data: string) => void;
 type OpenListener = () => void;
+type CloseListener = () => void;
 declare abstract class BaseWs {
     protected ws: WebSocket | null;
     protected pingTimer: ReturnType<typeof setInterval> | null;
     private messageListeners;
     private openListeners;
+    private closeListeners;
     private nextListenerId;
     protected abstract getWsUrl(): string;
     protected abstract getPingIntervalMs(): number;
@@ -77,6 +88,8 @@ declare abstract class BaseWs {
     removeMessageListener(id: string): void;
     addOpenListener(listener: OpenListener): string;
     removeOpenListener(id: string): void;
+    addCloseListener(listener: CloseListener): string;
+    removeCloseListener(id: string): void;
     destroy(): void;
     private startPing;
     private stopPing;
@@ -240,11 +253,19 @@ type ExchangeWsByConnector = {
     lighter: LighterExchangeWs;
     lighter_rhc: LighterExchangeWs;
 };
-type CreateExchangeWsConfig = {
+/**
+ * Hyperliquid's account channels are public, so its socket needs no credentials; every other venue
+ * still requires them. The tuple keeps the check whole, so a connector not known to be Hyperliquid
+ * (a `Connector` union) still requires them too.
+ */
+type CreateExchangeWsConfig<E extends Connector = Connector> = {
     demo: boolean;
+} & ([E] extends ['hyperliquid'] ? {
+    credentials?: SupportedCredentials;
+} : {
     credentials: SupportedCredentials;
-};
-declare function createExchangeWs<E extends Connector>(exchange: E, config: CreateExchangeWsConfig): Promise<ExchangeWsByConnector[E]>;
+});
+declare function createExchangeWs<E extends Connector>(exchange: E, config: CreateExchangeWsConfig<E>): Promise<ExchangeWsByConnector[E]>;
 
 interface HyperliquidHelper {
     checkAccountActivation(userAddress: `0x${string}`): Promise<boolean>;
@@ -1780,9 +1801,12 @@ interface AccountSnapshot {
 type AssetSnapshotMap = Record<string, TrackedAssetInfo | null>;
 
 type ErrorHandler = (error: Error) => void;
+/**
+ * What every tracker takes. Credentials are not part of it: a tracker that reads private venue
+ * channels declares them in its own config, while Hyperliquid reads public account state by address.
+ */
 type AccountTrackerConfig = {
     demo: boolean;
-    credentials: SupportedCredentials;
     onError?: ErrorHandler;
 };
 interface AccountTracker {
@@ -1803,7 +1827,6 @@ interface AccountTracker {
 declare abstract class BaseAccountTracker implements AccountTracker {
     protected onError: ErrorHandler;
     protected demo: boolean;
-    protected credentials: SupportedCredentials;
     private balance;
     private balanceInitialized;
     private positions;
@@ -2251,31 +2274,19 @@ declare const HyperliquidPortfolioMarginBalance: z.ZodObject<{
 }, z.core.$strip>;
 type HyperliquidPortfolioMarginBalance = z.infer<typeof HyperliquidPortfolioMarginBalance>;
 
-/**
- * Hyperliquid's two read paths: the live WebSocket tracker and the one-shot REST snapshot.
- *
- * Both fill the same `HyperliquidBalanceContext` and hand it to the same mapper, which is what
- * makes "same account state, same balance" true across two different transports. The tracker takes
- * every CHANGING value off a channel — `allDexsClearinghouseState`, `spotState`, `webData3`,
- * `allMids`, `activeAssetData` — including vault equity, which rides `webData3`, save one:
- * Portfolio Margin's health factor and reserve rates ride no channel, so it polls them while the
- * account is in that mode. Its only other REST reads happen at `start()`: the static dex metadata,
- * and the staking position, which the venue publishes on no channel at all.
- *
- * The snapshot has no channels, so it reads the same figures over REST — vault equity from
- * `userVaultEquities`, which was measured equal to the `webData3` figure on ten live accounts.
- */
-
 type HyperliquidAccountTrackerConfig = AccountTrackerConfig & {
-    account: TradeAccount;
-    credentials: SupportedCredentials;
+    /** The account whose state is read. Hyperliquid answers for any address, so no credentials are needed. */
+    address: `0x${string}`;
 };
 declare class HyperliquidAccountTracker extends BaseAccountTracker {
     private readonly address;
     private ws;
     private messageListenerId;
     private openListenerId;
+    private closeListenerId;
     private lifecycleVersion;
+    /** Whether the socket is down and the outage already reported, so its retries report nothing more. */
+    private socketDropped;
     private subscribedCoins;
     private lastSummary;
     private spotCoinBalances;
@@ -2296,6 +2307,17 @@ declare class HyperliquidAccountTracker extends BaseAccountTracker {
     private hasWebData3;
     private vaultEquity;
     private stakedHype;
+    /** Whether a staking re-read is running, whether another was asked for meanwhile, and its retry. */
+    private stakingReadRunning;
+    private stakingReadRequested;
+    private stakingRetryTimer;
+    private stakingEventReadStarting;
+    private stakingEventReadTimer;
+    private stakingEventReadPending;
+    /** Whether the latest staking summary reported at least one withdrawal still queued. */
+    private hasQueuedWithdrawal;
+    /** Advances on every stop, so a staking read fired before it is recognised and dropped. */
+    private stakingReadGeneration;
     private dexToMeta;
     private trackedAssetData;
     constructor(config: HyperliquidAccountTrackerConfig);
@@ -2324,6 +2346,15 @@ declare class HyperliquidAccountTracker extends BaseAccountTracker {
     /** Subscribes to the spot state variant required by the active account mode. */
     private sendSpotStateSubscription;
     private resubscribeAll;
+    /**
+     * Drops the live account state when the socket goes down, and reports the outage once.
+     *
+     * Without this, the last frame's positions would read as live for the whole outage, or for good
+     * if the socket never returns. Nothing is broadcast, since an empty list would read as a flat
+     * account; `isInitialized` turns false and the reopen resubscribes. partysocket fires `close` for
+     * every failed reconnect attempt too, so only the first close of an outage reaches `onError`.
+     */
+    private onSocketClosed;
     private routeRaw;
     private handle;
     private loadPerpMetas;
@@ -2366,6 +2397,37 @@ declare class HyperliquidAccountTracker extends BaseAccountTracker {
      * one missed read says nothing about the account that the last good one did not.
      */
     private refreshBorrowLendState;
+    /**
+     * Re-reads the staking account, one read at a time: a request made while a read runs is served by
+     * a single read after it, however many arrive.
+     *
+     * That follow-up matters. A read already in flight may have left before the withdrawal it should
+     * catch completed, so its answer can still hold that HYPE.
+     */
+    private requestStakingRead;
+    /**
+     * Requests at most one staking read per interval from spot frames, preserving one trailing read
+     * when more frames ask during the interval.
+     */
+    private requestStakingReadFromSpotState;
+    /** Starts one spot-triggered read, then opens the interval selected by its pending count. */
+    private startStakingReadInterval;
+    /**
+     * Stops the staking re-reads; the cached figure stays, as it was true when last read.
+     *
+     * Every stop opens a new generation (a session ending, or a restart), so a read still in flight
+     * from before it can never land.
+     */
+    private stopStakingReads;
+    /**
+     * Reads the staking account once, then republishes the balance with it.
+     *
+     * A failed read is reported and retried after `STAKING_READ_RETRY_MS`, keeping the last figure in
+     * place until one succeeds.
+     */
+    private refreshStakingAccount;
+    /** Retries a failed staking read once `STAKING_READ_RETRY_MS` has passed, unless the session stopped. */
+    private scheduleStakingRetry;
     /** The floor of `availableToTrade` over the tracked set; `null` when nothing is tracked. */
     private availableMargin;
     /** Clears both sides of the live balance join and the public account cache without emitting. */
@@ -2458,6 +2520,7 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     private readonly accountIdentifier;
     private readonly apiKeyIndex;
     private readonly apiPrivateKey;
+    private readonly creds;
     private ws;
     private messageListenerId;
     private openListenerId;
@@ -2822,6 +2885,11 @@ declare class ExchangesSDK {
      */
     status(connection: ExchangeConnection, options?: ConnectOptions): Promise<AccountStatus>;
     createTracker(connection: ExchangeConnection): AccountTracker;
+    /**
+     * A read-only tracker for any address, built without `connect()`: Hyperliquid answers account
+     * state for an address with no credentials, so none are fetched and no trade account is needed.
+     */
+    createPublicTracker(config: PublicTrackerConfig): AccountTracker;
     snapshot(tradeAccountId: string): Promise<AccountSnapshot>;
     snapshotAssets(tradeAccountId: string, coins: string[]): Promise<AssetSnapshotMap>;
     createHelper<E extends ExchangeHelperExchange>(exchange: E): ExchangeHelperMap[E];
@@ -2830,4 +2898,4 @@ declare class ExchangesSDK {
     private fetchCredentials;
 }
 
-export { ACCOUNT_MODE_LABELS, ASSET_DECIMALS, AccountBalance, AccountBalanceCore, type AccountHealthStatus, AccountMode, type AccountPosition, type AccountSnapshot, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTierCallback, type AccountTracker, type AccountTrackerConfig, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, AssetId, type AssetSnapshotMap, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceExchangeWs, BinanceMultiAssetBalance, BinanceSingleAssetBalance, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitExchangeWs, BybitIsolatedMarginBalance, BybitPortfolioMarginBalance, BybitRegularMarginBalance, BybitWs, type BybitWsConfig, type CctpDepositAddressParams, type CctpDepositAddressResult, type CctpDepositHistorySettlement, type CctpDepositParams, type CctpDepositRegistrationSettlement, type CctpDepositResult, type CctpDepositSettlement, type ChangeAccountTierParams, type ChangeAccountTierResult, type CheckApiWalletParams, CollateralBalance, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, DecimalString, type EthereumDepositParams, type EthereumDepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, FUNXYZ_DEPOSIT_MINIMUMS_USD, FUNXYZ_ETHEREUM_MAINNET_CHAIN_ID, FUNXYZ_EVM_CHAIN_NAMES, type FastWithdrawParams, type FastWithdrawResult, type FillSyncOutcome, type FundingSyncOutcome, type FunxyzAccountState, type FunxyzAsset, type FunxyzDepositAddressParams, type FunxyzDepositAddressResult, type FunxyzDepositCredit, type FunxyzDepositParams, type FunxyzDepositResult, type FunxyzDepositSettlement, type FunxyzDepositSource, type FunxyzMarket, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidBorrowLendReserve, HyperliquidDexState, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LIGHTER_NATIVE_USDC_ADDRESSES, LIGHTER_QUOTE_ASSETS, LIGHTER_RHC_CHAIN_ID, LIGHTER_RHC_USDG_ADDRESS, LIGHTER_RHC_USDG_DECIMALS, LIGHTER_USDC_DECIMALS, LighterAccountSyncer, type LighterAccountSyncerConfig, type LighterAccountTier, LighterAccountTracker, type LighterAccountTrackerConfig, type LighterApplyReferralCodeParams, type LighterAuthCredentials, LighterClassicBalance, type LighterConnector, type LighterDeposit, type LighterDepositAddressParams, type LighterDepositAddressResult, type LighterDepositCredit, type LighterDepositHistoryParams, type LighterDepositNetwork, type LighterDepositPage, type LighterDepositParams, type LighterDepositProgress, type LighterDepositResult, type LighterDepositStatus, type LighterDepositWalletAdapter, LighterExchangeWs, type LighterHelper, type LighterLookupResult, type LighterOnboardingStatus, type LighterReferral, type LighterReferralTotals, type LighterReferralTradeStats, LighterRhcAssetId, type LighterRhcDepositAddressParams, type LighterRhcDepositAddressResult, type LighterRhcDepositParams, type LighterRhcDepositResult, type LighterRhcDepositWallet, type LighterRhcHelper, type LighterSharedHelper, LighterUnifiedBalance, type LighterUserReferrals, type LighterUserReferralsParams, type LighterWithdraw, type LighterWithdrawHistoryParams, type LighterWithdrawPage, type LighterWithdrawStatus, type LighterWithdrawType, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_LIGHTER_CCTP_DEPOSIT_USDC, MIN_LIGHTER_FAST_WITHDRAW_COLLATERAL, MIN_LIGHTER_RHC_DEPOSIT_USDG, MIN_USER_API_KEY_INDEX, MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxExchangeWs, OkxFuturesBalance, OkxMultiCurrencyMarginBalance, OkxPortfolioMarginBalance, OkxSpotBalance, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, Side, SignedDecimalString, type StateUpdate, type SupportedCredentials, type SyncerThrottle, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, createLighterRhcHelper, findAvailableApiKeyIndex, getAssetDecimals, getLighterNativeUsdcAddress, listFunxyzTransferableChains, readFunxyzChainSource, readFunxyzMinimumUsd, retrieveLighterAuthToken, usdcAbi };
+export { ACCOUNT_MODE_LABELS, ASSET_DECIMALS, AccountBalance, AccountBalanceCore, type AccountHealthStatus, AccountMode, type AccountPosition, type AccountSnapshot, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTierCallback, type AccountTracker, type AccountTrackerConfig, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, AssetId, type AssetSnapshotMap, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceExchangeWs, BinanceMultiAssetBalance, BinanceSingleAssetBalance, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitExchangeWs, BybitIsolatedMarginBalance, BybitPortfolioMarginBalance, BybitRegularMarginBalance, BybitWs, type BybitWsConfig, type CctpDepositAddressParams, type CctpDepositAddressResult, type CctpDepositHistorySettlement, type CctpDepositParams, type CctpDepositRegistrationSettlement, type CctpDepositResult, type CctpDepositSettlement, type ChangeAccountTierParams, type ChangeAccountTierResult, type CheckApiWalletParams, type CloseListener, CollateralBalance, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, DecimalString, type EthereumDepositParams, type EthereumDepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, FUNXYZ_DEPOSIT_MINIMUMS_USD, FUNXYZ_ETHEREUM_MAINNET_CHAIN_ID, FUNXYZ_EVM_CHAIN_NAMES, type FastWithdrawParams, type FastWithdrawResult, type FillSyncOutcome, type FundingSyncOutcome, type FunxyzAccountState, type FunxyzAsset, type FunxyzDepositAddressParams, type FunxyzDepositAddressResult, type FunxyzDepositCredit, type FunxyzDepositParams, type FunxyzDepositResult, type FunxyzDepositSettlement, type FunxyzDepositSource, type FunxyzMarket, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidBorrowLendReserve, HyperliquidDexState, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LIGHTER_NATIVE_USDC_ADDRESSES, LIGHTER_QUOTE_ASSETS, LIGHTER_RHC_CHAIN_ID, LIGHTER_RHC_USDG_ADDRESS, LIGHTER_RHC_USDG_DECIMALS, LIGHTER_USDC_DECIMALS, LighterAccountSyncer, type LighterAccountSyncerConfig, type LighterAccountTier, LighterAccountTracker, type LighterAccountTrackerConfig, type LighterApplyReferralCodeParams, type LighterAuthCredentials, LighterClassicBalance, type LighterConnector, type LighterDeposit, type LighterDepositAddressParams, type LighterDepositAddressResult, type LighterDepositCredit, type LighterDepositHistoryParams, type LighterDepositNetwork, type LighterDepositPage, type LighterDepositParams, type LighterDepositProgress, type LighterDepositResult, type LighterDepositStatus, type LighterDepositWalletAdapter, LighterExchangeWs, type LighterHelper, type LighterLookupResult, type LighterOnboardingStatus, type LighterReferral, type LighterReferralTotals, type LighterReferralTradeStats, LighterRhcAssetId, type LighterRhcDepositAddressParams, type LighterRhcDepositAddressResult, type LighterRhcDepositParams, type LighterRhcDepositResult, type LighterRhcDepositWallet, type LighterRhcHelper, type LighterSharedHelper, LighterUnifiedBalance, type LighterUserReferrals, type LighterUserReferralsParams, type LighterWithdraw, type LighterWithdrawHistoryParams, type LighterWithdrawPage, type LighterWithdrawStatus, type LighterWithdrawType, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_LIGHTER_CCTP_DEPOSIT_USDC, MIN_LIGHTER_FAST_WITHDRAW_COLLATERAL, MIN_LIGHTER_RHC_DEPOSIT_USDG, MIN_USER_API_KEY_INDEX, MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxExchangeWs, OkxFuturesBalance, OkxMultiCurrencyMarginBalance, OkxPortfolioMarginBalance, OkxSpotBalance, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, type PublicTrackerConfig, RouteType, Side, SignedDecimalString, type StateUpdate, type SupportedCredentials, type SyncerThrottle, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, createLighterRhcHelper, findAvailableApiKeyIndex, getAssetDecimals, getLighterNativeUsdcAddress, listFunxyzTransferableChains, readFunxyzChainSource, readFunxyzMinimumUsd, retrieveLighterAuthToken, usdcAbi };

package/dist/sdk.js

@@ -2,7 +2,7 @@ import { configureProxy } from '@pear-protocol/utils';
 import { createExchangeHelper } from './helper/factory';
 import { checkAccountStatus } from './status';
 import { createAccountSyncer } from './syncer';
-import { createAccountTracker } from './tracker';
+import { HyperliquidAccountTracker, createAccountTracker } from './tracker';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -42,6 +42,20 @@ class ExchangesSDK {
   createTracker(connection) {
     return this.buildTracker(connection);
   }
+  /**
+  * A read-only tracker for any address, built without `connect()`: Hyperliquid answers account
+  * state for an address with no credentials, so none are fetched and no trade account is needed.
+  */
+  createPublicTracker(config) {
+    switch (config.connector) {
+      case "hyperliquid":
+        return new HyperliquidAccountTracker({
+          demo: this.demo,
+          onError: config.onError,
+          address: config.address
+        });
+    }
+  }
   async snapshot(tradeAccountId) {
     const connection = await this.fetchCredentials(tradeAccountId);
     return this.buildTracker(connection).snapshot();

package/dist/syncer/base.js

@@ -23,14 +23,14 @@ class BaseAccountSyncer {
   }
   // Phase A: Load current Pear state (positions, fills, instruments, watermark).
   async loadPearState() {
-    const [{ positions: openPositions }, { fills: provisionalFills }, { instruments }, watermark] = await Promise.all([
+    const watermark = await this.sdk.core.sync.fills.since({
+      overlapMs: OVERLAP_MS
+    });
+    const [{ positions: openPositions }, { fills: provisionalFills }, { instruments }] = await Promise.all([
       this.sdk.core.positions.openLite(),
       this.sdk.core.fills.provisionals(),
       this.sdk.core.instruments.lite({
         connector: this.connector
-      }),
-      this.sdk.core.sync.fills.since({
-        overlapMs: OVERLAP_MS
       })
     ]);
     const entryBySymbol = await this.loadEntryBySymbol(openPositions);
@@ -128,7 +128,9 @@ class BaseAccountSyncer {
       },
       ...firstSyncStartedAt === void 0 ? {} : {
         firstSyncStartedAt
-      }
+      },
+      // Core defers the create when any execution write postdates this server-minted token.
+      executionsUpdatedAtEpochMs: watermark.executionsUpdatedAtEpochMs
     };
     if (firstSyncTrim) {
       console.log(`${this.connector}: first-sync trim \u2014 dropped ${firstSyncTrim.trimmedCount} pre-cutoff fills (cutoffTs=${firstSyncTrim.cutoffTs})`);

package/dist/tracker/base.js

@@ -6,7 +6,6 @@ class BaseAccountTracker {
   }
   onError;
   demo;
-  credentials;
   balance = null;
   balanceInitialized = false;
   positions = /* @__PURE__ */ new Map();
@@ -16,7 +15,6 @@ class BaseAccountTracker {
   assetEntries = /* @__PURE__ */ new Map();
   constructor(config) {
     this.demo = config.demo;
-    this.credentials = config.credentials;
     this.onError = (error) => {
       console.warn("[AccountTracker] error:", error.message);
       config.onError?.(error);

package/dist/tracker/binance/tracker.js

@@ -61,7 +61,7 @@ class BinanceAccountTracker extends BaseAccountTracker {
     this.handlePositionRisk(positionRisk, false);
     const ws = await createExchangeWs("binance", {
       demo: this.demo,
-      credentials: this.credentials
+      credentials: this.creds
     });
     this.userDataWs = ws.userData;
     this.wsApiWs = ws.wsApi;

package/dist/tracker/bybit/tracker.js

@@ -82,7 +82,7 @@ class BybitAccountTracker extends BaseAccountTracker {
     this.handleInitialData(wallet ?? null, positions, toBybitAccountMode(accountInfo.marginMode));
     this.ws = await createExchangeWs("bybit", {
       demo: this.demo,
-      credentials: this.credentials
+      credentials: this.creds
     });
     this.messageListenerId = this.ws.main.addMessageListener((raw) => this.routeRaw(raw));
     this.openListenerId = this.ws.main.addOpenListener(() => {

package/dist/tracker/hyperliquid/tracker.js

@@ -17,6 +17,9 @@ const EMPTY_SPOT_META = {
   universe: []
 };
 const BORROW_LEND_POLL_INTERVAL_MS = 3e4;
+const STAKING_READ_RETRY_MS = 3e4;
+const STAKING_QUEUED_READ_INTERVAL_MS = 6e4;
+const STAKING_SPECULATIVE_READ_INTERVAL_MS = 3e5;
 class HyperliquidAccountTracker extends BaseAccountTracker {
   static {
     __name(this, "HyperliquidAccountTracker");
@@ -25,7 +28,10 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
   ws = null;
   messageListenerId = null;
   openListenerId = null;
+  closeListenerId = null;
   lifecycleVersion = 0;
+  /** Whether the socket is down and the outage already reported, so its retries report nothing more. */
+  socketDropped = false;
   subscribedCoins = /* @__PURE__ */ new Set();
   lastSummary = emptyClearinghouseSummary();
   spotCoinBalances = /* @__PURE__ */ new Map();
@@ -46,11 +52,22 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
   hasWebData3 = false;
   vaultEquity = "0";
   stakedHype = "0";
+  /** Whether a staking re-read is running, whether another was asked for meanwhile, and its retry. */
+  stakingReadRunning = false;
+  stakingReadRequested = false;
+  stakingRetryTimer = null;
+  stakingEventReadStarting = false;
+  stakingEventReadTimer = null;
+  stakingEventReadPending = false;
+  /** Whether the latest staking summary reported at least one withdrawal still queued. */
+  hasQueuedWithdrawal = false;
+  /** Advances on every stop, so a staking read fired before it is recognised and dropped. */
+  stakingReadGeneration = 0;
   dexToMeta = /* @__PURE__ */ new Map();
   trackedAssetData = /* @__PURE__ */ new Map();
   constructor(config) {
     super(config);
-    this.address = config.account.exchangeIdentifier;
+    this.address = config.address;
   }
   /**
   * Reads account mode, spot prices, collateral balances, per-DEX state, staking, vaults and
@@ -89,7 +106,7 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
       spotBalances: mapSpotBalances(spotState),
       prices: SpotPrices.from(spotMeta, mids),
       vaultEquity: sumRestVaultEquity(vaults),
-      stakedHype: stakingAccountHype(delegator),
+      stakedHype: _stakingAccountHype(delegator),
       availableMargin: minimumAvailableToTrade(assetData.values()),
       collateralTokenNames: buildCollateralTokenNames(spotMeta),
       availableMarginByToken: buildAvailableMarginByToken(summary.perDexState, assetData.values()),
@@ -127,9 +144,11 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
     const user = this.addrLower();
     this.destroyCurrentSocket();
     this.stopBorrowLendPoll();
+    this.stopStakingReads();
     this.subscribedCoins.clear();
     this.resetLiveAccountState();
     this.dexToMeta.clear();
+    this.socketDropped = false;
     const [allMetas, perpDexs, spotMeta, abstraction, delegator] = await Promise.all([
       fetchInfo({
         type: "allPerpMetas"
@@ -146,10 +165,10 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
     this.spotMeta = spotMeta;
     this.collateralTokenNames = buildCollateralTokenNames(spotMeta);
     this.accountType = resolveHyperliquidAccountType(abstraction);
-    this.stakedHype = stakingAccountHype(delegator);
+    this.stakedHype = _stakingAccountHype(delegator);
+    this.hasQueuedWithdrawal = delegator.nPendingWithdrawals > 0;
     const ws = (await createExchangeWs("hyperliquid", {
-      demo: this.demo,
-      credentials: this.credentials
+      demo: this.demo
     })).main;
     if (lifecycleVersion !== this.lifecycleVersion) {
       ws.destroy();
@@ -158,6 +177,7 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
     this.ws = ws;
     this.messageListenerId = this.ws.addMessageListener((raw) => this.routeRaw(raw));
     this.openListenerId = this.ws.addOpenListener(() => this.resubscribeAll());
+    this.closeListenerId = this.ws.addCloseListener(() => this.onSocketClosed());
     this.sendStaticSubs();
     this.syncBorrowLendPoll();
     const coinsToTrack = /* @__PURE__ */ new Set([
@@ -172,6 +192,7 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
     this.lifecycleVersion += 1;
     this.destroyCurrentSocket();
     this.stopBorrowLendPoll();
+    this.stopStakingReads();
     this.subscribedCoins.clear();
   }
   /** Detaches and destroys the active socket without changing the current lifecycle generation. */
@@ -184,6 +205,10 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
       this.ws?.removeOpenListener(this.openListenerId);
       this.openListenerId = null;
     }
+    if (this.closeListenerId) {
+      this.ws?.removeCloseListener(this.closeListenerId);
+      this.closeListenerId = null;
+    }
     this.ws?.destroy();
     this.ws = null;
   }
@@ -267,6 +292,7 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
   }
   resubscribeAll() {
     this.resetLiveAccountState();
+    this.socketDropped = false;
     this.sendStaticSubs();
     const user = this.addrLower();
     for (const coin of this.subscribedCoins) {
@@ -280,6 +306,22 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
       });
     }
   }
+  /**
+  * Drops the live account state when the socket goes down, and reports the outage once.
+  *
+  * Without this, the last frame's positions would read as live for the whole outage, or for good
+  * if the socket never returns. Nothing is broadcast, since an empty list would read as a flat
+  * account; `isInitialized` turns false and the reopen resubscribes. partysocket fires `close` for
+  * every failed reconnect attempt too, so only the first close of an outage reaches `onError`.
+  */
+  onSocketClosed() {
+    if (this.socketDropped) {
+      return;
+    }
+    this.socketDropped = true;
+    this.resetLiveAccountState();
+    this.onError(new Error("Hyperliquid WebSocket closed; account state is unavailable until it reconnects"));
+  }
   routeRaw(raw) {
     try {
       const msg = JSON.parse(raw);
@@ -315,6 +357,9 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
             data: msg.data
           });
           break;
+        case "error":
+          this.onError(new Error(`Hyperliquid WebSocket error: ${String(msg.data)}`));
+          break;
       }
     } catch (err) {
       this.onError(err instanceof Error ? err : new Error(String(err)));
@@ -454,10 +499,15 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
   onSpotState(data) {
     const balances = data?.spotState?.balances;
     if (!balances) return;
+    const hadSpotState = this.hasSpotState;
+    const previousHype = this.spotCoinBalances.get("HYPE")?.total;
     this.spotCoinBalances = mapSpotBalances(data.spotState);
     this.portfolioMarginRatio = data.spotState.portfolioMarginRatio ?? null;
     this.borrowRatioByToken = mapBorrowRatios(data.spotState);
     this.hasSpotState = true;
+    if (!toDecimal(this.stakedHype).isZero() && (!hadSpotState || spotHypeRose(previousHype, this.spotCoinBalances))) {
+      this.requestStakingReadFromSpotState();
+    }
     const balance = this.buildBalance();
     if (balance !== void 0) {
       this.onStateUpdate({
@@ -551,6 +601,115 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
       });
     }
   }
+  /**
+  * Re-reads the staking account, one read at a time: a request made while a read runs is served by
+  * a single read after it, however many arrive.
+  *
+  * That follow-up matters. A read already in flight may have left before the withdrawal it should
+  * catch completed, so its answer can still hold that HYPE.
+  */
+  async requestStakingRead() {
+    this.stakingReadRequested = true;
+    if (this.stakingReadRunning) {
+      return;
+    }
+    const generation = this.stakingReadGeneration;
+    this.stakingReadRunning = true;
+    while (this.stakingReadRequested && generation === this.stakingReadGeneration) {
+      this.stakingReadRequested = false;
+      await this.refreshStakingAccount(generation);
+    }
+    if (generation === this.stakingReadGeneration) {
+      this.stakingReadRunning = false;
+    }
+  }
+  /**
+  * Requests at most one staking read per interval from spot frames, preserving one trailing read
+  * when more frames ask during the interval.
+  */
+  requestStakingReadFromSpotState() {
+    if (this.stakingEventReadStarting || this.stakingEventReadTimer !== null) {
+      this.stakingEventReadPending = true;
+      return;
+    }
+    this.stakingEventReadStarting = true;
+    void this.startStakingReadInterval(this.stakingReadGeneration);
+  }
+  /** Starts one spot-triggered read, then opens the interval selected by its pending count. */
+  async startStakingReadInterval(generation) {
+    await this.requestStakingRead();
+    if (generation !== this.stakingReadGeneration) {
+      return;
+    }
+    this.stakingEventReadStarting = false;
+    const interval = this.hasQueuedWithdrawal ? STAKING_QUEUED_READ_INTERVAL_MS : STAKING_SPECULATIVE_READ_INTERVAL_MS;
+    this.stakingEventReadTimer = setTimeout(() => {
+      this.stakingEventReadTimer = null;
+      if (!this.stakingEventReadPending) {
+        return;
+      }
+      this.stakingEventReadPending = false;
+      this.requestStakingReadFromSpotState();
+    }, interval);
+  }
+  /**
+  * Stops the staking re-reads; the cached figure stays, as it was true when last read.
+  *
+  * Every stop opens a new generation (a session ending, or a restart), so a read still in flight
+  * from before it can never land.
+  */
+  stopStakingReads() {
+    if (this.stakingRetryTimer !== null) {
+      clearTimeout(this.stakingRetryTimer);
+      this.stakingRetryTimer = null;
+    }
+    if (this.stakingEventReadTimer !== null) {
+      clearTimeout(this.stakingEventReadTimer);
+      this.stakingEventReadTimer = null;
+    }
+    this.stakingEventReadStarting = false;
+    this.stakingEventReadPending = false;
+    this.stakingReadGeneration += 1;
+    this.stakingReadRunning = false;
+    this.stakingReadRequested = false;
+  }
+  /**
+  * Reads the staking account once, then republishes the balance with it.
+  *
+  * A failed read is reported and retried after `STAKING_READ_RETRY_MS`, keeping the last figure in
+  * place until one succeeds.
+  */
+  async refreshStakingAccount(generation) {
+    let delegator;
+    try {
+      delegator = await fetchDelegatorSummary(this.addrLower(), this.demo);
+    } catch (err) {
+      this.onError(err instanceof Error ? err : new Error(String(err)));
+      this.scheduleStakingRetry(generation);
+      return;
+    }
+    if (generation !== this.stakingReadGeneration) {
+      return;
+    }
+    this.stakedHype = _stakingAccountHype(delegator);
+    this.hasQueuedWithdrawal = delegator.nPendingWithdrawals > 0;
+    const balance = this.buildBalance();
+    if (balance !== void 0) {
+      this.onStateUpdate({
+        balance
+      });
+    }
+  }
+  /** Retries a failed staking read once `STAKING_READ_RETRY_MS` has passed, unless the session stopped. */
+  scheduleStakingRetry(generation) {
+    if (generation !== this.stakingReadGeneration || this.stakingRetryTimer !== null) {
+      return;
+    }
+    this.stakingRetryTimer = setTimeout(() => {
+      this.stakingRetryTimer = null;
+      void this.requestStakingRead();
+    }, STAKING_READ_RETRY_MS);
+  }
   /** The floor of `availableToTrade` over the tracked set; `null` when nothing is tracked. */
   availableMargin() {
     return minimumAvailableToTrade(this.trackedAssetData.values());
@@ -575,6 +734,10 @@ class HyperliquidAccountTracker extends BaseAccountTracker {
     return result;
   }
 }
+function _stakingAccountHype(delegator) {
+  return toDecimal(delegator.delegated).plus(toDecimal(delegator.undelegated)).plus(toDecimal(delegator.totalPendingWithdrawal)).toFixed();
+}
+__name(_stakingAccountHype, "_stakingAccountHype");
 function buildTrackedAssetInfo(data) {
   return {
     coin: data.coin,
@@ -625,10 +788,10 @@ function mapBorrowRatios(spotState) {
   return new Map(spotState.tokenToPortfolioBorrowRatio ?? []);
 }
 __name(mapBorrowRatios, "mapBorrowRatios");
-function stakingAccountHype(delegator) {
-  return toDecimal(delegator.delegated).plus(toDecimal(delegator.undelegated)).toFixed();
+function spotHypeRose(previousHype, balances) {
+  return toDecimal(balances.get("HYPE")?.total ?? "0").gt(toDecimal(previousHype ?? "0"));
 }
-__name(stakingAccountHype, "stakingAccountHype");
+__name(spotHypeRose, "spotHypeRose");
 function sumRestVaultEquity(vaults) {
   return vaults.reduce((total, vault) => total.plus(toDecimal(vault.equity)), ZERO).toFixed();
 }
@@ -638,4 +801,4 @@ function sumLiveVaultEquity(perpDexStates) {
 }
 __name(sumLiveVaultEquity, "sumLiveVaultEquity");
 
-export { HyperliquidAccountTracker };
+export { HyperliquidAccountTracker, _stakingAccountHype };

package/dist/tracker/index.js

@@ -45,8 +45,7 @@ function createAccountTracker(exchange, config) {
       return new HyperliquidAccountTracker({
         demo: config.demo,
         onError: config.onError,
-        account: config.account,
-        credentials: config.credentials
+        address: config.account.exchangeIdentifier
       });
     case "lighter":
     case "lighter_rhc":

package/dist/tracker/lighter/tracker.js

@@ -38,6 +38,7 @@ class LighterAccountTracker extends BaseAccountTracker {
   accountIdentifier;
   apiKeyIndex;
   apiPrivateKey;
+  creds;
   ws = null;
   messageListenerId = null;
   openListenerId = null;
@@ -75,6 +76,7 @@ class LighterAccountTracker extends BaseAccountTracker {
     this.accountIdentifier = config.account.exchangeIdentifier;
     this.apiKeyIndex = credentials.api_key_index;
     this.apiPrivateKey = credentials.api_private_key;
+    this.creds = credentials;
   }
   /**
   * The tier Lighter has the account on, and every later change to it.
@@ -177,7 +179,7 @@ class LighterAccountTracker extends BaseAccountTracker {
     });
     const ws = (await createExchangeWs(this.connector, {
       demo: this.demo,
-      credentials: this.credentials
+      credentials: this.creds
     })).main;
     if (lifecycleVersion !== this.lifecycleVersion) {
       ws.destroy();
@@ -502,12 +504,11 @@ class LighterAccountTracker extends BaseAccountTracker {
       return;
     }
     try {
-      const credentials = this.credentials;
       const accountIndex = Number(this.accountIdentifier);
       const authToken = await retrieveLighterAuthToken(this.sdk, this.connector, {
         accountIndex,
-        apiKeyIndex: credentials.api_key_index,
-        apiPrivateKey: credentials.api_private_key
+        apiKeyIndex: this.creds.api_key_index,
+        apiPrivateKey: this.creds.api_private_key
       }, this.demo);
       const limits = await fetchAccountLimits(accountIndex, authToken, this.connector, this.demo);
       const accountTier = toLighterAccountTier(limits.user_tier);

package/dist/tracker/okx/tracker.js

@@ -65,7 +65,7 @@ class OkxAccountTracker extends BaseAccountTracker {
     this.handleInitialData(balance, positions);
     this.ws = await createExchangeWs("okx", {
       demo: this.demo,
-      credentials: this.credentials
+      credentials: this.creds
     });
     this.messageListenerId = this.ws.main.addMessageListener((raw) => this.routeRaw(raw));
     this.openListenerId = this.ws.main.addOpenListener(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -27,9 +27,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@pear-protocol/core-sdk": "^2.2.0",
-    "@pear-protocol/types": "^2.2.0",
-    "@pear-protocol/utils": "^1.1.0",
+    "@pear-protocol/core-sdk": "^2.3.0",
+    "@pear-protocol/types": "^2.10.0",
+    "@pear-protocol/utils": "^1.2.0",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8",