@0xmonaco/core 1.0.73 → 1.0.74-develop.367860f

package/dist/api/profile/api.js

@@ -17,7 +17,7 @@
  * console.log(`User: ${profile.username} (${profile.address})`);
  * ```
  */
-import { GetUserMovementsSchema, GetUserTradesSchema, ListFundingPaymentsSchema, SetSelfTradePreventionDefaultSchema, validate } from "@0xmonaco/types";
+import { GetUserBalancesSchema, GetUserMovementsSchema, GetUserTradesSchema, ListFundingPaymentsSchema, SetSelfTradePreventionDefaultSchema, validate, } from "@0xmonaco/types";
 import { APIError } from "../../errors";
 import { BaseAPI } from "../base";
 export class ProfileAPIImpl extends BaseAPI {
@@ -53,14 +53,19 @@ export class ProfileAPIImpl extends BaseAPI {
      * Fetches the user's transaction history from the /api/v1/accounts/movements endpoint.
      * Requires a valid access token to be set.
      *
-     * The response `total` and `totalPages` are bounded by the listing's pagination reach:
-     * exact up to `pageSize` x 10,000 rows (10,000 pages) and saturating there, so a user
-     * with more matching movements than the listing can page through reads the cap, not
-     * their lifetime total. A `page` above 10,000 is rejected.
+     * Cursor paged (0XM-2788/0XM-2820): omit `pageToken` or pass `""` to start,
+     * then follow `nextPageToken` from each response until it comes back empty.
+     * There is no `page` — sending one is a `400`.
+     *
+     * The response `total` and `totalPages` are bounded by the server count
+     * ceiling; `totalCapped` is `true` when more than that matched, so `total`
+     * is a lower bound. Do not drive a paging loop off `total`: a user past the
+     * ceiling would stop early. Follow `nextPageToken`.
      *
      * @param params - Optional query parameters for pagination and filtering
-     * @param params.page - Page number (starts from 1, default: 1, at most 10,000)
-     * @param params.limit - Number of items per page (default: 20, max: 100)
+     * @param params.pageToken - Cursor from a previous response's `nextPageToken`
+     * @param params.pageSize - Number of items per page (default: 20, max: 1000)
+     * @param params.orderBy - Sort direction for `createdAt` (default: `"DESC"`)
      * @param params.entryType - Filter by entry type (CREDIT, DEBIT, LOCK, UNLOCK, FEE)
      * @param params.transactionType - Filter by transaction type (DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD)
      * @param params.assetId - Filter by asset ID (UUID)
@@ -73,9 +78,14 @@ export class ProfileAPIImpl extends BaseAPI {
      * const movements = await profileAPI.getPaginatedUserMovements();
      * console.log(`Total movements: ${movements.total}`);
      *
-     * // Get second page with custom pageSize
-     * const page2 = await profileAPI.getPaginatedUserMovements({ page: 2, pageSize: 50 });
-     * console.log(`Page ${page2.page} of ${page2.totalPages}`);
+     * // Walk every page
+     * let pageToken = "";
+     * for (;;) {
+     *   const page = await profileAPI.getPaginatedUserMovements({ pageToken, pageSize: 50 });
+     *   console.log(page.movements.length);
+     *   if (page.nextPageToken === "") break;
+     *   pageToken = page.nextPageToken;
+     * }
      *
      * // Filter by entry type and transaction type
      * const deposits = await profileAPI.getPaginatedUserMovements({ entryType: "CREDIT", transactionType: "DEPOSIT" });
@@ -89,12 +99,17 @@ export class ProfileAPIImpl extends BaseAPI {
             validate(GetUserMovementsSchema, params);
         }
         const searchParams = new URLSearchParams();
-        if (params?.page !== undefined) {
-            searchParams.append("page", params.page.toString());
-        }
         if (params?.pageSize !== undefined) {
             searchParams.append("pageSize", params.pageSize.toString());
         }
+        // An empty token is a distinct, meaningful value — "start the walk" — so
+        // it must reach the wire rather than be dropped as falsy.
+        if (params?.pageToken !== undefined) {
+            searchParams.append("pageToken", params.pageToken);
+        }
+        if (params?.orderBy !== undefined) {
+            searchParams.append("orderBy", params.orderBy);
+        }
         if (params?.entryType !== undefined) {
             searchParams.append("entryType", params.entryType);
         }
@@ -114,9 +129,13 @@ export class ProfileAPIImpl extends BaseAPI {
      * Fetches the user's token balances from the /api/v1/accounts/balances endpoint.
      * Requires a valid access token to be set.
      *
+     * Cursor paged (0XM-2788/0XM-2821): omit `pageToken` or pass `""` to start,
+     * then follow `nextPageToken` until it comes back empty. There is no `page`
+     * — sending one is a `400`.
+     *
      * @param params - Optional query parameters for pagination
-     * @param params.page - Page number (starts from 1, default: 1)
-     * @param params.pageSize - Number of items per page (default: 20, max: 100)
+     * @param params.pageToken - Cursor from a previous response's `nextPageToken`
+     * @param params.pageSize - Number of items per page (default: 20, max: 1000)
      * @returns Promise resolving to paginated balances response
      * @throws {APIError} When the request fails or user is not authenticated
      *
@@ -129,19 +148,29 @@ export class ProfileAPIImpl extends BaseAPI {
      *   console.log(`${balance.symbol}: ${balance.availableBalance}`);
      * });
      *
-     * // Get page 2 with 50 items per page
-     * const nextBalances = await profileAPI.getUserBalances({ page: 2, pageSize: 50 });
-     * console.log(`Returned ${nextBalances.balances.length} balances`);
+     * // Walk every page
+     * let pageToken = "";
+     * for (;;) {
+     *   const page = await profileAPI.getUserBalances({ pageToken, pageSize: 50 });
+     *   console.log(page.balances.length);
+     *   if (page.nextPageToken === "") break;
+     *   pageToken = page.nextPageToken;
+     * }
      * ```
      */
     async getUserBalances(params) {
-        const searchParams = new URLSearchParams();
-        if (params?.page !== undefined) {
-            searchParams.append("page", params.page.toString());
+        if (params) {
+            validate(GetUserBalancesSchema, params);
         }
+        const searchParams = new URLSearchParams();
         if (params?.pageSize !== undefined) {
             searchParams.append("pageSize", params.pageSize.toString());
         }
+        // An empty token is a distinct, meaningful value — "start the walk" — so
+        // it must reach the wire rather than be dropped as falsy.
+        if (params?.pageToken !== undefined) {
+            searchParams.append("pageToken", params.pageToken);
+        }
         const queryString = searchParams.toString();
         const url = queryString ? `/api/v1/accounts/balances?${queryString}` : "/api/v1/accounts/balances";
         return await this.makeAuthenticatedRequest(url);
@@ -315,12 +344,21 @@ export class ProfileAPIImpl extends BaseAPI {
      * Fetches funding payments from the /api/v1/accounts/funding-payments endpoint.
      * Requires a valid access token to be set.
      *
-     * The response `total` and `totalPages` are bounded by the listing's pagination reach:
-     * exact up to `pageSize` x 10,000 rows (10,000 pages) and saturating there, so a user
-     * with more matching payments than the listing can page through reads the cap, not
-     * their lifetime total. A `page` above 10,000 is rejected.
+     * Cursor paged (0XM-2788/0XM-2818): omit `pageToken` or pass `""` to start,
+     * then follow `nextPageToken` from each response until it comes back empty.
+     * There is no `page` — sending one is a `400`.
+     *
+     * The response `total` and `totalPages` are bounded by the server count
+     * ceiling; `totalCapped` is `true` when more than that matched, so `total`
+     * is a lower bound. Do not drive a paging loop off `total`: a user past the
+     * ceiling would stop early. Follow `nextPageToken`.
      *
      * @param params - Optional query parameters for pagination and filtering
+     * @param params.pageToken - Cursor from a previous response's `nextPageToken`
+     * @param params.pageSize - Number of items per page (default: 20, max: 1000)
+     * @param params.tradingPairId - Filter by trading pair ID (UUID)
+     * @param params.positionId - Filter by margin position ID (UUID)
+     * @param params.marginAccountId - Filter by margin account ID (UUID)
      * @returns Promise resolving to paginated funding payments response
      * @throws {APIError} When the request fails or user is not authenticated
      *
@@ -328,6 +366,15 @@ export class ProfileAPIImpl extends BaseAPI {
      * ```typescript
      * const funding = await profileAPI.listFundingPayments({ tradingPairId: "550e8400-e29b-41d4-a716-446655440000" });
      * console.log(`Total funding payments: ${funding.total}`);
+     *
+     * // Walk every page
+     * let pageToken = "";
+     * for (;;) {
+     *   const page = await profileAPI.listFundingPayments({ pageToken, pageSize: 100 });
+     *   console.log(page.records.length);
+     *   if (page.nextPageToken === "") break;
+     *   pageToken = page.nextPageToken;
+     * }
      * ```
      */
     async listFundingPayments(params) {
@@ -335,12 +382,14 @@ export class ProfileAPIImpl extends BaseAPI {
             validate(ListFundingPaymentsSchema, params);
         }
         const searchParams = new URLSearchParams();
-        if (params?.page !== undefined) {
-            searchParams.append("page", params.page.toString());
-        }
         if (params?.pageSize !== undefined) {
             searchParams.append("pageSize", params.pageSize.toString());
         }
+        // An empty token is a distinct, meaningful value — "start the walk" — so
+        // it must reach the wire rather than be dropped as falsy.
+        if (params?.pageToken !== undefined) {
+            searchParams.append("pageToken", params.pageToken);
+        }
         if (params?.tradingPairId !== undefined) {
             searchParams.append("tradingPairId", params.tradingPairId);
         }

package/dist/api/trades/api.d.ts

@@ -26,23 +26,54 @@ export declare function parseRawTradeEvent(raw: RawTradeEvent): TradeEvent;
  * Options for fetching trades
  */
 export interface GetTradesOptions {
-    /** Page number (starts from 1, default: 1) */
-    page?: number;
-    /** Maximum number of records to return (default: 25, max: 100) */
+    /** Maximum number of records to return (default: 25, max: 1000) */
     pageSize?: number;
+    /**
+     * Cursor from a previous response's `nextPageToken`. Omit (or pass "") to
+     * start at the most recent trade.
+     */
+    pageToken?: string;
+}
+/**
+ * One page of a pair's trade feed.
+ *
+ * `nextPageToken` is empty exactly when the walk is finished — the server
+ * over-fetches one row to prove it — so a caller can stop on the empty token
+ * without a confirming extra request.
+ */
+export interface GetTradesPage {
+    /** Trades in this page, newest first. */
+    trades: TradeEvent[];
+    /** Cursor to pass as `pageToken` for the next page; "" when exhausted. */
+    nextPageToken: string;
 }
 /**
  * Trades API for fetching historical trade data
  */
 export declare class TradesAPIImpl extends BaseAPI {
     /**
-     * Get historical trades for a trading pair
+     * Get one page of historical trades for a trading pair.
+     *
+     * Cursor paged (0XM-2821): the page number was removed because `trades` is
+     * appended to continuously, so an offset silently repeated the newest trades
+     * as fills landed mid-walk. Start with no `pageToken` and follow
+     * `nextPageToken` until it comes back empty.
      *
      * @param tradingPairId - The trading pair UUID
-     * @param options - Pagination options
-     * @returns Array of TradeEvent records sorted by executedAt descending (newest first)
+     * @param options - Cursor pagination options
+     * @returns One page of TradeEvent records sorted by executedAt descending (newest first), plus the next cursor
+     *
+     * @example
+     * ```typescript
+     * let pageToken: string | undefined;
+     * do {
+     *   const page = await sdk.trades.getTrades(pairId, { pageSize: 100, pageToken });
+     *   handle(page.trades);
+     *   pageToken = page.nextPageToken || undefined;
+     * } while (pageToken);
+     * ```
      */
-    getTrades(tradingPairId: string, options?: GetTradesOptions): Promise<TradeEvent[]>;
+    getTrades(tradingPairId: string, options?: GetTradesOptions): Promise<GetTradesPage>;
     /**
      * Get a single trade by its UUID.
      *

package/dist/api/trades/api.js

@@ -1,3 +1,4 @@
+import { GetTradesSchema, validate } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 import { perpRoutes } from "../perp";
 /**
@@ -22,23 +23,49 @@ export function parseRawTradeEvent(raw) {
  */
 export class TradesAPIImpl extends BaseAPI {
     /**
-     * Get historical trades for a trading pair
+     * Get one page of historical trades for a trading pair.
+     *
+     * Cursor paged (0XM-2821): the page number was removed because `trades` is
+     * appended to continuously, so an offset silently repeated the newest trades
+     * as fills landed mid-walk. Start with no `pageToken` and follow
+     * `nextPageToken` until it comes back empty.
      *
      * @param tradingPairId - The trading pair UUID
-     * @param options - Pagination options
-     * @returns Array of TradeEvent records sorted by executedAt descending (newest first)
+     * @param options - Cursor pagination options
+     * @returns One page of TradeEvent records sorted by executedAt descending (newest first), plus the next cursor
+     *
+     * @example
+     * ```typescript
+     * let pageToken: string | undefined;
+     * do {
+     *   const page = await sdk.trades.getTrades(pairId, { pageSize: 100, pageToken });
+     *   handle(page.trades);
+     *   pageToken = page.nextPageToken || undefined;
+     * } while (pageToken);
+     * ```
      */
     async getTrades(tradingPairId, options = {}) {
-        const { page = 1 } = options;
-        // Ensure pageSize is a positive number between 1 and 100, defaulting to 25
-        const pageSize = options.pageSize != null && options.pageSize > 0 ? Math.min(options.pageSize, 100) : 25;
+        validate(GetTradesSchema, options);
         const params = new URLSearchParams();
-        if (page > 1) {
-            params.set("page", String(page));
+        // Only send what the caller set: the server owns the 25 default, so
+        // restating it here would pin the SDK to a value the API can move.
+        if (options.pageSize != null) {
+            params.set("pageSize", String(options.pageSize));
+        }
+        if (options.pageToken != null && options.pageToken !== "") {
+            params.set("pageToken", options.pageToken);
         }
-        params.set("pageSize", String(pageSize));
-        const response = await this.makePublicRequest(`/api/v1/trades/${encodeURIComponent(tradingPairId)}?${params.toString()}`);
-        return response.trades.map(parseRawTradeEvent);
+        const query = params.toString();
+        const response = await this.makePublicRequest(`/api/v1/trades/${encodeURIComponent(tradingPairId)}${query === "" ? "" : `?${query}`}`);
+        return {
+            // `?? []` because an empty page omits `trades` entirely; without it the
+            // last page of a walk would throw instead of ending it.
+            trades: (response.trades ?? []).map(parseRawTradeEvent),
+            // Absent rather than "" on a wire that omits empty strings: either way the
+            // walk is finished, and a caller testing `nextPageToken || undefined`
+            // must not see `undefined` become a truthy string.
+            nextPageToken: response.nextPageToken ?? "",
+        };
     }
     /**
      * Get a single trade by its UUID.

package/dist/api/trading/api.d.ts

@@ -315,11 +315,10 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      * Gets orders based on query parameters, cursor-paginated by default.
      *
      * Retrieves orders with optional filtering by status, trading pair, and pagination.
-     * Every kind of order comes back in ONE stream ordered by timestamp: book orders,
-     * TWAP parents (`orderType: "TWAP"`, detail on `twap`) and conditional orders
-     * (`orderType: "CONDITIONAL"`, detail on `conditional`). There is no separate
-     * open-orders call — filter `status` to `["SUBMITTED", "PARTIALLY_FILLED"]` for the
-     * working set.
+     * Every row is a BOOK order (`LIMIT` or `MARKET`); filter `status` to
+     * `["SUBMITTED", "PARTIALLY_FILLED"]` for the resting working set. TWAP parents and
+     * conditional (TP/SL) orders are not rows here — list them with `listTwapOrders`
+     * and `listConditionalOrders`.
      * When neither `page` nor `pageToken` is passed, the SDK drives cursor (pageToken)
      * pagination: it starts a cursor walk from the newest (or oldest, for
      * `orderBy: "ASC"`) row and the response's `nextPageToken` resumes it. Both modes
@@ -342,13 +341,9 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      *
      * @example
      * ```typescript
-     * // Every working order, of every kind, in one page
+     * // The resting working set (book orders only)
      * const open = await tradingAPI.getPaginatedOrders({ status: ["SUBMITTED", "PARTIALLY_FILLED"] });
-     * for (const order of open.orders) {
-     *   if (order.orderType === "TWAP") console.log("TWAP parent", order.twap?.slicesPlaced);
-     *   else if (order.orderType === "CONDITIONAL") console.log("trigger", order.conditional?.triggerPrice);
-     *   else console.log("resting", order.price);
-     * }
+     * for (const order of open.orders) console.log("resting", order.quantity, "@", order.price);
      * ```
      *
      * @example

package/dist/api/trading/api.js

@@ -495,11 +495,10 @@ export class TradingAPIImpl extends BaseAPI {
      * Gets orders based on query parameters, cursor-paginated by default.
      *
      * Retrieves orders with optional filtering by status, trading pair, and pagination.
-     * Every kind of order comes back in ONE stream ordered by timestamp: book orders,
-     * TWAP parents (`orderType: "TWAP"`, detail on `twap`) and conditional orders
-     * (`orderType: "CONDITIONAL"`, detail on `conditional`). There is no separate
-     * open-orders call — filter `status` to `["SUBMITTED", "PARTIALLY_FILLED"]` for the
-     * working set.
+     * Every row is a BOOK order (`LIMIT` or `MARKET`); filter `status` to
+     * `["SUBMITTED", "PARTIALLY_FILLED"]` for the resting working set. TWAP parents and
+     * conditional (TP/SL) orders are not rows here — list them with `listTwapOrders`
+     * and `listConditionalOrders`.
      * When neither `page` nor `pageToken` is passed, the SDK drives cursor (pageToken)
      * pagination: it starts a cursor walk from the newest (or oldest, for
      * `orderBy: "ASC"`) row and the response's `nextPageToken` resumes it. Both modes
@@ -522,13 +521,9 @@ export class TradingAPIImpl extends BaseAPI {
      *
      * @example
      * ```typescript
-     * // Every working order, of every kind, in one page
+     * // The resting working set (book orders only)
      * const open = await tradingAPI.getPaginatedOrders({ status: ["SUBMITTED", "PARTIALLY_FILLED"] });
-     * for (const order of open.orders) {
-     *   if (order.orderType === "TWAP") console.log("TWAP parent", order.twap?.slicesPlaced);
-     *   else if (order.orderType === "CONDITIONAL") console.log("trigger", order.conditional?.triggerPrice);
-     *   else console.log("resting", order.price);
-     * }
+     * for (const order of open.orders) console.log("resting", order.quantity, "@", order.price);
      * ```
      *
      * @example