@pear-protocol/exchanges-sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @pear-protocol/exchanges-sdk
 
-Unified SDK for real-time account state (balance, positions, per-asset leverage) across supported derivative exchanges.
+Unified SDK for account state (balance, positions, per-asset leverage) across supported derivative exchanges — as a live WebSocket subscription or a stateless one-shot snapshot.
 
 ## Supported Exchanges
 
@@ -25,7 +25,16 @@ import PearSDK from '@pear-protocol/core-sdk';
 import { ExchangesSDK } from '@pear-protocol/exchanges-sdk';
 
 const sdk = new PearSDK({ /* ... */ });
-const exchanges = new ExchangesSDK({ sdk });
+const exchanges = new ExchangesSDK({
+  sdk,
+  options: {
+    builderAddress: '0x...',
+    builderFeeTenthsBps: 60,
+    integratorAccountIndex: 1234,
+    integratorMinPerpsMakerFee: 600,
+    integratorMinPerpsTakerFee: 600,
+  },
+});
 
 const connection = await exchanges.connect(tradeAccountId);
 
@@ -39,6 +48,7 @@ const syncer = exchanges.createSyncer(connection);
 await tracker.start();
 
 const offBalance = tracker.trackBalance((balance) => {
+  if (!balance) return; // unsupported/unrepresentable account mode
   console.log(balance.totalEquity, balance.unrealizedPnl);
 });
 
@@ -52,25 +62,26 @@ offPositions();
 await tracker.disconnect();
 ```
 
-Pass `demo: true` to target testnet:
+Pass `demo: true` to target each exchange's test or simulated-trading environment:
 
 ```typescript
 const exchanges = new ExchangesSDK({ sdk, demo: true });
 ```
 
+Hyperliquid and Lighter public REST/WebSocket reads are routed to testnet. Lighter operations that require a backend-generated auth token or signature currently fail closed in demo mode because the existing supporting API signs for mainnet only; public snapshots and tracking remain available, without authenticated account-tier enrichment.
+
 ## Connection
 
-`connect(tradeAccountId)` fetches decrypted credentials and the trade account from the core API, then opens the exchange websocket.
+`connect(tradeAccountId)` fetches decrypted credentials and the trade account from the core API. It does **not** open a socket — the exchange WebSocket is created lazily when you call `tracker.start()` and torn down by `tracker.disconnect()`. Syncers perform one-shot REST reads. For an account snapshot with no socket, use [`snapshot()`](#one-shot-snapshot-no-websocket).
 
 The connector comes from the backend trade account.
 
 ```typescript
 const connection = await exchanges.connect(tradeAccountId);
 
-connection.exchange; // "hyperliquid"
+connection.connector; // "hyperliquid"
 connection.account.exchangeIdentifier;
 connection.credentials;
-connection.ws;
 ```
 
 For exchanges that need account health checks, pass status options when creating the SDK:
@@ -80,12 +91,17 @@ const exchanges = new ExchangesSDK({
   sdk,
   options: {
     builderAddress: '0x...',
+    builderFeeTenthsBps: 60,
     integratorAccountIndex: 1234,
+    integratorMinPerpsMakerFee: 600,
+    integratorMinPerpsTakerFee: 600,
   },
 });
 ```
 
-`builderAddress` is used to check Hyperliquid builder fee approval. `integratorAccountIndex` is used to check Lighter integrator approval.
+Hyperliquid status requires the builder address and the minimum approved fee in tenths of a basis point. Lighter status requires the integrator account and minimum maker/taker approval caps in Lighter fee ticks (parts per million). These thresholds must match the fees configured by the trading backend.
+
+Historical Hyperliquid fill synchronization uses the exchange's globally unique `time:coin:tid` identity. Existing consumers that persisted bare `tid` identifiers must account for the transition overlap. Synchronization also fails closed when the exchange reports a maker rebate: the current core external-fill contract accepts only non-negative fees, so the SDK will not silently turn a rebate into a cost or advance the synchronization watermark past it.
 
 ## Account Status
 
@@ -108,9 +124,58 @@ Possible warning reasons:
 | `api_key_invalid` | API credentials failed the exchange account check |
 | `hyperliquid_api_wallet_invalid` | Hyperliquid agent wallet is missing or invalid |
 | `hyperliquid_builder_fee_not_approved` | Hyperliquid builder fee approval is missing |
