@pear-protocol/exchanges-sdk 0.2.0 → 0.4.0

package/dist/sdk.js

@@ -1,4 +1,3 @@
-import { createExchangeWs } from './client';
 import './helper';
 import { createExchangeHelper } from './helper/factory';
 import { checkAccountStatus } from './status';
@@ -15,12 +14,7 @@ class ExchangesSDK {
     this.options = config.options;
   }
   async connect(tradeAccountId) {
-    const connection = await this.fetchCredentials(tradeAccountId);
-    const ws = await createExchangeWs(connection.connector, {
-      demo: this.demo,
-      credentials: connection.credentials
-    });
-    return { ...connection, ws };
+    return this.fetchCredentials(tradeAccountId);
   }
   async status(connection) {
     return checkAccountStatus(connection.connector, {
@@ -33,19 +27,22 @@ class ExchangesSDK {
     });
   }
   createTracker(connection) {
-    return createAccountTracker(connection.connector, {
-      demo: this.demo,
-      account: connection.account,
-      credentials: connection.credentials,
-      ws: connection.ws
-    });
+    return this.buildTracker(connection);
+  }
+  async snapshot(tradeAccountId) {
+    const connection = await this.fetchCredentials(tradeAccountId);
+    return this.buildTracker(connection).snapshot();
+  }
+  async snapshotAssets(tradeAccountId, coins) {
+    const connection = await this.fetchCredentials(tradeAccountId);
+    return this.buildTracker(connection).snapshotAssets(coins);
   }
   createHelper(exchange) {
     switch (exchange) {
       case "hyperliquid":
-        return createExchangeHelper({ exchange: "hyperliquid" });
+        return createExchangeHelper({ exchange: "hyperliquid", demo: this.demo });
       case "lighter":
-        return createExchangeHelper({ exchange: "lighter", sdk: this.sdk });
+        return createExchangeHelper({ exchange: "lighter", sdk: this.sdk, demo: this.demo });
     }
   }
   createSyncer(connection) {
@@ -54,10 +51,17 @@ class ExchangesSDK {
       connector: connection.connector,
       account: connection.account,
       credentials: connection.credentials,
-      ws: connection.ws,
       demo: this.demo
     });
   }
+  buildTracker(connection) {
+    return createAccountTracker(connection.connector, {
+      demo: this.demo,
+      account: connection.account,
+      credentials: connection.credentials,
+      sdk: this.sdk
+    });
+  }
   async fetchCredentials(tradeAccountId) {
     return await this.sdk.core.accounts.credentials(tradeAccountId);
   }

package/dist/sdk.test.js

