@owney/sdk 0.3.5 → 0.4.0

package/README.md

@@ -298,11 +298,17 @@ console.log(allApy.apyByChainAndAsset[42161]?.USDT); // 4.7
 
 Get transaction history for a specific agent, or all agents. When querying all agents, results are merged into a single list sorted by date (newest first). Each entry includes the originating `agent` and a `transactions` array with typed on-chain transaction details.
 
-| Param              | Type                           | Description                          |
-| ------------------ | ------------------------------ | ------------------------------------ |
-| `agentId`          | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
-| `filters.fromDate` | `string` (optional)            | Start date (`YYYY-MM-DD`)            |
-| `filters.toDate`   | `string` (optional)            | End date (`YYYY-MM-DD`)              |
+Results are **cursor-paginated**. The first call (no `cursor`) anchors a stable snapshot at the current time; subsequent pages within that same snapshot are consistent. Each new cursorless call captures a fresh snapshot — if you need to preserve scroll position while paging, always carry forward the cursor returned by the previous call rather than starting a new cursorless fetch.
+
+> **Per-chain filtering:** The Zyfai backend no longer accepts a `chainId` filter directly. The SDK performs a bounded internal drain (up to 5 backend round-trips per logical page) to fill the requested `limit` with entries matching the active chain. This is transparent to callers — the `getHistory` API is unchanged.
+
+| Param              | Type                           | Description                                              |
+| ------------------ | ------------------------------ | -------------------------------------------------------- |
+| `agentId`          | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents.                     |
+| `filters.fromDate` | `string` (optional)            | Start date (`YYYY-MM-DD`)                                |
+| `filters.toDate`   | `string` (optional)            | End date (`YYYY-MM-DD`)                                  |
+| `filters.limit`    | `number` (optional)            | Max entries returned per call. Defaults to `10`.         |
+| `filters.cursor`   | `string` (optional)            | Opaque cursor returned by a previous `getHistory` call.  |
 
 Returns: `OwneyAgentHistory`
 
@@ -312,7 +318,7 @@ const history = await sdk.getHistory({
   agentId: "zyfai",
   filters: { fromDate: "2025-01-01" },
 });
-console.log(history.total); // 42
+console.log(history.hasMore); // true | false
 console.log(history.data[0].agent); // "zyfai"
 console.log(history.data[0].action); // "Rebalance"
 console.log(history.data[0].date); // "2025-03-15T12:00:00Z"
@@ -329,9 +335,20 @@ console.log(history.data[0].rebalanceLog[0].status); // "success"
 
 // All agents (merged and sorted by date)
 const allHistory = await sdk.getHistory();
-console.log(allHistory.total); // 57
+console.log(allHistory.hasMore); // true | false
 console.log(allHistory.data[0].agent); // "sail" (most recent entry)
 console.log(allHistory.data[0].action); // "Rebalance"