+| `hyperliquid_account_mode_check_failed` | Hyperliquid account mode could not be read |
+| `hyperliquid_account_mode_unsupported` | Portfolio Margin or deprecated DEX Abstraction cannot be valued safely |
 | `lighter_api_key_invalid` | Lighter API key cannot create an auth token |
 | `lighter_integrator_not_approved` | Lighter integrator approval is missing |
 
+## One-Shot Snapshot (no WebSocket)
+
+When you only need the current balance and positions once — a request/response read rather than a live subscription — use `snapshot()`. It fetches over REST, opens **no** WebSocket, and leaves nothing running.
+
+```typescript
+const { balance, positions } = await exchanges.snapshot(tradeAccountId);
+
+balance?.totalEquity;
+balance?.availableToTrade;
+for (const p of positions) {
+  console.log(p.symbol, p.side, p.leverage, p.liquidationPrice);
+}
+```
+
+`snapshot()` returns the same `AccountBalance` / `AccountPosition` shapes the live tracker produces — `{ balance: AccountBalance | null; positions: AccountPosition[] }` — so either path can feed the same consumer. `balance` is `null` when the account type cannot be represented safely. Hyperliquid currently supports Standard and Unified calculations; Portfolio Margin and deprecated DEX Abstraction fail closed and are surfaced by account status.
+
+There is nothing to tear down: no `disconnect()`, no socket. This is the read a stateless caller (such as an MCP tool) wants.
+
+> Hyperliquid Unified balances come from the spot clearinghouse state and use the documented maximum per-collateral maintenance ratio. Standard balances use per-DEX margin summaries, including isolated positions.
+
+### Per-Asset Settings: `snapshotAssets()`
+
+`snapshot()` carries leverage only for **open** positions.
+To read the currently configured leverage and margin mode for any asset — positioned or not — use `snapshotAssets()`.
+
+```typescript
+const assets = await exchanges.snapshotAssets(tradeAccountId, ['BTC', 'ETH']);
+
+assets.BTC?.leverage; // e.g. '20'
+assets.BTC?.marginType; // 'cross' | 'isolated'
+assets.ETH; // null when the exchange has no readable setting for that asset
+```
+
+It returns `Record<string, TrackedAssetInfo | null>` keyed by the requested asset id — the same `TrackedAssetInfo` shape the live `trackAsset()` path emits, and the same per-exchange identifier it uses (Hyperliquid coin, Binance/Bybit symbol, OKX instId, Lighter market id).
+
+The read is batch-first: each connector services the whole list with as few requests as its exchange allows.
+
+| Exchange | Requests for N assets | How |
+| --- | --- | --- |
+| Binance | 1 | all-symbols `positionRisk` |
+| Lighter | 2 | account read + market defaults |
+| OKX | ceil(N/20) | `leverage-info` accepts 20 instIds per call |
+| Bybit | 2 + k | settleCoin position lists; per-symbol fill-in for the k non-positioned symbols (direct per-symbol reads when N ≤ 2) |
+| Hyperliquid | N (parallel) | `activeAssetData` info request is per-coin (unauthenticated, cheap) |
+
+> For Lighter, a custom margin setting on a market with **no open position** is not exposed by the REST account read, so it reports the market default — the same figure the live path shows before a position exists.
+
 ## Tracking
 
 Each `track*` method returns an unsubscribe function. Callbacks fire with the current snapshot on subscribe (if available) and on every update.
@@ -119,6 +184,7 @@ Each `track*` method returns an unsubscribe function. Callbacks fire with the cu
 
 ```typescript
 tracker.trackBalance((balance) => {
+  if (!balance) return; // a live mode change can explicitly invalidate the cached balance
   balance.totalEquity;
   balance.walletBalance;
   balance.unrealizedPnl;
@@ -127,6 +193,7 @@ tracker.trackBalance((balance) => {
   balance.maintenanceMargin;
   balance.marginRatio;
   balance.accountType;
+  balance.accountTier; // Lighter account tier when reported
 
   for (const a of balance.assets) {
     a.asset;         // "USDT", "USDC", ...
@@ -177,16 +244,16 @@ Asset symbol format per exchange:
 | Lighter | base coin | `BTC` |
 | OKX | `instId` | `BTC-USDT-SWAP` |
 
-## Snapshot Reads
+## Cached Reads (live tracker)
 
-Synchronous getters for the latest cached state:
+Synchronous getters for the latest cached state on a running tracker:
 
 ```typescript
 tracker.getBalance();            // AccountBalance | null
 tracker.getPositions();          // AccountPosition[]
 tracker.getTrackedAsset('ETH');  // TrackedAssetInfo | null
 tracker.isConnected;
