@pear-protocol/exchanges-sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -161,6 +161,8 @@ declare class LighterWs extends BaseWs {
     protected getWsUrl(): string;
     protected getPingIntervalMs(): number;
     protected buildPingMessage(): WsMessage;
+    /** Subscribes to one account channel with the authentication Lighter requires. */
+    subscribe(channel: string, authToken: string): void;
 }
 
 declare class LighterExchangeWs extends ExchangeWs {
@@ -255,6 +257,15 @@ type ApiKey = {
     public_key: string;
     transaction_time: number;
 };
+/**
+ * The three account tiers Lighter offers, spelled the way the venue spells them.
+ *
+ * Tier decides an account's fees, latency, and read allowance, and it is the venue's own
+ * vocabulary on both sides of the wire — `/accountLimits` reports it and `/changeAccountTier`
+ * accepts it. It lives here so the reader and the writer each import it from the venue rather
+ * than from each other.
+ */
+type LighterAccountTier = 'standard' | 'plus' | 'premium';
 /** A source network Lighter currently credits through an intent address. */
 type LighterDepositNetwork = {
     name: string;
@@ -274,14 +285,30 @@ type LighterDeposit = {
     l1TxHash: string;
 };
 
+/** Shares one live Lighter auth token per account without crossing rotated credentials. */
+
+type LighterAuthCredentials = {
+    accountIndex: number;
+    apiKeyIndex: number;
+    apiPrivateKey: string;
+};
+/** Returns a live token while coalescing concurrent signing requests. */
+declare function retrieveLighterAuthToken(sdk: PearSDK, credentials: LighterAuthCredentials, demo: boolean): Promise<string>;
+
 type WalletClientWithAccount = WalletClient<Transport, Chain | undefined, Account>;
 
-/** Native USDC contracts and transfer operations for Lighter's CCTP source chains. */
+/** Native USDC contracts and transfer operations for Lighter's EVM deposit source chains. */
 
-/** Circle's native USDC token on every source chain supported by this build. */
-declare const LIGHTER_CCTP_USDC_ADDRESSES: Record<number, `0x${string}`>;
+/**
+ * Circle's native USDC token on every source chain this build can transfer from.
+ *
+ * Every route that moves USDC from a connected wallet reads this map. A chain is absent until its
+ * native USDC contract has been verified, because transferring to a wrong contract loses the funds —
+ * so the Fun.xyz route accepts fewer chains for a wallet transfer than the bridge itself accepts.
+ */
+declare const LIGHTER_NATIVE_USDC_ADDRESSES: Record<number, `0x${string}`>;
 /** USDC carries six decimals on every supported source chain. */
-declare const LIGHTER_CCTP_USDC_DECIMALS = 6;
+declare const LIGHTER_USDC_DECIMALS = 6;
 /** The ERC-20 calls used to read and transfer native USDC. */
 declare const usdcAbi: readonly [{
     readonly inputs: readonly [{
@@ -317,15 +344,7 @@ declare const usdcAbi: readonly [{
     readonly type: "function";
 }];
 /** Names native USDC for a source chain this SDK can transfer from safely. */
-declare function getLighterCctpUsdcAddress(chainId: number): `0x${string}` | undefined;
-
-/** Shares one live Lighter auth token per account without crossing rotated credentials. */
-
-type LighterAuthCredentials = {
-    accountIndex: number;
-    apiKeyIndex: number;
-    apiPrivateKey: string;
-};
+declare function getLighterNativeUsdcAddress(chainId: number): `0x${string}` | undefined;
 
 declare const AssetId: {
     readonly ETH: 1;
@@ -361,37 +380,54 @@ declare function getAssetDecimals(assetId: number): number;
 type ConnectWalletParams = {
     accountIndex: number;
 };
-type DepositParams = {
-    to: `0x${string}`;
-    assetId: number;
-    routeType: number;
-    amount: string;
-    nativeValue?: string;
-    /** Optional cached `assetDetails.l1_decimals`; the helper fetches assetDetails when omitted. */
-    l1Decimals?: number;
-};
-type CctpDepositIntentParams = {
-    /** A `chainId` from `listDepositNetworks()`; Lighter adds networks without a release. */
-    chainId: number;
-    /** The L1 owner whose main Lighter account receives funds, not necessarily the sender. */
-    ownerAddress: `0x${string}`;
-};
-type CctpDepositIntentResult = {
-    /** Send at least `MIN_LIGHTER_CCTP_DEPOSIT_USDC` on the selected chain to this address. */
-    intentAddress: `0x${string}`;
-    /** Local deadline before Lighter's documented ten-minute cancellation boundary. */
-    expiresAt: number;
+/** The Lighter book a Fun.xyz deposit funds. */
+type FunxyzMarket = 'perps' | 'spot';
+/** What a Fun.xyz deposit is denominated in at its source. Fun.xyz converts ETH to USDC on arrival. */
+type FunxyzAsset = 'USDC' | 'ETH';
+/**
+ * The EVM chains this SDK routes a Fun.xyz deposit from, by chain id.
+ *
+ * Narrower than the bridge's own roster: a chain stays out until Circle issues native USDC on it,
+ * because every deposit here moves Circle's own token and a bridged variant would be lost. That
+ * currently excludes BNB Smart Chain and Robinhood, which the bridge accepts and this SDK does not.
+ *
+ * Ethereum mainnet sits in the same map but carries its own deposit minimum, because a mainnet
+ * deposit pays far more to bridge than one from an L2.
+ */
+declare const FUNXYZ_EVM_CHAIN_NAMES: Record<number, string>;
+/** Ethereum mainnet, whose Fun.xyz minimum never drops for an existing account. */
+declare const FUNXYZ_ETHEREUM_MAINNET_CHAIN_ID = 1;
+/** The chain families Fun.xyz mints a deposit address for, each with its own minimum. */
+type FunxyzDepositSource = 'ethereum-mainnet' | 'evm' | 'solana' | 'tron' | 'bitcoin';
+/** Whether the depositing wallet already owns a Lighter account. */
+type FunxyzAccountState = 'new' | 'existing';
+/**
+ * Fun.xyz deposit minimums in whole US dollars, by source and by account state.
+ *
+ * Send more than the minimum: bridge and swap operations lose some of the amount to slippage, and a
+ * deposit that lands under the minimum is not credited.
+ */
+declare const FUNXYZ_DEPOSIT_MINIMUMS_USD: Record<FunxyzDepositSource, Record<FunxyzAccountState, string>>;
+/** What the Fun.xyz bridge will credit once a deposit to the minted addresses lands. */
+type FunxyzDepositCredit = {
+    account: 'existing';
+    accountIndex: number;
+} | {
+    account: 'new';
+    ownerAddress: string;
 };
 /**
  * A step in a deposit's life after its transfer is submitted.
  *
- * `credited` carries the history entry, whose `amount` is the figure Lighter actually
- * booked — the only place that figure appears. `registered` is the terminal state of a
- * first deposit, which carries the account indexes instead of a history entry. `untracked`
- * ends a transfer this caller cannot follow, and `unsettled` ends one whose watch window
- * closed first, so nobody waits for an outcome that never arrives.
+ * `credited` carries whichever record the route can actually read. `registered` is the terminal
+ * state of a first deposit, which reports the account indexes the deposit created. `untracked` ends
+ * a transfer this caller asked nobody to follow, and `unsettled` ends one whose watch window closed
+ * first, so nobody waits for an outcome that never arrives.
+ *
+ * `failed` and `action-required` are reachable only on the CCTP route: Lighter's deposit history is
+ * the one source that names them, and the Fun.xyz bridge documents no failure state at all.
  */
-type CctpDepositProgress = {
+type LighterDepositProgress = {
     state: 'confirming';
     txHash: string;
 } | {
@@ -400,7 +436,7 @@ type CctpDepositProgress = {
 } | {
     state: 'credited';
     txHash: string;
-    deposit: LighterDeposit;
+    credit: LighterDepositCredit;
 } | {
     state: 'failed';
     txHash: string;
@@ -421,13 +457,27 @@ type CctpDepositProgress = {
     state: 'unsettled';
     txHash: string;
 };
+/**
+ * The evidence that a deposit was credited, kept in the form its own route produces.
+ *
+ * The CCTP route reads Lighter's authenticated deposit history, which is the only place the booked
+ * amount appears. The Fun.xyz route reads the bridge's own transaction list, which answers before a
+ * first deposit has an account to authenticate with. Neither record substitutes for the other.
+ */
+type LighterDepositCredit = {
+    source: 'lighter-history';
+    deposit: LighterDeposit;
+} | {
+    source: 'funxyz-bridge';
+    transaction: HttpTypes.LighterUdaTransaction;
+};
 /** Wallet transport a deposit borrows from its caller, keeping this SDK free of any wallet library. */
-type CctpDepositWalletAdapter = {
+type LighterDepositWalletAdapter = {
     readUsdcBalance: (chainId: number, ownerAddress: `0x${string}`) => Promise<bigint>;
     retrieveWallet: (chainId: number) => Promise<WalletClientWithAccount>;
     confirmTransaction: (chainId: number, txHash: string) => Promise<void>;
 };
-/** Credentials that let a deposit watch read the credited main account's deposit history. */
+/** Credentials that let a CCTP deposit watch read the credited main account's deposit history. */
 type CctpDepositHistorySettlement = {
     follow: 'deposit-history';
     selectedAccountIndex: number;
@@ -438,35 +488,155 @@ type CctpDepositRegistrationSettlement = {
     follow: 'account-registration';
 };
 /**
- * How a submitted deposit is followed to its Lighter outcome.
+ * How a submitted CCTP deposit is followed to its Lighter outcome.
  *
  * A first deposit cannot supply credentials — it is the deposit that creates the account — so
  * it re-runs the onboarding read instead of the authenticated deposit history.
  */
 type CctpDepositSettlement = CctpDepositHistorySettlement | CctpDepositRegistrationSettlement;
+/**
+ * Follows a submitted Fun.xyz deposit to its Lighter outcome.
+ *
+ * Carries no follow mode on purpose: only the bridge knows which record can answer, and it says so
+ * when it mints the address. An account that already exists is confirmed from the bridge's own
+ * transaction list; the deposit that creates an account is confirmed by Lighter registering it.
+ * Asking a caller to predict that invites the one combination that never resolves. Omit this object
+ * to submit a deposit nobody waits on.
+ */
+type FunxyzDepositSettlement = {
+    follow: 'outcome';
+};
+/** Deposits through Lighter's Ethereum gateway contract, signed by the owner's own wallet. */
+type EthereumDepositParams = {
+    route: 'ethereum';
+    /** The mainnet wallet that signs the gateway call. */
+    walletClient: WalletClientWithAccount;
+    to: `0x${string}`;
+    assetId: number;
+    routeType: number;
+    amount: string;
+    nativeValue?: string;
+    /** Optional cached `assetDetails.l1_decimals`; the helper fetches assetDetails when omitted. */
+    l1Decimals?: number;
+};
+/** Deposits native USDC to a Lighter CCTP intent address bound to this exact amount. */
 type CctpDepositParams = {
+    route: 'cctp';
     /** The L1 wallet whose main Lighter account receives the deposit. */
     ownerAddress: `0x${string}`;
     /** The browser wallet allowed to use the direct-transfer path. */
     connectedAddress: `0x${string}` | undefined;
-    /** A `chainId` from `listDepositNetworks()`; the connected wallet must already be on it. */
+    /** A `chainId` from `listCctpDepositNetworks()`; the connected wallet must already be on it. */
     chainId: number;
     /** Positive human-readable USDC amount with at most six fractional digits. */
     amount: string;
     /** Supplies wallet transport operations without coupling the SDK to Wagmi. */
-    wallet: CctpDepositWalletAdapter;
+    wallet: LighterDepositWalletAdapter;
     /** Receives source-confirmation and Lighter-settlement state changes. */
-    onProgress: (progress: CctpDepositProgress) => void;
+    onProgress: (progress: LighterDepositProgress) => void;
     /** Stops in-memory settlement polling when the owning view changes. */
     signal?: AbortSignal;
     /** Follows deposit history for a funded account, or account registration for a first deposit. */
     settlement?: CctpDepositSettlement;
+    /** Overrides how long the settlement watch waits before reporting `unsettled`; defaults to `SETTLEMENT_WATCH_LIMIT_MS`. */
+    settlementTimeoutMs?: number;
+};
+/**
+ * Deposits native USDC to the wallet's Fun.xyz universal deposit address.
+ *
+ * USDC only: the wallet adapter reads a USDC balance and nothing else, so an ETH deposit goes
+ * through `createDepositAddress` and the depositor's own transfer instead.
+ */
+type FunxyzDepositParams = {
+    route: 'funxyz';
+    /** The L1 wallet whose Lighter account the bridge credits. */
+    ownerAddress: `0x${string}`;
+    /** The browser wallet allowed to use the direct-transfer path. */
+    connectedAddress: `0x${string}` | undefined;
+    /** A chain id from `FUNXYZ_EVM_CHAIN_NAMES`; the connected wallet must already be on it. */
+    chainId: number;
+    /** Positive human-readable USDC amount with at most six fractional digits. */
+    amount: string;
+    /** Which Lighter book the deposit funds. */
+    market: FunxyzMarket;
+    /** Targets a sub-account; omit to credit the owner's master account. */
+    accountIndex?: number;
+    /** Supplies wallet transport operations without coupling the SDK to Wagmi. */
+    wallet: LighterDepositWalletAdapter;
+    /** Receives source-confirmation and bridge-settlement state changes. */
+    onProgress: (progress: LighterDepositProgress) => void;
+    /** Stops in-memory settlement polling when the owning view changes. */
+    signal?: AbortSignal;
+    /** Follows the bridge, and account registration when this is the account's first deposit. */
+    settlement?: FunxyzDepositSettlement;
+};
+/** Every way this SDK can move funds into a Lighter account, selected by `route`. */
+type LighterDepositParams = EthereumDepositParams | CctpDepositParams | FunxyzDepositParams;
+type EthereumDepositResult = {
+    route: 'ethereum';
+    txHash: string;
 };
 type CctpDepositResult = {
+    route: 'cctp';
     txHash: string;
     /** The intent address the transfer credits, so a caller can link to what it funded. */
     intentAddress: `0x${string}`;
 };
+type FunxyzDepositResult = {
+    route: 'funxyz';
+    txHash: string;
+    /** The universal deposit address the transfer credits, so a caller can link to what it funded. */
+    depositAddress: `0x${string}`;
+    /** What the bridge will credit: an existing account index, or the account this deposit creates. */
+    credits: FunxyzDepositCredit;
+};
+type LighterDepositResult = EthereumDepositResult | CctpDepositResult | FunxyzDepositResult;
+/** Requests a short-lived CCTP address any wallet or exchange may send native USDC to. */
+type CctpDepositAddressParams = {
+    route: 'cctp';
+    /** A `chainId` from `listCctpDepositNetworks()`; Lighter adds networks without a release. */
+    chainId: number;
+    /** The L1 owner whose main Lighter account receives funds, not necessarily the sender. */
+    ownerAddress: `0x${string}`;
+};
+/** Requests the wallet's permanent Fun.xyz addresses, one per supported chain family. */
+type FunxyzDepositAddressParams = {
+    route: 'funxyz';
+    /** The L1 owner whose Lighter account receives funds, not necessarily the sender. */
+    ownerAddress: `0x${string}`;
+    /** Which Lighter book the deposit funds. */
+    market: FunxyzMarket;
+    /** What the depositor will send; Fun.xyz converts ETH to USDC on arrival. */
+    asset: FunxyzAsset;
+    /** Targets a sub-account; omit to credit the owner's master account. */
+    accountIndex?: number;
+};
+/** Every way this SDK can hand out an address that credits a Lighter account, selected by `route`. */
+type LighterDepositAddressParams = CctpDepositAddressParams | FunxyzDepositAddressParams;
+type CctpDepositAddressResult = {
+    route: 'cctp';
+    /** Send at least `MIN_LIGHTER_CCTP_DEPOSIT_USDC` on the selected chain to this address. */
+    intentAddress: `0x${string}`;
+    /** Local deadline before Lighter's documented ten-minute cancellation boundary. */
+    expiresAt: number;
+};
+/**
+ * The wallet's Fun.xyz addresses, which the bridge mints once and then reuses.
+ *
+ * Unlike a CCTP intent these never expire and are not bound to an amount, so a caller may show them
+ * for as long as the wallet is connected. A family the bridge cannot currently serve is absent
+ * rather than empty, so no caller offers an address that credits nobody.
+ */
+type FunxyzDepositAddressResult = {
+    route: 'funxyz';
+    evmAddress: `0x${string}`;
+    solanaAddress?: string;
+    tronAddress?: string;
+    bitcoinSegwitAddress?: string;
+    /** What the bridge will credit: an existing account index, or the account a first deposit creates. */
+    credits: FunxyzDepositCredit;
+};
+type LighterDepositAddressResult = CctpDepositAddressResult | FunxyzDepositAddressResult;
 type WithdrawParams = {
     accountIndex: number;
     assetId: number;
@@ -496,15 +666,22 @@ type ApproveIntegratorParams = {
 type ApproveIntegratorResult = {
     txHash: string;
 };
+type ChangeAccountTierParams = {
+    accountIndex: number;
+    apiKeyIndex: number;
+    apiPrivateKey: string;
+    /** The tier to move onto; the tier in force reads off the account tracker. */
+    tier: LighterAccountTier;
+};
+type ChangeAccountTierResult = {
+    tier: LighterAccountTier;
+};
 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;
-};
 type WithdrawResult = {
     txHash: string;
 };
@@ -529,13 +706,19 @@ type LighterOnboardingStatus = {
 interface LighterHelper {
     checkOnboarding(l1Address: string): Promise<LighterOnboardingStatus>;
     lookupAccount(l1Address: string): Promise<LighterLookupResult>;
-    checkIntegratorApproval(accountIndex: number, integratorAccountIndex: number, requirements?: IntegratorApprovalRequirements): Promise<boolean>;
+    checkIntegratorApproval(accountIndex: number, integratorAccountIndex: number, requirements?: IntegratorApprovalRequirements, authToken?: string): Promise<boolean>;
     connectWallet(walletClient: WalletClientWithAccount, params: ConnectWalletParams): Promise<ConnectWalletResult>;
     approveIntegrator(walletClient: WalletClientWithAccount, params: ApproveIntegratorParams): Promise<ApproveIntegratorResult>;
-    listDepositNetworks(): Promise<LighterDepositNetwork[]>;
-    createExternalCctpDepositIntent(params: CctpDepositIntentParams): Promise<CctpDepositIntentResult>;
-    depositUsdcViaCctp(params: CctpDepositParams): Promise<CctpDepositResult>;
-    deposit(walletClient: WalletClientWithAccount, params: DepositParams): Promise<DepositResult>;
+    changeAccountTier(params: ChangeAccountTierParams): Promise<ChangeAccountTierResult>;
+    listCctpDepositNetworks(): Promise<LighterDepositNetwork[]>;
+    /** Runs one deposit route end to end, narrowing its result to the route the caller selected. */
+    deposit<TParams extends LighterDepositParams>(params: TParams): Promise<Extract<LighterDepositResult, {
+        route: TParams['route'];
+    }>>;
+    /** Hands out an address any sender may fund, narrowed to the route the caller selected. */
+    createDepositAddress<TParams extends LighterDepositAddressParams>(params: TParams): Promise<Extract<LighterDepositAddressResult, {
+        route: TParams['route'];
+    }>>;
     fastWithdraw(walletClient: WalletClientWithAccount, params: FastWithdrawParams): Promise<FastWithdrawResult>;
     withdraw(walletClient: WalletClientWithAccount, params: WithdrawParams): Promise<WithdrawResult>;
 }
@@ -544,6 +727,33 @@ type LighterLookupResult = {
     subAccountIndexes: number[];
 };
 
+/**
+ * Functional Lighter deposit operations that route through the Fun.xyz bridge.
+ *
+ * The bridge mints a universal deposit address (UDA) per wallet and credits anything sent to it,
+ * creating the Lighter account when the first deposit lands. That is what lets one operation serve a
+ * wallet Lighter has never seen and one that already holds an account.
+ *
+ * Every bridge call goes through Core, which holds the builder API key. The key authenticates a
+ * builder rather than a user, so it must never reach a browser bundle.
+ */
+
+/** Names the Fun.xyz minimum, in whole US dollars, for one source and account state. */
+declare function readFunxyzMinimumUsd(source: FunxyzDepositSource, account: FunxyzAccountState): string;
+/**
+ * Lists the EVM chains a connected wallet can deposit from through `deposit({ route: 'funxyz' })`.
+ *
+ * Narrower than what the bridge accepts: this SDK submits the ERC-20 transfer itself, so it offers a
+ * chain only once that chain's native USDC contract is verified. A caller wanting the rest of the
+ * bridge's roster hands out an address from `createDepositAddress` instead.
+ */
+declare function listFunxyzTransferableChains(): Array<{
+    chainId: number;
+    name: string;
+}>;
+/** Names which minimum an EVM chain falls under, since mainnet never gets the reduced one. */
+declare function readFunxyzChainSource(chainId: number): FunxyzDepositSource;
+
 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;
@@ -1950,11 +2160,18 @@ declare const LighterUnifiedBalance: z.ZodObject<{
 type LighterUnifiedBalance = z.infer<typeof LighterUnifiedBalance>;
 
 type LighterAccountTrackerConfig = AccountTrackerConfig & {
+    /** Null leaves the tier unread: `/accountLimits` is authenticated and only Core mints a token. */
+    sdk: PearSDK | null;
     account: TradeAccount;
     credentials: SupportedCredentials;
 };
+/** Told the account's tier, or told there is no answer yet. */
+type AccountTierCallback = (tier: LighterAccountTier | null) => void;
 declare class LighterAccountTracker extends BaseAccountTracker {
+    private readonly sdk;
     private readonly accountIdentifier;
+    private readonly apiKeyIndex;
+    private readonly apiPrivateKey;
     private ws;
     private messageListenerId;
     private openListenerId;
@@ -1962,8 +2179,10 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     private positionPollInFlight;
     private marketRefreshTimer;
     private marketRefreshInFlight;
+    private subscribeRetryTimer;
     private startInFlight;
     private lifecycleVersion;
+    private wsConnectionVersion;
     private stateVersion;
     private assetsByAssetId;
     private wsPositionsByMarketId;
@@ -1971,9 +2190,30 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     private marketsBySymbol;
     private spotPriceBySymbol;
     private stats;
+    private accountTier;
+    private accountTierListeners;
+    private accountTierInFlight;
     private hasAssets;
     constructor(config: LighterAccountTrackerConfig);
-    /** Stateless one-shot account read — public endpoints only, and no websocket. */
+    /**
+     * The tier Lighter has the account on, and every later change to it.
+     *
+     * A separate channel from the balance on purpose: tier is account configuration, so it neither
+     * moves with the account's figures nor belongs to a trading mode. No websocket channel carries
+     * it — `/accountLimits` is the only source — so this reports what the last read said, and
+     * `refreshAccountTier` is what asks again.
+     */
+    trackAccountTier(callback: AccountTierCallback): () => void;
+    /** The tier as the last read left it, without asking the venue again. */
+    getAccountTier(): LighterAccountTier | null;
+    /**
+     * Re-reads the tier and tells every subscriber what changed.
+     *
+     * Called after something moves the tier — a change this account submitted — because nothing on
+     * the socket announces one. Repeated callers share one in-flight read.
+     */
+    refreshAccountTier(): Promise<void>;
+    /** Stateless one-shot account read — authenticated for connected accounts, and no websocket. */
     snapshot(): Promise<AccountSnapshot>;
     /**
      * Stateless one-shot per-asset settings read, keyed by market id (the same identifier the live
@@ -1995,7 +2235,21 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     protected releaseAsset(_coin: string): void;
     /** Starts a clean account-data epoch before subscribing on each websocket connection. */
     private handleWsOpen;
-    private sendStaticSubs;
+    /**
+     * Subscribes this socket epoch's account channels, and keeps trying until one attempt lands.
+     *
+     * This is the sole subscriber of `account_all` and `user_stats`, and the live balance is built
+     * from those two channels alone — see `buildBalance`. A mint that failed once and was never
+     * retried therefore left the tracker connected but permanently unsubscribed: the 2s REST poll
+     * kept positions moving while the balance silently froze until some incidental reconnect.
+     *
+     * The wait doubles up to a ceiling, and only a new connection epoch or teardown ends it.
+     */
+    private subscribeAccountChannels;
+    /** Mints a live token for this socket epoch and authenticates every account subscription. */
+    private sendAccountSubscriptions;
+    /** Drops a pending subscription retry, so nothing outlives the connection that scheduled it. */
+    private clearSubscribeRetry;
     private routeRaw;
     private handle;
     private onAccountAll;
@@ -2018,7 +2272,14 @@ declare class LighterAccountTracker extends BaseAccountTracker {
     private marketContext;
     /** The account's current per-market settings as the base tracker already holds them. */
     private liveAccountSettings;
+    /** Reads the account with credentials when present, or explicitly uses the read-only verifier path. */
     private fetchPrimaryAccount;
+    /** Reads market context under the same account identity as the snapshot that consumes it. */
+    private fetchMarkets;
+    /** Returns this account's cached auth token, or no token for the explicit empty-key verifier. */
+    private retrieveAuthToken;
+    /** Requires credentials for private WebSocket channels even when REST is in verifier mode. */
+    private retrieveRequiredAuthToken;
     private pollPositions;
     /**
      * Republishes positions and per-market settings from REST.
@@ -2033,6 +2294,15 @@ declare class LighterAccountTracker extends BaseAccountTracker {
      * partly REST-derived without any reader being able to tell.
      */
     private performPositionPoll;
+    /**
+     * Reads the tier Lighter currently has the account on, and publishes it when it moved.
+     *
+     * `/accountLimits` is authenticated, so a tracker with no SDK to mint a token through — and demo,
+     * where no such account exists — reports no tier rather than a wrong one. A failed read does the
+     * same and leaves the last known tier standing: the endpoint failing is not the account losing
+     * its tier, and blanking it would announce a change nobody made.
+     */
+    private performAccountTierRead;
     /** Shares one in-flight market read, so a slow response cannot stack requests behind the WAF. */
     private refreshMarkets;
     /**
@@ -2248,6 +2518,8 @@ declare class OkxAccountTracker extends BaseAccountTracker {
 }
 
 type CreateAccountTrackerConfig = AccountTrackerConfig & {
+    /** Lighter only: null there leaves the account's tier unread. */
+    sdk: PearSDK | null;
     account: TradeAccount;
     credentials: SupportedCredentials;
 };
@@ -2278,4 +2550,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 AccountTracker, type AccountTrackerConfig, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, AssetId, type AssetSnapshotMap, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BasketLeg, 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 CappedBasketLeg, type CctpDepositHistorySettlement, type CctpDepositIntentParams, type CctpDepositIntentResult, type CctpDepositParams, type CctpDepositProgress, type CctpDepositRegistrationSettlement, type CctpDepositResult, type CctpDepositSettlement, type CctpDepositWalletAdapter, type CheckApiWalletParams, CollateralBalance, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, DecimalString, type DepositParams, type DepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, type FastWithdrawParams, type FastWithdrawResult, type FillSyncOutcome, type FundingSyncOutcome, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidDexState, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LIGHTER_CCTP_USDC_ADDRESSES, LIGHTER_CCTP_USDC_DECIMALS, LighterAccountSyncer, LighterAccountTracker, type LighterAccountTrackerConfig, LighterClassicBalance, type LighterDeposit, type LighterDepositNetwork, LighterExchangeWs, type LighterHelper, type LighterLookupResult, type LighterOnboardingStatus, LighterUnifiedBalance, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_LIGHTER_CCTP_DEPOSIT_USDC, MIN_LIGHTER_FAST_WITHDRAW_USDC, MIN_USER_API_KEY_INDEX, MarginMode, type MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizeResult, 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 TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, computeMaxBasketSize, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, findAvailableApiKeyIndex, getAssetDecimals, getLighterCctpUsdcAddress, 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, BasketLeg, 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 CappedBasketLeg, 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, HyperliquidDexState, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidPortfolioMarginBalance, HyperliquidPortfolioMarginCollateral, HyperliquidStandardBalance, HyperliquidUnifiedBalance, HyperliquidWs, type IntegratorApprovalRequirements, L2_ASSET_DECIMALS, LIGHTER_NATIVE_USDC_ADDRESSES, LIGHTER_USDC_DECIMALS, LighterAccountSyncer, type LighterAccountTier, LighterAccountTracker, type LighterAccountTrackerConfig, type LighterAuthCredentials, LighterClassicBalance, type LighterDeposit, type LighterDepositAddressParams, type LighterDepositAddressResult, type LighterDepositCredit, type LighterDepositNetwork, type LighterDepositParams, type LighterDepositProgress, type LighterDepositResult, type LighterDepositWalletAdapter, LighterExchangeWs, type LighterHelper, type LighterLookupResult, type LighterOnboardingStatus, LighterUnifiedBalance, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, MAX_API_KEY_INDEX, MIN_LIGHTER_CCTP_DEPOSIT_USDC, MIN_LIGHTER_FAST_WITHDRAW_USDC, MIN_USER_API_KEY_INDEX, MarginMode, type MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizeResult, 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 TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, computeMaxBasketSize, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, findAvailableApiKeyIndex, getAssetDecimals, getLighterNativeUsdcAddress, listFunxyzTransferableChains, readFunxyzChainSource, readFunxyzMinimumUsd, retrieveLighterAuthToken, usdcAbi };

package/dist/sdk.js

@@ -80,6 +80,8 @@ class ExchangesSDK {
   }
   buildTracker(connection) {
     return createAccountTracker(connection.connector, {
+      // Lighter's tier read is authenticated, and Core is what mints the token for it.
+      sdk: this.sdk,
       demo: this.demo,
       account: connection.account,
       credentials: connection.credentials

package/dist/status/lighter/status.js

@@ -32,6 +32,11 @@ async function checkLighterAccountStatus(config) {
   }
   if (integratorAccountIndex !== void 0 && integratorMinPerpsMakerFee !== void 0 && integratorMinPerpsTakerFee !== void 0) {
     try {
+      const token = await retrieveLighterAuthToken(config.sdk, {
+        accountIndex,
+        apiKeyIndex: credentials.api_key_index,
+        apiPrivateKey: credentials.api_private_key
+      }, config.demo);
       const helper = createExchangeHelper({
         exchange: "lighter",
         sdk: config.sdk,
@@ -40,7 +45,7 @@ async function checkLighterAccountStatus(config) {
       const approved = await helper.checkIntegratorApproval(accountIndex, integratorAccountIndex, {
         minPerpsMakerFee: integratorMinPerpsMakerFee,
         minPerpsTakerFee: integratorMinPerpsTakerFee
-      });
+      }, token);
       if (!approved) reasons.push("lighter_integrator_not_approved");
     } catch {
       reasons.push("lighter_integrator_not_approved");

package/dist/syncer/lighter/syncer.js

@@ -30,11 +30,13 @@ class LighterAccountSyncer extends BaseAccountSyncer {
     }, this.demo);
   }
   async listExternalPositions({ instruments }) {
+    this.assertAuthenticatedSyncAvailable();
     const contractSizeByInstrumentId = new Map(instruments.map((instrument) => [
       instrument.id,
       instrument.precision.quantity.contractSize
     ]));
-    const response = await fetchAccount(this.accountIndex, this.demo);
+    const token = await this.retrieveAuthToken();
+    const response = await fetchAccount(this.accountIndex, token, this.demo);
     const rawPositions = response.accounts?.[0]?.positions ?? [];
     return rawPositions.reduce((positions, rawPosition) => {
       const instrumentId = rawPosition.market_id.toString();

package/dist/tracker/index.js

@@ -50,6 +50,7 @@ function createAccountTracker(exchange, config) {
       });
     case "lighter":
       return new LighterAccountTracker({
+        sdk: config.sdk,
         demo: config.demo,
         onError: config.onError,
         account: config.account,