@@ -0,0 +1,101 @@
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+import { ExchangesSDK } from './sdk';
+
+const { checkAccountStatusMock, createAccountSyncerMock, createAccountTrackerMock, createExchangeWsMock } = vi.hoisted(
+  () => ({
+    checkAccountStatusMock: vi.fn(),
+    createAccountSyncerMock: vi.fn(),
+    createAccountTrackerMock: vi.fn(),
+    createExchangeWsMock: vi.fn()
+  })
+);
+vi.mock("./status", () => ({
+  checkAccountStatus: checkAccountStatusMock
+}));
+vi.mock("./syncer", () => ({
+  createAccountSyncer: createAccountSyncerMock
+}));
+vi.mock("./client", () => ({
+  createExchangeWs: createExchangeWsMock
+}));
+vi.mock("./tracker", () => ({
+  createAccountTracker: createAccountTrackerMock
+}));
+const connection = {
+  connector: "okx",
+  account: { id: "account-1" },
+  credentials: { api_key: "k", api_secret: "s", api_pass: "p" }
+};
+function buildSdk(credentials = vi.fn().mockResolvedValue(connection), demo = true) {
+  const sdk = {
+    core: { accounts: { credentials } }
+  };
+  return { exchangesSdk: new ExchangesSDK({ sdk, demo }), credentials, sdk };
+}
+describe("ExchangesSDK.snapshot", () => {
+  beforeEach(() => {
+    checkAccountStatusMock.mockReset().mockResolvedValue({ status: "active", reasons: [] });
+    createAccountSyncerMock.mockReset().mockReturnValue({});
+    createExchangeWsMock.mockReset();
+    createAccountTrackerMock.mockReset();
+  });
+  it("fetches credentials, builds a ws-free tracker, and returns tracker.snapshot() without opening a socket", async () => {
+    const fakeSnapshot = { balance: null, positions: [] };
+    const trackerSnapshot = vi.fn().mockResolvedValue(fakeSnapshot);
+    createAccountTrackerMock.mockReturnValue({ snapshot: trackerSnapshot });
+    const { exchangesSdk, credentials, sdk } = buildSdk();
+    const result = await exchangesSdk.snapshot("trade-account-1");
+    expect(credentials).toHaveBeenCalledWith("trade-account-1");
+    expect(createAccountTrackerMock).toHaveBeenCalledWith(
+      "okx",
+      expect.objectContaining({
+        demo: true,
+        account: connection.account,
+        credentials: connection.credentials,
+        sdk
+      })
+    );
+    expect(trackerSnapshot).toHaveBeenCalledTimes(1);
+    expect(result).toBe(fakeSnapshot);
+    expect(createExchangeWsMock).not.toHaveBeenCalled();
+  });
+  it("snapshotAssets() delegates the coin list to a ws-free tracker", async () => {
+    const fakeAssets = { BTC: { coin: "BTC", leverage: "10", marginType: "cross" } };
+    const trackerSnapshotAssets = vi.fn().mockResolvedValue(fakeAssets);
+    createAccountTrackerMock.mockReturnValue({ snapshotAssets: trackerSnapshotAssets });
+    const { exchangesSdk, credentials } = buildSdk();
+    const result = await exchangesSdk.snapshotAssets("trade-account-1", ["BTC", "ETH"]);
+    expect(credentials).toHaveBeenCalledWith("trade-account-1");
+    expect(trackerSnapshotAssets).toHaveBeenCalledWith(["BTC", "ETH"]);
+    expect(result).toBe(fakeAssets);
+    expect(createExchangeWsMock).not.toHaveBeenCalled();
+  });
+  it("propagates credential fetch failures", async () => {
+    const { exchangesSdk } = buildSdk(vi.fn().mockRejectedValue(new Error("no access")));
+    await expect(exchangesSdk.snapshot("trade-account-1")).rejects.toThrow("no access");
+    expect(createAccountTrackerMock).not.toHaveBeenCalled();
+    expect(createExchangeWsMock).not.toHaveBeenCalled();
+  });
+  it("connect() is credential-only and opens no socket", async () => {
+    const { exchangesSdk } = buildSdk();
+    const result = await exchangesSdk.connect("trade-account-1");
+    expect(result).toEqual(connection);
+    expect(createExchangeWsMock).not.toHaveBeenCalled();
+  });
+});
+describe("ExchangesSDK configured network routing", () => {
+  beforeEach(() => {
+    checkAccountStatusMock.mockReset().mockResolvedValue({ status: "active", reasons: [] });
+    createAccountSyncerMock.mockReset().mockReturnValue({});
+    createAccountTrackerMock.mockReset().mockReturnValue({});
+  });
+  it("uses the SDK demo option for account-bound operations", async () => {
+    const { exchangesSdk } = buildSdk(void 0, true);
+    await exchangesSdk.status(connection);
+    exchangesSdk.createTracker(connection);
+    exchangesSdk.createSyncer(connection);
+    expect(checkAccountStatusMock).toHaveBeenCalledWith("okx", expect.objectContaining({ demo: true }));
+    expect(createAccountTrackerMock).toHaveBeenCalledWith("okx", expect.objectContaining({ demo: true }));
+    expect(createAccountSyncerMock).toHaveBeenCalledWith("okx", expect.objectContaining({ demo: true }));
+  });
+});

package/dist/status/hyperliquid/status.js

@@ -1,20 +1,32 @@
+import { fetchUserAbstraction } from '../../client/hyperliquid/rest';
 import { createExchangeHelper } from '../../helper/factory';