-tracker.isInitialized;           // true after first snapshot
+tracker.isInitialized;           // true after first balance/position state (asset metadata alone does not count)
 ```
 
 ## Account Type Labels
@@ -202,8 +269,7 @@ ACCOUNT_TYPE_LABELS[balance.accountType]; // "Cross Margin", "Portfolio Margin",
 ## Cleanup
 
 ```typescript
-await tracker.disconnect();
-connection.ws.destroy();
+await tracker.disconnect(); // closes the WebSocket opened by start()
 ```
 
 Credentials and the trade account are fetched automatically on `connect`; Hyperliquid and Lighter account identifiers come from `connection.account.exchangeIdentifier`.

package/dist/client/hyperliquid/client.test.js

@@ -0,0 +1,41 @@
+import { describe, afterEach, vi, it, expect } from 'vitest';
+import { fetchInfo } from './rest';
+import { HyperliquidWs } from './ws';
+
+class InspectableHyperliquidWs extends HyperliquidWs {
+  /** Exposes the selected URL for a transport regression assertion. */
+  url() {
+    return this.getWsUrl();
+  }
+  /** Exposes heartbeat cadence for a transport regression assertion. */
+  pingInterval() {
+    return this.getPingIntervalMs();
+  }
+  /** Exposes the heartbeat payload for a transport regression assertion. */
+  pingMessage() {
+    return this.buildPingMessage();
+  }
+}
+describe("Hyperliquid network clients", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+  it.each([
+    [false, "https://api.hyperliquid.xyz/info"],
+    [true, "https://api.hyperliquid-testnet.xyz/info"]
+  ])("routes info requests to the selected network", async (demo, expectedUrl) => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ ok: true }) });
+    vi.stubGlobal("fetch", fetchMock);
+    await fetchInfo({ type: "perpDexs" }, demo);
+    expect(fetchMock).toHaveBeenCalledWith(expectedUrl, expect.objectContaining({ method: "POST" }));
+  });
+  it("uses testnet websocket routing and Hyperliquid heartbeats in demo mode", () => {
+    const ws = new InspectableHyperliquidWs(true);
+    expect(ws.url()).toBe("wss://api.hyperliquid-testnet.xyz/ws");
+    expect(ws.pingInterval()).toBe(3e4);
+    expect(ws.pingMessage()).toEqual({ method: "ping" });
+  });
+  it("keeps no-argument websocket construction on mainnet", () => {
+    expect(new InspectableHyperliquidWs().url()).toBe("wss://api.hyperliquid.xyz/ws");
+  });
+});

package/dist/client/hyperliquid/exchange-ws.js

@@ -11,8 +11,9 @@ class HyperliquidExchangeWs extends ExchangeWs {
   connections() {
     return [this.main];
   }
-  static async create() {
-    const main = new HyperliquidWs();
+  /** Opens the Hyperliquid socket on the requested network. */
+  static async create(config = { demo: false }) {
+    const main = new HyperliquidWs(config.demo);
     await main.connect();
     return new HyperliquidExchangeWs(main);
   }

package/dist/client/hyperliquid/rest.js

@@ -1,12 +1,33 @@
-const HL_INFO_URL = "https://api.hyperliquid.xyz/info";
-async function fetchInfo(body) {
-  const res = await fetch(HL_INFO_URL, {
+const HL_INFO_URLS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
+async function fetchInfo(body, demo = false) {
+  const url = demo ? HL_INFO_URLS.testnet : HL_INFO_URLS.mainnet;
+  const res = await fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
-  if (!res.ok) throw new Error(`Hyperliquid info request failed: ${res.status}`);
+  if (!res.ok) {
+    throw new Error(`Hyperliquid info request failed: ${res.status}`);
+  }
   return res.json();
 }
+async function fetchPerpDexs(demo = false) {
+  return fetchInfo({ type: "perpDexs" }, demo);
+}
+async function fetchClearinghouseState(user, dex, demo = false) {
+  return fetchInfo({ type: "clearinghouseState", user, dex }, demo);
+}
+async function fetchUserAbstraction(user, demo = false) {
+  return fetchInfo({ type: "userAbstraction", user }, demo);
+}
+async function fetchSpotClearinghouseState(user, demo = false) {
+  return fetchInfo({ type: "spotClearinghouseState", user }, demo);
+}
+async function fetchActiveAssetData(user, coin, demo = false) {
+  return fetchInfo({ type: "activeAssetData", user, coin }, demo);
+}
 
-export { fetchInfo };
+export { fetchActiveAssetData, fetchClearinghouseState, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction };

package/dist/client/hyperliquid/ws.js

@@ -1,15 +1,27 @@
 import { BaseWs } from '../base-ws';
 
-const HL_WS_URL = "wss://api.hyperliquid.xyz/ws";
+const HL_WS_URLS = {
+  mainnet: "wss://api.hyperliquid.xyz/ws",
+  testnet: "wss://api.hyperliquid-testnet.xyz/ws"
+};
 class HyperliquidWs extends BaseWs {
+  /** Creates a Hyperliquid socket for the selected network. */
+  constructor(demo = false) {
+    super();
+    this.demo = demo;
+  }
+  demo;
+  /** Selects the mainnet or testnet websocket origin. */
   getWsUrl() {
-    return HL_WS_URL;
+    return this.demo ? HL_WS_URLS.testnet : HL_WS_URLS.mainnet;
   }
+  /** Sends heartbeats before Hyperliquid's 60-second idle timeout. */
   getPingIntervalMs() {
-    return 0;
+    return 3e4;
   }
+  /** Builds Hyperliquid's documented application-level heartbeat. */
   buildPingMessage() {
-    return null;
+    return { method: "ping" };
   }
 }
 

package/dist/client/index.js

@@ -34,9 +34,9 @@ async function createExchangeWs(exchange, config) {
         credentials: config.credentials
       });
     case "hyperliquid":
-      return HyperliquidExchangeWs.create();
+      return HyperliquidExchangeWs.create({ demo: config.demo });
     case "lighter":
-      return LighterExchangeWs.create();
+      return LighterExchangeWs.create({ demo: config.demo });
     default: {
       const _exhaustive = exchange;
       throw new Error(`Unsupported exchange: ${String(_exhaustive)}`);

package/dist/client/lighter/constants.js

@@ -1,4 +1,12 @@
 const LIGHTER_BASE_URL = "https://mainnet.zklighter.elliot.ai";
+const LIGHTER_BASE_URL_TESTNET = "https://testnet.zklighter.elliot.ai";
 const LIGHTER_WS_URL = "wss://mainnet.zklighter.elliot.ai/stream";
+const LIGHTER_WS_URL_TESTNET = "wss://testnet.zklighter.elliot.ai/stream";
+function getLighterBaseUrl(demo) {
+  return demo ? LIGHTER_BASE_URL_TESTNET : LIGHTER_BASE_URL;
+}
+function getLighterWsUrl(demo) {
+  return demo ? LIGHTER_WS_URL_TESTNET : LIGHTER_WS_URL;
+}
 
-export { LIGHTER_BASE_URL, LIGHTER_WS_URL };
+export { LIGHTER_BASE_URL, LIGHTER_BASE_URL_TESTNET, LIGHTER_WS_URL, LIGHTER_WS_URL_TESTNET, getLighterBaseUrl, getLighterWsUrl };

package/dist/client/lighter/constants.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { getLighterBaseUrl, getLighterWsUrl } from './constants';
+import { LighterWs } from './ws';
+
+class InspectableLighterWs extends LighterWs {
+  url() {
+    return this.getWsUrl();
+  }
+}
+describe("Lighter network endpoints", () => {
+  it("routes demo traffic to testnet", () => {
+    expect(getLighterBaseUrl(true)).toBe("https://testnet.zklighter.elliot.ai");
+    expect(getLighterWsUrl(true)).toBe("wss://testnet.zklighter.elliot.ai/stream");
+  });
+  it("routes non-demo traffic to mainnet", () => {
+    expect(getLighterBaseUrl(false)).toBe("https://mainnet.zklighter.elliot.ai");
+    expect(getLighterWsUrl(false)).toBe("wss://mainnet.zklighter.elliot.ai/stream");
+  });
+  it("keeps no-argument websocket construction on mainnet", () => {
+    expect(new InspectableLighterWs().url()).toBe("wss://mainnet.zklighter.elliot.ai/stream");
+  });
+});

package/dist/client/lighter/exchange-ws.js

@@ -11,8 +11,8 @@ class LighterExchangeWs extends ExchangeWs {
   connections() {
     return [this.main];
   }
-  static async create() {
-    const main = new LighterWs();
+  static async create(config = { demo: false }) {
+    const main = new LighterWs(config.demo);
     await main.connect();
     return new LighterExchangeWs(main);
   }

package/dist/client/lighter/rest.js

@@ -1,46 +1,76 @@
-import { LIGHTER_BASE_URL } from './constants';
+import { getLighterBaseUrl } from './constants';
 
-async function fetchApiKeys(accountIndex) {
-  const url = `${LIGHTER_BASE_URL}/api/v1/apikeys?account_index=${accountIndex}`;
+async function fetchApiKeys(accountIndex, demo = false) {
+  const url = `${getLighterBaseUrl(demo)}/api/v1/apikeys?account_index=${accountIndex}`;
   const response = await fetch(url);
-  if (!response.ok) throw new Error(`Lighter /apikeys returned ${response.status}`);
-  const data = await response.json();
+  const data = await readLighterResponse(response, "/apikeys");
   return data.api_keys;
 }
-async function fetchAccountsByL1Address(l1Address) {
-  const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/accountsByL1Address?l1_address=${l1Address}`);
-  return res.json();
+async function fetchAccountsByL1Address(l1Address, demo = false) {
+  const subAccounts = /* @__PURE__ */ new Map();
+  const seenCursors = /* @__PURE__ */ new Set();
+  let cursor;
+  let message;
+  do {
+    const params = new URLSearchParams({
+      l1_address: l1Address,
+      ...cursor ? { cursor } : {}
+    });
+    const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/accountsByL1Address?${params.toString()}`);
+    const data = await readLighterResponse(response, "/accountsByL1Address", [200, 21100]);
+    if (data.code === 21100) return data;
+    message ??= data.message;
+    for (const account of data.sub_accounts ?? []) {
+      subAccounts.set(account.index, account);
+    }
+    const nextCursor = data.next_cursor || void 0;
+    cursor = nextCursor && !seenCursors.has(nextCursor) ? nextCursor : void 0;
+    if (cursor) {
+      seenCursors.add(cursor);
+    }
+  } while (cursor);
+  return {
+    code: 200,
+    ...message ? { message } : {},
+    sub_accounts: Array.from(subAccounts.values())
+  };
+}
+async function fetchAccount(accountIndex, demo = false) {
+  const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/account?by=index&value=${accountIndex}`);
+  return readLighterResponse(response, "/account");
 }