+
+// Paginate through all history (per-chain, anchored to a single snapshot)
+const allEntries: AgentHistoryEntry[] = [];
+let cursor: string | undefined;
+do {
+  const page = await sdk.getHistory({
+    filters: { cursor, limit: 50 },
+  });
+  allEntries.push(...page.data);
+  cursor = page.hasMore ? page.nextCursor : undefined;
+} while (cursor);
 ```
 
 ### `pauseAgent(agentId)`
@@ -481,6 +498,10 @@ interface ConnectionState {
 type HistoryFilters = {
   fromDate?: string; // YYYY-MM-DD
   toDate?: string; // YYYY-MM-DD
+  /** Max entries returned per call. Defaults to 10. */
+  limit?: number;
+  /** Opaque cursor returned by a previous getHistory call. */
+  cursor?: string;
 };
 
 type HistoryOptions = {
@@ -612,7 +633,10 @@ interface AgentHistoryEntry {
 
 interface OwneyAgentHistory {
   data: AgentHistoryEntry[];
-  total: number;
+  /** True iff a subsequent page exists; pair with `nextCursor`. */
+  hasMore: boolean;
+  /** Opaque cursor for the next page. Present iff `hasMore === true`. */
+  nextCursor?: string;
 }
 
 interface OwneyAgentStatus {
@@ -750,6 +774,38 @@ The three convenience subclasses extend `OwneyError` and remain backwards-compat
 | `AgentNotFoundError`          | `AGENT_NOT_FOUND`          | —                                        |
 | `AgentChainIncompatibleError` | `AGENT_CHAIN_INCOMPATIBLE` | `incompatibleAgents`, `connectedChainId` |
 
+### Cursor errors
+
+`InvalidHistoryCursorError` is thrown by `getHistory` when the supplied cursor is invalid. It extends `Error` directly — **not** `OwneyError` — so a `catch` block that only checks `instanceof OwneyError` will not catch it. Catch it separately:
+
+```typescript
+import { InvalidHistoryCursorError } from "@owney/sdk";
+
+try {
+  const page = await sdk.getHistory({ filters: { cursor: storedCursor } });
+} catch (error) {
+  if (error instanceof InvalidHistoryCursorError) {
+    // Stored cursor is stale or malformed — reset pagination.
+    storedCursor = undefined;
+    // Refetch first page...
+  } else {
+    throw error;
+  }
+}
+```
+
+`InvalidHistoryCursorError` carries a stable `code` property (value: `"invalid_cursor"`) and is thrown when:
+
+- The supplied cursor is an empty string.
+- The cursor is not valid base64 JSON.
+- The cursor payload has the wrong shape (e.g. a cursor from a different pagination context).
+
+**Recovery:** catch `InvalidHistoryCursorError`, clear your stored cursor, and refetch from page 1.
+
+| Class                        | `code`            | Extends    |
+| ---------------------------- | ----------------- | ---------- |
+| `InvalidHistoryCursorError`  | `"invalid_cursor"`| `Error`    |
+
 ## License
 
 ELv2

package/dist/index.cjs

@@ -22,6 +22,7 @@ var src_exports = {};
 __export(src_exports, {
   AgentChainIncompatibleError: () => AgentChainIncompatibleError,
   AgentNotFoundError: () => AgentNotFoundError,
+  InvalidHistoryCursorError: () => InvalidHistoryCursorError,
   NotConnectedError: () => NotConnectedError,
   OwneyError: () => OwneyError,
   OwneySDK: () => OwneySDK
@@ -237,7 +238,7 @@ function mapApyHistory(raw) {
     apyByChainAndAsset: mapWeightedApyByChain(raw.weightedApyAfterFeeByChain)
   };
 }
-function mapHistory(raw, chainId) {
+function mapEntries(rawEntries, chainId) {
   const actionMap = {
     "Deposit to protocol": "Deposit",
     "Top up wallet": "Top up",
@@ -245,50 +246,47 @@ function mapHistory(raw, chainId) {
     "Withdraw from protocol": "Withdraw",
     Rebalance: "Rebalance"
   };
-  return {
-    total: raw.total,
-    data: raw.data.filter((d) => d.chainId === chainId).map((entry) => {
-      const rawLog = entry.rebalanceLog;
-      const positions = entry.positions ?? [];
-      let rebalanceLog = [];
-      let oldApy = null;
-      let newApy = null;
-      if (rawLog) {
-        const matched = positions.find(
-          (p) => p.protocol_name ? rawLog.newOpportunity.includes(`${p.protocol_name} (${p.pool})`) : false
-        );
-        oldApy = Number(rawLog.oldApy);
-        newApy = Number(rawLog.newApy);
-        rebalanceLog = [
-          {
-            fromProtocol: rawLog.oldOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
-            toProtocol: rawLog.newOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
-            tokenSymbol: matched?.token_symbol ?? "",
-            amount: matched ? String(hexToDecimal(matched.amount || "0x")) : "",
-            status: "success"
-          }
-        ];
-      }
-      const rawAmount = entry?.positions?.[0]?.amount;
-      const hasAmount = typeof rawAmount === "string" && rawAmount !== "" && rawAmount !== "0x" && rawAmount !== "0x0" && rawAmount !== "0";
-      return {
-        agent: "zyfai",
-        action: (entry.action ? actionMap[entry.action] : void 0) ?? entry.action,
-        date: entry.date || "",
-        newApy: String(newApy),
-        oldApy: String(oldApy),
-        transactions: [
-          {
-            txHashes: entry.transactionHash ? [entry.transactionHash] : [],
-            chainId: entry.chainId,
-            tokenSymbol: entry?.positions?.[0]?.token_symbol,
-            amount: hasAmount ? String(hexToDecimal(rawAmount)) : void 0
-          }
-        ],
-        rebalanceLog
-      };
-    })
-  };
+  return rawEntries.map((entry) => {
+    const rawLog = entry.rebalanceLog;
+    const positions = entry.positions ?? [];
+    let rebalanceLog = [];
+    let oldApy = null;
+    let newApy = null;
+    if (rawLog) {
+      const matched = positions.find(
+        (p) => p.protocol_name ? rawLog.newOpportunity.includes(`${p.protocol_name} (${p.pool})`) : false
+      );
+      oldApy = Number(rawLog.oldApy);
+      newApy = Number(rawLog.newApy);
+      rebalanceLog = [
+        {
+          fromProtocol: rawLog.oldOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
+          toProtocol: rawLog.newOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
+          tokenSymbol: matched?.token_symbol ?? "",
+          amount: matched ? String(hexToDecimal(matched.amount || "0x")) : "",
+          status: "success"
+        }
+      ];
+    }
+    const rawAmount = entry?.positions?.[0]?.amount;
+    const hasAmount = typeof rawAmount === "string" && rawAmount !== "" && rawAmount !== "0x" && rawAmount !== "0x0" && rawAmount !== "0";
+    return {
+      agent: "zyfai",
+      action: (entry.action ? actionMap[entry.action] : void 0) ?? entry.action,
+      date: entry.date || "",
+      newApy: newApy === null ? null : String(newApy),
+      oldApy: oldApy === null ? null : String(oldApy),
+      transactions: [
+        {
+          txHashes: entry.transactionHash ? [entry.transactionHash] : [],
+          chainId: entry.chainId,
+          tokenSymbol: entry?.positions?.[0]?.token_symbol,
+          amount: hasAmount ? String(hexToDecimal(rawAmount)) : void 0
+        }
+      ],
+      rebalanceLog
+    };
+  });
 }
 function mapAgentStatus(raw) {
   return {
@@ -333,6 +331,33 @@ function mapApyByStrategy(raw) {
   };
 }
 
+// src/agents/zyfai/zyfai.history-cursor.ts
+var InvalidHistoryCursorError = class extends Error {
+  code = "invalid_cursor";
+  constructor(message) {
+    super(message);
+    this.name = "InvalidHistoryCursorError";
+  }
+};
+function encodeHistoryCursor(payload) {
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function decodeHistoryCursor(token) {
+  if (!token)
+    throw new InvalidHistoryCursorError("Cursor is empty.");
+  let parsed;
+  try {
+    const json = Buffer.from(token, "base64").toString("utf8");
+    parsed = JSON.parse(json);
+  } catch {
+    throw new InvalidHistoryCursorError("Cursor is not valid base64 JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || typeof parsed.toDate !== "string" || parsed.toDate.length === 0 || Number.isNaN(Date.parse(parsed.toDate)) || typeof parsed.rawOffset !== "number" || !Number.isFinite(parsed.rawOffset) || parsed.rawOffset < 0 || !Number.isInteger(parsed.rawOffset)) {
+    throw new InvalidHistoryCursorError("Cursor payload has wrong shape.");
+  }
+  return parsed;
+}
+
 // src/agents/zyfai/zyfai.auth-cache.ts
 var KEY_PREFIX = "owney.zyfai.session";
 var storage = () => {
@@ -647,8 +672,38 @@ var ZyfaiAgent = class {
   }
   async getHistory(state, chainId, options) {
     const { smartWallet, chainId: validChainId } = await this.resolveSmartWallet(state, chainId);
-    const raw = await this.sdk.getHistory(smartWallet, validChainId, options);
-    return mapHistory(raw, validChainId);
+    const limit = options?.limit ?? 10;
+    const cursor = options?.cursor ? decodeHistoryCursor(options.cursor) : null;
+    const toDate = cursor?.toDate ?? options?.toDate ?? (/* @__PURE__ */ new Date()).toISOString();
+    let offset = cursor?.rawOffset ?? 0;
+    const MAX_BACKEND_CALLS = 5;
+    const MIN_BACKEND_PAGE_SIZE = 20;
+    const backendPageSize = Math.max(limit, MIN_BACKEND_PAGE_SIZE);
+    const matched = [];
+    let backendExhausted = false;
+    for (let i = 0; i < MAX_BACKEND_CALLS && matched.length < limit; i++) {
+      const raw = await this.sdk.getHistory(smartWallet, validChainId, {
+        limit: backendPageSize,
+        offset,
+        fromDate: options?.fromDate,
+        toDate
+      });
+      matched.push(...raw.data.filter((e) => e.chainId === validChainId));
+      offset += raw.data.length;
+      if (raw.data.length < backendPageSize) {
+        backendExhausted = true;
+        break;
+      }
+    }
+    const overshoot = Math.max(0, matched.length - limit);
+    const pageData = matched.slice(0, limit);
+    const hasMore = !backendExhausted || overshoot > 0;
+    const nextCursor = hasMore ? encodeHistoryCursor({ toDate, rawOffset: offset - overshoot }) : void 0;
+    return {
+      data: mapEntries(pageData, validChainId),
+      hasMore,
+      nextCursor
+    };
   }
   // --- IAgent: Agent control ---
   async pause(state, chainId) {
@@ -840,6 +895,26 @@ function aggregateApyByChainAndAsset(agentApys, agentBalances) {
 }
 
 // src/client.ts
+function encodeMultiAgentCursor(map) {
+  return Buffer.from(JSON.stringify(map), "utf8").toString("base64");
+}
+function decodeMultiAgentCursor(token) {
+  let parsed;
+  try {
+    const json = Buffer.from(token, "base64").toString("utf8");
+    parsed = JSON.parse(json);
+  } catch {
+    throw new InvalidHistoryCursorError(
+      "Multi-agent cursor is not valid base64 JSON."
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || !Object.values(parsed).every((v) => typeof v === "string")) {
+    throw new InvalidHistoryCursorError(
+      "Multi-agent cursor payload has wrong shape."
+    );
+  }
+  return parsed;
+}
 var OwneySDK = class {
   agents = /* @__PURE__ */ new Map();
   activeAgents = /* @__PURE__ */ new Set();
@@ -1509,10 +1584,20 @@ var OwneySDK = class {
   }
   /**
    * Get transaction history for a specific agent, or all agents.
-   * @param params - Optional. Contains agentId and filters.
-   * @param params.agentId - Optional. Agent to query. Omit for all agents.
-   * @param params.filters - Optional. Pagination and date filters (fromDate, toDate)
-   * @returns {OwneyAgentHistory} with per-agent history
+   *
+   * Pagination uses an opaque cursor (`filters.cursor`). The first call without
+   * a cursor anchors a snapshot at "now"; subsequent pages within that snapshot
+   * are stable. Each cursorless call captures a NEW snapshot, so do not mix
+   * cursors issued by different first-page calls — refreshes that need to
+   * preserve the user's scroll position should keep using cursors from the
+   * original snapshot.
+   *
+   * @param params.agentId - Optional. Agent to query. Omit for all active agents.
+   * @param params.filters - Optional. Pagination + date filters.
+   *   - `limit`: max entries per page (default 10)
+   *   - `cursor`: opaque cursor returned by a previous call
+   *   - `fromDate` / `toDate`: ISO 8601 date strings
+   * @returns {OwneyAgentHistory} `data` (up to `limit` entries), `hasMore`, `nextCursor`.
    */
   async getHistory(params) {
     const state = this.requireState();
@@ -1521,21 +1606,40 @@ var OwneySDK = class {
     if (agentId) {
       return this.getAgent(agentId).getHistory(state, chainId, filters);
     }
-    const historyResults = await Promise.all(
-      [...this.getActiveAgents().values()].map(
-        (agent) => agent.getHistory(state, chainId, filters)
-      )
+    const activeAgents = [...this.getActiveAgents().values()];
+    const cursorMap = filters?.cursor ? decodeMultiAgentCursor(filters.cursor) : {};
+    const perAgent = await Promise.all(
+      activeAgents.map(async (agent) => {
+        const agentCursor = cursorMap[agent.id];
+        if (filters?.cursor && agentCursor === void 0) {
+          return { agentId: agent.id, page: null };
+        }
+        const page = await agent.getHistory(state, chainId, {
+          ...filters,
+          cursor: agentCursor
+        });
+        return { agentId: agent.id, page };
+      })
     );
-    let results = [];
-    for (const { data } of historyResults) {
-      results = [...results, ...data];
+    const merged = [];
+    const nextCursorMap = {};
+    let hasMore = false;
+    for (const { agentId: id, page } of perAgent) {
+      if (!page)
+        continue;
+      merged.push(...page.data);
+      if (page.hasMore && page.nextCursor) {
+        nextCursorMap[id] = page.nextCursor;
+        hasMore = true;
+      }
     }
-    results.sort(
+    merged.sort(
       (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()
     );
     return {
-      total: results.length,
-      data: results
+      data: merged,
+      hasMore,
+      nextCursor: hasMore ? encodeMultiAgentCursor(nextCursorMap) : void 0
     };
   }
   // --- Agent control ---
@@ -1690,6 +1794,7 @@ var OwneySDK = class {
 0 && (module.exports = {
   AgentChainIncompatibleError,
   AgentNotFoundError,
+  InvalidHistoryCursorError,
   NotConnectedError,
   OwneyError,
   OwneySDK

package/dist/index.d.cts

@@ -48,7 +48,7 @@ type AgentApyOptions = {
     chainId?: number;
 };
 
-type AgentId = "zyfai";
+type AgentId = "zyfai" | "sail";
 type Asset = string;
 type AgentSupportedAsset = {
     readonly symbol: string;
@@ -63,6 +63,10 @@ type DailyApyDays = "7D" | "14D" | "30D";
 type HistoryFilters = {
     fromDate?: string;
     toDate?: string;
+    /** Max entries returned per call. Defaults to 10. */
+    limit?: number;
+    /** Opaque cursor returned by a previous getHistory call. */
+    cursor?: string;
 };
 type HistoryOptions = {
     agentId?: AgentId;
@@ -177,7 +181,10 @@ interface AgentHistoryEntry {
 }
 interface OwneyAgentHistory {
     data: AgentHistoryEntry[];
-    total: number;
+    /** True iff a subsequent page exists; pair with `nextCursor`. */
+    hasMore: boolean;
+    /** Opaque cursor for the next page. Present iff `hasMore === true`. */
+    nextCursor?: string;
 }
 interface OwneyAgentStatus {
     success: boolean;
@@ -320,10 +327,20 @@ declare class OwneySDK {
     getAccountApy({ agentId, days, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
     /**
      * Get transaction history for a specific agent, or all agents.
-     * @param params - Optional. Contains agentId and filters.
-     * @param params.agentId - Optional. Agent to query. Omit for all agents.
-     * @param params.filters - Optional. Pagination and date filters (fromDate, toDate)
-     * @returns {OwneyAgentHistory} with per-agent history
+     *
+     * Pagination uses an opaque cursor (`filters.cursor`). The first call without
+     * a cursor anchors a snapshot at "now"; subsequent pages within that snapshot
+     * are stable. Each cursorless call captures a NEW snapshot, so do not mix
+     * cursors issued by different first-page calls — refreshes that need to
+     * preserve the user's scroll position should keep using cursors from the
+     * original snapshot.
+     *
+     * @param params.agentId - Optional. Agent to query. Omit for all active agents.
+     * @param params.filters - Optional. Pagination + date filters.
+     *   - `limit`: max entries per page (default 10)
+     *   - `cursor`: opaque cursor returned by a previous call
+     *   - `fromDate` / `toDate`: ISO 8601 date strings
+     * @returns {OwneyAgentHistory} `data` (up to `limit` entries), `hasMore`, `nextCursor`.
      */
     getHistory(params?: HistoryOptions): Promise<OwneyAgentHistory>;
     /**
@@ -389,4 +406,9 @@ declare class AgentChainIncompatibleError extends OwneyError {
     }>, connectedChainId: number);
 }
 
-export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAgentStatus, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneySDK, OwneySDKConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions };
+declare class InvalidHistoryCursorError extends Error {
+    readonly code: "invalid_cursor";
+    constructor(message: string);
+}
+
+export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, InvalidHistoryCursorError, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAgentStatus, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneySDK, OwneySDKConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions };

package/dist/index.d.ts

@@ -48,7 +48,7 @@ type AgentApyOptions = {
     chainId?: number;
 };
 
-type AgentId = "zyfai";
+type AgentId = "zyfai" | "sail";
 type Asset = string;
 type AgentSupportedAsset = {
     readonly symbol: string;
@@ -63,6 +63,10 @@ type DailyApyDays = "7D" | "14D" | "30D";
 type HistoryFilters = {
     fromDate?: string;
     toDate?: string;
+    /** Max entries returned per call. Defaults to 10. */
+    limit?: number;
+    /** Opaque cursor returned by a previous getHistory call. */
+    cursor?: string;
 };
 type HistoryOptions = {
     agentId?: AgentId;
@@ -177,7 +181,10 @@ interface AgentHistoryEntry {
 }
 interface OwneyAgentHistory {
     data: AgentHistoryEntry[];
-    total: number;
+    /** True iff a subsequent page exists; pair with `nextCursor`. */
+    hasMore: boolean;
+    /** Opaque cursor for the next page. Present iff `hasMore === true`. */
+    nextCursor?: string;
 }
 interface OwneyAgentStatus {
     success: boolean;
@@ -320,10 +327,20 @@ declare class OwneySDK {
     getAccountApy({ agentId, days, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
     /**
      * Get transaction history for a specific agent, or all agents.
-     * @param params - Optional. Contains agentId and filters.
-     * @param params.agentId - Optional. Agent to query. Omit for all agents.
-     * @param params.filters - Optional. Pagination and date filters (fromDate, toDate)
-     * @returns {OwneyAgentHistory} with per-agent history
+     *
+     * Pagination uses an opaque cursor (`filters.cursor`). The first call without
+     * a cursor anchors a snapshot at "now"; subsequent pages within that snapshot
+     * are stable. Each cursorless call captures a NEW snapshot, so do not mix
+     * cursors issued by different first-page calls — refreshes that need to
+     * preserve the user's scroll position should keep using cursors from the
+     * original snapshot.
+     *
+     * @param params.agentId - Optional. Agent to query. Omit for all active agents.
+     * @param params.filters - Optional. Pagination + date filters.
+     *   - `limit`: max entries per page (default 10)
+     *   - `cursor`: opaque cursor returned by a previous call
+     *   - `fromDate` / `toDate`: ISO 8601 date strings
+     * @returns {OwneyAgentHistory} `data` (up to `limit` entries), `hasMore`, `nextCursor`.
      */
     getHistory(params?: HistoryOptions): Promise<OwneyAgentHistory>;
     /**
@@ -389,4 +406,9 @@ declare class AgentChainIncompatibleError extends OwneyError {
     }>, connectedChainId: number);
 }
 
-export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAgentStatus, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneySDK, OwneySDKConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions };
+declare class InvalidHistoryCursorError extends Error {
+    readonly code: "invalid_cursor";
+    constructor(message: string);
+}
+
+export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, InvalidHistoryCursorError, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAgentStatus, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneySDK, OwneySDKConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions };

package/dist/index.js

@@ -207,7 +207,7 @@ function mapApyHistory(raw) {
     apyByChainAndAsset: mapWeightedApyByChain(raw.weightedApyAfterFeeByChain)
   };
 }
-function mapHistory(raw, chainId) {
+function mapEntries(rawEntries, chainId) {
   const actionMap = {
     "Deposit to protocol": "Deposit",
     "Top up wallet": "Top up",
@@ -215,50 +215,47 @@ function mapHistory(raw, chainId) {
     "Withdraw from protocol": "Withdraw",
     Rebalance: "Rebalance"
   };
-  return {
-    total: raw.total,
-    data: raw.data.filter((d) => d.chainId === chainId).map((entry) => {
-      const rawLog = entry.rebalanceLog;
-      const positions = entry.positions ?? [];
-      let rebalanceLog = [];
-      let oldApy = null;
-      let newApy = null;
-      if (rawLog) {
-        const matched = positions.find(
-          (p) => p.protocol_name ? rawLog.newOpportunity.includes(`${p.protocol_name} (${p.pool})`) : false
-        );
-        oldApy = Number(rawLog.oldApy);
-        newApy = Number(rawLog.newApy);
-        rebalanceLog = [
-          {
-            fromProtocol: rawLog.oldOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
-            toProtocol: rawLog.newOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
-            tokenSymbol: matched?.token_symbol ?? "",
-            amount: matched ? String(hexToDecimal(matched.amount || "0x")) : "",
-            status: "success"
-          }
-        ];
-      }
-      const rawAmount = entry?.positions?.[0]?.amount;
-      const hasAmount = typeof rawAmount === "string" && rawAmount !== "" && rawAmount !== "0x" && rawAmount !== "0x0" && rawAmount !== "0";
-      return {
-        agent: "zyfai",
-        action: (entry.action ? actionMap[entry.action] : void 0) ?? entry.action,
-        date: entry.date || "",
-        newApy: String(newApy),
-        oldApy: String(oldApy),
-        transactions: [
-          {
-            txHashes: entry.transactionHash ? [entry.transactionHash] : [],
-            chainId: entry.chainId,
-            tokenSymbol: entry?.positions?.[0]?.token_symbol,
-            amount: hasAmount ? String(hexToDecimal(rawAmount)) : void 0
-          }
-        ],
-        rebalanceLog
-      };
-    })
-  };
+  return rawEntries.map((entry) => {
+    const rawLog = entry.rebalanceLog;
+    const positions = entry.positions ?? [];
+    let rebalanceLog = [];
+    let oldApy = null;
+    let newApy = null;
+    if (rawLog) {
+      const matched = positions.find(
+        (p) => p.protocol_name ? rawLog.newOpportunity.includes(`${p.protocol_name} (${p.pool})`) : false
+      );
+      oldApy = Number(rawLog.oldApy);
+      newApy = Number(rawLog.newApy);
+      rebalanceLog = [
+        {
+          fromProtocol: rawLog.oldOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
+          toProtocol: rawLog.newOpportunity.replace(/\s*\(.*?\)/g, "").trim(),
+          tokenSymbol: matched?.token_symbol ?? "",
+          amount: matched ? String(hexToDecimal(matched.amount || "0x")) : "",
+          status: "success"
+        }
+      ];
+    }
+    const rawAmount = entry?.positions?.[0]?.amount;
+    const hasAmount = typeof rawAmount === "string" && rawAmount !== "" && rawAmount !== "0x" && rawAmount !== "0x0" && rawAmount !== "0";
+    return {
+      agent: "zyfai",
+      action: (entry.action ? actionMap[entry.action] : void 0) ?? entry.action,
+      date: entry.date || "",
+      newApy: newApy === null ? null : String(newApy),
+      oldApy: oldApy === null ? null : String(oldApy),
+      transactions: [
+        {
+          txHashes: entry.transactionHash ? [entry.transactionHash] : [],
+          chainId: entry.chainId,
+          tokenSymbol: entry?.positions?.[0]?.token_symbol,
+          amount: hasAmount ? String(hexToDecimal(rawAmount)) : void 0
+        }
+      ],
+      rebalanceLog
+    };
+  });
 }
 function mapAgentStatus(raw) {
   return {
@@ -303,6 +300,33 @@ function mapApyByStrategy(raw) {
   };
 }
 
+// src/agents/zyfai/zyfai.history-cursor.ts
+var InvalidHistoryCursorError = class extends Error {
+  code = "invalid_cursor";
+  constructor(message) {
+    super(message);
+    this.name = "InvalidHistoryCursorError";
+  }
+};
+function encodeHistoryCursor(payload) {
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function decodeHistoryCursor(token) {
+  if (!token)
+    throw new InvalidHistoryCursorError("Cursor is empty.");
+  let parsed;
+  try {
+    const json = Buffer.from(token, "base64").toString("utf8");
+    parsed = JSON.parse(json);
+  } catch {
+    throw new InvalidHistoryCursorError("Cursor is not valid base64 JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || typeof parsed.toDate !== "string" || parsed.toDate.length === 0 || Number.isNaN(Date.parse(parsed.toDate)) || typeof parsed.rawOffset !== "number" || !Number.isFinite(parsed.rawOffset) || parsed.rawOffset < 0 || !Number.isInteger(parsed.rawOffset)) {
+    throw new InvalidHistoryCursorError("Cursor payload has wrong shape.");
+  }
+  return parsed;
+}
+
 // src/agents/zyfai/zyfai.auth-cache.ts
 var KEY_PREFIX = "owney.zyfai.session";
 var storage = () => {
@@ -617,8 +641,38 @@ var ZyfaiAgent = class {
   }
   async getHistory(state, chainId, options) {
     const { smartWallet, chainId: validChainId } = await this.resolveSmartWallet(state, chainId);
-    const raw = await this.sdk.getHistory(smartWallet, validChainId, options);
-    return mapHistory(raw, validChainId);
+    const limit = options?.limit ?? 10;
+    const cursor = options?.cursor ? decodeHistoryCursor(options.cursor) : null;
+    const toDate = cursor?.toDate ?? options?.toDate ?? (/* @__PURE__ */ new Date()).toISOString();
+    let offset = cursor?.rawOffset ?? 0;
+    const MAX_BACKEND_CALLS = 5;
+    const MIN_BACKEND_PAGE_SIZE = 20;
+    const backendPageSize = Math.max(limit, MIN_BACKEND_PAGE_SIZE);
+    const matched = [];
+    let backendExhausted = false;
+    for (let i = 0; i < MAX_BACKEND_CALLS && matched.length < limit; i++) {
+      const raw = await this.sdk.getHistory(smartWallet, validChainId, {
+        limit: backendPageSize,
+        offset,
+        fromDate: options?.fromDate,
+        toDate
+      });
+      matched.push(...raw.data.filter((e) => e.chainId === validChainId));
+      offset += raw.data.length;
+      if (raw.data.length < backendPageSize) {
+        backendExhausted = true;
+        break;
+      }
+    }
+    const overshoot = Math.max(0, matched.length - limit);
+    const pageData = matched.slice(0, limit);
+    const hasMore = !backendExhausted || overshoot > 0;
+    const nextCursor = hasMore ? encodeHistoryCursor({ toDate, rawOffset: offset - overshoot }) : void 0;
+    return {
+      data: mapEntries(pageData, validChainId),
+      hasMore,
+      nextCursor
+    };
   }
   // --- IAgent: Agent control ---
   async pause(state, chainId) {
@@ -810,6 +864,26 @@ function aggregateApyByChainAndAsset(agentApys, agentBalances) {
 }
 
 // src/client.ts
+function encodeMultiAgentCursor(map) {
+  return Buffer.from(JSON.stringify(map), "utf8").toString("base64");
+}
+function decodeMultiAgentCursor(token) {
+  let parsed;
+  try {
+    const json = Buffer.from(token, "base64").toString("utf8");
+    parsed = JSON.parse(json);
+  } catch {
+    throw new InvalidHistoryCursorError(
+      "Multi-agent cursor is not valid base64 JSON."
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || !Object.values(parsed).every((v) => typeof v === "string")) {
+    throw new InvalidHistoryCursorError(
+      "Multi-agent cursor payload has wrong shape."
+    );
+  }
+  return parsed;
+}
 var OwneySDK = class {
   agents = /* @__PURE__ */ new Map();
   activeAgents = /* @__PURE__ */ new Set();
@@ -1479,10 +1553,20 @@ var OwneySDK = class {
   }
   /**
    * Get transaction history for a specific agent, or all agents.
-   * @param params - Optional. Contains agentId and filters.
-   * @param params.agentId - Optional. Agent to query. Omit for all agents.
-   * @param params.filters - Optional. Pagination and date filters (fromDate, toDate)
-   * @returns {OwneyAgentHistory} with per-agent history
+   *
+   * Pagination uses an opaque cursor (`filters.cursor`). The first call without
+   * a cursor anchors a snapshot at "now"; subsequent pages within that snapshot
+   * are stable. Each cursorless call captures a NEW snapshot, so do not mix
+   * cursors issued by different first-page calls — refreshes that need to
+   * preserve the user's scroll position should keep using cursors from the
+   * original snapshot.
+   *
+   * @param params.agentId - Optional. Agent to query. Omit for all active agents.
+   * @param params.filters - Optional. Pagination + date filters.
+   *   - `limit`: max entries per page (default 10)
+   *   - `cursor`: opaque cursor returned by a previous call
+   *   - `fromDate` / `toDate`: ISO 8601 date strings
+   * @returns {OwneyAgentHistory} `data` (up to `limit` entries), `hasMore`, `nextCursor`.
    */
   async getHistory(params) {
     const state = this.requireState();
@@ -1491,21 +1575,40 @@ var OwneySDK = class {
     if (agentId) {
       return this.getAgent(agentId).getHistory(state, chainId, filters);
     }
-    const historyResults = await Promise.all(
-      [...this.getActiveAgents().values()].map(
-        (agent) => agent.getHistory(state, chainId, filters)
-      )
+    const activeAgents = [...this.getActiveAgents().values()];
+    const cursorMap = filters?.cursor ? decodeMultiAgentCursor(filters.cursor) : {};
+    const perAgent = await Promise.all(
+      activeAgents.map(async (agent) => {
+        const agentCursor = cursorMap[agent.id];
+        if (filters?.cursor && agentCursor === void 0) {
+          return { agentId: agent.id, page: null };
+        }
+        const page = await agent.getHistory(state, chainId, {
+          ...filters,
+          cursor: agentCursor
+        });
+        return { agentId: agent.id, page };
+      })
     );
-    let results = [];
-    for (const { data } of historyResults) {
-      results = [...results, ...data];
+    const merged = [];
+    const nextCursorMap = {};
+    let hasMore = false;
+    for (const { agentId: id, page } of perAgent) {
+      if (!page)
+        continue;
+      merged.push(...page.data);
+      if (page.hasMore && page.nextCursor) {
+        nextCursorMap[id] = page.nextCursor;
+        hasMore = true;
+      }
     }
-    results.sort(
+    merged.sort(
       (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()
     );
     return {
-      total: results.length,
-      data: results
+      data: merged,
+      hasMore,
+      nextCursor: hasMore ? encodeMultiAgentCursor(nextCursorMap) : void 0
     };
   }
   // --- Agent control ---
@@ -1659,6 +1762,7 @@ var OwneySDK = class {
 export {
   AgentChainIncompatibleError,
   AgentNotFoundError,
+  InvalidHistoryCursorError,
   NotConnectedError,
   OwneyError,
   OwneySDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owney/sdk",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",