@pear-protocol/exchanges-sdk 0.5.2 → 0.6.1

package/dist/client/hyperliquid/rest.js

@@ -25,6 +25,9 @@ async function fetchClearinghouseState(user, dex, demo = false) {
 async function fetchUserAbstraction(user, demo = false) {
   return fetchInfo({ type: "userAbstraction", user }, demo);
 }
+async function fetchUserRole(user, demo = false) {
+  return fetchInfo({ type: "userRole", user }, demo);
+}
 async function fetchSpotClearinghouseState(user, demo = false) {
   return fetchInfo({ type: "spotClearinghouseState", user }, demo);
 }
@@ -32,4 +35,4 @@ async function fetchActiveAssetData(user, coin, demo = false) {
   return fetchInfo({ type: "activeAssetData", user, coin }, demo);
 }
 
-export { fetchActiveAssetData, fetchClearinghouseState, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction };
+export { fetchActiveAssetData, fetchClearinghouseState, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole };

package/dist/helper/hyperliquid/helper.js

@@ -1,7 +1,17 @@
-import { fetchInfo } from '../../client/hyperliquid/rest';
+import { fetchInfo, fetchUserRole } from '../../client/hyperliquid/rest';
 
 function createHyperliquidHelper(demo = false) {
   return {
+    /**
+     * Checks that the address holds a Hyperliquid account, which the exchange only creates on the
+     * first deposit. This is account existence alone — builder-fee approval, Pear trade-account
+     * setup, and agent approval stay separate gates. A failed request throws rather than reporting
+     * an inactive account, so callers never mistake an outage for a user who has to deposit.
+     */
+    async checkAccountActivation(userAddress) {
+      const role = await fetchUserRole(userAddress, demo);
+      return role.role !== "missing";
+    },
     /** Checks that the requested API wallet exists and has not expired. */
     async checkApiWallet(params) {
       const agents = await fetchInfo(

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

@@ -1,14 +1,41 @@
 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 { fetchInfoMock, fetchUserRoleMock } = vi.hoisted(() => ({
+  fetchInfoMock: vi.fn(),
+  fetchUserRoleMock: vi.fn()
+}));
+vi.mock("../../client/hyperliquid/rest", () => ({ fetchInfo: fetchInfoMock, fetchUserRole: fetchUserRoleMock }));
 const userAddress = "0x1111111111111111111111111111111111111111";
 const agentWalletAddress = "0x2222222222222222222222222222222222222222";
 const builderAddress = "0x3333333333333333333333333333333333333333";
+const masterAddress = "0x4444444444444444444444444444444444444444";
 describe("createHyperliquidHelper", () => {
   beforeEach(() => {
     fetchInfoMock.mockReset();
+    fetchUserRoleMock.mockReset();
+  });
+  it("reports an address Hyperliquid does not know as not activated", async () => {
+    fetchUserRoleMock.mockResolvedValue({ role: "missing" });
+    const activated = await createHyperliquidHelper(true).checkAccountActivation(userAddress);
+    expect(activated).toBe(false);
+    expect(fetchUserRoleMock).toHaveBeenCalledWith(userAddress, true);
+  });
+  it.each([
+    ["user", { role: "user" }],
+    ["agent", { role: "agent", data: { user: masterAddress } }],
+    ["vault", { role: "vault" }],
+    ["subAccount", { role: "subAccount", data: { master: masterAddress } }]
+  ])("reports the %s role as activated", async (_role, response) => {
+    fetchUserRoleMock.mockResolvedValue(response);
+    await expect(createHyperliquidHelper().checkAccountActivation(userAddress)).resolves.toBe(true);
+    expect(fetchUserRoleMock).toHaveBeenCalledWith(userAddress, false);
+  });
+  it("surfaces a failed role request as an error instead of an inactive account", async () => {
+    fetchUserRoleMock.mockRejectedValue(new Error("Hyperliquid info request failed: 429"));
+    await expect(createHyperliquidHelper().checkAccountActivation(userAddress)).rejects.toThrow(
+      "Hyperliquid info request failed: 429"
+    );
   });
   it("accepts unexpired and non-expiring API wallets on the selected network", async () => {
     fetchInfoMock.mockResolvedValue([

package/dist/index.d.ts

@@ -8,7 +8,6 @@ type SupportedCredentials = HttpTypes.ExchangeCredentialsResponse['credentials']
 type ExchangesSDKConfig = {
     sdk: PearSDK;
     demo?: boolean;
-    options?: ConnectOptions;
     /**
      * 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
@@ -212,6 +211,7 @@ type CreateExchangeWsConfig = {
 declare function createExchangeWs<E extends Connector>(exchange: E, config: CreateExchangeWsConfig): Promise<ExchangeWsByConnector[E]>;
 
 interface HyperliquidHelper {
+    checkAccountActivation(userAddress: `0x${string}`): Promise<boolean>;
     checkApiWallet(params: CheckApiWalletParams): Promise<boolean>;
     checkBuilderFeeApproval(userAddress: `0x${string}`, builderAddress: `0x${string}`, requiredFeeTenthsBps?: number): Promise<boolean>;
 }
@@ -368,16 +368,16 @@ interface AccountSyncer {
 }
 interface ListExternalFillsParams {
     since: Date;
-    instruments: HttpTypes.Instrument[];
+    instruments: HttpTypes.InstrumentLite[];
     openPositions: HttpTypes.OpenPositionLite[];
     provisionalFills: HttpTypes.ProvisionalFill[];
 }
 interface ListExternalPositionsParams {
-    instruments: HttpTypes.Instrument[];
+    instruments: HttpTypes.InstrumentLite[];
 }
 interface ListExternalFundingParams {
     since: Date;
-    instruments: HttpTypes.Instrument[];
+    instruments: HttpTypes.InstrumentLite[];
 }
 declare abstract class BaseAccountSyncer<ExternalFill> implements AccountSyncer {
     protected sdk: PearSDK;
@@ -1007,10 +1007,14 @@ declare function createAccountTracker(exchange: Connector, config: CreateAccount
 declare class ExchangesSDK {
     private sdk;
     private demo;
-    private options?;
     constructor(config: ExchangesSDKConfig);
     connect(tradeAccountId: string): Promise<ExchangeConnection>;
-    status(connection: ExchangeConnection): Promise<AccountStatus>;
+    /**
+     * Options come in per call rather than at construction: the approval targets live in the
+     * backend's fee-recipient source and can change, so the caller fetches (and caches) them and
+     * passes the current values with every check.
+     */
+    status(connection: ExchangeConnection, options?: ConnectOptions): Promise<AccountStatus>;
     createTracker(connection: ExchangeConnection): AccountTracker;
     snapshot(tradeAccountId: string): Promise<AccountSnapshot>;
     snapshotAssets(tradeAccountId: string, coins: string[]): Promise<AssetSnapshotMap>;

package/dist/sdk.js

@@ -8,23 +8,26 @@ import { createAccountTracker } from './tracker';
 class ExchangesSDK {
   sdk;
   demo;
-  options;
   constructor(config) {
     this.sdk = config.sdk;
     this.demo = config.demo ?? false;
-    this.options = config.options;
     if (config.proxy) configureProxy(config.proxy);
   }
   async connect(tradeAccountId) {
     return this.fetchCredentials(tradeAccountId);
   }
-  async status(connection) {
+  /**
+   * Options come in per call rather than at construction: the approval targets live in the
+   * backend's fee-recipient source and can change, so the caller fetches (and caches) them and
+   * passes the current values with every check.
+   */
+  async status(connection, options) {
     return checkAccountStatus(connection.connector, {
       sdk: this.sdk,
       connector: connection.connector,
       account: connection.account,
       credentials: connection.credentials,
-      statusOptions: this.options,
+      statusOptions: options,
       demo: this.demo
     });
   }

package/dist/sdk.test.js

@@ -99,3 +99,19 @@ describe("ExchangesSDK configured network routing", () => {
     expect(createAccountSyncerMock).toHaveBeenCalledWith("okx", expect.objectContaining({ demo: true }));
   });
 });
+describe("ExchangesSDK status options", () => {
+  beforeEach(() => {
+    checkAccountStatusMock.mockReset().mockResolvedValue({ status: "active", reasons: [] });
+  });
+  it("passes per-call options through to the status check unchanged", async () => {
+    const options = { builderAddress: "0xabc", builderFeeTenthsBps: 60 };
+    const { exchangesSdk } = buildSdk();
+    await exchangesSdk.status(connection, options);
+    expect(checkAccountStatusMock).toHaveBeenCalledWith("okx", expect.objectContaining({ statusOptions: options }));
+  });
+  it("leaves the options absent when the caller passes none", async () => {
+    const { exchangesSdk } = buildSdk();
+    await exchangesSdk.status(connection);
+    expect(checkAccountStatusMock).toHaveBeenCalledWith("okx", expect.objectContaining({ statusOptions: void 0 }));
+  });
+});

package/dist/status/hyperliquid/status.js

@@ -6,7 +6,8 @@ import { warningStatus } from '../base';
 async function checkHyperliquidAccountStatus(config) {
   const reasons = [];
   const options = config.statusOptions;
-  if (!options?.builderAddress || !options.builderFeeTenthsBps) {
+  const builderAddress = options?.builderAddress;
+  if (builderAddress && !options?.builderFeeTenthsBps) {
     throw new Error("Missing required hyperliquid connect options");
   }
   const helper = createExchangeHelper({ exchange: "hyperliquid", demo: config.demo });
@@ -34,15 +35,17 @@ async function checkHyperliquidAccountStatus(config) {
       reasons.push("hyperliquid_api_wallet_invalid");
     }
   }
-  try {
-    const approved = await helper.checkBuilderFeeApproval(
-      approvalAddress,
-      options.builderAddress,
-      options.builderFeeTenthsBps
-    );
-    if (!approved) reasons.push("hyperliquid_builder_fee_not_approved");
-  } catch {
-    reasons.push("hyperliquid_builder_fee_not_approved");
+  if (builderAddress) {
+    try {
+      const approved = await helper.checkBuilderFeeApproval(
+        approvalAddress,
+        builderAddress,
+        options?.builderFeeTenthsBps
+      );
+      if (!approved) reasons.push("hyperliquid_builder_fee_not_approved");
+    } catch {
+      reasons.push("hyperliquid_builder_fee_not_approved");
+    }
   }
   return warningStatus(reasons);
 }

package/dist/status/hyperliquid/status.test.js

@@ -83,4 +83,12 @@ describe("checkHyperliquidAccountStatus", () => {
     config.statusOptions = { builderAddress };
     await expect(checkHyperliquidAccountStatus(config)).rejects.toThrow("Missing required hyperliquid connect options");
   });
+  it("skips the builder-fee check when no builder address is configured, keeping the other checks", async () => {
+    const config = statusConfig();
+    config.statusOptions = { builderFeeTenthsBps: 10 };
+    const status = await checkHyperliquidAccountStatus(config);
+    expect(status).toEqual({ status: "active", reasons: [] });
+    expect(checkBuilderFeeApprovalMock).not.toHaveBeenCalled();
+    expect(checkApiWalletMock).toHaveBeenCalled();
+  });
 });

package/dist/status/lighter/status.js

@@ -5,7 +5,10 @@ import { warningStatus } from '../base';
 async function checkLighterAccountStatus(config) {
   const reasons = [];
   const options = config.statusOptions;
-  if (options?.integratorAccountIndex === void 0 || options.integratorMinPerpsMakerFee === void 0 || options.integratorMinPerpsTakerFee === void 0) {
+  const integratorAccountIndex = options?.integratorAccountIndex;
+  const integratorMinPerpsMakerFee = options?.integratorMinPerpsMakerFee;
+  const integratorMinPerpsTakerFee = options?.integratorMinPerpsTakerFee;
+  if (integratorAccountIndex !== void 0 && (integratorMinPerpsMakerFee === void 0 || integratorMinPerpsTakerFee === void 0)) {
     throw new Error("Missing required lighter connect options");
   }
   const credentials = config.credentials;
@@ -24,15 +27,17 @@ async function checkLighterAccountStatus(config) {
       reasons.push("lighter_api_key_invalid");
     }
   }
-  try {
-    const helper = createExchangeHelper({ exchange: "lighter", sdk: config.sdk, demo: config.demo });
-    const approved = await helper.checkIntegratorApproval(accountIndex, options.integratorAccountIndex, {
-      minPerpsMakerFee: options.integratorMinPerpsMakerFee,
-      minPerpsTakerFee: options.integratorMinPerpsTakerFee
-    });
-    if (!approved) reasons.push("lighter_integrator_not_approved");
-  } catch {
-    reasons.push("lighter_integrator_not_approved");
+  if (integratorAccountIndex !== void 0 && integratorMinPerpsMakerFee !== void 0 && integratorMinPerpsTakerFee !== void 0) {
+    try {
+      const helper = createExchangeHelper({ exchange: "lighter", sdk: config.sdk, demo: config.demo });
+      const approved = await helper.checkIntegratorApproval(accountIndex, integratorAccountIndex, {
+        minPerpsMakerFee: integratorMinPerpsMakerFee,
+        minPerpsTakerFee: integratorMinPerpsTakerFee
+      });
+      if (!approved) reasons.push("lighter_integrator_not_approved");
+    } catch {
+      reasons.push("lighter_integrator_not_approved");
+    }
   }
   return warningStatus(reasons);
 }

package/dist/status/lighter/status.test.js

@@ -72,4 +72,15 @@ describe("checkLighterAccountStatus", () => {
     );
     expect(fetchAccountMetadataMock).not.toHaveBeenCalled();
   });
+  it("skips the integrator check when no integrator is configured, keeping the api-key check", async () => {
+    const noIntegrator = config();
+    noIntegrator.demo = false;
+    noIntegrator.statusOptions = {
+      integratorMinPerpsMakerFee: 500,
+      integratorMinPerpsTakerFee: 600
+    };
+    await expect(checkLighterAccountStatus(noIntegrator)).resolves.toEqual({ status: "active", reasons: [] });
+    expect(checkIntegratorApprovalMock).not.toHaveBeenCalled();
+    expect(fetchAccountMetadataMock).toHaveBeenCalled();
+  });
 });

package/dist/syncer/base.js

@@ -19,7 +19,7 @@ class BaseAccountSyncer {
     const [{ positions: openPositions }, { fills: provisionalFills }, { instruments }, watermark] = await Promise.all([
       this.sdk.core.positions.openLite(),
       this.sdk.core.fills.provisionals(),
-      this.sdk.core.instruments.list({ connector: this.connector }),
+      this.sdk.core.instruments.lite({ connector: this.connector }),
       this.sdk.core.sync.fills.since({ overlapMs: OVERLAP_MS })
     ]);
     const entryBySymbol = await this.loadEntryBySymbol(openPositions);
@@ -49,6 +49,7 @@ class BaseAccountSyncer {
   // Phase B: Snapshot the exchange — fetch positions and fills since the watermark.
   async snapshotExchange(state) {
     const { openPositions, provisionalFills, instruments, watermark } = state;
+    const { firstSyncStartedAt } = watermark;
     const externalFills = await this.listExternalFills({
       since: new Date(watermark.sinceMs),
       instruments,
@@ -56,12 +57,16 @@ class BaseAccountSyncer {
       provisionalFills
     });
     const exchangePositions = await this.listExternalPositions({ instruments });
-    return { exchangePositions, externalFills };
+    return {
+      exchangePositions,
+      externalFills,
+      firstSyncStartedAt
+    };
   }
   // Phase C: Compute the sync payload and post it across the three sync endpoints.
   async computeAndPostSync(state, snapshot) {
     const { openPositions, entryBySymbol, provisionalFills, watermark } = state;
-    const { exchangePositions, externalFills } = snapshot;
+    const { exchangePositions, externalFills, firstSyncStartedAt } = snapshot;
     const payload = await computeSyncPayload({
       tradeAccountId: this.account.id,
       connector: this.connector,
@@ -83,7 +88,10 @@ class BaseAccountSyncer {
       await this.sdk.core.sync.fills.confirm(payload.confirmables);
     }
     const { firstSyncTrim } = payload;
-    let meta = payload.meta;
+    let meta = {
+      ...payload.meta,
+      ...firstSyncStartedAt === void 0 ? {} : { firstSyncStartedAt }
+    };
     if (firstSyncTrim) {
       console.log(
         `${this.connector}: first-sync trim \u2014 dropped ${firstSyncTrim.trimmedCount} pre-cutoff fills (cutoffTs=${firstSyncTrim.cutoffTs})`
@@ -111,7 +119,7 @@ class BaseAccountSyncer {
    */
   async synchronizeFunding() {
     const [{ instruments }, watermark] = await Promise.all([
-      this.sdk.core.instruments.list({ connector: this.connector }),
+      this.sdk.core.instruments.lite({ connector: this.connector }),
       this.sdk.core.sync.funding.since({ overlapMs: 6e4 })
     ]);
     const payments = await this.listExternalFunding({ since: new Date(watermark.sinceMs), instruments });

package/dist/syncer/base.test.js

@@ -39,7 +39,12 @@ class FakeSyncer extends BaseAccountSyncer {
 }
 function makeSyncer(args) {
   const fills = {
-    since: vi.fn().mockResolvedValue({ sinceMs: 0, neverSynced: args.neverSynced, confirmedExchangeFillIds: [] }),
+    since: vi.fn().mockResolvedValue({
+      sinceMs: 0,
+      neverSynced: args.neverSynced,
+      firstSyncStartedAt: args.neverSynced ? FIRST_SYNC_STARTED_AT : void 0,
+      confirmedExchangeFillIds: []
+    }),
     reconcile: vi.fn().mockResolvedValue({}),
     confirm: vi.fn().mockResolvedValue({}),
     create: vi.fn().mockResolvedValue({}),
@@ -50,7 +55,7 @@ function makeSyncer(args) {
     core: {
       positions: { openLite: vi.fn().mockResolvedValue({ positions: [] }) },
       fills: { provisionals: vi.fn().mockResolvedValue({ fills: [] }), details: vi.fn() },
-      instruments: { list: vi.fn().mockResolvedValue({ instruments: [] }) },
+      instruments: { lite: vi.fn().mockResolvedValue({ instruments: [] }) },
       sync
     }
   };
@@ -64,6 +69,7 @@ function makeSyncer(args) {
   return { syncer: new FakeSyncer(config), sync };
 }
 const NEWEST_TS = 105e4;
+const FIRST_SYNC_STARTED_AT = 1e6;
 function trimmableFills(btcEraTs) {
   return [
     extFill({ exchangeFillId: "a", symbol: "BTC", side: "BUY", quantity: "1", timestamp: btcEraTs.open }),
@@ -90,6 +96,17 @@ describe("BaseAccountSyncer \u2014 first-sync plumbing", () => {
     expect(sync.fills.create).toHaveBeenCalledTimes(1);
     expect(sync.fills.create.mock.calls[0]?.[0]?.exchangePositions).toBe(SOL_SNAPSHOT);
   });
+  it("captures an empty first-sync checkpoint before fetching fills", async () => {
+    const { syncer, sync } = makeSyncer({ neverSynced: true });
+    syncer.positionsFn.mockResolvedValue([]);
+    syncer.fillsFn.mockResolvedValue([]);
+    await syncer.synchronizeFills();
+    expect(sync.fills.since.mock.invocationCallOrder[0]).toBeLessThan(syncer.fillsFn.mock.invocationCallOrder[0] ?? 0);
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta).toEqual({
+      externalMaxTs: null,
+      firstSyncStartedAt: FIRST_SYNC_STARTED_AT
+    });
+  });
   it("bumps the posted watermark past the overlap window when trimmed fills fall inside it", async () => {
     const { syncer, sync } = makeSyncer({ neverSynced: true });
     syncer.positionsFn.mockResolvedValue(SOL_SNAPSHOT);
@@ -125,7 +142,7 @@ describe("BaseAccountSyncer \u2014 first-sync plumbing", () => {
     ]);
     await syncer.synchronizeFills();
     expect(syncer.positionsFn).toHaveBeenCalledTimes(1);
-    expect(sync.fills.create.mock.calls[0]?.[0]?.meta.externalMaxTs).toBe(NEWEST_TS);
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta).toEqual({ externalMaxTs: NEWEST_TS });
     expect(logSpy).not.toHaveBeenCalled();
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -27,9 +27,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@pear-protocol/core-sdk": "^1.11.1",
-    "@pear-protocol/types": "^1.14.1",
-    "@pear-protocol/utils": "^0.3.0",
+    "@pear-protocol/core-sdk": "^1.12.0",
+    "@pear-protocol/types": "^1.15.1",
+    "@pear-protocol/utils": "^0.4.1",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8"