@pear-protocol/exchanges-sdk 0.12.1 → 0.13.0

package/dist/client/hyperliquid/rest.js

@@ -6,6 +6,16 @@ const HL_INFO_URLS = {
   mainnet: "https://api.hyperliquid.xyz/info",
   testnet: "https://api.hyperliquid-testnet.xyz/info"
 };
+class HyperliquidInfoRequestError extends Error {
+  static {
+    __name(this, "HyperliquidInfoRequestError");
+  }
+  status;
+  constructor(status) {
+    super(`Hyperliquid info request failed: ${status}`);
+    this.status = status;
+  }
+}
 async function fetchInfo(body, demo = false) {
   const url = demo ? HL_INFO_URLS.testnet : HL_INFO_URLS.mainnet;
   const res = await proxyFetch(url, {
@@ -16,7 +26,7 @@ async function fetchInfo(body, demo = false) {
     body: JSON.stringify(body)
   });
   if (!res.ok) {
-    throw new Error(`Hyperliquid info request failed: ${res.status}`);
+    throw new HyperliquidInfoRequestError(res.status);
   }
   return res.json();
 }
@@ -85,4 +95,4 @@ async function fetchActiveAssetData(user, coin, demo = false) {
 }
 __name(fetchActiveAssetData, "fetchActiveAssetData");
 
-export { fetchActiveAssetData, fetchAllMids, fetchClearinghouseState, fetchDelegatorSummary, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole, fetchUserVaultEquities };
+export { HyperliquidInfoRequestError, fetchActiveAssetData, fetchAllMids, fetchClearinghouseState, fetchDelegatorSummary, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole, fetchUserVaultEquities };

package/dist/client/lighter/rest.js

@@ -3,6 +3,17 @@ import { getLighterBaseUrl } from './constants';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+class LighterRequestError extends Error {
+  static {
+    __name(this, "LighterRequestError");
+  }
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "LighterRequestError";
+    this.status = status;
+  }
+}
 const INTENT_REQUEST_ATTEMPTS = 3;
 const INTENT_RETRY_BASE_DELAY_MS = 500;
 const RETRYABLE_INTENT_STATUSES = /* @__PURE__ */ new Set([
@@ -176,9 +187,11 @@ async function fetchAccountsByL1Address(l1Address, demo = false) {
   };
 }
 __name(fetchAccountsByL1Address, "fetchAccountsByL1Address");
-async function fetchAccount(accountIndex, authToken, demo = false) {
-  const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/account?by=index&value=${accountIndex}`, authToken);
-  return readLighterResponse(response, "/account");
+async function fetchAccount(accountIndex, authToken, demo = false, throttle) {
+  return gatedLighterRead(throttle, "account", async () => {
+    const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/account?by=index&value=${accountIndex}`, authToken);
+    return readLighterResponse(response, "/account");
+  }, () => 0);
 }
 __name(fetchAccount, "fetchAccount");
 async function fetchPublicAccount(accountIndex, demo = false) {
@@ -232,7 +245,7 @@ async function fetchAssetDetails(demo) {
   return data.asset_details;
 }
 __name(fetchAssetDetails, "fetchAssetDetails");
-async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
+async function fetchTradesSince(accountIndex, authToken, since, demo = false, throttle) {
   const results = [];
   const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
@@ -251,8 +264,10 @@ async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
         cursor
       } : {}
     });
-    const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/trades?${params.toString()}`, authToken);
-    const data = await readLighterResponse(response, "/trades");
+    const data = await gatedLighterRead(throttle, "trades", async () => {
+      const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/trades?${params.toString()}`, authToken);
+      return readLighterResponse(response, "/trades");
+    }, (page2) => (page2.trades ?? []).length);
     const page = data.trades ?? [];
     results.push(...page.filter((trade) => trade.timestamp >= since.getTime()));
     const reachedSince = page.some((trade) => trade.timestamp < since.getTime());
@@ -269,7 +284,7 @@ async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
   return Array.from(byId.values());
 }
 __name(fetchTradesSince, "fetchTradesSince");
-async function fetchPositionFundingSince(accountIndex, authToken, since, demo = false) {
+async function fetchPositionFundingSince(accountIndex, authToken, since, demo = false, throttle) {
   const results = /* @__PURE__ */ new Map();
   const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
@@ -284,8 +299,10 @@ async function fetchPositionFundingSince(accountIndex, authToken, since, demo =
         cursor
       } : {}
     });
