@pear-protocol/exchanges-sdk 0.3.0 → 0.4.0

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

@@ -0,0 +1,152 @@
+import { afterEach, vi, describe, it, expect } from 'vitest';
+import { fetchAccount, fetchAssetDetails, fetchAccountsByL1Address, fetchAccountLimits, fetchPositionFundingSince, fetchTradesSince } from './rest';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+describe("Lighter REST client", () => {
+  it("routes demo account reads to testnet and rejects exchange-level errors", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: 20001, message: "account not found" }), {
+        status: 200
+      })
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(fetchAccount(42, true)).rejects.toThrow("Lighter /account returned 20001: account not found");
+    expect(fetchMock).toHaveBeenCalledWith("https://testnet.zklighter.elliot.ai/api/v1/account?by=index&value=42");
+  });
+  it("rejects HTTP failures before reading endpoint data", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("unavailable", { status: 503 })));
+    await expect(fetchAssetDetails(false)).rejects.toThrow("Lighter /assetDetails returned 503");
+  });
+  it("preserves the account-not-registered lookup result for the helper", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ code: 21100, message: "account not found" }), {
+          status: 200
+        })
+      )
+    );
+    await expect(fetchAccountsByL1Address("0xabc", true)).resolves.toEqual({
+      code: 21100,
+      message: "account not found"
+    });
+  });
+  it("paginates and de-duplicates subaccounts while stopping a repeated cursor", async () => {
+    const fetchMock = vi.fn().mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          code: 200,
+          sub_accounts: [
+            { account_type: 0, index: 1 },
+            { account_type: 1, index: 2 }
+          ],
+          next_cursor: "page-2"
+        }),
+        { status: 200 }
+      )
+    ).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          code: 200,
+          sub_accounts: [
+            { account_type: 1, index: 2 },
+            { account_type: 1, index: 3 }
+          ],
+          next_cursor: "page-2"
+        }),
+        { status: 200 }
+      )
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(fetchAccountsByL1Address("0xabc", true)).resolves.toMatchObject({
+      code: 200,
+      sub_accounts: [
+        { account_type: 0, index: 1 },
+        { account_type: 1, index: 2 },
+        { account_type: 1, index: 3 }
+      ]
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[1]?.[0])).toContain("cursor=page-2");
+  });
+  it("reads authenticated account limits from the selected environment", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: 200, user_tier: "premium" }), {
+        status: 200
+      })
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(fetchAccountLimits(42, "auth-token", true)).resolves.toMatchObject({ user_tier: "premium" });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://testnet.zklighter.elliot.ai/api/v1/accountLimits?account_index=42",
+      { headers: { authorization: "auth-token" } }
+    );
+  });
+  it("returns typed L1 and L2 decimals from assetDetails", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 200,
+          asset_details: [{ asset_id: 1, symbol: "ETH", l1_decimals: 18, decimals: 8 }]
+        }),
+        { status: 200 }
+      )
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(fetchAssetDetails(false)).resolves.toEqual([
+      { asset_id: 1, symbol: "ETH", l1_decimals: 18, decimals: 8 }
+    ]);
+    expect(fetchMock).toHaveBeenCalledWith("https://mainnet.zklighter.elliot.ai/api/v1/assetDetails");
+  });
+  it("paginates and de-duplicates funding rows by market and funding id", async () => {
+    const duplicate = fundingRow({ funding_id: 2, timestamp: 2e3 });
+    const fetchMock = vi.fn().mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          code: 200,
+          position_fundings: [fundingRow({ funding_id: 1, timestamp: 1e3 }), duplicate],
+          next_cursor: "page-2"
+        }),
+        { status: 200 }
+      )
+    ).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          code: 200,
+          position_fundings: [duplicate, fundingRow({ funding_id: 3, timestamp: 3e3 })]
+        }),
+        { status: 200 }
+      )
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const rows = await fetchPositionFundingSince(42, "auth", /* @__PURE__ */ new Date(1e3), true);
+    expect(rows.map((row) => row.funding_id)).toEqual([1, 2, 3]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[0]?.[0])).toContain("start_timestamp=1000");
+    expect(String(fetchMock.mock.calls[1]?.[0])).toContain("cursor=page-2");
+  });
+  it("stops trades pagination when the API repeats a cursor", async () => {
+    const page = new Response(JSON.stringify({ code: 200, trades: [], next_cursor: "same-page" }), { status: 200 });
+    const fetchMock = vi.fn().mockResolvedValueOnce(page).mockResolvedValueOnce(
+      new Response(JSON.stringify({ code: 200, trades: [], next_cursor: "same-page" }), { status: 200 })
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(fetchTradesSince(42, "auth", /* @__PURE__ */ new Date(1e3), true)).resolves.toEqual([]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[1]?.[0])).toContain("cursor=same-page");
+  });
+});
+function fundingRow(overrides) {
+  return {
+    timestamp: overrides.timestamp,
+    market_id: 1,
+    funding_id: overrides.funding_id,
+    change: "-2",
+    discount: "0",
+    rate: "0.0001",
+    position_size: "4",
+    position_side: "long"
+  };
+}