+import { HyperliquidAccountType } from '../../tracker/hyperliquid/types';
 import { warningStatus } from '../base';
 
 async function checkHyperliquidAccountStatus(config) {
   const reasons = [];
   const options = config.statusOptions;
-  if (!options?.builderAddress) {
+  if (!options?.builderAddress || !options.builderFeeTenthsBps) {
     throw new Error("Missing required hyperliquid connect options");
   }
-  const helper = createExchangeHelper({ exchange: "hyperliquid" });
+  const helper = createExchangeHelper({ exchange: "hyperliquid", demo: config.demo });
   const metadata = config.account.metadata;
+  const approvalAddress = metadata && "isSubaccount" in metadata && metadata.isSubaccount ? metadata.mainAccountAddress : config.account.exchangeIdentifier;
+  try {
+    const abstraction = await fetchUserAbstraction(config.account.exchangeIdentifier, config.demo);
+    const supportedAccountMode = abstraction === HyperliquidAccountType.DEFAULT || abstraction === HyperliquidAccountType.DISABLED || abstraction === HyperliquidAccountType.UNIFIED_ACCOUNT;
+    if (!supportedAccountMode) {
+      reasons.push("hyperliquid_account_mode_unsupported");
+    }
+  } catch {
+    reasons.push("hyperliquid_account_mode_check_failed");
+  }
   if (!metadata || !("agentWalletAddress" in metadata)) {
     reasons.push("hyperliquid_api_wallet_invalid");
   } else {
     try {
       const apiWalletValid = await helper.checkApiWallet({
-        userAddress: config.account.exchangeIdentifier,
+        userAddress: approvalAddress,
         agentWalletAddress: metadata.agentWalletAddress
       });
       if (!apiWalletValid) reasons.push("hyperliquid_api_wallet_invalid");
@@ -24,8 +36,9 @@ async function checkHyperliquidAccountStatus(config) {
   }
   try {
     const approved = await helper.checkBuilderFeeApproval(
-      config.account.exchangeIdentifier,
-      options.builderAddress
+      approvalAddress,
+      options.builderAddress,
+      options.builderFeeTenthsBps
     );
     if (!approved) reasons.push("hyperliquid_builder_fee_not_approved");
   } catch {

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

@@ -0,0 +1,81 @@
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+import { checkHyperliquidAccountStatus } from './status';
+
+const { checkApiWalletMock, checkBuilderFeeApprovalMock, fetchUserAbstractionMock } = vi.hoisted(() => ({
+  checkApiWalletMock: vi.fn(),
+  checkBuilderFeeApprovalMock: vi.fn(),
+  fetchUserAbstractionMock: vi.fn()
+}));
+vi.mock("../../helper/factory", () => ({
+  createExchangeHelper: () => ({
+    checkApiWallet: checkApiWalletMock,
+    checkBuilderFeeApproval: checkBuilderFeeApprovalMock
+  })
+}));
+vi.mock("../../client/hyperliquid/rest", () => ({
+  fetchUserAbstraction: fetchUserAbstractionMock
+}));
+const subaccountAddress = "0x1111111111111111111111111111111111111111";
+const mainAccountAddress = "0x2222222222222222222222222222222222222222";
+const agentWalletAddress = "0x3333333333333333333333333333333333333333";
+const builderAddress = "0x4444444444444444444444444444444444444444";
+function statusConfig() {
+  return {
+    sdk: {},
+    connector: "hyperliquid",
+    account: {
+      id: crypto.randomUUID(),
+      alias: "HL",
+      connector: "hyperliquid",
+      exchangeIdentifier: subaccountAddress,
+      metadata: {
+        agentWalletAddress,
+        isSubaccount: true,
+        mainAccountAddress
+      },
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    credentials: { signer_key: "sk" },
+    statusOptions: { builderAddress, builderFeeTenthsBps: 10 },
+    demo: true
+  };
+}
+describe("checkHyperliquidAccountStatus", () => {
+  beforeEach(() => {
+    checkApiWalletMock.mockReset().mockResolvedValue(true);
+    checkBuilderFeeApprovalMock.mockReset().mockResolvedValue(true);
+    fetchUserAbstractionMock.mockReset().mockResolvedValue("disabled");
+  });
+  it("checks subaccount approvals against the main account and mode against the trading account", async () => {
+    const status = await checkHyperliquidAccountStatus(statusConfig());
+    expect(status).toEqual({ status: "active", reasons: [] });
+    expect(fetchUserAbstractionMock).toHaveBeenCalledWith(subaccountAddress, true);
+    expect(checkApiWalletMock).toHaveBeenCalledWith({ userAddress: mainAccountAddress, agentWalletAddress });
+    expect(checkBuilderFeeApprovalMock).toHaveBeenCalledWith(mainAccountAddress, builderAddress, 10);
+  });
+  it.each(["portfolioMargin", "dexAbstraction", "somethingNew"])(
+    "warns when account mode %s cannot be represented safely",
+    async (abstraction) => {
+      fetchUserAbstractionMock.mockResolvedValue(abstraction);
+      const status = await checkHyperliquidAccountStatus(statusConfig());
+      expect(status).toEqual({
+        status: "warning",
+        reasons: ["hyperliquid_account_mode_unsupported"]
+      });
+    }
+  );
+  it("distinguishes an account-mode API failure from an unsupported mode", async () => {
+    fetchUserAbstractionMock.mockRejectedValue(new Error("503"));
+    const status = await checkHyperliquidAccountStatus(statusConfig());
+    expect(status).toEqual({
+      status: "warning",
+      reasons: ["hyperliquid_account_mode_check_failed"]
+    });
+  });
+  it("fails closed when the required builder fee is missing", async () => {
+    const config = statusConfig();
+    config.statusOptions = { builderAddress };
+    await expect(checkHyperliquidAccountStatus(config)).rejects.toThrow("Missing required hyperliquid connect options");
+  });
+});

package/dist/status/lighter/status.js

@@ -5,24 +5,31 @@ import { warningStatus } from '../base';
 async function checkLighterAccountStatus(config) {
   const reasons = [];
   const options = config.statusOptions;
-  if (options?.integratorAccountIndex === void 0) {
+  if (options?.integratorAccountIndex === void 0 || options.integratorMinPerpsMakerFee === void 0 || options.integratorMinPerpsTakerFee === void 0) {
     throw new Error("Missing required lighter connect options");
   }
   const credentials = config.credentials;
   const accountIndex = Number(config.account.exchangeIdentifier);
-  try {
-    const { token } = await config.sdk.core.misc.lighter.createAuthToken({
-      accountIndex,
-      apiKeyIndex: credentials.api_key_index,
-      apiPrivateKey: credentials.api_private_key
-    });
-    await fetchAccountMetadata(accountIndex, token);
-  } catch {
+  if (config.demo) {
     reasons.push("lighter_api_key_invalid");
+  } else {
+    try {
+      const { token } = await config.sdk.core.misc.lighter.createAuthToken({
+        accountIndex,
+        apiKeyIndex: credentials.api_key_index,
+        apiPrivateKey: credentials.api_private_key
+      });
+      await fetchAccountMetadata(accountIndex, token, config.demo);
+    } catch {
+      reasons.push("lighter_api_key_invalid");
+    }
   }
   try {
-    const helper = createExchangeHelper({ exchange: "lighter", sdk: config.sdk });
-    const approved = await helper.checkIntegratorApproval(accountIndex, options.integratorAccountIndex);
+    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");

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

@@ -0,0 +1,75 @@
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+import { checkLighterAccountStatus } from './status';
+
+const { checkIntegratorApprovalMock, createAuthTokenMock, createExchangeHelperMock, fetchAccountMetadataMock } = vi.hoisted(() => ({
+  checkIntegratorApprovalMock: vi.fn(),
+  createAuthTokenMock: vi.fn(),
+  createExchangeHelperMock: vi.fn(),
+  fetchAccountMetadataMock: vi.fn()
+}));
+vi.mock("../../client/lighter/rest", () => ({ fetchAccountMetadata: fetchAccountMetadataMock }));
+vi.mock("../../helper/factory", () => ({ createExchangeHelper: createExchangeHelperMock }));
+function config() {
+  return {
+    sdk: {
+      core: {
+        misc: {
+          lighter: {
+            createAuthToken: createAuthTokenMock
+          }
+        }
+      }
+    },
+    connector: "lighter",
+    account: { exchangeIdentifier: "42" },
+    credentials: { api_key_index: 4, api_private_key: "private" },
+    statusOptions: {
+      integratorAccountIndex: 77,
+      integratorMinPerpsMakerFee: 500,
+      integratorMinPerpsTakerFee: 600
+    },
+    demo: true
+  };
+}
+describe("checkLighterAccountStatus", () => {
+  beforeEach(() => {
+    createAuthTokenMock.mockReset().mockResolvedValue({ token: "token" });
+    fetchAccountMetadataMock.mockReset().mockResolvedValue(void 0);
+    checkIntegratorApprovalMock.mockReset().mockResolvedValue(true);
+    createExchangeHelperMock.mockReset().mockReturnValue({
+      checkIntegratorApproval: checkIntegratorApprovalMock
+    });
+  });
+  it("fails demo auth closed without minting a mainnet token and still checks testnet approval", async () => {
+    await expect(checkLighterAccountStatus(config())).resolves.toEqual({
+      status: "warning",
+      reasons: ["lighter_api_key_invalid"]
+    });
+    expect(createAuthTokenMock).not.toHaveBeenCalled();
+    expect(fetchAccountMetadataMock).not.toHaveBeenCalled();
+    expect(createExchangeHelperMock).toHaveBeenCalledWith(expect.objectContaining({ demo: true }));
+    expect(checkIntegratorApprovalMock).toHaveBeenCalledWith(42, 77, {
+      minPerpsMakerFee: 500,
+      minPerpsTakerFee: 600
+    });
+  });
+  it("authenticates mainnet status without unsupported payload fields", async () => {
+    const mainnetConfig = config();
+    mainnetConfig.demo = false;
+    await expect(checkLighterAccountStatus(mainnetConfig)).resolves.toEqual({ status: "active", reasons: [] });
+    expect(createAuthTokenMock).toHaveBeenCalledWith({
+      accountIndex: 42,
+      apiKeyIndex: 4,
+      apiPrivateKey: "private"
+    });
+    expect(fetchAccountMetadataMock).toHaveBeenCalledWith(42, "token", false);
+  });
+  it("fails closed when required approval thresholds are absent", async () => {
+    const missingThresholds = config();
+    missingThresholds.statusOptions = { integratorAccountIndex: 77 };
+    await expect(checkLighterAccountStatus(missingThresholds)).rejects.toThrow(
+      "Missing required lighter connect options"
+    );
+    expect(fetchAccountMetadataMock).not.toHaveBeenCalled();
+  });
+});

package/dist/syncer/base.js

@@ -1,60 +1,142 @@
-import { computeSyncPayload } from '@pear-protocol/utils';
+import { computeEntryPriceForAsset, computeSyncPayload } from '@pear-protocol/utils';
 
+const OVERLAP_MS = 6e4;
 class BaseAccountSyncer {
   sdk;
   connector;
   account;
   credentials;
-  ws;
   demo;
   constructor(config) {
     this.sdk = config.sdk;
     this.connector = config.connector;
     this.account = config.account;
     this.credentials = config.credentials;
-    this.ws = config.ws;
     this.demo = config.demo;
   }
-  async synchronize() {
-    const [{ positions }, { fills: provisionalFills }] = await Promise.all([
+  // Phase A: Load current Pear state (positions, fills, instruments, watermark).
+  async loadPearState() {
+    const [{ positions: openPositions }, { fills: provisionalFills }, { instruments }, watermark] = await Promise.all([
       this.sdk.core.positions.openLite(),
-      this.sdk.core.fills.provisionals()
-    ]);
-    if (!positions.length && !provisionalFills.length) {
-      return;
-    }
-    const [{ instruments }, since] = await Promise.all([
+      this.sdk.core.fills.provisionals(),
       this.sdk.core.instruments.list({ connector: this.connector }),
-      this.sdk.core.sync.since({
-        overlapMs: 6e4,
-        nowMs: Date.now(),
-        bootstrapLookbackMs: 30 * 24 * 60 * 60 * 1e3
-      })
+      this.sdk.core.sync.fills.since({ overlapMs: OVERLAP_MS })
     ]);
+    const entryBySymbol = await this.loadEntryBySymbol(openPositions);
+    return { openPositions, entryBySymbol, provisionalFills, instruments, watermark };
+  }
+  /**
+   * Global per-symbol cost-basis entry of existing open positions, derived by pulling each
+   * position's fills and folding them (mirrors example-ui). One call per open position today —
+   * can collapse to a single endpoint later.
+   */
+  async loadEntryBySymbol(openPositions) {
+    const responses = await Promise.all(openPositions.map((position) => this.sdk.core.fills.details(position.id)));
+    const fills = responses.flatMap((response) => response.fills).sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const fillsBySymbol = /* @__PURE__ */ new Map();
+    for (const fill of fills) {
+      const list = fillsBySymbol.get(fill.symbol) ?? [];
+      list.push(fill);
+      fillsBySymbol.set(fill.symbol, list);
+    }
+    const entryBySymbol = {};
+    for (const [symbol, symbolFills] of fillsBySymbol) {
+      const entry = computeEntryPriceForAsset(symbolFills);
+      if (!entry.isZero()) entryBySymbol[symbol] = entry.toFixed();
+    }
+    return entryBySymbol;
+  }
+  // Phase B: Snapshot the exchange — fetch positions and fills since the watermark.
+  async snapshotExchange(state) {
+    const { openPositions, provisionalFills, instruments, watermark } = state;
     const externalFills = await this.listExternalFills({
-      since: new Date(since.since),
+      since: new Date(watermark.sinceMs),
       instruments,
-      openPositions: positions,
+      openPositions,
       provisionalFills
     });
+    const exchangePositions = await this.listExternalPositions({ instruments });
+    return { exchangePositions, externalFills };
+  }
+  // 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 payload = await computeSyncPayload({
-      openPositions: positions,
+      tradeAccountId: this.account.id,
+      connector: this.connector,
+      openPositions,
+      entryBySymbol,
       provisionalFills,
-      confirmedExchangeFillIds: since.confirmedExchangeFillIds ?? [],
-      externalFills
+      confirmedExchangeFillIds: watermark.confirmedExchangeFillIds ?? [],
+      externalFills,
+      exchangePositions,
+      neverSynced: watermark.neverSynced
     });
     if (!payload) {
       return;
     }
     if (payload.reconcilables) {
-      await this.sdk.core.sync.reconcile(payload.reconcilables);
+      await this.sdk.core.sync.fills.reconcile(payload.reconcilables);
     }
     if (payload.confirmables) {
-      await this.sdk.core.sync.confirm(payload.confirmables);
+      await this.sdk.core.sync.fills.confirm(payload.confirmables);
+    }
+    const { firstSyncTrim } = payload;
+    let meta = payload.meta;
+    if (firstSyncTrim) {
+      console.log(
+        `${this.connector}: first-sync trim \u2014 dropped ${firstSyncTrim.trimmedCount} pre-cutoff fills (cutoffTs=${firstSyncTrim.cutoffTs})`
+      );
+      if (meta.externalMaxTs !== null && firstSyncTrim.trimmedMaxTs >= meta.externalMaxTs - OVERLAP_MS) {
+        meta = { ...meta, externalMaxTs: meta.externalMaxTs + OVERLAP_MS + 1 };
+      }
+    }
+    const createBody = {
+      applicables: payload.applicables,
+      exchangePositions: payload.exchangePositions,
+      meta
+    };
+    const bytes = new Blob([JSON.stringify(createBody)]).size;
+    if (bytes > 50 * 1024) {
+      await this.sdk.core.sync.fills.createBulk(createBody);
+      return;
+    }
+    await this.sdk.core.sync.fills.create(createBody);
+  }
+  /**
+   * Pull historical funding payments since the funding watermark and post them.
+   * Independent of the fill sync cycle (`synchronizeFills`) — funding rows are
+   * immutable and upsert idempotently, so this is driven on its own cadence.
+   */
+  async synchronizeFunding() {
+    const [{ instruments }, watermark] = await Promise.all([
+      this.sdk.core.instruments.list({ connector: this.connector }),
+      this.sdk.core.sync.funding.since({ overlapMs: 6e4 })
+    ]);
+    const payments = await this.listExternalFunding({ since: new Date(watermark.sinceMs), instruments });
+    if (payments.length === 0) {
+      return;
+    }
+    const externalMaxTs = Math.max(...payments.map((payment) => payment.timestamp));
+    const createBody = { payments, meta: { externalMaxTs } };
+    const bytes = new Blob([JSON.stringify(createBody)]).size;
+    if (bytes > 50 * 1024) {
+      await this.sdk.core.sync.funding.createBulk(createBody);
+      return;
     }
-    if (payload.creatables) {
-      await this.sdk.core.sync.create(payload.creatables);
+    await this.sdk.core.sync.funding.create(createBody);
+  }
+  async synchronizeFills() {
+    const state = await this.loadPearState();
+    let snapshot;
+    try {
+      snapshot = await this.snapshotExchange(state);
+    } catch (error) {
+      console.error(`${this.connector}: position/fill fetch failed \u2014 sync cycle aborted, retry next tick`, error);
+      return;
     }
+    await this.computeAndPostSync(state, snapshot);
   }
 }