-    const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/positionFunding?${params.toString()}`, authToken);
-    const data = await readLighterResponse(response, "/positionFunding");
+    const data = await gatedLighterRead(throttle, "positionFunding", async () => {
+      const response = await authenticatedLighterFetch(`${getLighterBaseUrl(demo)}/api/v1/positionFunding?${params.toString()}`, authToken);
+      return readLighterResponse(response, "/positionFunding");
+    }, (page) => (page.position_fundings ?? []).length);
     for (const funding of data.position_fundings ?? []) {
       if (funding.timestamp >= sinceSeconds) {
         results.set(`${funding.market_id}:${funding.funding_id}`, funding);
@@ -374,6 +391,21 @@ async function fetchUserReferrals(params, demo = false) {
   };
 }
 __name(fetchUserReferrals, "fetchUserReferrals");
+async function gatedLighterRead(throttle, requestType, run, countItems) {
+  if (!throttle) {
+    return run();
+  }
+  await throttle.beforeRequest(requestType);
+  try {
+    const result = await run();
+    throttle.afterRequest(requestType, countItems(result));
+    return result;
+  } catch (error) {
+    throttle.afterRequestError(requestType, error);
+    throw error;
+  }
+}
+__name(gatedLighterRead, "gatedLighterRead");
 async function authenticatedLighterFetch(url, authToken, init) {
   const headers = new Headers(init?.headers);
   headers.set("authorization", authToken);
@@ -440,10 +472,10 @@ async function readLighterResponse(response, endpoint, acceptedCodes = [
     data = void 0;
   }
   if (!data) {
-    throw new Error(`Lighter ${endpoint} returned ${response.status}`);
+    throw new LighterRequestError(`Lighter ${endpoint} returned ${response.status}`, response.status);
   }
   if (!acceptedCodes.includes(data.code)) {
-    throw new Error(`Lighter ${endpoint} returned ${data.code}: ${data.message ?? `HTTP ${response.status}`}`);
+    throw new LighterRequestError(`Lighter ${endpoint} returned ${data.code}: ${data.message ?? `HTTP ${response.status}`}`, response.status);
   }
   return data;
 }
@@ -493,4 +525,4 @@ function readReferralAmount(value) {
 }
 __name(readReferralAmount, "readReferralAmount");
 
-export { createCctpDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchPublicAccount, fetchPublicOrderBookDetails, fetchTradesSince, fetchUserReferrals, fetchWithdrawHistory, submitReferralCode };
+export { LighterRequestError, createCctpDepositIntentAddress, fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchDepositHistory, fetchDepositNetworks, fetchOrderBookDetails, fetchPositionFundingSince, fetchPublicAccount, fetchPublicOrderBookDetails, fetchTradesSince, fetchUserReferrals, fetchWithdrawHistory, submitReferralCode };

package/dist/index.d.ts

@@ -6,9 +6,30 @@ import { WalletClient, Transport, Chain, Account } from 'viem';
 import { z } from 'zod';
 
 type SupportedCredentials = HttpTypes.ExchangeCredentialsResponse['credentials'];
+/**
+ * Optional pacing seam around the syncer's exchange info requests. The SDK stays
+ * rate-limit-agnostic: it only exposes when a request starts, what it returned,
+ * and when it failed — the caller owns all budget math and waiting.
+ */
+type SyncerThrottle = {
+    /** Awaited before the request fires; the caller blocks here until its budget allows the call. */
+    beforeRequest(requestType: string): Promise<void>;
+    /** Called after a successful response; `itemCount` is the response array length (0 for object responses). */
+    afterRequest(requestType: string, itemCount: number): void;
+    /** Called when the request threw, before the error propagates; lets the caller inspect rate-limit rejections. */
+    afterRequestError(requestType: string, error: unknown): void;
+};
 type ExchangesSDKConfig = {
     sdk: PearSDK;
     demo?: boolean;
+    /** Optional pacing seam around the syncer's exchange info requests; absent = unthrottled (current behavior). */
+    throttle?: SyncerThrottle;
+    /**
+     * Optional pre-fetched Hyperliquid perp-dex names ('' = the main dex). The list is
+     * global (identical for every account), so a batch caller fetches it once per run and
+     * passes it here; absent = the syncer fetches it per sync (current behavior).
+     */
+    hyperliquidPerpDexNames?: string[];
     /**
      * Optional forward-proxy for the exchange REST calls. When enabled, requests are re-pointed at
      * `proxy.url` with the original venue host in `X-Proxy-Target`. Injected here because the SDK
@@ -918,6 +939,10 @@ interface AccountSyncerConfig {
     account: TradeAccount;
     credentials: SupportedCredentials;
     demo: boolean;
+    /** Optional pacing seam around the exchange info requests; absent = unthrottled (current behavior). */
+    throttle?: SyncerThrottle;
+    /** Optional pre-fetched Hyperliquid perp-dex names ('' = the main dex); absent = fetched per sync. */
+    hyperliquidPerpDexNames?: string[];
 }
 /**
  * Outcome of one fill sync cycle, so batch/cron callers can tell a completed
@@ -959,6 +984,7 @@ declare abstract class BaseAccountSyncer<ExternalFill> implements AccountSyncer
     protected account: TradeAccount;
     protected credentials: SupportedCredentials;
     protected demo: boolean;
+    protected throttle: SyncerThrottle | undefined;
     constructor(config: AccountSyncerConfig);
     /**
      * Fetch the account's currently-open positions from the exchange, normalized
@@ -1125,11 +1151,19 @@ type UserFillsByTimeResponse = {
 type HyperliquidRawFill = UserFillsByTimeResponse;
 declare class HyperliquidAccountSyncer extends BaseAccountSyncer<HyperliquidRawFill> {
     private readonly address;
+    private readonly perpDexNames;
     constructor(config: AccountSyncerConfig);
     protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
     protected listExternalFunding({ since, instruments, }: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
     protected isReduceOnly(rawFill: HyperliquidRawFill): boolean;
+    /** Fetch the perp-dex descriptors and reduce them to unique dex names ('' = the main dex). */
+    private fetchPerpDexNames;
+    /**
+     * Route one info request through the optional throttle seam: gate before the
+     * call, report the response size after, surface a failure before it propagates.
+     */
+    private fetchInfoGated;
 }
 
 type RawFill$1 = LighterRawTrade;
@@ -2531,6 +2565,8 @@ declare function createAccountTracker(exchange: Connector, config: CreateAccount
 declare class ExchangesSDK {
     private sdk;
     private demo;
+    private throttle;
+    private hyperliquidPerpDexNames;
     constructor(config: ExchangesSDKConfig);
     connect(tradeAccountId: string): Promise<ExchangeConnection>;
     /**
@@ -2548,4 +2584,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, 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 LighterApplyReferralCodeParams, type LighterAuthCredentials, LighterClassicBalance, 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, 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_USDC, 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 TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, 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, 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 LighterApplyReferralCodeParams, type LighterAuthCredentials, LighterClassicBalance, 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, 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_USDC, 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, findAvailableApiKeyIndex, getAssetDecimals, getLighterNativeUsdcAddress, listFunxyzTransferableChains, readFunxyzChainSource, readFunxyzMinimumUsd, retrieveLighterAuthToken, usdcAbi };

package/dist/sdk.js

@@ -12,9 +12,13 @@ class ExchangesSDK {
   }
   sdk;
   demo;
+  throttle;
+  hyperliquidPerpDexNames;
   constructor(config) {
     this.sdk = config.sdk;
     this.demo = config.demo ?? false;
+    this.throttle = config.throttle;
+    this.hyperliquidPerpDexNames = config.hyperliquidPerpDexNames;
     if (config.proxy) configureProxy(config.proxy);
   }
   async connect(tradeAccountId) {
@@ -67,7 +71,9 @@ class ExchangesSDK {
       connector: connection.connector,
       account: connection.account,
       credentials: connection.credentials,
-      demo: this.demo
+      demo: this.demo,
+      throttle: this.throttle,
+      hyperliquidPerpDexNames: this.hyperliquidPerpDexNames
     });
   }
   buildTracker(connection) {

package/dist/syncer/base.js

@@ -12,12 +12,14 @@ class BaseAccountSyncer {
   account;
   credentials;
   demo;
+  throttle;
   constructor(config) {
     this.sdk = config.sdk;
     this.connector = config.connector;
     this.account = config.account;
     this.credentials = config.credentials;
     this.demo = config.demo;
+    this.throttle = config.throttle;
   }
   // Phase A: Load current Pear state (positions, fills, instruments, watermark).
   async loadPearState() {

package/dist/syncer/hyperliquid/syncer.js

@@ -11,9 +11,11 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     __name(this, "HyperliquidAccountSyncer");
   }
   address;
+  perpDexNames;
   constructor(config) {
     super(config);
     this.address = config.account.exchangeIdentifier;
+    this.perpDexNames = config.hyperliquidPerpDexNames;
   }
   async listExternalPositions({ instruments }) {
     const instrumentByBase = new Map(instruments.map((instrument) => [
@@ -23,17 +25,12 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
         contractSize: instrument.precision.quantity.contractSize
       }
     ]));
-    const perpDexs = await fetchInfo({
-      type: "perpDexs"
-    }, this.demo);
-    const dexNames = [
-      ...new Set(perpDexs.map((perpDex) => perpDex?.name ?? ""))
-    ];
-    const states = await Promise.all(dexNames.map((dex) => fetchInfo({
+    const dexNames = this.perpDexNames ?? await this.fetchPerpDexNames();
+    const states = await Promise.all(dexNames.map((dex) => this.fetchInfoGated({
       type: "clearinghouseState",
       user: this.address,
       dex
-    }, this.demo)));
+    })));
     const assetPositions = states.flatMap((state) => state.assetPositions);
     return assetPositions.reduce((positions, { position: rawPosition }) => {
       const szi = new BigNumber(rawPosition.szi);
@@ -72,12 +69,12 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     let cursor = since.getTime();
     let batchSize;
     do {
-      const batch = await fetchInfo({
+      const batch = await this.fetchInfoGated({
         type: "userFillsByTime",
         user: this.address,
         startTime: cursor,
         aggregateByTime: true
-      }, this.demo);
+      });
       batchSize = batch.length;
       for (const rawFill of batch) {
         addFill(rawFill);
@@ -93,12 +90,12 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     } while (batchSize === HYPERLIQUID_FILL_PAGE_LIMIT);
     cursor = since.getTime();
     do {
-      const twapBatch = await fetchInfo({
+      const twapBatch = await this.fetchInfoGated({
         type: "userTwapSliceFillsByTime",
         user: this.address,
         startTime: cursor,
         aggregateByTime: true
-      }, this.demo);
+      });
       batchSize = twapBatch.length;
       for (const item of twapBatch) {
         addFill(item.fill);
@@ -149,11 +146,11 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     let cursor = since.getTime();
     let batchSize;
     do {
-      const batch = await fetchInfo({
+      const batch = await this.fetchInfoGated({
         type: "userFunding",
         user: this.address,
         startTime: cursor
-      }, this.demo);
+      });
       batchSize = batch.length;
       for (const event of batch) {
         allEvents.set(`${event.time}:${event.delta.coin}:${event.hash}`, event);
@@ -174,6 +171,33 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
   isReduceOnly(rawFill) {
     return rawFill.dir.includes("Close");
   }
+  /** Fetch the perp-dex descriptors and reduce them to unique dex names ('' = the main dex). */
+  async fetchPerpDexNames() {
+    const perpDexs = await this.fetchInfoGated({
+      type: "perpDexs"
+    });
+    return [
+      ...new Set(perpDexs.map((perpDex) => perpDex?.name ?? ""))
+    ];
+  }
+  /**
+  * Route one info request through the optional throttle seam: gate before the
+  * call, report the response size after, surface a failure before it propagates.
+  */
+  async fetchInfoGated(body) {
+    if (!this.throttle) {
+      return fetchInfo(body, this.demo);
+    }
+    await this.throttle.beforeRequest(body.type);
+    try {
+      const response = await fetchInfo(body, this.demo);
+      this.throttle.afterRequest(body.type, Array.isArray(response) ? response.length : 0);
+      return response;
+    } catch (error) {
+      this.throttle.afterRequestError(body.type, error);
+      throw error;
+    }
+  }
 }
 function warnStalledPagination(stream, cursor) {
   console.warn(`Hyperliquid ${stream} pagination stalled at timestamp ${cursor}; returned history may be incomplete.`);

package/dist/syncer/lighter/syncer.js

@@ -36,7 +36,7 @@ class LighterAccountSyncer extends BaseAccountSyncer {
       instrument.precision.quantity.contractSize
     ]));
     const token = await this.retrieveAuthToken();
-    const response = await fetchAccount(this.accountIndex, token, this.demo);
+    const response = await fetchAccount(this.accountIndex, token, this.demo, this.throttle);
     const rawPositions = response.accounts?.[0]?.positions ?? [];
     return rawPositions.reduce((positions, rawPosition) => {
       const instrumentId = rawPosition.market_id.toString();
@@ -59,7 +59,7 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   async listExternalFills({ since, instruments }) {
     this.assertAuthenticatedSyncAvailable();
     const token = await this.retrieveAuthToken();
-    const trades = await fetchTradesSince(this.accountIndex, token, since, this.demo);
+    const trades = await fetchTradesSince(this.accountIndex, token, since, this.demo, this.throttle);
     const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
     return trades.toSorted((a, b) => a.timestamp - b.timestamp).reduce((fills, rawFill) => {
       const instrumentId = rawFill.market_id.toString();
@@ -92,7 +92,7 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   async listExternalFunding({ since, instruments }) {
     this.assertAuthenticatedSyncAvailable();
     const token = await this.retrieveAuthToken();
-    const fundingEvents = await fetchPositionFundingSince(this.accountIndex, token, since, this.demo);
+    const fundingEvents = await fetchPositionFundingSince(this.accountIndex, token, since, this.demo, this.throttle);
     const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
     return toFundingPaymentEntries(fundingEvents, instrumentIds);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -27,9 +27,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@pear-protocol/core-sdk": "^1.19.2",
-    "@pear-protocol/types": "^1.30.1",
-    "@pear-protocol/utils": "^0.7.0",
+    "@pear-protocol/core-sdk": "^1.20.0",
+    "@pear-protocol/types": "^1.32.0",
+    "@pear-protocol/utils": "^0.8.1",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8",