@pear-protocol/exchanges-sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -311,7 +311,8 @@ interface AccountSyncerConfig {
     demo: boolean;
 }
 interface AccountSyncer {
-    synchronize(): Promise<void>;
+    synchronizeFills(): Promise<void>;
+    synchronizeFunding(): Promise<void>;
 }
 interface ListExternalFillsParams {
     since: Date;
@@ -319,6 +320,13 @@ interface ListExternalFillsParams {
     openPositions: HttpTypes.OpenPositionLite[];
     provisionalFills: HttpTypes.ProvisionalFill[];
 }
+interface ListExternalPositionsParams {
+    instruments: HttpTypes.Instrument[];
+}
+interface ListExternalFundingParams {
+    since: Date;
+    instruments: HttpTypes.Instrument[];
+}
 declare abstract class BaseAccountSyncer<ExternalFill> implements AccountSyncer {
     protected sdk: PearSDK;
     protected connector: Connector;
@@ -327,9 +335,36 @@ declare abstract class BaseAccountSyncer<ExternalFill> implements AccountSyncer
     protected ws: ExchangeWsByConnector[Connector];
     protected demo: boolean;
     constructor(config: AccountSyncerConfig);
+    /**
+     * Fetch the account's currently-open positions from the exchange, normalized
+     * to BASE units (contractSize applied). The exchange position API is the
+     * source of truth for current exposure. Account-wide; no symbol scoping.
+     * Hedge-mode (LONG/SHORT legs on one symbol) is rejected — skipped this cycle.
+     */
+    protected abstract listExternalPositions(params: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected abstract listExternalFills(params: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
+    /**
+     * Fetch the account's historical funding payments since the watermark,
+     * applied-rate-only and mapped to instrument ids. Account-wide, no symbol scoping.
+     */
+    protected abstract listExternalFunding(params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
     protected abstract isReduceOnly(fill: ExternalFill): boolean;
-    synchronize(): Promise<void>;
+    private loadPearState;
+    /**
+     * 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.
+     */
+    private loadEntryBySymbol;
+    private snapshotExchange;
+    private computeAndPostSync;
+    /**
+     * 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.
+     */
+    synchronizeFunding(): Promise<void>;
+    synchronizeFills(): Promise<void>;
 }
 
 interface BinanceRawUserTrade {
@@ -352,8 +387,10 @@ interface BinanceRawUserTrade {
 declare class BinanceAccountSyncer extends BaseAccountSyncer<BinanceRawUserTrade> {
     private readonly creds;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, openPositions, provisionalFills, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(trade: BinanceRawUserTrade): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: BinanceRawUserTrade): boolean;
     private collectRequestedInstrumentIds;
     private mapOrdersBySymbolOrderId;
     private orderKey;
@@ -376,8 +413,10 @@ interface BybitRawExecution {
 declare class BybitAccountSyncer extends BaseAccountSyncer<BybitRawExecution> {
     private readonly creds;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(execution: BybitRawExecution): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: BybitRawExecution): boolean;
 }
 
 declare function createAccountSyncer(exchange: Connector, config: AccountSyncerConfig): AccountSyncer;
@@ -458,20 +497,26 @@ type UserFillsByTimeResponse = {
     };
 };
 
-declare class HyperliquidAccountSyncer extends BaseAccountSyncer<UserFillsByTimeResponse> {
+type HyperliquidRawFill = UserFillsByTimeResponse;
+declare class HyperliquidAccountSyncer extends BaseAccountSyncer<HyperliquidRawFill> {
     private readonly address;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(fill: UserFillsByTimeResponse): boolean;
+    protected listExternalFunding({ since, instruments, }: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: HyperliquidRawFill): boolean;
 }
 
-declare class LighterAccountSyncer extends BaseAccountSyncer<LighterRawTrade> {
+type RawFill$1 = LighterRawTrade;
+declare class LighterAccountSyncer extends BaseAccountSyncer<RawFill$1> {
     private readonly accountIndex;
     private readonly apiKeyIndex;
     private readonly apiPrivateKey;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(trade: LighterRawTrade): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: RawFill$1): boolean;
     private getAccountSide;
     private getClientOrderId;
     private isMaker;
@@ -499,11 +544,14 @@ interface OkxRawFill {
     ts: string;
 }
 
-declare class OkxAccountSyncer extends BaseAccountSyncer<OkxRawFill> {
+type RawFill = OkxRawFill;
+declare class OkxAccountSyncer extends BaseAccountSyncer<RawFill> {
     private readonly creds;
     constructor(config: AccountSyncerConfig);
+    protected listExternalPositions({ instruments, }: ListExternalPositionsParams): Promise<HttpTypes.ExternalPosition[]>;
     protected listExternalFills({ since, instruments, }: ListExternalFillsParams): Promise<HttpTypes.UnknownExternalFill[]>;
-    protected isReduceOnly(fill: OkxRawFill): boolean;
+    protected listExternalFunding(_params: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
+    protected isReduceOnly(rawFill: RawFill): boolean;
     private contractsToBase;
 }
 
@@ -822,4 +870,4 @@ declare class ExchangesSDK {
     private fetchCredentials;
 }
 
-export { ACCOUNT_TYPE_LABELS, ASSET_DECIMALS, type AccountBalance, type AccountHealthStatus, type AccountPosition, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTracker, type AccountTrackerConfig, type AccountType, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, type AssetBalance, AssetId, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceAccountType, BinanceExchangeWs, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitAccountType, BybitExchangeWs, BybitWs, type BybitWsConfig, type CheckApiWalletParams, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, type DepositParams, type DepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidAccountType, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidWs, LighterAccountSyncer, LighterAccountTracker, type LighterAccountTrackerConfig, LighterAccountType, LighterExchangeWs, type LighterHelper, type LighterLookupResult, LighterWs, type ListExternalFillsParams, type MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxAccountType, OkxExchangeWs, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, type StateUpdate, type SupportedCredentials, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, getAssetDecimals };
+export { ACCOUNT_TYPE_LABELS, ASSET_DECIMALS, type AccountBalance, type AccountHealthStatus, type AccountPosition, type AccountStatus, type AccountSyncer, type AccountSyncerConfig, type AccountTracker, type AccountTrackerConfig, type AccountType, type AccountWarningReason, type ApiKey, type ApproveIntegratorParams, type ApproveIntegratorResult, type AssetBalance, AssetId, type BalanceCallback, BaseAccountSyncer, BaseAccountTracker, BaseWs, BinanceAccountSyncer, BinanceAccountTracker, type BinanceAccountTrackerConfig, BinanceAccountType, BinanceExchangeWs, BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig, BybitAccountSyncer, BybitAccountTracker, type BybitAccountTrackerConfig, BybitAccountType, BybitExchangeWs, BybitWs, type BybitWsConfig, type CheckApiWalletParams, type ConnectOptions, type ConnectWalletParams, type ConnectWalletResult, type CreateAccountTrackerConfig, type CreateExchangeWsConfig, type DepositParams, type DepositResult, type ExchangeConnection, type ExchangeHelperExchange, type ExchangeHelperMap, type ExchangeState, ExchangeWs, type ExchangeWsByConnector, ExchangesSDK, type ExchangesSDKConfig, HyperliquidAccountSyncer, HyperliquidAccountTracker, type HyperliquidAccountTrackerConfig, HyperliquidAccountType, HyperliquidExchangeWs, type HyperliquidHelper, HyperliquidWs, LighterAccountSyncer, LighterAccountTracker, type LighterAccountTrackerConfig, LighterAccountType, LighterExchangeWs, type LighterHelper, type LighterLookupResult, LighterWs, type ListExternalFillsParams, type ListExternalFundingParams, type ListExternalPositionsParams, type MarginMode, type MessageListener, OkxAccountSyncer, OkxAccountTracker, type OkxAccountTrackerConfig, OkxAccountType, OkxExchangeWs, OkxWs, type OkxWsConfig, type OpenListener, type PositionsCallback, RouteType, type StateUpdate, type SupportedCredentials, type TrackedAssetCallback, type TrackedAssetInfo, type WalletClientWithAccount, type WithdrawParams, type WithdrawResult, type WsMessage, createAccountSyncer, createAccountTracker, createExchangeWs, createHyperliquidHelper, createLighterHelper, getAssetDecimals };

package/dist/syncer/base.js

@@ -1,5 +1,6 @@
-import { computeSyncPayload } from '@pear-protocol/utils';
+import { computeEntryPriceForAsset, computeSyncPayload } from '@pear-protocol/utils';
 
+const OVERLAP_MS = 6e4;
 class BaseAccountSyncer {
   sdk;
   connector;
@@ -15,46 +16,129 @@ class BaseAccountSyncer {
     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);
   }
 }
 

package/dist/syncer/base.test.js

@@ -0,0 +1,132 @@
+import { describe, afterEach, vi, it, expect } from 'vitest';
+import { BaseAccountSyncer } from './base';
+
+function extFill(overrides = {}) {
+  return {
+    exchangeFillId: "tx-default",
+    cloid: null,
+    connector: "hyperliquid",
+    symbol: "BTC",
+    price: "100",
+    quantity: "1",
+    side: "BUY",
+    reduceOnly: false,
+    timestamp: 1e3,
+    tradeFee: "0",
+    builderFee: "0",
+    liquidation: null,
+    ...overrides
+  };
+}
+function exchangePos(overrides = {}) {
+  return { symbol: "BTC", size: "1", side: "BUY", entryPrice: "100", markPrice: "100", ...overrides };
+}
+class FakeSyncer extends BaseAccountSyncer {
+  positionsFn = vi.fn();
+  fillsFn = vi.fn();
+  listExternalPositions(params) {
+    return this.positionsFn(params);
+  }
+  listExternalFills(params) {
+    return this.fillsFn(params);
+  }
+  listExternalFunding() {
+    return Promise.resolve([]);
+  }
+  isReduceOnly() {
+    return false;
+  }
+}
+function makeSyncer(args) {
+  const fills = {
+    since: vi.fn().mockResolvedValue({ sinceMs: 0, neverSynced: args.neverSynced, confirmedExchangeFillIds: [] }),
+    reconcile: vi.fn().mockResolvedValue({}),
+    confirm: vi.fn().mockResolvedValue({}),
+    create: vi.fn().mockResolvedValue({}),
+    createBulk: vi.fn().mockResolvedValue({})
+  };
+  const sync = { fills };
+  const sdk = {
+    core: {
+      positions: { openLite: vi.fn().mockResolvedValue({ positions: [] }) },
+      fills: { provisionals: vi.fn().mockResolvedValue({ fills: [] }), details: vi.fn() },
+      instruments: { list: vi.fn().mockResolvedValue({ instruments: [] }) },
+      sync
+    }
+  };
+  const config = {
+    sdk,
+    connector: "hyperliquid",
+    account: { id: "acct-1" },
+    credentials: {},
+    ws: {},
+    demo: false
+  };
+  return { syncer: new FakeSyncer(config), sync };
+}
+const NEWEST_TS = 105e4;
+function trimmableFills(btcEraTs) {
+  return [
+    extFill({ exchangeFillId: "a", symbol: "BTC", side: "BUY", quantity: "1", timestamp: btcEraTs.open }),
+    extFill({ exchangeFillId: "b", symbol: "BTC", side: "SELL", quantity: "1", timestamp: btcEraTs.close }),
+    extFill({ exchangeFillId: "e", symbol: "SOL", side: "BUY", quantity: "2", timestamp: NEWEST_TS })
+  ];
+}
+const SOL_SNAPSHOT = [exchangePos({ symbol: "SOL", size: "2" })];
+describe("BaseAccountSyncer \u2014 first-sync plumbing", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it("neverSynced=true: the posted snapshot is fetched AFTER the fill stream", async () => {
+    const { syncer, sync } = makeSyncer({ neverSynced: true });
+    syncer.positionsFn.mockResolvedValue(SOL_SNAPSHOT);
+    syncer.fillsFn.mockResolvedValue([
+      extFill({ exchangeFillId: "e", symbol: "SOL", side: "BUY", quantity: "2", timestamp: NEWEST_TS })
+    ]);
+    await syncer.synchronizeFills();
+    expect(syncer.positionsFn).toHaveBeenCalledTimes(1);
+    expect(syncer.fillsFn.mock.invocationCallOrder[0]).toBeLessThan(
+      syncer.positionsFn.mock.invocationCallOrder[0] ?? 0
+    );
+    expect(sync.fills.create).toHaveBeenCalledTimes(1);
+    expect(sync.fills.create.mock.calls[0]?.[0]?.exchangePositions).toBe(SOL_SNAPSHOT);
+  });
+  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);
+    syncer.fillsFn.mockResolvedValue(trimmableFills({ open: 1e6, close: NEWEST_TS - 2e4 }));
+    await syncer.synchronizeFills();
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta.externalMaxTs).toBe(NEWEST_TS + 6e4 + 1);
+  });
+  it("leaves the watermark unbumped when the trimmed era is entirely older than the overlap window", async () => {
+    const { syncer, sync } = makeSyncer({ neverSynced: true });
+    syncer.positionsFn.mockResolvedValue(SOL_SNAPSHOT);
+    syncer.fillsFn.mockResolvedValue(trimmableFills({ open: 1e5, close: 2e5 }));
+    await syncer.synchronizeFills();
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta.externalMaxTs).toBe(NEWEST_TS);
+  });
+  it("logs the trim exactly once when a trim happened", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {
+    });
+    const { syncer } = makeSyncer({ neverSynced: true });
+    syncer.positionsFn.mockResolvedValue(SOL_SNAPSHOT);
+    syncer.fillsFn.mockResolvedValue(trimmableFills({ open: 1e5, close: 2e5 }));
+    await syncer.synchronizeFills();
+    const trimLogs = logSpy.mock.calls.filter((call) => String(call[0]).includes("first-sync trim"));
+    expect(trimLogs).toHaveLength(1);
+    expect(String(trimLogs[0]?.[0])).toContain("hyperliquid");
+  });
+  it("neverSynced=false: positions fetched once, no bump, no trim log", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {
+    });
+    const { syncer, sync } = makeSyncer({ neverSynced: false });
+    syncer.positionsFn.mockResolvedValue(SOL_SNAPSHOT);
+    syncer.fillsFn.mockResolvedValue([
+      extFill({ exchangeFillId: "e", symbol: "SOL", side: "BUY", quantity: "2", timestamp: NEWEST_TS })
+    ]);
+    await syncer.synchronizeFills();
+    expect(syncer.positionsFn).toHaveBeenCalledTimes(1);
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta.externalMaxTs).toBe(NEWEST_TS);
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+});

