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,10 @@ export const ComboPositionSchema = z
     shares_balance: DecimalishSchema,
     entry_avg_price_usdc: DecimalishSchema.nullish(),
     entry_cost_usdc: DecimalishSchema.nullish(),
+    // These fields exist to preserve the exact entry basis and must never
+    // accept numeric JSON that has already lost decimal precision.
+    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 +238,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 +259,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

@@ -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', {
@@ -203,6 +212,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 +259,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', {

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,35 @@
+import { describe, expect, it } from 'vitest';
+import { UserInputError } from './errors';
+import { decodeOffsetCursor, encodeOffsetCursor, 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 continuation computed from the last legal offset', () => {
+    const lastPage = { offset: 10_000, pageSize: 500 };
+    const cursor = encodeOffsetCursor({
+      offset: lastPage.offset + lastPage.pageSize,
+      pageSize: lastPage.pageSize,
+    });
+
+    expect(() => decodeOffsetCursor(cursor, 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

@@ -15,7 +15,9 @@ export type Page<T> = {
    *
    * On methods without a server-provided continuation signal, a full page
    * reports `true` and the follow-up request returns an empty final page when
-   * the collection ended exactly on a page boundary.
+   * the collection ended exactly on a page boundary. On offset-capped history
+   * methods, following a full page past the endpoint maximum rejects instead,
+   * so capped results are not reported as complete history.
    */
   hasMore: boolean;
   nextCursor?: PaginationCursor;
@@ -63,7 +65,7 @@ export function paginate<T, TError>(
 
   function createPaginator(cursor = initialCursor): Paginated<T> {
     return {
-      firstPage() {
+      async firstPage() {
         return unwrap(fetchPage(cursor));
       },
       from(nextCursor) {
@@ -105,6 +107,7 @@ export function encodeOffsetCursor(state: OffsetCursorState): PaginationCursor {
 export function decodeOffsetCursor(
   cursor: PaginationCursor | undefined,
   pageSize: number,
+  maxOffset?: number,
 ): OffsetCursorState {
   if (cursor === undefined) {
     return {
@@ -113,9 +116,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();
+      const result = session.listFundingPayments({ cursor }).firstPage();
 
-      let thrown: unknown;
-      try {
-        session.listFundingPayments({ cursor }).firstPage();
-      } catch (error) {
-        thrown = error;
-      }
-
-      expect(thrown).toBeInstanceOf(UserInputError);
-      expect(thrown).toMatchObject({
+      await expect(result).rejects.toBeInstanceOf(UserInputError);
+      await expect(result).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', () => {

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

@@ -107,6 +107,8 @@ describe('Portfolio', () => {
           positionId: expect.any(String),
           redeemable: expect.any(Boolean),
           wallet: TEST_USER,
+          grossEntryCostUsdc: expect.any(String),
+          entryFeesUsdc: expect.any(String),
           realizedPayoutUsdc: expect.any(String),
           totalCostUsdc: expect.any(String),
         }),