package/dist/client/lighter/ws.js

@@ -1,10 +1,15 @@
 import { BaseWs } from '../base-ws';
-import { LIGHTER_WS_URL } from './constants';
+import { getLighterWsUrl } from './constants';
 
 const PING_INTERVAL_MS = 9e4;
 class LighterWs extends BaseWs {
+  constructor(demo = false) {
+    super();
+    this.demo = demo;
+  }
+  demo;
   getWsUrl() {
-    return LIGHTER_WS_URL;
+    return getLighterWsUrl(this.demo);
   }
   getPingIntervalMs() {
     return PING_INTERVAL_MS;

package/dist/client/okx/rest.js

@@ -44,14 +44,23 @@ async function fetchBalance(creds, demo) {
 async function fetchPositions(creds, demo) {
   return signedGet(creds, "/api/v5/account/positions", { instType: "SWAP" }, demo);
 }
-async function fetchLeverageInfo(creds, instId, demo) {
-  const result = await signedGet(
-    creds,
-    "/api/v5/account/leverage-info",
-    { instId, mgnMode: "cross" },
-    demo
-  ).catch(() => []);
-  return result[0];
+const LEVERAGE_INFO_MAX_INST_IDS = 20;
+async function fetchLeverageInfos(creds, instIds, demo) {
+  const chunks = [];
+  for (let i = 0; i < instIds.length; i += LEVERAGE_INFO_MAX_INST_IDS) {
+    chunks.push(instIds.slice(i, i + LEVERAGE_INFO_MAX_INST_IDS));
+  }
+  const results = await Promise.all(
+    chunks.map(
+      (chunk) => signedGet(
+        creds,
+        "/api/v5/account/leverage-info",
+        { instId: chunk.join(","), mgnMode: "cross" },
+        demo
+      )
+    )
+  );
+  return results.flat();
 }
 const FILLS_HISTORY_LIMIT = 100;
 async function fetchFillsHistorySince(creds, since, demo) {
@@ -81,4 +90,4 @@ async function fetchFillsHistorySince(creds, since, demo) {
   return Array.from(byId.values());
 }
 
-export { fetchAccountConfig, fetchBalance, fetchFillsHistorySince, fetchLeverageInfo, fetchPositions };
+export { fetchAccountConfig, fetchBalance, fetchFillsHistorySince, fetchLeverageInfos, fetchPositions };

package/dist/helper/factory.js

@@ -4,9 +4,9 @@ import { createLighterHelper } from './lighter';
 function createExchangeHelper(config) {
   switch (config.exchange) {
     case "hyperliquid":
-      return createHyperliquidHelper();
+      return createHyperliquidHelper(config.demo ?? false);
     case "lighter":
-      return createLighterHelper(config.sdk);
+      return createLighterHelper(config.sdk, config.demo ?? false);
   }
 }
 

package/dist/helper/hyperliquid/helper.js

@@ -1,21 +1,36 @@
 import { fetchInfo } from '../../client/hyperliquid/rest';
 
-function createHyperliquidHelper() {
+function createHyperliquidHelper(demo = false) {
   return {
+    /** Checks that the requested API wallet exists and has not expired. */
     async checkApiWallet(params) {
-      const agents = await fetchInfo({
-        type: "extraAgents",
-        user: params.userAddress
-      });
-      return agents.some((agent) => agent.address.toLowerCase() === params.agentWalletAddress.toLowerCase());
+      const agents = await fetchInfo(
+        {
+          type: "extraAgents",
+          user: params.userAddress
+        },
+        demo
+      );
+      const now = Date.now();
+      return agents.some(
+        (agent) => agent.address.toLowerCase() === params.agentWalletAddress.toLowerCase() && (agent.validUntil === null || agent.validUntil > now)
+      );
     },
-    async checkBuilderFeeApproval(userAddress, builderAddress) {
-      const maxBuilderFee = await fetchInfo({
-        type: "maxBuilderFee",
-        user: userAddress,
-        builder: builderAddress
-      });
-      return Number(maxBuilderFee) > 0;
+    /** Checks that the approval covers the exact builder fee requested by orders. */
+    async checkBuilderFeeApproval(userAddress, builderAddress, requiredFeeTenthsBps) {
+      const requiredFee = requiredFeeTenthsBps ?? 1;
+      if (!Number.isInteger(requiredFee) || requiredFee <= 0) {
+        return false;
+      }
+      const maxBuilderFee = await fetchInfo(
+        {
+          type: "maxBuilderFee",
+          user: userAddress,
+          builder: builderAddress
+        },
+        demo
+      );
+      return Number(maxBuilderFee) >= requiredFee;
     }
   };
 }

package/dist/helper/hyperliquid/helper.test.js

@@ -0,0 +1,45 @@
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+import { createHyperliquidHelper } from './helper';
+
+const { fetchInfoMock } = vi.hoisted(() => ({ fetchInfoMock: vi.fn() }));
+vi.mock("../../client/hyperliquid/rest", () => ({ fetchInfo: fetchInfoMock }));
+const userAddress = "0x1111111111111111111111111111111111111111";
+const agentWalletAddress = "0x2222222222222222222222222222222222222222";
+const builderAddress = "0x3333333333333333333333333333333333333333";
+describe("createHyperliquidHelper", () => {
+  beforeEach(() => {
+    fetchInfoMock.mockReset();
+  });
+  it("accepts unexpired and non-expiring API wallets on the selected network", async () => {
+    fetchInfoMock.mockResolvedValue([
+      { name: "expired", address: agentWalletAddress, validUntil: Date.now() - 1 },
+      { name: "active", address: agentWalletAddress.toUpperCase(), validUntil: null }
+    ]);
+    const valid = await createHyperliquidHelper(true).checkApiWallet({ userAddress, agentWalletAddress });
+    expect(valid).toBe(true);
+    expect(fetchInfoMock).toHaveBeenCalledWith({ type: "extraAgents", user: userAddress }, true);
+  });
+  it("rejects an expired API wallet", async () => {
+    fetchInfoMock.mockResolvedValue([{ name: "expired", address: agentWalletAddress, validUntil: Date.now() - 1 }]);
+    await expect(createHyperliquidHelper().checkApiWallet({ userAddress, agentWalletAddress })).resolves.toBe(false);
+  });
+  it("requires the approval to cover the requested fee rather than merely be positive", async () => {
+    fetchInfoMock.mockResolvedValue(6);
+    const helper = createHyperliquidHelper(true);
+    await expect(helper.checkBuilderFeeApproval(userAddress, builderAddress, 10)).resolves.toBe(false);
+    await expect(helper.checkBuilderFeeApproval(userAddress, builderAddress, 6)).resolves.toBe(true);
+    expect(fetchInfoMock).toHaveBeenCalledWith(
+      { type: "maxBuilderFee", user: userAddress, builder: builderAddress },
+      true
+    );
+  });
+  it("preserves the two-argument helper contract as an any-positive-approval check", async () => {
+    fetchInfoMock.mockResolvedValue(1);
+    const approved = await createHyperliquidHelper().checkBuilderFeeApproval(userAddress, builderAddress);
+    expect(approved).toBe(true);
+    expect(fetchInfoMock).toHaveBeenCalledWith(
+      { type: "maxBuilderFee", user: userAddress, builder: builderAddress },
+      false
+    );
+  });
+});

package/dist/helper/lighter/helper.js

@@ -1,12 +1,46 @@
 import { parseUnits, parseEther } from 'viem';
-import { fetchApiKeys, fetchAccount, fetchAccountsByL1Address } from '../../client/lighter/rest';
+import { fetchApiKeys, fetchAccount, fetchAccountsByL1Address, fetchAssetDetails } from '../../client/lighter/rest';
 import { writeWithdraw, writeDeposit } from './ethereum';
-import { getAssetDecimals } from './types';
+import { AssetId } from './types';
 
-function createLighterHelper(sdk) {
+const MIN_USER_API_KEY_INDEX = 4;
+const MAX_API_KEY_INDEX = 254;
+function findAvailableApiKeyIndex(apiKeys) {
+  const occupied = new Set(apiKeys.map((key) => key.api_key_index));
+  for (let index = MIN_USER_API_KEY_INDEX; index <= MAX_API_KEY_INDEX; index += 1) {
+    if (!occupied.has(index)) return index;
+  }
+  throw new Error(
+    `No available Lighter API key slots: non-reserved indices ${MIN_USER_API_KEY_INDEX}-${MAX_API_KEY_INDEX} are occupied`
+  );
+}
+function validateDecimals(decimals, source) {
+  if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 255) {
+    throw new Error(`Invalid ${source} decimals: ${decimals}`);
+  }
+  return decimals;
+}
+async function resolveAssetDecimals(assetId, field, suppliedDecimals, demo) {
+  if (suppliedDecimals !== void 0) return validateDecimals(suppliedDecimals, field);
+  const assets = await fetchAssetDetails(demo);
+  const asset = assets.find((candidate) => candidate.asset_id === assetId);
+  if (!asset) throw new Error(`Lighter asset ${assetId} was not returned by assetDetails`);
+  return validateDecimals(asset[field], `assetDetails.${field}`);
+}
+function validateApprovalRequirements(requirements) {
+  for (const [name, value] of [
+    ["minPerpsMakerFee", requirements.minPerpsMakerFee],
+    ["minPerpsTakerFee", requirements.minPerpsTakerFee]
+  ]) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(`Invalid Lighter integrator ${name}: ${value}`);
+    }
+  }
+}
+function createLighterHelper(sdk, demo = false) {
   return {
     async lookupAccount(l1Address) {
-      const data = await fetchAccountsByL1Address(l1Address);
+      const data = await fetchAccountsByL1Address(l1Address, demo);
       if (data.code === 21100) {
         throw new Error("Account not registered on Lighter");
       }
@@ -20,16 +54,24 @@ function createLighterHelper(sdk) {
         subAccountIndexes: accounts.filter((s) => s.account_type !== 0).map((s) => s.index)
       };
     },
-    async checkIntegratorApproval(accountIndex, integratorAccountIndex) {
-      const data = await fetchAccount(accountIndex);
+    async checkIntegratorApproval(accountIndex, integratorAccountIndex, requirements) {
+      if (requirements) validateApprovalRequirements(requirements);
+      const data = await fetchAccount(accountIndex, demo);
       const account = data.accounts[0];
       if (!account) return false;
+      const minMakerFee = requirements?.minPerpsMakerFee ?? 0;
+      const minTakerFee = requirements?.minPerpsTakerFee ?? 0;
       const integrators = account.approved_integrators ?? [];
-      return integrators.some((i) => i.account_index === integratorAccountIndex);
+      return integrators.some(
+        (integrator) => integrator.account_index === integratorAccountIndex && integrator.approval_expiry > Date.now() && integrator.max_perps_maker_fee >= minMakerFee && integrator.max_perps_taker_fee >= minTakerFee
+      );
     },
     async connectWallet(walletClient, params) {
-      const apiKeys = await fetchApiKeys(params.accountIndex);
-      const apiKeyIndex = Math.max(4, ...apiKeys.map((k) => k.api_key_index + 1));
+      if (demo) {
+        throw new Error("Lighter demo wallet connection is unavailable because backend signing is mainnet-only");
+      }
+      const apiKeys = await fetchApiKeys(params.accountIndex, demo);
+      const apiKeyIndex = findAvailableApiKeyIndex(apiKeys);
       const { privateKey, messageToSign, txInfo } = await sdk.core.misc.lighter.createApiKey({
         accountIndex: params.accountIndex,
         apiKeyIndex
@@ -47,6 +89,9 @@ function createLighterHelper(sdk) {
       return { txHash, apiKeyIndex, apiPrivateKey: privateKey };
     },
     async approveIntegrator(walletClient, params) {
+      if (demo) {
+        throw new Error("Lighter demo integrator approval is unavailable because backend signing is mainnet-only");
+      }
       const { messageToSign, txInfo } = await sdk.core.misc.lighter.prepareApproveIntegrator({
         accountIndex: params.accountIndex,
         apiKeyIndex: params.apiKeyIndex,
@@ -65,28 +110,44 @@ function createLighterHelper(sdk) {
       return { txHash };
     },
     async deposit(walletClient, params) {
+      if (demo) {
+        throw new Error("Lighter demo deposits are unavailable because the testnet gateway is not verified");
+      }
+      const l1Decimals = await resolveAssetDecimals(params.assetId, "l1_decimals", params.l1Decimals, demo);
+      const amount = parseUnits(params.amount, l1Decimals);
+      let value;
+      if (params.assetId === AssetId.ETH) {
+        value = parseEther(params.nativeValue ?? params.amount);
+        if (value !== amount) {
+          throw new Error("Lighter native ETH deposit amount and msg.value must match");
+        }
+      } else if (params.nativeValue !== void 0 && parseEther(params.nativeValue) !== 0n) {
+        throw new Error("Lighter nativeValue is only valid for ETH deposits");
+      }
       const txHash = await writeDeposit(walletClient, {
         to: params.to,
         assetIndex: params.assetId,
         routeType: params.routeType,
-        // `amount` is a human string in the asset's own units; scale to base units.
-        amount: parseUnits(params.amount, getAssetDecimals(params.assetId)),
-        // Native-ETH deposits are payable; `nativeValue` is the ETH sent as
-        // msg.value (18-decimal wei), separate from the accounting `amount`.
-        value: params.nativeValue ? parseEther(params.nativeValue) : void 0
+        // Ethereum deposits use the L1 token precision, not Lighter's L2/base-amount precision.
+        amount,
+        value
       });
       return { txHash };
     },
     async withdraw(walletClient, params) {
+      if (demo) {
+        throw new Error("Lighter demo withdrawals are unavailable because the testnet gateway is not verified");
+      }
+      const l2Decimals = await resolveAssetDecimals(params.assetId, "decimals", params.l2Decimals, demo);
       const txHash = await writeWithdraw(walletClient, {
         accountIndex: params.accountIndex,
         assetIndex: params.assetId,
         routeType: params.routeType,
-        baseAmount: parseUnits(params.amount, getAssetDecimals(params.assetId))
+        baseAmount: parseUnits(params.amount, l2Decimals)
       });
       return { txHash };
     }
   };
 }
 
-export { createLighterHelper };
+export { MAX_API_KEY_INDEX, MIN_USER_API_KEY_INDEX, createLighterHelper, findAvailableApiKeyIndex };