@pear-protocol/exchanges-sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -10,18 +10,22 @@ type ExchangesSDKConfig = {
     options?: ConnectOptions;
 };
 type AccountHealthStatus = 'active' | 'warning';
-type AccountWarningReason = 'lighter_api_key_invalid' | 'lighter_integrator_not_approved' | 'hyperliquid_api_wallet_invalid' | 'hyperliquid_builder_fee_not_approved' | 'api_key_invalid';
+type AccountWarningReason = 'lighter_api_key_invalid' | 'lighter_integrator_not_approved' | 'hyperliquid_api_wallet_invalid' | 'hyperliquid_builder_fee_not_approved' | 'hyperliquid_account_mode_check_failed' | 'hyperliquid_account_mode_unsupported' | 'api_key_invalid';
 type AccountStatus = {
     status: AccountHealthStatus;
     reasons: AccountWarningReason[];
 };
 type ConnectOptions = {
     builderAddress?: `0x${string}`;
+    /** Minimum approved Hyperliquid builder fee, in tenths of a basis point. */
+    builderFeeTenthsBps?: number;
     integratorAccountIndex?: number;
+    /** Minimum approved Lighter perps maker fee, in exchange fee ticks (parts per million). */
+    integratorMinPerpsMakerFee?: number;
+    /** Minimum approved Lighter perps taker fee, in exchange fee ticks (parts per million). */
+    integratorMinPerpsTakerFee?: number;
 };
