feat(data): align combo fields and history ceilings

.changeset/data-history-contract.md

@@ -0,0 +1,6 @@
+---
+"@polymarket/bindings": patch
+"@polymarket/client": patch
+---
+
+Preserve exact combo entry-basis fields and reject Data history pagination past documented offset ceilings.

packages/bindings/src/data/portfolio.ts

@@ -3,6 +3,7 @@ import {
   ComboConditionIdSchema,
   ConditionIdSchema,
   DecimalishSchema,
+  DecimalStringSchema,
   EpochSecondsToMillisecondsSchema,
   emptyStringToNull,
   IsoCalendarDateStringSchema,
@@ -211,6 +212,8 @@ export const ComboPositionSchema = z
     shares_balance: DecimalishSchema,
     entry_avg_price_usdc: DecimalishSchema.nullish(),
     entry_cost_usdc: DecimalishSchema.nullish(),
+    gross_entry_cost_usdc: DecimalStringSchema.nullish(),
+    entry_fees_usdc: DecimalStringSchema.nullish(),
     realized_payout_usdc: DecimalishSchema.nullish(),
     total_cost_usdc: DecimalishSchema.nullish(),
     status: ComboPositionStatusSchema,
@@ -233,6 +236,8 @@ export const ComboPositionSchema = z
       shares_balance,
       entry_avg_price_usdc,
       entry_cost_usdc,
+      gross_entry_cost_usdc,
+      entry_fees_usdc,
       realized_payout_usdc,
       total_cost_usdc,
       first_entry_at,
@@ -252,6 +257,8 @@ export const ComboPositionSchema = z
       shares: shares_balance,
       entryAvgPriceUsdc: entry_avg_price_usdc,
       entryCostUsdc: entry_cost_usdc,
+      grossEntryCostUsdc: gross_entry_cost_usdc,
+      entryFeesUsdc: entry_fees_usdc,
       realizedPayoutUsdc: realized_payout_usdc,
       totalCostUsdc: total_cost_usdc,
       firstEntryAt: first_entry_at,

packages/client/src/actions/activity.ts

@@ -25,7 +25,7 @@ import {
 import { parseUserInput } from '../input';
 import {
   decodeOffsetCursor,
-  encodeOffsetCursor,
+  offsetContinuation,
   PageSizeSchema,
   type Paginated,
   paginate,
@@ -35,6 +35,9 @@ import { snakeCase, toDataSearchParams, toSearchParams } from './params';
 
 export { ComboActivityType } from '@polymarket/bindings/data';
 
+const MAX_TRADES_OFFSET = 10_000;
+const MAX_ACTIVITY_OFFSET = 5_000;
+
 const TradeFilterTypeSchema = z.enum(['CASH', 'TOKENS']);
 
 const ListTradesRequestSchema = z
@@ -86,6 +89,12 @@ export const ListTradesError = makeErrorGuard(
  * @remarks
  * This is a low-level function. Most SDK consumers should prefer the client instance API.
  *
+ * Pagination rejects continuation past the documented 10,000 offset ceiling.
+ * Use `start` and `end` to query bounded time windows when deeper history is
+ * required. Without `start`, queries default to roughly three years of
+ * history. A positive `start` can extend user-scoped queries further back,
+ * while market- and event-scoped queries retain the three-year floor.
+ *
  * @throws {@link ListTradesError}
  * Thrown on failure.
  *
@@ -128,7 +137,7 @@ export function listTrades(
   );
 
   return paginate((cursor) => {
-    const decoded = decodeOffsetCursor(cursor, pageSize);
+    const decoded = decodeOffsetCursor(cursor, pageSize, MAX_TRADES_OFFSET);
 
     return client.data
       .get('/trades', {
@@ -140,17 +149,9 @@ export function listTrades(
       })
       .andThen(validateWith(ListTradesResponseSchema))
       .map((trades) => {
-        const hasMore = trades.length >= decoded.pageSize;
-
         return {
           items: trades,
-          hasMore,
-          nextCursor: hasMore
-            ? encodeOffsetCursor({
-                offset: decoded.offset + decoded.pageSize,
-                pageSize: decoded.pageSize,
-              })
-            : undefined,
+          ...offsetContinuation(decoded, trades.length >= decoded.pageSize),
         };
       });
   }, cursor);
@@ -203,6 +204,11 @@ export const ListActivityError = makeErrorGuard(
  * @remarks
  * This is a low-level function. Most SDK consumers should prefer the client instance API.
  *
+ * Pagination rejects continuation past the documented 5,000 offset ceiling.
+ * Use `start` and `end` to query bounded time windows when deeper history is
+ * required. Without `start`, descending queries default to roughly three
+ * years of history; ascending queries read from the beginning.
+ *
  * @throws {@link ListActivityError}
  * Thrown on failure.
  *
@@ -245,7 +251,7 @@ export function listActivity(
   );
 
   return paginate((cursor) => {
-    const decoded = decodeOffsetCursor(cursor, pageSize);
+    const decoded = decodeOffsetCursor(cursor, pageSize, MAX_ACTIVITY_OFFSET);
 
     return client.data
       .get('/activity', {
@@ -262,17 +268,9 @@ export function listActivity(
       })
       .andThen(validateWith(ListActivityResponseSchema))
       .map((activity) => {
-        const hasMore = activity.length >= decoded.pageSize;
-
         return {
           items: activity,
-          hasMore,
-          nextCursor: hasMore
-            ? encodeOffsetCursor({
-                offset: decoded.offset + decoded.pageSize,
-                pageSize: decoded.pageSize,
-              })
-            : undefined,
+          ...offsetContinuation(decoded, activity.length >= decoded.pageSize),
         };
       });
   }, cursor);

packages/client/src/decorators/account.ts

@@ -261,6 +261,10 @@ export type PublicAccountActions = Prettify<
      * Lists wallet activity.
      *
      * All activity types are returned by default, including deposits and withdrawals; use the `type` filter to narrow results.
+     * Pagination rejects continuation past offset 5,000. Without `start`,
+     * descending queries default to roughly three years of history; ascending
+     * queries read from the beginning. Use `start` and `end` to split deeper
+     * history into bounded windows.
      *
      * @throws {@link ListActivityError}
      * Thrown on failure.
@@ -400,6 +404,10 @@ export type SecureAccountActions = Prettify<
      * Defaults to the authenticated account's wallet when `user` is omitted.
      *
      * All activity types are returned by default, including deposits and withdrawals; use the `type` filter to narrow results.
+     * Pagination rejects continuation past offset 5,000. Without `start`,
+     * descending queries default to roughly three years of history; ascending
+     * queries read from the beginning. Use `start` and `end` to split deeper
+     * history into bounded windows.
      *
      * @throws {@link ListActivityError}
      * Thrown on failure.

packages/client/src/decorators/data.ts

@@ -268,6 +268,12 @@ export type DataActions = {
   /**
    * Lists trades for a wallet, market, or event.
    *
+   * Pagination rejects continuation past offset 10,000. Without `start`,
+   * queries default to roughly three years of history. A positive `start` can
+   * extend user-scoped queries further back, while market- and event-scoped
+   * queries retain the three-year floor. Use `start` and `end` to split deeper
+   * history into bounded windows.
+   *
    * @throws {@link ListTradesError}
    * Thrown on failure.
    *

packages/client/src/pagination.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { UserInputError } from './errors';
+import {
+  decodeOffsetCursor,
+  encodeOffsetCursor,
+  offsetContinuation,
+  paginate,
+} from './pagination';
+
+describe('capped offset pagination', () => {
+  it('allows the last documented offset', () => {
+    const cursor = encodeOffsetCursor({ offset: 10_000, pageSize: 500 });
+
+    expect(decodeOffsetCursor(cursor, 1, 10_000)).toEqual({
+      offset: 10_000,
+      pageSize: 500,
+    });
+  });
+
+  it('rejects a supplied cursor above the ceiling', () => {
+    const cursor = encodeOffsetCursor({ offset: 10_001, pageSize: 20 });
+
+    expect(() => decodeOffsetCursor(cursor, 20, 10_000)).toThrow(
+      UserInputError,
+    );
+  });
+
+  it('signals truncation by rejecting the continuation after the ceiling', () => {
+    const continuation = offsetContinuation(
+      { offset: 10_000, pageSize: 500 },
+      true,
+    );
+
+    expect(continuation.hasMore).toBe(true);
+    expect(() =>
+      decodeOffsetCursor(continuation.nextCursor, 500, 10_000),
+    ).toThrow(UserInputError);
+  });
+
+  it('rejects synchronous page setup failures through the promise contract', async () => {
+    const failure = new UserInputError('Invalid page');
+    const paginator = paginate(() => {
+      throw failure;
+    });
+
+    await expect(paginator.firstPage()).rejects.toBe(failure);
+  });
+});

packages/client/src/pagination.ts

@@ -63,7 +63,7 @@ export function paginate<T, TError>(
 
   function createPaginator(cursor = initialCursor): Paginated<T> {
     return {
-      firstPage() {
+      async firstPage() {
         return unwrap(fetchPage(cursor));
       },
       from(nextCursor) {
@@ -101,10 +101,31 @@ export function encodeOffsetCursor(state: OffsetCursorState): PaginationCursor {
   );
 }
 
+/** @internal */
+export function offsetContinuation(
+  state: OffsetCursorState,
+  pageHasMore: boolean,
+):
+  | { hasMore: false; nextCursor?: undefined }
+  | { hasMore: true; nextCursor: PaginationCursor } {
+  if (!pageHasMore) {
+    return { hasMore: false };
+  }
+
+  return {
+    hasMore: true,
+    nextCursor: encodeOffsetCursor({
+      offset: state.offset + state.pageSize,
+      pageSize: state.pageSize,
+    }),
+  };
+}
+
 /** @internal */
 export function decodeOffsetCursor(
   cursor: PaginationCursor | undefined,
   pageSize: number,
+  maxOffset?: number,
 ): OffsetCursorState {
   if (cursor === undefined) {
     return {
@@ -113,9 +134,18 @@ export function decodeOffsetCursor(
     };
   }
 
+  let state: OffsetCursorState;
   try {
-    return OffsetCursorStateSchema.parse(JSON.parse(atob(cursor)));
+    state = OffsetCursorStateSchema.parse(JSON.parse(atob(cursor)));
   } catch (error) {
     throw new UserInputError('Invalid pagination cursor', { cause: error });
   }
+
+  if (maxOffset !== undefined && state.offset > maxOffset) {
+    throw new UserInputError(
+      `Pagination cannot continue past the endpoint maximum offset of ${maxOffset}; narrow the query before continuing`,
+    );
+  }
+
+  return state;
 }

packages/client/src/websockets/perps/session.test.ts

@@ -1497,21 +1497,16 @@ describe('PerpsSession', () => {
       });
     });
 
-    it('throws user input errors for invalid account pagination cursors', () => {
+    it('rejects user input errors for invalid account pagination cursors', async () => {
       const cursor = toPaginationCursor(
         btoa(JSON.stringify({ kind: 'perpsTrades' })),
       );
       const session = createSession();
 
-      let thrown: unknown;
-      try {
-        session.listFundingPayments({ cursor }).firstPage();
-      } catch (error) {
-        thrown = error;
-      }
-
-      expect(thrown).toBeInstanceOf(UserInputError);
-      expect(thrown).toMatchObject({
+      await expect(
+        session.listFundingPayments({ cursor }).firstPage(),
+      ).rejects.toMatchObject({
+        name: UserInputError.name,
         message: 'Invalid Perps account pagination cursor',
         cause: expect.any(Error),
       });

packages/client/tests/integration/activity.test.ts

@@ -1,17 +1,28 @@
-import { ActivityType, ComboActivityType } from '@polymarket/client';
+import {
+  ActivityType,
+  ComboActivityType,
+  UserInputError,
+} from '@polymarket/client';
 import { expectPresent, isSameEvmAddress } from '@polymarket/types';
+import { afterEach, vi } from 'vitest';
 import { describe, expect, it } from './fixtures';
 import { expectNonEmptyPage, expectPageWindow } from './helpers';
 
 const TEST_USER = '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b';
 
 describe('Activity', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   describe('listTrades', () => {
     it('lists trades for a wallet', async ({ publicClient }) => {
       const result = await publicClient
         .listTrades({
           user: TEST_USER,
           pageSize: 1,
+          start: 1_700_000_000,
+          end: 2_000_000_000,
         })
         .firstPage();
 
@@ -34,6 +45,18 @@ describe('Activity', () => {
 
       expect(firstPage.items.length).toBeGreaterThan(0);
     });
+
+    it('rejects a cursor above the documented ceiling before transport', async ({
+      publicClient,
+    }) => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch');
+      const cursor = btoa(JSON.stringify({ offset: 10_001, pageSize: 20 }));
+
+      await expect(
+        publicClient.listTrades({ cursor: cursor as never }).firstPage(),
+      ).rejects.toThrow(UserInputError);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe('listActivity', () => {
@@ -43,6 +66,8 @@ describe('Activity', () => {
           user: TEST_USER,
           pageSize: 100,
           type: [ActivityType.TRADE],
+          start: 1_700_000_000,
+          end: 2_000_000_000,
         })
         .firstPage()
         .then(expectNonEmptyPage);
@@ -70,6 +95,20 @@ describe('Activity', () => {
         isSameEvmAddress(wallet, depositWalletAddress),
       );
     });
+
+    it('rejects a cursor above the documented ceiling before transport', async ({
+      publicClient,
+    }) => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch');
+      const cursor = btoa(JSON.stringify({ offset: 5_001, pageSize: 20 }));
+
+      await expect(
+        publicClient
+          .listActivity({ cursor: cursor as never, user: TEST_USER })
+          .firstPage(),
+      ).rejects.toThrow(UserInputError);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe('listComboActivity', () => {