@0xmonaco/types 1.0.73 → 1.0.75

package/dist/pitpass/responses.js

@@ -118,11 +118,20 @@ export const ReferralRewardEntrySchema = z.object({
     /** RFC 3339 timestamp when the reward row was recorded. */
     createdAt: z.string(),
 });
+/** One ancestor in the caller's referral chain. */
+export const ReferralUplineEntrySchema = z.object({
+    /** Public wallet address of the ancestor. */
+    wallet: z.string(),
+    /** Human-facing name for the ancestor: their custom handle if claimed, else the wallet. */
+    display: z.string(),
+    /** How far above the caller this ancestor is: 1 (direct referrer), 2, or 3. */
+    level: z.number(),
+});
 /** The caller's own referral position: who referred them and what they've earned. */
 export const GetMyReferralPositionResponseSchema = z.object({
     /**
      * Public wallet address of the caller's direct (L1) referrer. Empty string
-     * when the caller was not referred. Only the direct referrer is exposed.
+     * when the caller was not referred. Same wallet as the first `upline` entry.
      */
     referrer: z.string(),
     /** Human-facing name for the referrer: their custom handle if claimed, else the wallet (empty when not referred). */
@@ -131,6 +140,13 @@ export const GetMyReferralPositionResponseSchema = z.object({
     totalEarned: z.string(),
     /** The caller's most recent reward rows, newest first (bounded server-side). */
     rewards: z.array(ReferralRewardEntrySchema),
+    /**
+     * The caller's referral chain upward, nearest first: L1, L2, and so on, at
+     * most as many entries as PitPass currently rewards levels (at most 10);
+     * empty when the caller was not referred. These are the wallets the caller's
+     * own trades pay referral rewards to.
+     */
+    upline: z.array(ReferralUplineEntrySchema),
 });
 /** One aggregated earnings row per (source trader, level, token) the caller earns from. */
 export const ReferralEarningsSourceSchema = z.object({
@@ -138,7 +154,7 @@ export const ReferralEarningsSourceSchema = z.object({
     source: z.string(),
     /** Human-facing name for the source: their custom handle if claimed, else the wallet. */
     sourceDisplay: z.string(),
-    /** Referral level the caller earns from this source at (1/2/3). */
+    /** Referral level the caller earns from this source at: 1 (direct), 2, and so on (at most 10). */
     level: z.number(),
     /** Total earned from this source at this level and token, in RAW atomic units. */
     totalEarned: z.string(),
@@ -156,26 +172,94 @@ export const ReferralDirectRefereeSchema = z.object({
     /** Total the caller has earned from this referee's own (L1) trades, RAW units. `0` if they haven't traded. */
     totalEarned: z.string(),
 });
+/** What the caller has earned at one referral level. */
+export const LevelEarningsSchema = z.object({
+    /** Referral level: 1 for direct referees, 2 for their referees, and so on (at most 10). */
+    level: z.number(),
+    /** All-time credited earnings at this level, in RAW atomic units. */
+    earned: z.string(),
+});
 /** Per-level breakdown of the caller's total referral earnings. */
 export const ReferralEarningsSummarySchema = z.object({
     /** Total earned across all levels and tokens, in RAW atomic units. */
     totalEarned: z.string(),
-    /** Total earned from direct (L1) referees, in RAW atomic units. */
+    /** @deprecated Use `byLevel`. Total earned from direct (L1) referees, in RAW atomic units. */
     level1Earned: z.string(),
-    /** Total earned from L2 downline, in RAW atomic units. */
+    /** @deprecated Use `byLevel`. Total earned from L2 downline, in RAW atomic units. */
     level2Earned: z.string(),
-    /** Total earned from L3 downline, in RAW atomic units. */
+    /** @deprecated Use `byLevel`. Total earned from L3 downline, in RAW atomic units. */
     level3Earned: z.string(),
+    /**
+     * Earnings per level, ascending, one entry per level with earnings. Covers
+     * every level, including levels deeper than PitPass rewards today.
+     */
+    byLevel: z.array(LevelEarningsSchema),
+});
+/** Query parameters for reading the caller's downline. */
+export const GetMyReferralDownlineParamsSchema = z.object({
+    /** `earningsBySource` rows per page (1-500, default 100). */
+    pageSize: z.number().int().min(1).max(500).optional(),
+    /** Opaque cursor from a previous response's `nextPageToken`. */
+    pageToken: z.string().optional(),
 });
 /** The caller's own downline: who they earn from, their L1 roster, and a summary. */
 export const GetMyReferralDownlineResponseSchema = z.object({
-    /** One row per (source trader, level, token) the caller earns from, across L1/L2/L3. */
+    /**
+     * One page of rows, one per (source, level, token) the caller earns from,
+     * across every reward level, ordered by each source account's total,
+     * largest first; a wallet's per-application rows are merged within a page
+     * at the first row's position. Follow
+     * `nextPageToken` for the rest.
+     */
     earningsBySource: z.array(ReferralEarningsSourceSchema),
     /** The caller's direct (L1) referees, newest first, including those who haven't traded. */
     directReferees: z.array(ReferralDirectRefereeSchema),
     /**
-     * Total earned broken down by level (L1/L2/L3). The server always populates
-     * this — even a brand-new user gets a zeroed summary — so it is required.
+     * Total earned broken down by level, covering every level and source
+     * whatever the page. The server always populates this — even a brand-new
+     * user gets a zeroed summary — so it is required.
      */
     summary: ReferralEarningsSummarySchema,
+    /** Cursor for the next `earningsBySource` page; empty when there are no more rows. */
+    nextPageToken: z.string(),
+});
+/** Query parameters for reading one level of the caller's referral tree. */
+export const GetMyReferralTreeParamsSchema = z.object({
+    /**
+     * Wallet whose direct referees to list. Omit for your own L1 referees; set to
+     * one of your referees above the deepest rewarded level to expand that node.
+     */
+    parent: z.string().optional(),
+    /** Nodes per page (1-200, default 50). */
+    pageSize: z.number().int().min(1).max(200).optional(),
+    /** Opaque cursor from a previous response's `nextPageToken`. Only valid with the same `parent`. */
+    pageToken: z.string().optional(),
+});
+/** One wallet in the caller's referral tree. */
+export const ReferralTreeNodeSchema = z.object({
+    /** Public wallet address of this referee. */
+    wallet: z.string(),
+    /** Human-facing name: their custom handle if claimed, else the wallet. */
+    display: z.string(),
+    /** Depth below the caller: 1 (you referred them), 2, and so on up to the configured reward depth (at most 10). */
+    level: z.number(),
+    /** Wallet address of this node's referrer — your own wallet for a level-1 node. */
+    parent: z.string(),
+    /** RFC 3339 time this wallet signed up under its parent. */
+    referredAt: z.string(),
+    /** How many wallets this node has referred. Expandable when above 0; always 0 at the deepest rewarded level. */
+    refereeCount: z.number(),
+    /** What you have earned from this wallet's own trades, RAW atomic units. `0` if they haven't traded. */
+    totalEarned: z.string(),
+});
+/** One page of one level of the caller's referral tree. */
+export const GetMyReferralTreeResponseSchema = z.object({
+    /** Wallet whose referees `nodes` lists — your own wallet when `parent` was omitted. */
+    parent: z.string(),
+    /** Depth of `parent` below you: 0 for yourself, otherwise the level of the expanded referee. */
+    parentLevel: z.number(),
+    /** The wallets `parent` referred, newest first. */
+    nodes: z.array(ReferralTreeNodeSchema),
+    /** Cursor for the next page; empty when there are no more. */
+    nextPageToken: z.string(),
 });

package/dist/portfolio/index.d.ts

@@ -166,15 +166,15 @@ export interface PortfolioMarginTotal {
      * bound the engine enforces on transfers-out and withdrawals, and therefore
      * also the effective ceiling on funding new isolated or first-use order
      * capacity (allocating collateral to a risk bucket passes through the same
-     * principal-gated door).
+     * capacity-gated door).
      *
      * NOT a clamped `parentAvailableCollateral`: that is an equity figure which
-     * credits settled realized PnL, accrued funding, and unrealized gains that a
-     * transfer-out cannot move. This bound never credits an unrealized gain, and
-     * under the default capacity basis it also excludes non-principal balances —
-     * `min(deposited principal - bucket allocations, freeCollateral - max(unrealizedPnl, 0))`,
-     * floored at zero. Whatever the engine's configured capacity basis, this is
-     * the bound its gates actually enforce. Size transfers-out, withdrawals, and
+     * credits unrealized gains and realized PnL still held in open risk
+     * buckets, which a transfer-out of the parent cannot move. This bound never
+     * credits an unrealized gain; it counts net deposits plus the account's
+     * settled realized PnL and funding, less what risk buckets have allocated —
+     * `min(net deposits + settled realized PnL - bucket allocations, freeCollateral - max(unrealizedPnl, 0))`,
+     * floored at zero. This is the bound the engine's gates actually enforce. Size transfers-out, withdrawals, and
      * new isolated or first-use positions from this field;
      * `parentAvailableCollateral` remains the trading-margin headroom for
      * existing cross exposure.
@@ -196,12 +196,14 @@ export interface PortfolioRiskBucket {
     positionCount: number;
     /**
      * The largest transfer-out of this risk bucket the engine will actually
-     * accept. NOT a clamped `freeCollateral`: capped by the bucket's settled
-     * capacity (its allocated collateral, under the default capacity basis),
-     * and an unrealized gain never raises it. This is the largest
-     * accepted transfer-out, not a promise that every smaller one is accepted —
-     * an underwater flat bucket accepts its full close-out while refusing
-     * partial withdrawals below it.
+     * accept. NOT a clamped `freeCollateral`: the bucket's allocated
+     * collateral plus its realized PnL, less funding paid, unrealized losses
+     * and the margin its positions and resting orders require. Realized profit
+     * can leave a live bucket this way (the bucket's allocation may go
+     * negative); an unrealized gain never raises it. This is the largest
+     * accepted transfer-out, and every smaller amount is accepted too. It is
+     * zero on a risk bucket that is not `NORMAL` and on one whose realized loss
+     * has used up its allocation.
      */
     withdrawableCollateral: string;
     /**
@@ -267,11 +269,31 @@ export interface PortfolioRiskBucket {
      */
     tradingPairId?: string;
 }
+/** One of the caller's open margin accounts in the owner rollup. */
+export interface PortfolioMarginAccount {
+    marginAccountId: string;
+    /** `default` for the default margin account, else the sub-account's key. */
+    subaccountKey: string;
+    /** The account's totals; `withdrawableCollateral` is the persisted reconstruction of the engine's bound. */
+    total: PortfolioMarginTotal;
+}
 export interface PortfolioMargin {
     asOf: string;
     total: PortfolioMarginTotal;
     positions: PortfolioMarginPositionCounts;
     riskBuckets: PortfolioRiskBucket[];
+    /** The margin account `total`, `positions` and `riskBuckets` describe; absent before the first margin account. */
+    marginAccountId?: string;
+    /** With `includeAccounts`: every open margin account, the default one first. */
+    accounts?: PortfolioMarginAccount[];
+    /** With `includeAccounts`: the sum of `accounts`' totals (the owner rollup). */
+    ownerTotal?: PortfolioMarginTotal;
+}
+export interface PortfolioMarginParams {
+    /** One of your margin accounts (default or a sub-account) to describe instead of the default one. */
+    marginAccountId?: string;
+    /** Also return every open margin account's totals and their sum. */
+    includeAccounts?: boolean;
 }
 /** Authoritative, application-scoped portfolio analytics. */
 export interface PortfolioAPI extends BaseAPI {
@@ -279,5 +301,5 @@ export interface PortfolioAPI extends BaseAPI {
     getPerformance(params?: PortfolioPeriodParams): Promise<PortfolioPerformance>;
     getRealizedPnl(params?: PortfolioPeriodParams): Promise<PortfolioRealizedPnl>;
     getAssets(params?: PortfolioPeriodParams): Promise<PortfolioAssets>;
-    getMargin(): Promise<PortfolioMargin>;
+    getMargin(params?: PortfolioMarginParams): Promise<PortfolioMargin>;
 }

package/dist/positions/index.d.ts

@@ -142,25 +142,80 @@ export interface Position {
      * holds the state but not the version, so it cannot rank itself.
      */
     version?: number;
+    /**
+     * When the position OPENED (ISO 8601): the fill that took its exposure from
+     * zero to non-zero. Time held is now minus `openedAt` for an OPEN position
+     * and `updatedAt` minus `openedAt` for a terminal one. It never changes for
+     * the life of `positionId`; a flip opens a new position with its own.
+     *
+     * `null` (or absent, from an older server) when the opening instant is
+     * unknown — never filled with the read time, so check for both before
+     * doing date arithmetic, and clamp the result at zero: the value can sit
+     * slightly ahead of the client's clock, and after a server restart it can
+     * move by the server's own clock drift. Positions opened before the field existed report
+     * the stored value, which can trail the opening fill by the server's
+     * persistence lag where that fill could not be recovered.
+     *
+     * Not versioned, and not guaranteed constant at a given `version`: a
+     * one-off server correction can move it earlier without a version change.
+     * Take it from the newest payload rather than skipping it on an equal
+     * version.
+     */
+    openedAt?: string | null;
 }
 export interface ListPositionsParams {
     marginAccountId?: string;
     tradingPairId?: string;
     status?: PositionStatusFilter;
-    page?: number;
+    /** Items per page, 1 to 1000 (default 20). */
     pageSize?: number;
+    /**
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position.
+     * - Non-empty: an opaque cursor from a previous response's
+     *   `nextPageToken`; results resume immediately after that position.
+     *
+     * **Order depends on the filter.** `status: "OPEN"` is answered from the
+     * matching engine's live view and is ordered by
+     * `(marginAccountId, tradingPairId, positionId)` ascending — stable, but
+     * UUID order, NOT newest-first. Every other filter reads persisted rows
+     * newest-opened first. The two are separate cursor spaces, so a token is
+     * only valid in the one that minted it, and crossing between them is
+     * ASYMMETRIC: a persisted token offered to `status: "OPEN"` is served by
+     * the persisted walk while the engine is reachable, but a LIVE token
+     * cannot cross — once the engine is unreachable the request is a 400 and
+     * the walk must restart, because the two relations share no sort key and
+     * resuming at a key from the wrong one would skip or repeat rows silently.
+     *
+     * Page-number pagination was removed (0XM-2788): there is no `page`, and
+     * sending one is a 400. Filters must match the request that produced the
+     * token, or the request is rejected.
+     */
+    pageToken?: string;
 }
 export interface ListPositionsResponse {
     positions: Position[];
     /**
-     * Matching positions. Exact up to 10,000 pages of the requested page size
-     * (`pageSize` x 10,000 rows) and saturates there, so a caller with more
-     * matching positions than the listing can page through reads the cap, not
-     * its lifetime total. `page` is capped at 10,000.
+     * Positions matching the filter, bounded by the server count ceiling — see
+     * `totalCapped`. A lower bound when `totalCapped` is `true`.
      */
     total: number;
-    page: number;
     pageSize: number;
+    /**
+     * Cursor for the next page, minted from the last row of an over-fetched
+     * page: this listing is one ordered read, so a page shorter than `pageSize`
+     * proves the walk is exhausted and this is `""`. A non-empty token always
+     * has at least one further row behind it.
+     */
+    nextPageToken: string;
+    /**
+     * `true` when MORE than the server ceiling of positions matched, so the
+     * count stopped at the ceiling and `total` is a lower bound. `false` when
+     * `total` is the exact count — including exactly the ceiling, which is
+     * still reported exactly.
+     */
+    totalCapped: boolean;
 }
 export type GetPositionResponse = Position;
 export interface ClosePositionRequest {
@@ -309,10 +364,23 @@ export interface ListPositionHistoryParams {
     positionId?: string;
     marginAccountId?: string;
     tradingPairId?: string;
-    page?: number;
+    /** Items per page, 1 to 1000 (default 20). */
     pageSize?: number;
     /** Return only per-execution position reductions, closes, and liquidations. */
     reductionOnly?: boolean;
+    /**
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position, from the newest row — this listing always sorts
+     *   newest-first.
+     * - Non-empty: an opaque cursor from a previous response's
+     *   `nextPageToken`; results resume immediately after that position.
+     *
+     * Page-number pagination was removed (0XM-2788): there is no `page`, and
+     * sending one is a 400. Filters must match the request that produced the
+     * token, or the request is rejected.
+     */
+    pageToken?: string;
 }
 export interface PositionHistoryEvent {
     /** Wire-format event ID. */
@@ -353,15 +421,14 @@ export interface PositionHistoryEvent {
 }
 export interface ListPositionHistoryResponse {
     events: PositionHistoryEvent[];
+    pageSize: number;
     /**
-     * Matching position-history events. Exact up to 10,000 pages of the
-     * requested page size (`pageSize` x 10,000 rows) and saturates there, so a
-     * caller with more history than the listing can page through reads the cap,
-     * not its lifetime total. `page` is capped at 10,000.
+     * Cursor for the next page, minted from the last row of an over-fetched
+     * page: this listing is one ordered read, so a page shorter than `pageSize`
+     * proves the walk is exhausted and this is `""`. A non-empty token always
+     * has at least one further row behind it.
      */
-    total: number;
-    page: number;
-    pageSize: number;
+    nextPageToken: string;
 }
 /**
  * Sample interval for position PnL history queries (matches the candles

package/dist/profile/index.d.ts

@@ -98,13 +98,24 @@ export type TransactionType = "DEPOSIT" | "WITHDRAWAL" | "TRADE" | "FEE" | "FUND
  * Query parameters for getting user movements
  */
 export interface GetUserMovementsParams {
+    /** Number of items per page, 1 to 1000 (default 20) */
+    pageSize?: number;
     /**
-     * Page number (starts from 1, at most 10,000 — the last page this listing
-     * counts towards; a larger page is rejected).
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position, from the newest row (or the oldest, when `orderBy`
+     *   is `"ASC"`).
+     * - Non-empty: an opaque cursor from a previous response's
+     *   `nextPageToken`; results resume immediately after that position.
+     *
+     * Page-number pagination was removed (0XM-2788): there is no `page`, and
+     * sending one is a `400`. Every walk covers the ledger and funding arms
+     * merged. Filters and `orderBy` must match the request that minted the
+     * token.
      */
-    page?: number;
-    /** Number of items per page (max 100) */
-    pageSize?: number;
+    pageToken?: string;
+    /** Sort direction for `createdAt`: `"ASC"` or `"DESC"` (default `"DESC"`) */
+    orderBy?: "ASC" | "DESC";
     /** Filter by entry type (CREDIT, DEBIT, LOCK, UNLOCK, FEE) */
     entryType?: LedgerEntryType;
     /** Filter by transaction type (DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD) */
@@ -116,10 +127,22 @@ export interface GetUserMovementsParams {
  * Query parameters for getting user balances
  */
 export interface GetUserBalancesParams {
-    /** Page number (starts from 1) */
-    page?: number;
-    /** Number of items per page (max 100) */
+    /** Number of items per page, 1 to 1000 (default 20) */
     pageSize?: number;
+    /**
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position, from the lowest token address.
+     * - Non-empty: an opaque cursor from a previous response's
+     *   `nextPageToken`; results resume immediately after that position.
+     *
+     * Page-number pagination was removed (0XM-2788): there is no `page`, and
+     * sending one is a `400`. The walk seeks on `(token, assetId)` over the
+     * balance set the server builds after overlaying the matching engine's
+     * authoritative amounts, so a balance that appears or is zeroed mid-walk no
+     * longer shifts the rows behind it across the resume point.
+     */
+    pageToken?: string;
 }
 /**
  * Response from getting user movements
@@ -127,22 +150,30 @@ export interface GetUserBalancesParams {
 export interface GetPaginatedUserMovementsResponse {
     /** All movements from PostgreSQL (historical, paginated) */
     movements: LedgerMovement[];
-    /** Current page number */
-    page: number;
     /** Items per page */
     pageSize: number;
     /**
-     * Matching movements. Exact up to 10,000 pages of the requested `pageSize`
-     * (`pageSize` x 10,000 rows) and saturates there, so a user with more
-     * matching movements than the listing can page through reads the cap, not
-     * their lifetime total.
+     * Movements matching the filter, bounded by the server count ceiling — see
+     * `totalCapped`. A lower bound when `totalCapped` is `true`.
      */
     total: number;
+    /** Pages at this `pageSize`, bounded by the same ceiling as `total`. */
+    totalPages: number;
     /**
-     * Number of pages at the requested `pageSize`. Exact up to 10,000 and
-     * saturates there, the last page this listing can reach.
+     * Cursor for the next page, minted from the last row of an over-fetched
+     * page. Each arm of the ledger+funding union is cut at the same
+     * over-fetched depth inside one statement, so a page shorter than
+     * `pageSize` means both arms are exhausted and this is `""`. A non-empty
+     * token always has at least one further row behind it.
      */
-    totalPages: number;
+    nextPageToken: string;
+    /**
+     * `true` when MORE than the server ceiling of movements matched, so the
+     * count stopped at the ceiling and `total` / `totalPages` are a lower
+     * bound. `false` when `total` is the exact count — including exactly the
+     * ceiling, which is still reported exactly.
+     */
+    totalCapped: boolean;
 }
 /**
  * Response from getting user balances
@@ -150,14 +181,21 @@ export interface GetPaginatedUserMovementsResponse {
 export interface GetUserBalancesResponse {
     /** List of token balances for the user */
     balances: AccountBalance[];
-    /** Total number of balances */
+    /**
+     * Total number of balances. Exact — the set is bounded by the asset universe
+     * and counted in memory after the live overlay, so no ceiling applies.
+     */
     total: number;
     /** Items per page */
     pageSize: number;
-    /** Current page number */
-    page: number;
     /** Total number of pages */
     totalPages: number;
+    /**
+     * Cursor for the next page, `""` once the walk is exhausted. The whole set
+     * is already in memory, so each page over-fetches one row and an empty token
+     * is definitive — follow a non-empty token, stop on an empty one.
+     */
+    nextPageToken: string;
 }
 /**
  * Order information for recent orders.
@@ -351,13 +389,21 @@ export interface FundingPayment {
  * Query parameters for listing funding payments.
  */
 export interface ListFundingPaymentsParams {
+    /** Number of items per page, 1 to 1000 (default 20) */
+    pageSize?: number;
     /**
-     * Page number (starts from 1, at most 10,000 — the last page this listing
-     * counts towards; a larger page is rejected).
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position, from the newest payment.
+     * - Non-empty: an opaque cursor from a previous response's
+     *   `nextPageToken`; results resume immediately after that position.
+     *
+     * Page-number pagination was removed (0XM-2788): there is no `page`, and
+     * sending one is a `400`. The walk seeks on `(createdAt, id)` descending —
+     * not `periodEnd`, which the removed mode led its sort with and which is
+     * nullable. Filters must match the request that minted the token.
      */
-    page?: number;
-    /** Number of items per page (max 100) */
-    pageSize?: number;
+    pageToken?: string;
     /** Filter by trading pair ID (UUID) */
     tradingPairId?: string;
     /** Filter by margin position ID (UUID) */
@@ -371,22 +417,29 @@ export interface ListFundingPaymentsParams {
 export interface ListFundingPaymentsResponse {
     /** List of funding payment records */
     records: FundingPayment[];
-    /** Current page number */
-    page: number;
     /** Items per page */
     pageSize: number;
     /**
-     * Matching funding payment records. Exact up to 10,000 pages of the
-     * requested `pageSize` (`pageSize` x 10,000 rows) and saturates there, so a
-     * user with more matching payments than the listing can page through reads
-     * the cap, not their lifetime total.
+     * Payments matching the filter, bounded by the server count ceiling — see
+     * `totalCapped`. A lower bound when `totalCapped` is `true`.
      */
     total: number;
+    /** Pages at this `pageSize`, bounded by the same ceiling as `total`. */
+    totalPages: number;
     /**
-     * Number of pages at the requested `pageSize`. Exact up to 10,000 and
-     * saturates there, the last page this listing can reach.
+     * Cursor for the next page, minted from the last row of an over-fetched
+     * page. This listing is one ordered read, so a page shorter than `pageSize`
+     * proves the walk is exhausted and this is `""`. A non-empty token always
+     * has at least one further row behind it.
      */
-    totalPages: number;
+    nextPageToken: string;
+    /**
+     * `true` when MORE than the server ceiling of payments matched, so the count
+     * stopped at the ceiling and `total` / `totalPages` are a lower bound.
+     * `false` when `total` is the exact count — including exactly the ceiling,
+     * which is still reported exactly.
+     */
+    totalCapped: boolean;
 }
 /**
  * Time period for portfolio stats and chart queries.
@@ -539,9 +592,14 @@ export interface ProfileAPI extends BaseAPI {
      * Fetches the user's transaction history from the /api/v1/accounts/movements endpoint.
      * Requires a valid access token to be set.
      *
+     * Cursor paged (0XM-2788/0XM-2820): 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 and filtering
-     * @param params.page - Page number (starts from 1)
-     * @param params.limit - Number of items per page (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)
@@ -554,10 +612,15 @@ export interface ProfileAPI 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.limit - Number of items to return
-     * @param params.offset - Number of items to skip
+     * @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 ValidationError If the page size is invalid or `page` is sent; this may occur before any network request.
      */
     getUserBalances(params?: GetUserBalancesParams): Promise<GetUserBalancesResponse>;
     /**
@@ -597,12 +660,15 @@ export interface ProfileAPI extends BaseAPI {
      * Fetches the user's executed trades from the /api/v1/accounts/trades endpoint.
      * Requires a valid access token to be set.
      *
+     * Cursor paged (0XM-2963): omit `pageToken` or pass `""` to start, then
+     * follow `nextPageToken` until it comes back empty. There is no `page`.
+     *
      * @param params - Optional query parameters for pagination and filtering
-     * @param params.page - Page number (starts from 1)
-     * @param params.limit - Number of items per page (max 1000)
+     * @param params.pageToken - Cursor from a previous response's `nextPageToken`
+     * @param params.pageSize - Number of items per page (max 1000)
      * @param params.tradingPairId - Filter by trading pair ID (UUID)
      * @returns Promise resolving to paginated trades response
-     * @throws ValidationError If pagination params (page/limit) are invalid or tradingPairId is not a valid UUID; this may occur before any network request.
+     * @throws ValidationError If the page size is invalid, `page` is sent, or tradingPairId is not a valid UUID; this may occur before any network request.
      */
     getUserTrades(params?: GetUserTradesParams): Promise<GetUserTradesResponse>;
     /**
@@ -619,14 +685,18 @@ export interface ProfileAPI extends BaseAPI {
      * Fetches funding payments from the /api/v1/accounts/funding-payments endpoint.
      * Requires a valid access token to be set.
      *
+     * Cursor paged (0XM-2788/0XM-2818): 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 and filtering
-     * @param params.page - Page number (starts from 1)
-     * @param params.pageSize - Number of items per page (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.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 ValidationError If pagination params or a UUID filter are invalid; this may occur before any network request.
+     * @throws ValidationError If the page size is invalid, `page` is sent, or a UUID filter is invalid; this may occur before any network request.
      */
     listFundingPayments(params?: ListFundingPaymentsParams): Promise<ListFundingPaymentsResponse>;
     /**

package/dist/trading/index.d.ts

@@ -267,6 +267,6 @@ export interface TradingAPI extends BaseAPI {
      */
     listTwapOrders(params?: ListTwapOrdersParams): Promise<ListTwapOrdersResponse>;
 }
-export type { ConditionalOrderConditionType, ConditionalOrderState, ConditionalOrderTriggerSource, ListedOrderType, Order, OrderRole, OrderSide, OrderStatus, OrderStatusFilter, OrderTerminalReason, OrderType, PositionSide, SelfTradePreventionMode, TimeInForce, TradingMode, TwapExecutionStyle, TwapOrderState, } from "./orders";
+export type { ConditionalOrderConditionType, ConditionalOrderState, ConditionalOrderTriggerSource, Order, OrderRole, OrderSide, OrderStatus, OrderStatusFilter, OrderTerminalReason, OrderType, PositionSide, SelfTradePreventionMode, TimeInForce, TradingMode, TwapExecutionStyle, TwapOrderState, } from "./orders";
 export { ORDER_STATUS_VALUES } from "./orders";
 export type { BatchCancelError, BatchCancelOrdersResponse, BatchCancelResult, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchCreateResult, BatchError, BatchReplaceOrderParams, BatchReplaceOrdersResponse, BatchReplaceResult, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, GetTwapOrderTcaResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, MatchResult, ParentTpSlLegParams, ParentTrailingStopLegParams, ReplaceOrderResponse, TriggeredOrderSummary, TwapOrder, UpdatedFields, } from "./responses";