-type ExchangeConnection = HttpTypes.ExchangeCredentialsResponse & {
-    ws: ExchangeWsByConnector[Connector];
-};
+type ExchangeConnection = HttpTypes.ExchangeCredentialsResponse;
 
 interface WsMessage {
     [key: string]: unknown;
@@ -120,9 +124,17 @@ declare class BybitExchangeWs extends ExchangeWs {
 }
 
 declare class HyperliquidWs extends BaseWs {
+    private readonly demo;
+    /** Creates a Hyperliquid socket for the selected network. */
+    constructor(demo?: boolean);
+    /** Selects the mainnet or testnet websocket origin. */
     protected getWsUrl(): string;
+    /** Sends heartbeats before Hyperliquid's 60-second idle timeout. */
     protected getPingIntervalMs(): number;
-    protected buildPingMessage(): null;
+    /** Builds Hyperliquid's documented application-level heartbeat. */
+    protected buildPingMessage(): {
+        method: 'ping';
+    };
 }
 
 declare class HyperliquidExchangeWs extends ExchangeWs {
@@ -130,10 +142,15 @@ declare class HyperliquidExchangeWs extends ExchangeWs {
     readonly exchange: "hyperliquid";
     constructor(main: HyperliquidWs);
     protected connections(): BaseWs[];
-    static create(): Promise<HyperliquidExchangeWs>;
+    /** Opens the Hyperliquid socket on the requested network. */
+    static create(config?: {
+        demo: boolean;
+    }): Promise<HyperliquidExchangeWs>;
 }
 
 declare class LighterWs extends BaseWs {
+    private readonly demo;
+    constructor(demo?: boolean);
     protected getWsUrl(): string;
     protected getPingIntervalMs(): number;
     protected buildPingMessage(): WsMessage;
@@ -144,7 +161,9 @@ declare class LighterExchangeWs extends ExchangeWs {
     readonly exchange: "lighter";
     constructor(main: LighterWs);
     protected connections(): BaseWs[];
-    static create(): Promise<LighterExchangeWs>;
+    static create(config?: {
+        demo: boolean;
+    }): Promise<LighterExchangeWs>;
 }
 
 type OkxWsConfig = {
@@ -187,16 +206,15 @@ declare function createExchangeWs<E extends Connector>(exchange: E, config: Crea
 
 interface HyperliquidHelper {
     checkApiWallet(params: CheckApiWalletParams): Promise<boolean>;
-    checkBuilderFeeApproval(userAddress: `0x${string}`, builderAddress: `0x${string}`): Promise<boolean>;
+    checkBuilderFeeApproval(userAddress: `0x${string}`, builderAddress: `0x${string}`, requiredFeeTenthsBps?: number): Promise<boolean>;
 }
 type CheckApiWalletParams = {
     userAddress: `0x${string}`;
     agentWalletAddress: `0x${string}`;
 };
 
-declare function createHyperliquidHelper(): HyperliquidHelper;
-
-type WalletClientWithAccount = WalletClient<Transport, Chain | undefined, Account>;
+/** Creates Hyperliquid approval checks for the selected network. */
+declare function createHyperliquidHelper(demo?: boolean): HyperliquidHelper;
 
 type LighterRawTrade = {
     trade_id: number;
@@ -216,6 +234,8 @@ type LighterRawTrade = {
     taker_position_size_before?: string;
     maker_fee?: number;
     maker_position_size_before?: string;
+    taker_position_sign_changed?: boolean;
+    maker_position_sign_changed?: boolean;
     integrator_taker_fee?: number;
     integrator_maker_fee?: number;
 };
@@ -228,6 +248,8 @@ type ApiKey = {
     transaction_time: number;
 };
 
+type WalletClientWithAccount = WalletClient<Transport, Chain | undefined, Account>;
+
 declare const AssetId: {
     readonly ETH: 1;
     readonly LIT: 2;
@@ -237,6 +259,7 @@ declare const AssetId: {
     readonly AAVE: 7;
     readonly SKY: 8;
     readonly LDO: 9;
+    readonly AZTEC: 10;
 };
 type AssetId = (typeof AssetId)[keyof typeof AssetId];
 declare const RouteType: {
@@ -244,7 +267,17 @@ declare const RouteType: {
     readonly SPOT: 1;
 };
 type RouteType = (typeof RouteType)[keyof typeof RouteType];
+/** Lighter L2/base-amount precision (`assetDetails.decimals`). */
+declare const L2_ASSET_DECIMALS: Record<number, number>;
+/**
+ * @deprecated Prefer the authoritative `assetDetails.decimals` value returned by Lighter.
+ * Kept as the L2 map for backwards compatibility.
+ */
 declare const ASSET_DECIMALS: Record<number, number>;
+/**
+ * @deprecated Prefer the authoritative `assetDetails.decimals` value returned by Lighter.
+ * Kept for backwards compatibility with callers that only handle known assets.
+ */
 declare function getAssetDecimals(assetId: number): number;
 type ConnectWalletParams = {
     accountIndex: number;
@@ -255,12 +288,16 @@ type DepositParams = {
     routeType: number;
     amount: string;
     nativeValue?: string;
+    /** Optional cached `assetDetails.l1_decimals`; the helper fetches assetDetails when omitted. */
+    l1Decimals?: number;
 };
 type WithdrawParams = {
     accountIndex: number;
     assetId: number;
     routeType: number;
     amount: string;
+    /** Optional cached `assetDetails.decimals`; the helper fetches assetDetails when omitted. */
+    l2Decimals?: number;
 };
 type ConnectWalletResult = {
     txHash: string;
@@ -275,6 +312,12 @@ type ApproveIntegratorParams = {
 type ApproveIntegratorResult = {
     txHash: string;
 };
+type IntegratorApprovalRequirements = {
+    /** Minimum perps maker-fee cap, in Lighter's integer fee-tick units. */
+    minPerpsMakerFee: number;
+    /** Minimum perps taker-fee cap, in Lighter's integer fee-tick units. */
+    minPerpsTakerFee: number;
+};
 type DepositResult = {
     txHash: string;
 };
@@ -283,7 +326,7 @@ type WithdrawResult = {
 };
 interface LighterHelper {
     lookupAccount(l1Address: string): Promise<LighterLookupResult>;
-    checkIntegratorApproval(accountIndex: number, integratorAccountIndex: number): Promise<boolean>;
+    checkIntegratorApproval(accountIndex: number, integratorAccountIndex: number, requirements?: IntegratorApprovalRequirements): Promise<boolean>;
     connectWallet(walletClient: WalletClientWithAccount, params: ConnectWalletParams): Promise<ConnectWalletResult>;
     approveIntegrator(walletClient: WalletClientWithAccount, params: ApproveIntegratorParams): Promise<ApproveIntegratorResult>;
     deposit(walletClient: WalletClientWithAccount, params: DepositParams): Promise<DepositResult>;
@@ -294,7 +337,10 @@ type LighterLookupResult = {
     subAccountIndexes: number[];
 };
 
-declare function createLighterHelper(sdk: PearSDK): LighterHelper;
+declare const MIN_USER_API_KEY_INDEX = 4;
+declare const MAX_API_KEY_INDEX = 254;
+declare function findAvailableApiKeyIndex(apiKeys: ReadonlyArray<Pick<ApiKey, 'api_key_index'>>): number;
+declare function createLighterHelper(sdk: PearSDK, demo?: boolean): LighterHelper;
 
 type ExchangeHelperMap = {
     hyperliquid: HyperliquidHelper;
@@ -307,11 +353,11 @@ interface AccountSyncerConfig {
     connector: Connector;
     account: TradeAccount;
     credentials: SupportedCredentials;
-    ws: ExchangeWsByConnector[Connector];
     demo: boolean;
 }
 interface AccountSyncer {
-    synchronize(): Promise<void>;
+    synchronizeFills(): Promise<void>;
+    synchronizeFunding(): Promise<void>;
 }
 interface ListExternalFillsParams {
     since: Date;
@@ -319,17 +365,50 @@ interface ListExternalFillsParams {
     openPositions: HttpTypes.OpenPositionLite[];
     provisionalFills: HttpTypes.ProvisionalFill[];
 }
+interface ListExternalPositionsParams {
+    instruments: HttpTypes.Instrument[];
+}
+interface ListExternalFundingParams {
+    since: Date;
+    instruments: HttpTypes.Instrument[];
+}
 declare abstract class BaseAccountSyncer<ExternalFill> implements AccountSyncer {
     protected sdk: PearSDK;
     protected connector: Connector;
     protected account: TradeAccount;
     protected credentials: SupportedCredentials;
-    protected ws: ExchangeWsByConnector[Connector];
     protected demo: boolean;
     constructor(config: AccountSyncerConfig);
+    /**
+     * Fetch the account's currently-open positions from the exchange, normalized
+     * to BASE units (contractSize applied). The exchange position API is the
+     * source of truth for current exposure. Account-wide; no symbol scoping.
+     * Hedge-mode (LONG/SHORT legs on one symbol) is rejected — skipped this cycle.
+     */
+    protected abstract listExternalPositions(params: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected abstract listExternalFills(params: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
+    /**
+     * Fetch the account's historical funding payments since the watermark,
+     * applied-rate-only and mapped to instrument ids. Account-wide, no symbol scoping.
+     */
+    protected abstract listExternalFunding(params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
     protected abstract isReduceOnly(fill: ExternalFill): boolean;
-    synchronize(): Promise<void>;
+    private loadPearState;
+    /**
+     * Global per-symbol cost-basis entry of existing open positions, derived by pulling each
+     * position's fills and folding them (mirrors example-ui). One call per open position today —
+     * can collapse to a single endpoint later.
+     */
+    private loadEntryBySymbol;
+    private snapshotExchange;
+    private computeAndPostSync;
+    /**
+     * Pull historical funding payments since the funding watermark and post them.
+     * Independent of the fill sync cycle (`synchronizeFills`) — funding rows are
+     * immutable and upsert idempotently, so this is driven on its own cadence.
+     */
+    synchronizeFunding(): Promise<void>;
+    synchronizeFills(): Promise<void>;
 }
 
 interface BinanceRawUserTrade {
@@ -352,8 +431,10 @@ interface BinanceRawUserTrade {
 declare class BinanceAccountSyncer extends BaseAccountSyncer<BinanceRawUserTrade> {
     private readonly creds;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, openPositions, provisionalFills, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(trade: BinanceRawUserTrade): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: BinanceRawUserTrade): boolean;
     private collectRequestedInstrumentIds;
     private mapOrdersBySymbolOrderId;
     private orderKey;
@@ -376,8 +457,10 @@ interface BybitRawExecution {
 declare class BybitAccountSyncer extends BaseAccountSyncer<BybitRawExecution> {
     private readonly creds;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(execution: BybitRawExecution): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: BybitRawExecution): boolean;
 }
 
 declare function createAccountSyncer(exchange: Connector, config: AccountSyncerConfig): AccountSyncer;
@@ -458,26 +541,34 @@ type UserFillsByTimeResponse = {
     };
 };
 
-declare class HyperliquidAccountSyncer extends BaseAccountSyncer<UserFillsByTimeResponse> {
+type HyperliquidRawFill = UserFillsByTimeResponse;
+declare class HyperliquidAccountSyncer extends BaseAccountSyncer<HyperliquidRawFill> {
     private readonly address;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(fill: UserFillsByTimeResponse): boolean;
+    protected listExternalFunding({ since, instruments, }: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: HyperliquidRawFill): boolean;
 }
 
-declare class LighterAccountSyncer extends BaseAccountSyncer<LighterRawTrade> {
+type RawFill$1 = LighterRawTrade;
+declare class LighterAccountSyncer extends BaseAccountSyncer<RawFill$1> {
     private readonly accountIndex;
     private readonly apiKeyIndex;
     private readonly apiPrivateKey;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(trade: LighterRawTrade): boolean;
+    protected listExternalFunding({ since, instruments, }: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: RawFill$1): boolean;
     private getAccountSide;
     private getClientOrderId;
     private isMaker;
     private getPositionSizeBefore;
     private getTradeFee;
     private getIntegratorFee;
+    /** Prevents testnet reads from silently minting a mainnet auth token. */
+    private assertAuthenticatedSyncAvailable;
     private feeTickToAmount;
 }
 
@@ -499,11 +590,14 @@ interface OkxRawFill {
     ts: string;
 }
 
-declare class OkxAccountSyncer extends BaseAccountSyncer<OkxRawFill> {
+type RawFill = OkxRawFill;
+declare class OkxAccountSyncer extends BaseAccountSyncer<RawFill> {
     private readonly creds;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(fill: OkxRawFill): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: RawFill): boolean;
     private contractsToBase;
 }
 
@@ -527,7 +621,10 @@ declare enum HyperliquidAccountType {
 }
 
 declare enum LighterAccountType {
-    BASIC = "basic"
+    /** @deprecated Use `CLASSIC`; retained as a source-compatible alias. */
+    BASIC = "classic",
+    CLASSIC = "classic",
+    UNIFIED = "unified"
 }
 
 declare enum OkxAccountType {
@@ -550,6 +647,7 @@ interface AssetBalance {
 }
 interface AccountBalance {
     accountType: AccountType;
+    accountTier?: string;
     free: Record<string, string>;
     used: Record<string, string>;
     total: Record<string, string>;
@@ -584,23 +682,41 @@ interface ExchangeState {
     lastUpdated: number;
     initialized: boolean;
 }
-type BalanceCallback = (balance: AccountBalance) => void;
+type BalanceCallback = (balance: AccountBalance | null) => void;
 type PositionsCallback = (positions: AccountPosition[]) => void;
 type TrackedAssetCallback = (info: TrackedAssetInfo) => void;
 interface StateUpdate {
-    balance?: AccountBalance;
+    /** `null` explicitly clears a balance that can no longer be represented safely. */
+    balance?: AccountBalance | null;
     positions?: Map<string, AccountPosition>;
+    /** Full snapshots replace cached positions; incremental exchange events merge by position key. */
+    positionsMode?: 'merge' | 'replace';
     trackedAssets?: Map<string, TrackedAssetInfo>;
 }
+/** A stateless, one-shot read of an account's balance + positions over REST — no WebSocket. */
+interface AccountSnapshot {
+    balance: AccountBalance | null;
+    positions: AccountPosition[];
+}
+/**
+ * A stateless, one-shot read of per-asset account settings (current leverage + margin mode) over
+ * REST — no WebSocket. Keyed by the requested asset id, which follows the same per-exchange
+ * identifier `trackAsset` uses (hyperliquid coin, binance/bybit symbol, okx instId, lighter
+ * market id). A requested asset the exchange returns no setting for maps to an explicit `null`.
+ */
+type AssetSnapshotMap = Record<string, TrackedAssetInfo | null>;
 
 type ErrorHandler = (error: Error) => void;
 type AccountTrackerConfig = {
     demo: boolean;
+    credentials: SupportedCredentials;
     onError?: ErrorHandler;
 };
 interface AccountTracker {
     start(): Promise<void>;
     disconnect(): Promise<void>;
+    snapshot(): Promise<AccountSnapshot>;
+    snapshotAssets(coins: string[]): Promise<AssetSnapshotMap>;
     readonly isConnected: boolean;
     readonly isInitialized: boolean;
     readonly hasListeners: boolean;
@@ -614,14 +730,16 @@ interface AccountTracker {
 declare abstract class BaseAccountTracker implements AccountTracker {
     protected onError: ErrorHandler;
     protected demo: boolean;
-    protected credentials: SupportedCredentials | null;
+    protected credentials: SupportedCredentials;
     private balance;
+    private balanceInitialized;
     private positions;
     private initialized;
     private balanceListeners;
     private positionListeners;
     private assetEntries;
     constructor(config: AccountTrackerConfig);
+    snapshotAssets(coins: string[]): Promise<AssetSnapshotMap>;
     disconnect(): Promise<void>;
     get isInitialized(): boolean;
     get hasListeners(): boolean;
@@ -633,6 +751,8 @@ declare abstract class BaseAccountTracker implements AccountTracker {
     getBalance(): AccountBalance | null;
     getPositions(): AccountPosition[];
     getTrackedAsset(coin: string): TrackedAssetInfo | null;
+    /** Drops cached account snapshots without broadcasting a fabricated explicit-null update. */
+    protected resetAccountState(): void;
     protected onStateUpdate(update: StateUpdate): void;
     private applyBalanceUpdate;
     private applyPositionsUpdate;
@@ -642,6 +762,8 @@ declare abstract class BaseAccountTracker implements AccountTracker {
     private notify;
     private broadcast;
     abstract start(): Promise<void>;
+    abstract snapshot(): Promise<AccountSnapshot>;
+    protected abstract fetchAssetSnapshots(coins: string[]): Promise<AssetSnapshotMap>;
     abstract get isConnected(): boolean;
     protected abstract ensureAssetTracked(asset: string): void;
     protected abstract releaseAsset(asset: string): void;
@@ -650,15 +772,13 @@ declare abstract class BaseAccountTracker implements AccountTracker {
 
 type BinanceAccountTrackerConfig = AccountTrackerConfig & {
     credentials: SupportedCredentials;
-    userDataWs: BinanceUserDataWs;
-    wsApiWs: BinanceWsApi;
     listenKeyRefreshMs?: number;
     accountPollMs?: number;
 };
 declare class BinanceAccountTracker extends BaseAccountTracker {
     private readonly creds;
-    private readonly userDataWs;
-    private readonly wsApiWs;
+    private userDataWs;
+    private wsApiWs;
     private readonly listenKeyRefreshMs;
     private readonly accountPollMs;
     private userDataListenerId;
@@ -669,9 +789,16 @@ declare class BinanceAccountTracker extends BaseAccountTracker {
     private accountType;
     private trackedAssetInfos;
     constructor(config: BinanceAccountTrackerConfig);
+    snapshot(): Promise<AccountSnapshot>;
+    /**
+     * Stateless one-shot per-asset settings read: `positionRisk` with no symbol returns leverage +
+     * margin type for every symbol (positioned or not), so any number of assets costs one call.
+     */
+    protected fetchAssetSnapshots(coins: string[]): Promise<AssetSnapshotMap>;
     start(): Promise<void>;
     protected cleanupConnections(): Promise<void>;
     get isConnected(): boolean;
+    private fetchSnapshotData;
     protected ensureAssetTracked(coin: string): void;
     protected releaseAsset(coin: string): void;
     private pollAccountStatus;
@@ -685,11 +812,10 @@ declare class BinanceAccountTracker extends BaseAccountTracker {
 
 type BybitAccountTrackerConfig = AccountTrackerConfig & {
     credentials: SupportedCredentials;
-    ws: BybitExchangeWs;
 };
 declare class BybitAccountTracker extends BaseAccountTracker {
     private readonly creds;
-    private readonly ws;
+    private ws;
     private messageListenerId;
     private openListenerId;
     private rawCoins;
@@ -697,9 +823,20 @@ declare class BybitAccountTracker extends BaseAccountTracker {
     private accountType;
     private trackedAssetInfos;
     constructor(config: BybitAccountTrackerConfig);
+    snapshot(): Promise<AccountSnapshot>;
+    /**
+     * Stateless one-shot per-asset settings read. Bybit has no batch leverage endpoint, but
+     * `position/list` by settleCoin returns every open position (with leverage) in one call, so
+     * only requested symbols without an open position need a per-symbol fill-in read (`?symbol=`
+     * returns the leverage setting even at size 0). For ≤2 symbols the per-symbol reads alone are
+     * cheaper than the two settleCoin reads, so the batch step is skipped. A failed fill-in maps
+     * to `null`; the read only throws when no underlying read succeeded.
+     */
+    protected fetchAssetSnapshots(coins: string[]): Promise<AssetSnapshotMap>;
     start(): Promise<void>;
     protected cleanupConnections(): Promise<void>;
     get isConnected(): boolean;
+    private fetchSnapshotData;
     protected ensureAssetTracked(coin: string): void;
     protected releaseAsset(coin: string): void;
     private subscribe;
@@ -712,29 +849,46 @@ declare class BybitAccountTracker extends BaseAccountTracker {
 type HyperliquidAccountTrackerConfig = AccountTrackerConfig & {
     account: TradeAccount;
     credentials: SupportedCredentials;
-    ws: HyperliquidWs;
 };
 declare class HyperliquidAccountTracker extends BaseAccountTracker {
     private readonly address;
-    private readonly ws;
+    private ws;
     private messageListenerId;
     private openListenerId;
+    private lifecycleVersion;
     private subscribedCoins;
     private lastSummary;
     private spotCoinBalances;
+    private hasSpotState;
+    private hasClearinghouseState;
     private accountType;
-    private symbolToCollateralToken;
-    private availableToTradeByCollateral;
+    private collateralTokenMap;
+    private dexToMeta;
     private trackedAssetData;
     constructor(config: HyperliquidAccountTrackerConfig);
+    /**
+     * Reads account mode, collateral balances, per-DEX state, and positions without opening a socket.
+     */
+    snapshot(): Promise<AccountSnapshot>;
+    /**
+     * Stateless one-shot per-asset settings read via the `activeAssetData` info request (the REST
+     * twin of the live WS subscription), one request per coin fired in parallel — the info endpoint
+     * has no batch form. Per-coin reads are tolerant (a failed coin maps to `null`); the read only
+     * throws if every coin fetch fails.
+     */
+    protected fetchAssetSnapshots(coins: string[]): Promise<AssetSnapshotMap>;
     start(): Promise<void>;
     protected cleanupConnections(): Promise<void>;
+    /** Detaches and destroys the active socket without changing the current lifecycle generation. */
+    private destroyCurrentSocket;
     get isConnected(): boolean;
     protected ensureAssetTracked(coin: string): void;
     protected releaseAsset(coin: string): void;
     private isLocked;
     private addrLower;
     private sendStaticSubs;
+    /** Subscribes to the spot state variant required by the active account mode. */
+    private sendSpotStateSubscription;
     private resubscribeAll;
     private routeRaw;
     private handle;
@@ -744,45 +898,72 @@ declare class HyperliquidAccountTracker extends BaseAccountTracker {
     private onWebData3;
     private onSpotState;
     private buildBalance;
+    /** Clears both sides of the live balance join and the public account cache without emitting. */
+    private resetLiveAccountState;
     private buildTrackedAssetsMap;
 }
 
 type LighterAccountTrackerConfig = AccountTrackerConfig & {
     account: TradeAccount;
     credentials: SupportedCredentials;
-    ws: LighterWs;
+    sdk?: PearSDK;
 };
 declare class LighterAccountTracker extends BaseAccountTracker {
     private readonly accountIdentifier;
-    private readonly ws;
+    private readonly sdk;
+    private ws;
     private messageListenerId;
     private openListenerId;
     private pollTimer;
+    private pollInFlight;
+    private startInFlight;
+    private lifecycleVersion;
+    private stateVersion;
     private assetsByAssetId;
+    private rawPositionsByMarketId;
+    private marketsByMarketId;
     private summary;
+    private accountTier;
+    private lastAccountTierFetchAt;
     private hasAssets;
     constructor(config: LighterAccountTrackerConfig);
+    /** Stateless one-shot account read; tier enrichment is optional and requires SDK-backed auth. */
+    snapshot(): Promise<AccountSnapshot>;
+    /**
+     * Stateless one-shot per-asset settings read, keyed by market id (the same identifier the live
+     * trackAsset path uses). One public `GET /api/v1/account` covers every market the account holds
+     * a position row for (custom margin included, even when its size is zero); `orderBookDetails`
+     * supplies the exchange default for markets absent from the account payload.
+     */
+    protected fetchAssetSnapshots(marketIds: string[]): Promise<AssetSnapshotMap>;
     start(): Promise<void>;
+    /** Creates one tracker lifecycle while repeated callers share the same pending start. */
+    private performStart;
     protected cleanupConnections(): Promise<void>;
     get isConnected(): boolean;
     protected ensureAssetTracked(_coin: string): void;
     protected releaseAsset(_coin: string): void;
+    /** Starts a clean account-data epoch before subscribing on each websocket connection. */
+    private handleWsOpen;
     private sendStaticSubs;
     private routeRaw;
     private handle;
     private onAccountAll;
     private onUserStats;
     private buildBalance;
+    private fetchPrimaryAccount;
+    private fetchAccountTier;
     private pollAccount;
+    private performAccountPoll;
+    private shouldRefreshAccountTier;
 }
 
 type OkxAccountTrackerConfig = AccountTrackerConfig & {
     credentials: SupportedCredentials;
-    ws: OkxExchangeWs;
 };
 declare class OkxAccountTracker extends BaseAccountTracker {
     private readonly creds;
-    private readonly ws;
+    private ws;
     private messageListenerId;
     private openListenerId;
     private rawCoins;
@@ -790,9 +971,17 @@ declare class OkxAccountTracker extends BaseAccountTracker {
     private accountType;
     private trackedAssetInfos;
     constructor(config: OkxAccountTrackerConfig);
+    snapshot(): Promise<AccountSnapshot>;
+    /**
+     * Stateless one-shot per-asset leverage read via `leverage-info`, which accepts up to 20 instIds
+     * per request (chunked in the client), so N assets cost ceil(N/20) calls. Cross margin only,
+     * matching the account-level assumption used everywhere else in this connector.
+     */
+    protected fetchAssetSnapshots(instIds: string[]): Promise<AssetSnapshotMap>;
     start(): Promise<void>;
     protected cleanupConnections(): Promise<void>;
     get isConnected(): boolean;
+    private fetchSnapshotData;
     protected ensureAssetTracked(instId: string): void;
     protected releaseAsset(instId: string): void;
     private subscribe;
@@ -802,12 +991,12 @@ declare class OkxAccountTracker extends BaseAccountTracker {
     private handleBalanceUpdate;
 }
 
-type CreateAccountTrackerConfig<E extends Connector> = AccountTrackerConfig & {
+type CreateAccountTrackerConfig = AccountTrackerConfig & {
     account: TradeAccount;
     credentials: SupportedCredentials;
-    ws: ExchangeWsByConnector[E];
+    sdk?: PearSDK;
 };
-declare function createAccountTracker<E extends Connector>(exchange: E, config: CreateAccountTrackerConfig<E>): AccountTracker;
+declare function createAccountTracker(exchange: Connector, config: CreateAccountTrackerConfig): AccountTracker;
 
 declare class ExchangesSDK {
     private sdk;
@@ -817,9 +1006,12 @@ declare class ExchangesSDK {
     connect(tradeAccountId: string): Promise<ExchangeConnection>;
     status(connection: ExchangeConnection): Promise<AccountStatus>;
     createTracker(connection: ExchangeConnection): AccountTracker;
+    snapshot(tradeAccountId: string): Promise<AccountSnapshot>;
+    snapshotAssets(tradeAccountId: string, coins: string[]): Promise<AssetSnapshotMap>;
     createHelper<E extends ExchangeHelperExchange>(exchange: E): ExchangeHelperMap[E];
     createSyncer(connection: ExchangeConnection): AccountSyncer;
+    private buildTracker;
     private fetchCredentials;
 }
 
-export { ACCOUNT_TYPE_LABELS, ASSET_DECIMALS, type AccountBalance, type AccountHealthStatus, type AccountPosition, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTracker, type AccountTrackerConfig, type AccountType, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, type AssetBalance, AssetId, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceAccountType, BinanceExchangeWs, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitAccountType, BybitExchangeWs, BybitWs, type BybitWsConfig, type CheckApiWalletParams, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, type DepositParams, type DepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidAccountType, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidWs, LighterAccountSyncer, LighterAccountTracker, type LighterAccountTrackerConfig, LighterAccountType, LighterExchangeWs, type LighterHelper, type LighterLookupResult, LighterWs, type ListExternalFillsParams, type MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxAccountType, OkxExchangeWs, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, type StateUpdate, type SupportedCredentials, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, getAssetDecimals };
+export { ACCOUNT_TYPE_LABELS, ASSET_DECIMALS, type AccountBalance, type AccountHealthStatus, type AccountPosition, type AccountSnapshot, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTracker, type AccountTrackerConfig, type AccountType, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, type AssetBalance, AssetId, type AssetSnapshotMap, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceAccountType, BinanceExchangeWs, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitAccountType, BybitExchangeWs, BybitWs, type BybitWsConfig, type CheckApiWalletParams, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, type DepositParams, type DepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidAccountType, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LighterAccountSyncer, LighterAccountTracker, type LighterAccountTrackerConfig, LighterAccountType, LighterExchangeWs, type LighterHelper, type LighterLookupResult, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_USER_API_KEY_INDEX, type MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxAccountType, OkxExchangeWs, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, type StateUpdate, type SupportedCredentials, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, findAvailableApiKeyIndex, getAssetDecimals };