package/dist/syncer/binance/syncer.js

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { fetchUserTradesSince, fetchAllOrdersSince } from '../../client/binance/rest';
+import { fetchAllPositionRisk, fetchUserTradesSince, fetchAllOrdersSince } from '../../client/binance/rest';
 import { BaseAccountSyncer } from '../base';
 
 class BinanceAccountSyncer extends BaseAccountSyncer {
@@ -8,6 +8,31 @@ class BinanceAccountSyncer extends BaseAccountSyncer {
     super(config);
     this.creds = config.credentials;
   }
+  async listExternalPositions({
+    instruments
+  }) {
+    const contractSizeByInstrumentId = new Map(
+      instruments.map((instrument) => [instrument.id, instrument.precision.quantity.contractSize])
+    );
+    const rawPositions = await fetchAllPositionRisk(this.creds, this.demo);
+    return rawPositions.reduce((positions, rawPosition) => {
+      const signedSize = new BigNumber(rawPosition.positionAmt);
+      if (signedSize.isZero()) {
+        return positions;
+      }
+      const contractSize = contractSizeByInstrumentId.get(rawPosition.symbol) ?? 1;
+      const size = signedSize.abs().times(contractSize).toFixed();
+      const side = signedSize.isGreaterThan(0) ? "BUY" : "SELL";
+      positions.push({
+        symbol: rawPosition.symbol,
+        size,
+        side,
+        entryPrice: rawPosition.entryPrice,
+        markPrice: rawPosition.markPrice
+      });
+      return positions;
+    }, []);
+  }
   async listExternalFills({
     since,
     instruments,
@@ -25,33 +50,36 @@ class BinanceAccountSyncer extends BaseAccountSyncer {
       fetchAllOrdersSince(this.creds, instrumentIds, since, this.demo)
     ]);
     const ordersBySymbolOrderId = this.mapOrdersBySymbolOrderId(orders);
-    return trades.reduce((acc, trade) => {
-      if (!requestedInstrumentIds.has(trade.symbol)) {
-        return acc;
+    return trades.reduce((fills, rawFill) => {
+      if (!requestedInstrumentIds.has(rawFill.symbol)) {
+        return fills;
       }
-      const order = ordersBySymbolOrderId.get(this.orderKey(trade.symbol, trade.orderId));
-      acc.push({
+      const order = ordersBySymbolOrderId.get(this.orderKey(rawFill.symbol, rawFill.orderId));
+      fills.push({
         connector: "binance",
-        exchangeFillId: trade.id.toString(),
+        exchangeFillId: rawFill.id.toString(),
         cloid: order?.clientOrderId || null,
-        symbol: trade.symbol,
-        price: trade.price,
-        quantity: trade.qty,
-        side: trade.side,
-        reduceOnly: this.isReduceOnly(trade),
-        timestamp: trade.time,
-        tradeFee: new BigNumber(trade.commission || 0).abs().toFixed(),
+        symbol: rawFill.symbol,
+        price: rawFill.price,
+        quantity: rawFill.qty,
+        side: rawFill.side,
+        reduceOnly: this.isReduceOnly(rawFill),
+        timestamp: rawFill.time,
+        tradeFee: new BigNumber(rawFill.commission || 0).abs().toFixed(),
         builderFee: "0",
         liquidation: null
       });
-      return acc;
+      return fills;
     }, []);
   }
-  isReduceOnly(trade) {
-    if (trade.positionSide === "LONG") return trade.side === "SELL";
-    if (trade.positionSide === "SHORT") return trade.side === "BUY";
-    if (trade.positionSide === "BOTH") {
-      return !new BigNumber(trade.realizedPnl || 0).isZero();
+  async listExternalFunding(_params) {
+    throw new Error("funding sync is not implemented for binance");
+  }
+  isReduceOnly(rawFill) {
+    if (rawFill.positionSide === "LONG") return rawFill.side === "SELL";
+    if (rawFill.positionSide === "SHORT") return rawFill.side === "BUY";
+    if (rawFill.positionSide === "BOTH") {
+      return !new BigNumber(rawFill.realizedPnl || 0).isZero();
     }
     return false;
   }

package/dist/syncer/bybit/syncer.js

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { fetchExecutionsSince } from '../../client/bybit/rest';
+import { fetchPositions, fetchExecutionsSince } from '../../client/bybit/rest';
 import { BaseAccountSyncer } from '../base';
 
 class BybitAccountSyncer extends BaseAccountSyncer {
@@ -8,28 +8,52 @@ class BybitAccountSyncer extends BaseAccountSyncer {
     super(config);
     this.creds = config.credentials;
   }
+  async listExternalPositions({
+    instruments
+  }) {
+    const rawPositions = await fetchPositions(this.creds, "USDT", this.demo);
+    const contractSizeByInstrumentId = new Map(
+      instruments.map((instrument) => [instrument.id, instrument.precision.quantity.contractSize])
+    );
+    return rawPositions.reduce((positions, rawPosition) => {
+      if (!rawPosition.size || rawPosition.size === "0" || !rawPosition.side) return positions;
+      const contractSize = contractSizeByInstrumentId.get(rawPosition.symbol) ?? 1;
+      const size = new BigNumber(rawPosition.size).abs().times(contractSize).toFixed();
+      positions.push({
+        symbol: rawPosition.symbol,
+        size,
+        side: rawPosition.side === "Buy" ? "BUY" : "SELL",
+        entryPrice: rawPosition.avgPrice,
+        markPrice: rawPosition.avgPrice
+      });
+      return positions;
+    }, []);
+  }
   async listExternalFills({ since }) {
     const executions = await fetchExecutionsSince(this.creds, since, this.demo);
-    return executions.reduce((acc, execution) => {
-      acc.push({
+    return executions.reduce((fills, rawFill) => {
+      fills.push({
         connector: "bybit",
-        exchangeFillId: execution.execId,
-        cloid: execution.orderLinkId || null,
-        symbol: execution.symbol,
-        price: execution.execPrice,
-        quantity: execution.execQty,
-        side: execution.side === "Buy" ? "BUY" : "SELL",
-        reduceOnly: this.isReduceOnly(execution),
-        timestamp: Number(execution.execTime),
-        tradeFee: new BigNumber(execution.execFee || 0).abs().toFixed(),
+        exchangeFillId: rawFill.execId,
+        cloid: rawFill.orderLinkId || null,
+        symbol: rawFill.symbol,
+        price: rawFill.execPrice,
+        quantity: rawFill.execQty,
+        side: rawFill.side === "Buy" ? "BUY" : "SELL",
+        reduceOnly: this.isReduceOnly(rawFill),
+        timestamp: Number(rawFill.execTime),
+        tradeFee: new BigNumber(rawFill.execFee || 0).abs().toFixed(),
         builderFee: "0",
         liquidation: null
       });
-      return acc;
+      return fills;
     }, []);
   }
-  isReduceOnly(execution) {
-    return Number(execution.closedSize || "0") > 0;
+  async listExternalFunding(_params) {
+    throw new Error("funding sync is not implemented for bybit");
+  }
+  isReduceOnly(rawFill) {
+    return Number(rawFill.closedSize || "0") > 0;
   }
 }
 

package/dist/syncer/hyperliquid/funding.js

@@ -0,0 +1,24 @@
+import BigNumber from 'bignumber.js';
+
+function toFundingPaymentEntries(events, symbolToInstrumentId) {
+  return events.reduce((entries, event) => {
+    const instrumentId = symbolToInstrumentId[event.delta.coin];
+    if (!instrumentId) {
+      console.warn(`Instrument symbol ${event.delta.coin} not found in instrument symbol to id map.`);
+      return entries;
+    }
+    const size = new BigNumber(event.delta.szi);
+    const fundingPerUnit = size.isZero() ? "0" : new BigNumber(event.delta.usdc).div(size).toFixed();
+    entries.push({
+      connector: "hyperliquid",
+      instrumentId,
+      fundingRate: event.delta.fundingRate,
+      notional: event.delta.usdc,
+      fundingPerUnit,
+      timestamp: event.time
+    });
+    return entries;
+  }, []);
+}
+
+export { toFundingPaymentEntries };

package/dist/syncer/hyperliquid/funding.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { toFundingPaymentEntries } from './funding';
+
+const fundingEvent = (over) => ({
+  time: over.time,
+  hash: "0xabc",
+  delta: {
+    type: "funding",
+    coin: over.coin,
+    usdc: over.usdc ?? "1.5",
+    szi: over.szi ?? "10",
+    fundingRate: over.fundingRate,
+    nSamples: 1
+  }
+});
+describe("toFundingPaymentEntries", () => {
+  const map = {
+    BTC: "HL-BTC",
+    ETH: "HL-ETH"
+  };
+  it("maps a funding event to a funding-payment entry (rate + notional + per-size)", () => {
+    const result = toFundingPaymentEntries(
+      [fundingEvent({ coin: "BTC", fundingRate: "-0.0001", usdc: "-2.5", szi: "5", time: 1e3 })],
+      map
+    );
+    expect(result).toEqual([
+      {
+        connector: "hyperliquid",
+        instrumentId: "HL-BTC",
+        fundingRate: "-0.0001",
+        notional: "-2.5",
+        // notional / szi = -2.5 / 5
+        fundingPerUnit: "-0.5",
+        timestamp: 1e3
+      }
+    ]);
+  });
+  it("uses signed division by szi (per-size is the attribution coefficient)", () => {
+    const result = toFundingPaymentEntries(
+      [fundingEvent({ coin: "BTC", fundingRate: "0.0001", usdc: "2.5", szi: "-5", time: 1e3 })],
+      map
+    );
+    expect(result[0]?.fundingPerUnit).toBe("-0.5");
+  });
+  it("uses zero per-size when size is zero (no divide by zero)", () => {
+    const result = toFundingPaymentEntries(
+      [fundingEvent({ coin: "BTC", fundingRate: "0.0001", usdc: "0", szi: "0", time: 1e3 })],
+      map
+    );
+    expect(result[0]?.fundingPerUnit).toBe("0");
+  });
+  it("skips events whose coin is not in the instrument map", () => {
+    const result = toFundingPaymentEntries(
+      [
+        fundingEvent({ coin: "BTC", fundingRate: "0.0001", time: 1e3 }),
+        fundingEvent({ coin: "DOGE", fundingRate: "0.0002", time: 2e3 }),
+        fundingEvent({ coin: "ETH", fundingRate: "0.0003", time: 3e3 })
+      ],
+      map
+    );
+    expect(result.map((entry) => entry.instrumentId)).toEqual(["HL-BTC", "HL-ETH"]);
+  });
+});

package/dist/syncer/hyperliquid/syncer.js

@@ -1,5 +1,7 @@
+import BigNumber from 'bignumber.js';
 import { fetchInfo } from '../../client/hyperliquid/rest';
 import { BaseAccountSyncer } from '../base';
+import { toFundingPaymentEntries } from './funding';
 
 class HyperliquidAccountSyncer extends BaseAccountSyncer {
   address;
@@ -7,6 +9,47 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
     super(config);
     this.address = config.account.exchangeIdentifier;
   }
+  async listExternalPositions({
+    instruments
+  }) {
+    const instrumentByBase = new Map(
+      instruments.map((instrument) => [
+        instrument.base,
+        { id: instrument.id, contractSize: instrument.precision.quantity.contractSize }
+      ])
+    );
+    const perpDexs = await fetchInfo({ type: "perpDexs" });
+    const dexNames = perpDexs.map((perpDex) => perpDex?.name ?? "");
+    const states = await Promise.all(
+      dexNames.map(
+        (dex) => fetchInfo({
+          type: "clearinghouseState",
+          user: this.address,
+          dex
+        })
+      )
+    );
+    const assetPositions = states.flatMap((state) => state.assetPositions);
+    return assetPositions.reduce((positions, { position: rawPosition }) => {
+      const szi = new BigNumber(rawPosition.szi);
+      if (szi.isZero()) {
+        return positions;
+      }
+      const instrument = instrumentByBase.get(rawPosition.coin);
+      if (!instrument) {
+        console.warn(`Instrument for coin ${rawPosition.coin} not found.`);
+        return positions;
+      }
+      positions.push({
+        symbol: instrument.id,
+        size: szi.abs().times(instrument.contractSize).toFixed(),
+        side: szi.isPositive() ? "BUY" : "SELL",
+        entryPrice: rawPosition.entryPx,
+        markPrice: rawPosition.entryPx
+      });
+      return positions;
+    }, []);
+  }
   async listExternalFills({
     since,
     instruments
@@ -15,37 +58,100 @@ class HyperliquidAccountSyncer extends BaseAccountSyncer {
       acc[instrument.base] = instrument.id;
       return acc;
     }, {});
-    const result = await fetchInfo({
-      type: "userFillsByTime",
-      user: this.address,
-      startTime: since.getTime(),
-      aggregateByTime: true
-    });
-    return result.reduce((acc, fill) => {
-      const instrumentId = instrumentSymbolToIdMap[fill.coin];
+    const PAGE_LIMIT = 2e3;
+    const allFills = [];
+    const seenTids = /* @__PURE__ */ new Set();
+    const addFill = (fill) => {
+      if (!seenTids.has(fill.tid)) {
+        seenTids.add(fill.tid);
+        allFills.push(fill);
+      }
+    };
+    let cursor = since.getTime();
+    let batchSize;
+    do {
+      const batch = await fetchInfo({
+        type: "userFillsByTime",
+        user: this.address,
+        startTime: cursor,
+        aggregateByTime: true
+      });
+      batchSize = batch.length;
+      for (const rawFill of batch) {
+        addFill(rawFill);
+      }
+      if (batchSize === PAGE_LIMIT) {
+        cursor = batch[batch.length - 1]?.time ?? cursor;
+      }
+    } while (batchSize === PAGE_LIMIT);
+    cursor = since.getTime();
+    do {
+      const twapBatch = await fetchInfo({
+        type: "userTwapSliceFillsByTime",
+        user: this.address,
+        startTime: cursor,
+        aggregateByTime: true
+      });
+      batchSize = twapBatch.length;
+      for (const item of twapBatch) {
+        addFill(item.fill);
+      }
+      if (batchSize === PAGE_LIMIT) {
+        cursor = twapBatch[twapBatch.length - 1]?.fill.time ?? cursor;
+      }
+    } while (batchSize === PAGE_LIMIT);
+    allFills.sort((a, b) => a.time - b.time);
+    return allFills.reduce((fills, rawFill) => {
+      const instrumentId = instrumentSymbolToIdMap[rawFill.coin];
       if (!instrumentId) {
-        console.warn(`Instrument symbol ${fill.coin} not found in instrument symbol to id map.`);
-        return acc;
+        console.warn(`Instrument symbol ${rawFill.coin} not found in instrument symbol to id map.`);
+        return fills;
       }
-      acc.push({
+      fills.push({
         connector: "hyperliquid",
-        exchangeFillId: fill.tid.toFixed(),
-        cloid: fill.cloid ?? null,
+        exchangeFillId: rawFill.tid.toFixed(),
+        cloid: rawFill.cloid ?? null,
         symbol: instrumentId,
-        price: fill.px,
-        quantity: fill.sz,
-        side: fill.side === "B" ? "BUY" : "SELL",
-        reduceOnly: this.isReduceOnly(fill),
-        timestamp: fill.time,
-        tradeFee: fill.fee,
-        builderFee: fill.builderFee ?? "0",
-        liquidation: fill.liquidation ? { mark: fill.liquidation.markPx } : null
+        price: rawFill.px,
+        quantity: rawFill.sz,
+        side: rawFill.side === "B" ? "BUY" : "SELL",
+        reduceOnly: this.isReduceOnly(rawFill),
+        timestamp: rawFill.time,
+        tradeFee: rawFill.fee,
+        builderFee: rawFill.builderFee ?? "0",
+        liquidation: rawFill.liquidation ? { mark: rawFill.liquidation.markPx } : null
       });
-      return acc;
+      return fills;
     }, []);
   }
-  isReduceOnly(fill) {
-    return fill.dir.includes("Close");
+  async listExternalFunding({
+    since,
+    instruments
+  }) {
+    const instrumentSymbolToIdMap = instruments.reduce((acc, instrument) => {
+      acc[instrument.base] = instrument.id;
+      return acc;
+    }, {});
+    const PAGE_LIMIT = 500;
+    const allEvents = [];
+    let cursor = since.getTime();
+    let batchSize;
+    do {
+      const batch = await fetchInfo({
+        type: "userFunding",
+        user: this.address,
+        startTime: cursor
+      });
+      batchSize = batch.length;
+      allEvents.push(...batch);
+      if (batchSize === PAGE_LIMIT) {
+        cursor = batch[batch.length - 1].time;
+      }
+    } while (batchSize === PAGE_LIMIT);
+    return toFundingPaymentEntries(allEvents, instrumentSymbolToIdMap);
+  }
+  isReduceOnly(rawFill) {
+    return rawFill.dir.includes("Close");
   }
 }
 

package/dist/syncer/lighter/syncer.js

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { fetchTradesSince } from '../../client/lighter/rest';
+import { fetchAccount, fetchTradesSince } from '../../client/lighter/rest';
 import { BaseAccountSyncer } from '../base';
 
 const LIGHTER_FEE_TICK_DENOMINATOR = new BigNumber(1e6);
@@ -9,10 +9,35 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   apiPrivateKey;
   constructor(config) {
     super(config);
-    const creds = config.credentials;
+    const credentials = config.credentials;
     this.accountIndex = Number(config.account.exchangeIdentifier);
-    this.apiKeyIndex = creds.api_key_index;
-    this.apiPrivateKey = creds.api_private_key;
+    this.apiKeyIndex = credentials.api_key_index;
+    this.apiPrivateKey = credentials.api_private_key;
+  }
+  async listExternalPositions({
+    instruments
+  }) {
+    const contractSizeByInstrumentId = new Map(
+      instruments.map((instrument) => [instrument.id, instrument.precision.quantity.contractSize])
+    );
+    const response = await fetchAccount(this.accountIndex);
+    const rawPositions = response.accounts?.[0]?.positions ?? [];
+    return rawPositions.reduce((positions, rawPosition) => {
+      const instrumentId = rawPosition.market_id.toString();
+      const signedSize = new BigNumber(rawPosition.position).times(rawPosition.sign);
+      if (signedSize.isZero()) return positions;
+      const contractSize = contractSizeByInstrumentId.get(instrumentId) ?? 1;
+      const size = signedSize.abs().times(contractSize).toFixed();
+      const side = rawPosition.sign === 1 ? "BUY" : "SELL";
+      positions.push({
+        symbol: instrumentId,
+        size,
+        side,
+        entryPrice: rawPosition.avg_entry_price,
+        markPrice: rawPosition.avg_entry_price
+      });
+      return positions;
+    }, []);
   }
   async listExternalFills({
     since,
@@ -25,68 +50,71 @@ class LighterAccountSyncer extends BaseAccountSyncer {
     });
     const trades = await fetchTradesSince(this.accountIndex, token, since);
     const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
-    return trades.toSorted((a, b) => a.timestamp - b.timestamp).reduce((acc, trade) => {
-      const instrumentId = trade.market_id.toString();
+    return trades.toSorted((a, b) => a.timestamp - b.timestamp).reduce((fills, rawFill) => {
+      const instrumentId = rawFill.market_id.toString();
       if (!instrumentIds.has(instrumentId)) {
-        console.warn(`Lighter market id ${trade.market_id} not found in instrument id map.`);
-        return acc;
+        console.warn(`Lighter market id ${rawFill.market_id} not found in instrument id map.`);
+        return fills;
       }
-      const accountSide = this.getAccountSide(trade);
-      if (!accountSide) return acc;
+      const accountSide = this.getAccountSide(rawFill);
+      if (!accountSide) return fills;
       const side = accountSide === "ask" ? "SELL" : "BUY";
-      acc.push({
+      fills.push({
         connector: "lighter",
-        exchangeFillId: trade.trade_id_str ?? trade.trade_id.toString(),
-        cloid: this.getClientOrderId(trade, accountSide),
+        exchangeFillId: rawFill.trade_id_str ?? rawFill.trade_id.toString(),
+        cloid: this.getClientOrderId(rawFill, accountSide),
         symbol: instrumentId,
-        price: trade.price,
-        quantity: trade.size,
+        price: rawFill.price,
+        quantity: rawFill.size,
         side,
-        reduceOnly: this.isReduceOnly(trade),
-        timestamp: trade.timestamp,
-        tradeFee: this.getTradeFee(trade, accountSide),
-        builderFee: this.getIntegratorFee(trade, accountSide),
-        liquidation: trade.type === "liquidation" ? { mark: trade.price } : null
+        reduceOnly: this.isReduceOnly(rawFill),
+        timestamp: rawFill.timestamp,
+        tradeFee: this.getTradeFee(rawFill, accountSide),
+        builderFee: this.getIntegratorFee(rawFill, accountSide),
+        liquidation: rawFill.type === "liquidation" ? { mark: rawFill.price } : null
       });
-      return acc;
+      return fills;
     }, []);
   }
-  isReduceOnly(trade) {
-    if (trade.type === "liquidation" || trade.type === "deleverage" || trade.type === "market-settlement") {
+  async listExternalFunding(_params) {
+    throw new Error("funding sync is not implemented for lighter");
+  }
+  isReduceOnly(rawFill) {
+    if (rawFill.type === "liquidation" || rawFill.type === "deleverage" || rawFill.type === "market-settlement") {
       return true;
     }
-    const accountSide = this.getAccountSide(trade);
+    const accountSide = this.getAccountSide(rawFill);
     if (!accountSide) {
       return false;
     }
-    const positionSizeBefore = this.getPositionSizeBefore(trade, accountSide);
+    const positionSizeBefore = this.getPositionSizeBefore(rawFill, accountSide);
     if (positionSizeBefore.isZero()) {
       return false;
     }
     return positionSizeBefore.isPositive() && accountSide === "ask" || positionSizeBefore.isNegative() && accountSide === "bid";
   }
-  getAccountSide(trade) {
-    if (trade.ask_account_id === this.accountIndex) return "ask";
-    if (trade.bid_account_id === this.accountIndex) return "bid";
+  getAccountSide(rawFill) {
+    if (rawFill.ask_account_id === this.accountIndex) return "ask";
+    if (rawFill.bid_account_id === this.accountIndex) return "bid";
     return null;
   }
-  getClientOrderId(trade, side) {
-    return (side === "ask" ? trade.ask_client_id_str : trade.bid_client_id_str) || null;
+  getClientOrderId(rawFill, side) {
+    return (side === "ask" ? rawFill.ask_client_id_str : rawFill.bid_client_id_str) || null;
   }
-  isMaker(trade, side) {
-    return side === "ask" ? trade.is_maker_ask : !trade.is_maker_ask;
+  isMaker(rawFill, side) {
+    return side === "ask" ? rawFill.is_maker_ask : !rawFill.is_maker_ask;
   }
-  getPositionSizeBefore(trade, side) {
-    const value = this.isMaker(trade, side) ? trade.maker_position_size_before : trade.taker_position_size_before;
+  getPositionSizeBefore(rawFill, side) {
+    const value = this.isMaker(rawFill, side) ? rawFill.maker_position_size_before : rawFill.taker_position_size_before;
     return new BigNumber(value ?? 0);
   }
-  getTradeFee(trade, side) {
-    const rateTick = this.isMaker(trade, side) ? trade.maker_fee : trade.taker_fee;
-    return this.feeTickToAmount(rateTick, trade.usd_amount);
+  getTradeFee(rawFill, side) {
+    const rateTick = this.isMaker(rawFill, side) ? rawFill.maker_fee : rawFill.taker_fee;
+    return this.feeTickToAmount(rateTick, rawFill.usd_amount);
   }
-  getIntegratorFee(trade, side) {
-    const rateTick = this.isMaker(trade, side) ? trade.integrator_maker_fee : trade.integrator_taker_fee;
-    return this.feeTickToAmount(rateTick, trade.usd_amount);
+  getIntegratorFee(rawFill, side) {
+    const rateTick = this.isMaker(rawFill, side) ? rawFill.integrator_maker_fee : rawFill.integrator_taker_fee;
+    return this.feeTickToAmount(rateTick, rawFill.usd_amount);
   }
   // Lighter fees come as ppm rates (÷1e6), not amounts — the charged fee is that rate times the trade's USD notional.
   feeTickToAmount(rateTick, usdAmount) {

package/dist/syncer/okx/syncer.js

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { fetchFillsHistorySince } from '../../client/okx/rest';
+import { fetchPositions, fetchFillsHistorySince } from '../../client/okx/rest';
 import { BaseAccountSyncer } from '../base';
 
 class OkxAccountSyncer extends BaseAccountSyncer {
@@ -8,6 +8,27 @@ class OkxAccountSyncer extends BaseAccountSyncer {
     super(config);
     this.creds = config.credentials;
   }
+  async listExternalPositions({
+    instruments
+  }) {
+    const rawPositions = await fetchPositions(this.creds, this.demo);
+    const contractSizeByInstrumentId = new Map(
+      instruments.map((instrument) => [instrument.id, instrument.precision.quantity.contractSize])
+    );
+    return rawPositions.reduce((positions, rawPosition) => {
+      if (!rawPosition.pos || rawPosition.pos === "0") return positions;
+      const contractSize = contractSizeByInstrumentId.get(rawPosition.instId) ?? 1;
+      const signedSize = new BigNumber(rawPosition.pos);
+      positions.push({
+        symbol: rawPosition.instId,
+        size: signedSize.abs().times(contractSize).toFixed(),
+        side: signedSize.isGreaterThan(0) ? "BUY" : "SELL",
+        entryPrice: rawPosition.avgPx,
+        markPrice: rawPosition.avgPx
+      });
+      return positions;
+    }, []);
+  }
   async listExternalFills({
     since,
     instruments
@@ -16,28 +37,31 @@ class OkxAccountSyncer extends BaseAccountSyncer {
     const contractSizeByInstrumentId = new Map(
       instruments.map((instrument) => [instrument.id, instrument.precision.quantity.contractSize])
     );
-    return fills.reduce((acc, fill) => {
-      const contractSize = contractSizeByInstrumentId.get(fill.instId) ?? 1;
-      acc.push({
+    return fills.reduce((result, rawFill) => {
+      const contractSize = contractSizeByInstrumentId.get(rawFill.instId) ?? 1;
+      result.push({
         connector: "okx",
-        exchangeFillId: fill.billId || fill.tradeId,
-        cloid: fill.clOrdId || null,
-        symbol: fill.instId,
-        price: fill.fillPx,
-        quantity: this.contractsToBase(fill.fillSz, contractSize),
-        side: fill.side === "buy" ? "BUY" : "SELL",
-        reduceOnly: this.isReduceOnly(fill),
-        timestamp: Number(fill.fillTime || fill.ts),
-        tradeFee: new BigNumber(fill.fee || 0).abs().toFixed(),
+        exchangeFillId: rawFill.billId || rawFill.tradeId,
+        cloid: rawFill.clOrdId || null,
+        symbol: rawFill.instId,
+        price: rawFill.fillPx,
+        quantity: this.contractsToBase(rawFill.fillSz, contractSize),
+        side: rawFill.side === "buy" ? "BUY" : "SELL",
+        reduceOnly: this.isReduceOnly(rawFill),
+        timestamp: Number(rawFill.fillTime || rawFill.ts),
+        tradeFee: new BigNumber(rawFill.fee || 0).abs().toFixed(),
         builderFee: "0",
         liquidation: null
       });
-      return acc;
+      return result;
     }, []);
   }
-  isReduceOnly(fill) {
-    if (fill.posSide === "long") return fill.side === "sell";
-    if (fill.posSide === "short") return fill.side === "buy";
+  async listExternalFunding(_params) {
+    throw new Error("funding sync is not implemented for okx");
+  }
+  isReduceOnly(rawFill) {
+    if (rawFill.posSide === "long") return rawFill.side === "sell";
+    if (rawFill.posSide === "short") return rawFill.side === "buy";
     return false;
   }
   contractsToBase(quantity, contractSize) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -26,9 +26,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@pear-protocol/core-sdk": "^1.0.0",
-    "@pear-protocol/types": "^1.0.0",
-    "@pear-protocol/utils": "^0.0.23",
+    "@pear-protocol/core-sdk": "^1.5.0",
+    "@pear-protocol/types": "^1.6.0",
+    "@pear-protocol/utils": "^0.1.0",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8"