-async function fetchAccount(accountIndex) {
-  const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/account?by=index&value=${accountIndex}`);
-  if (!res.ok) throw new Error(`Lighter /account returned ${res.status}`);
-  return res.json();
+async function fetchAccountLimits(accountIndex, authToken, demo = false) {
+  const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/accountLimits?account_index=${accountIndex}`, {
+    headers: { authorization: authToken }
+  });
+  return readLighterResponse(response, "/accountLimits");
 }
-async function fetchAccountMetadata(accountIndex, authToken) {
-  const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/accountMetadata?by=index&value=${accountIndex}`, {
+async function fetchAccountMetadata(accountIndex, authToken, demo = false) {
+  const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/accountMetadata?by=index&value=${accountIndex}`, {
     headers: {
       accept: "application/json",
       authorization: authToken
     }
   });
-  if (!res.ok) throw new Error(`Lighter /accountMetadata returned ${res.status}`);
-  const data = await res.json();
-  if (data.code !== 200) {
-    throw new Error(`Lighter /accountMetadata returned ${data.code}: ${data.message ?? "unknown error"}`);
-  }
+  const data = await readLighterResponse(response, "/accountMetadata");
   const matchesAccount = data.account_metadatas?.some((metadata) => metadata.account_index === accountIndex);
   if (!matchesAccount) {
     throw new Error(`Lighter /accountMetadata did not return account ${accountIndex}`);
   }
 }
-async function fetchOrderBookDetails() {
-  const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/orderBookDetails?filter=perp`);
-  if (!res.ok) throw new Error(`Lighter /orderBookDetails returned ${res.status}`);
-  const data = await res.json();
+async function fetchOrderBookDetails(demo = false) {
+  const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/orderBookDetails?filter=perp`);
+  const data = await readLighterResponse(response, "/orderBookDetails");
   return data.order_book_details;
 }
-async function fetchTradesSince(accountIndex, authToken, since) {
+async function fetchAssetDetails(demo) {
+  const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/assetDetails`);
+  const data = await readLighterResponse(response, "/assetDetails");
+  return data.asset_details;
+}
+async function fetchTradesSince(accountIndex, authToken, since, demo = false) {
   const results = [];
+  const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
   do {
     const params = new URLSearchParams({
@@ -55,18 +85,18 @@ async function fetchTradesSince(accountIndex, authToken, since) {
       aggregate: "false",
       ...cursor ? { cursor } : {}
     });
-    const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/trades?${params.toString()}`, {
+    const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/trades?${params.toString()}`, {
       headers: { authorization: authToken }
     });
-    if (!res.ok) throw new Error(`Lighter /trades returned ${res.status}`);
-    const data = await res.json();
-    if (data.code !== 200) {
-      throw new Error(`Lighter /trades returned ${data.code}: ${data.message ?? "unknown error"}`);
-    }
+    const data = await readLighterResponse(response, "/trades");
     const page = data.trades ?? [];
     results.push(...page.filter((trade) => trade.timestamp >= since.getTime()));
     const reachedSince = page.some((trade) => trade.timestamp < since.getTime());
-    cursor = reachedSince ? void 0 : data.next_cursor || void 0;
+    const nextCursor = data.next_cursor || void 0;
+    cursor = !reachedSince && nextCursor && !seenCursors.has(nextCursor) ? nextCursor : void 0;
+    if (cursor) {
+      seenCursors.add(cursor);
+    }
   } while (cursor);
   const byId = /* @__PURE__ */ new Map();
   for (const trade of results) {
@@ -74,5 +104,44 @@ async function fetchTradesSince(accountIndex, authToken, since) {
   }
   return Array.from(byId.values());
 }
+async function fetchPositionFundingSince(accountIndex, authToken, since, demo = false) {
+  const results = /* @__PURE__ */ new Map();
+  const seenCursors = /* @__PURE__ */ new Set();
+  let cursor;
+  do {
+    const params = new URLSearchParams({
+      account_index: accountIndex.toString(),
+      limit: "100",
+      side: "all",
+      start_timestamp: since.getTime().toString(),
+      ...cursor ? { cursor } : {}
+    });
+    const response = await fetch(`${getLighterBaseUrl(demo)}/api/v1/positionFunding?${params.toString()}`, {
+      headers: { authorization: authToken }
+    });
+    const data = await readLighterResponse(response, "/positionFunding");
+    for (const funding of data.position_fundings ?? []) {
+      if (funding.timestamp >= since.getTime()) {
+        results.set(`${funding.market_id}:${funding.funding_id}`, funding);
+      }
+    }
+    const nextCursor = data.next_cursor || void 0;
+    cursor = nextCursor && !seenCursors.has(nextCursor) ? nextCursor : void 0;
+    if (cursor) {
+      seenCursors.add(cursor);
+    }
+  } while (cursor);
+  return Array.from(results.values());
+}
+async function readLighterResponse(response, endpoint, acceptedCodes = [200]) {
+  if (!response.ok) {
+    throw new Error(`Lighter ${endpoint} returned ${response.status}`);
+  }
+  const data = await response.json();
+  if (!acceptedCodes.includes(data.code)) {
+    throw new Error(`Lighter ${endpoint} returned ${data.code}: ${data.message ?? "unknown error"}`);
+  }
+  return data;
+}
 
-export { fetchAccount, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchOrderBookDetails, fetchTradesSince };
+export { fetchAccount, fetchAccountLimits, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchAssetDetails, fetchOrderBookDetails, fetchPositionFundingSince, fetchTradesSince };