@0xmonaco/types 1.0.74 → 1.0.76

package/dist/margin-accounts/index.d.ts

@@ -42,7 +42,8 @@ export interface MarginAccountSummary {
      * liquidation or frozen as bad debt) and on one whose realized loss has used
      * up its allocation; the parent margin account is charged at most a risk
      * bucket's allocation. Size transfers against this field, not
-     * `freeCollateral`.
+     * `freeCollateral`. Truncated toward zero at the quote asset's precision,
+     * so the printed amount itself is always accepted.
      */
     withdrawableCollateral: string;
     totalPositionNotional: string;
@@ -88,7 +89,8 @@ export interface MarginAccountSummary {
      *
      * Present only on risk-bucket rows served from a live risk engine snapshot;
      * absent (the key is omitted, never null) on parent rows and on
-     * persisted-fallback reads.
+     * persisted-fallback reads. Truncated toward zero at the quote asset's
+     * precision, like `withdrawableCollateral`.
      */
     availableOrderCollateral?: string;
     /**
@@ -105,8 +107,29 @@ export interface MarginAccountSummary {
     copyLeaderHandle?: string;
 }
 export interface ListMarginAccountsParams {
-    page?: number;
+    /** 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 margin account id.
+     * - 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
+     * `(marginAccountId, tradingPairId, riskBucketId, strategyKey)` over the
+     * repriced set the server builds per request — the parent account row ahead
+     * of its own bucket rows — so a bucket that opens or closes mid-walk no
+     * longer shifts the rows behind it across the resume point. The strategy key
+     * is part of the key because an auto bucket the engine has not materialized
+     * yet carries no `riskBucketId`, and one account and pair can hold several
+     * strategies; such a row sorts under the id its bucket will carry once the
+     * engine projects it, so provisioning completing mid-walk cannot serve the
+     * same risk bucket twice. The filters must match the request that minted the
+     * token.
+     */
+    pageToken?: string;
     /**
      * Keep only risk-bucket rows in this state (see
      * {@link MarginAccountSummary.riskBucketState}). A parent margin account row
@@ -117,9 +140,19 @@ export interface ListMarginAccountsParams {
 }
 export interface ListMarginAccountsResponse {
     accounts: MarginAccountSummary[];
+    /**
+     * Rows matching the filters. Exact — a user's margin accounts and risk
+     * buckets are a small bounded set, counted in memory after the repricing
+     * pass.
+     */
     total: number;
-    page: number;
     pageSize: 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;
 }
 export interface GetMarginAccountSummaryParams {
     tradingPairId?: string;
@@ -247,6 +280,10 @@ export interface TransferCollateralResponse {
     status: string;
     newEquity: string;
     newTotalCollateralValue: string;
+    /**
+     * The largest amount a further transfer-out will accept after this one,
+     * truncated toward zero at the collateral asset's precision.
+     */
     newWithdrawableCollateral: string;
     /**
      * Whether the transfer was committed to a position's stored margin. Present
@@ -261,8 +298,21 @@ export interface TransferCollateralResponse {
 }
 export interface GetMarginAccountMovementsParams {
     movementType?: string;
-    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, 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 MarginAccountMovement {
     movementId: string;
@@ -274,15 +324,17 @@ export interface MarginAccountMovement {
 }
 export interface GetMarginAccountMovementsResponse {
     movements: MarginAccountMovement[];
+    pageSize: number;
     /**
-     * Matching movements. Exact up to 10,000 pages of the requested page size
-     * (`pageSize` x 10,000 rows) and saturates there, so a caller with more
-     * movements 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.
+     *
+     * The response carries no item count: the underlying ledger is too large to
+     * count behind a filter.
      */
-    total: number;
-    page: number;
-    pageSize: number;
+    nextPageToken: string;
 }
 export interface SimulateOrderRiskRequest {
     tradingPairId: string;
@@ -521,6 +573,14 @@ export interface MarginAccountsAPI extends BaseAPI {
     /** One of the caller's margin accounts' own realized and unrealized PnL. */
     getMarginAccountPnl(marginAccountId: string): Promise<MarginAccountPnl>;
     transferMarginCollateral(request: TransferMarginCollateralRequest): Promise<TransferMarginCollateralResponse>;
+    /**
+     * Move collateral from the default margin account to one of the caller's sub-accounts, in one
+     * sequenced step. The default margin account itself is refused; fund it with the
+     * parent-margin-account routes.
+     */
+    transferCollateralToSubAccount(marginAccountId: string, amount: string): Promise<TransferMarginCollateralResponse>;
+    /** Move collateral from one of the caller's sub-accounts back to the default margin account. */
+    transferCollateralFromSubAccount(marginAccountId: string, amount: string): Promise<TransferMarginCollateralResponse>;
     listMarginAccounts(params?: ListMarginAccountsParams): Promise<ListMarginAccountsResponse>;
     getParentMarginAccountSummary(params?: GetMarginAccountSummaryParams): Promise<MarginAccountSummary>;
     /**

package/dist/market/index.d.ts

@@ -48,6 +48,12 @@ export interface TradingPair {
     category: string;
     /** Whether the market is active */
     isActive: boolean;
+    /**
+     * Isolated-only market: cross margin may only reduce a position here. A
+     * CROSS order that is not reduce-only is rejected with the error code
+     * `CROSS_MARGIN_NOT_ALLOWED`; open the position with `marginMode: "ISOLATED"`.
+     */
+    isolatedOnly: boolean;
     /** Maker fee in basis points */
     makerFeeBps: number;
     /** Taker fee in basis points */
@@ -486,30 +492,94 @@ export interface FundingRecord {
 export interface ListFundingHistoryParams {
     startTime?: string;
     endTime?: string;
-    page?: number;
+    /** Number of items per page, 1 to 1000 (default 50) */
     pageSize?: number;
-    /** Sort direction for epoch: "ASC" or "DESC" (default DESC). */
+    /** Sort direction for `settledAt`: "ASC" or "DESC" (default DESC). */
     orderBy?: "ASC" | "DESC";
+    /**
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position, from the newest settlement (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`. The walk seeks on `(settledAt, id)` in the
+     * requested direction. Filters and `orderBy` must match the request that
+     * minted the token.
+     */
+    pageToken?: string;
 }
 export interface ListFundingHistoryResponse {
     records: FundingRecord[];
+    /**
+     * Settlements matching the filter, bounded by the server count ceiling — see
+     * `totalCapped`. A lower bound when `totalCapped` is `true`.
+     */
     total: number;
-    page: number;
+    /** Items per page */
     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 settlements 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 interface ListAllFundingHistoryParams {
     startTime?: string;
     endTime?: string;
-    page?: number;
+    /** Number of items per page, 1 to 1000 (default 50) */
     pageSize?: number;
-    /** Sort direction for settledAt (default DESC). */
+    /** Sort direction for `settledAt` (default DESC). */
     orderBy?: "ASC" | "DESC";
+    /**
+     * Pagination cursor with two states:
+     * - Omitted (`undefined`) or empty string (`""`): start a cursor walk with
+     *   no prior position, from the newest settlement (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`. The walk seeks on `(settledAt, id)` in the
+     * requested direction. Filters and `orderBy` must match the request that
+     * minted the token.
+     */
+    pageToken?: string;
 }
 export interface ListAllFundingHistoryResponse {
     records: FundingRecord[];
+    /**
+     * Settlements matching the filter, bounded by the server count ceiling — see
+     * `totalCapped`. A lower bound when `totalCapped` is `true`.
+     */
     total: number;
-    page: number;
+    /** Items per page */
     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 settlements 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 interface OpenInterest {
     tradingPairId: string;

package/dist/pitpass/index.d.ts

@@ -4,7 +4,7 @@
  * Types for PitPass TraderCode API: code lookup, rewards balance, and transfer.
  */
 import type { BaseAPI } from "../api";
-import type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetMyReferralTreeParams, GetMyReferralTreeResponse, GetRewardsBalanceResponse, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse } from "./responses";
+import type { GetMyReferralDownlineParams, GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetMyReferralTreeParams, GetMyReferralTreeResponse, GetRewardsBalanceResponse, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse } from "./responses";
 /**
  * PitPass TraderCode API interface.
  *
@@ -106,24 +106,29 @@ export interface PitpassAPI extends BaseAPI {
      */
     getMyReferralPosition(): Promise<GetMyReferralPositionResponse>;
     /**
-     * Read your own downline: who you earn from and how much (earnings by source
-     * across L1/L2/L3), your L1 direct-referee roster (including referees who have
-     * not traded yet), and a per-level earnings summary.
+     * Read your own downline: one page of who you earn from and how much
+     * (earnings by source across every reward level, largest first), your L1
+     * direct-referee roster (including referees who have not traded yet), and a
+     * per-level earnings summary that covers every level and source on every
+     * page. Without `pageSize` / `pageToken` you get the first page (100 rows),
+     * not every row: follow `nextPageToken` until it is empty.
      *
      * Self-scoped and read-only. Every source and referee is a public wallet
      * address plus a `display` handle-or-wallet variant, never an internal id.
      *
-     * @returns Promise resolving to earnings-by-source, the direct-referee roster, and a summary
+     * @param params - Optional `pageSize` (1-500, default 100) and `pageToken`
+     * @returns Promise resolving to the earnings page, the direct-referee roster, a summary, and the next page token
      */
-    getMyReferralDownline(): Promise<GetMyReferralDownlineResponse>;
+    getMyReferralDownline(params?: GetMyReferralDownlineParams): Promise<GetMyReferralDownlineResponse>;
     /**
      * Read one level of your own referral tree: the wallets `parent` directly
      * referred (yourself when `parent` is omitted), a page at a time, newest
      * first. Expand a node by calling again with `parent` set to its wallet;
-     * nodes with `refereeCount > 0` are expandable, down to level 3.
+     * nodes with `refereeCount > 0` are expandable, down to the deepest level
+     * PitPass rewards (configured by Monaco, at most 10).
      *
-     * Self-scoped: `parent` must be you or one of your own L1/L2 referees — any
-     * other wallet is a 404. Each wallet appears once, under the referrer that
+     * Self-scoped: `parent` must be you or one of your own referees above that
+     * deepest level — any other wallet is a 404. Each wallet appears once, under the referrer that
      * earns from it.
      *
      * @param params - Optional `parent` wallet, `pageSize` (1-200), and `pageToken`
@@ -131,5 +136,5 @@ export interface PitpassAPI extends BaseAPI {
      */
     getMyReferralTree(params?: GetMyReferralTreeParams): Promise<GetMyReferralTreeResponse>;
 }
-export type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetMyReferralTreeParams, GetMyReferralTreeResponse, GetRewardsBalanceResponse, ReferralDirectReferee, ReferralEarningsSource, ReferralEarningsSummary, ReferralRewardEntry, ReferralTreeNode, ReferralUplineEntry, RewardsBalanceEntry, SetTraderCodeParams, TraderCodeAvailabilityReason, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse, } from "./responses";
-export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetMyReferralTreeParamsSchema, GetMyReferralTreeResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, ReferralTreeNodeSchema, ReferralUplineEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";
+export type { GetMyReferralDownlineParams, GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetMyReferralTreeParams, GetMyReferralTreeResponse, GetRewardsBalanceResponse, LevelEarnings, ReferralDirectReferee, ReferralEarningsSource, ReferralEarningsSummary, ReferralRewardEntry, ReferralTreeNode, ReferralUplineEntry, RewardsBalanceEntry, SetTraderCodeParams, TraderCodeAvailabilityReason, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse, } from "./responses";
+export { GetMyReferralDownlineParamsSchema, GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetMyReferralTreeParamsSchema, GetMyReferralTreeResponseSchema, GetRewardsBalanceResponseSchema, LevelEarningsSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, ReferralTreeNodeSchema, ReferralUplineEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";

package/dist/pitpass/index.js

@@ -3,4 +3,4 @@
  *
  * Types for PitPass TraderCode API: code lookup, rewards balance, and transfer.
  */
-export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetMyReferralTreeParamsSchema, GetMyReferralTreeResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, ReferralTreeNodeSchema, ReferralUplineEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";
+export { GetMyReferralDownlineParamsSchema, GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetMyReferralTreeParamsSchema, GetMyReferralTreeResponseSchema, GetRewardsBalanceResponseSchema, LevelEarningsSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, ReferralTreeNodeSchema, ReferralUplineEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";

package/dist/pitpass/responses.d.ts

@@ -118,12 +118,26 @@ export declare const ReferralDirectRefereeSchema: z.ZodObject<{
     referredAt: z.ZodString;
     totalEarned: z.ZodString;
 }, z.core.$strip>;
+/** What the caller has earned at one referral level. */
+export declare const LevelEarningsSchema: z.ZodObject<{
+    level: z.ZodNumber;
+    earned: z.ZodString;
+}, z.core.$strip>;
 /** Per-level breakdown of the caller's total referral earnings. */
 export declare const ReferralEarningsSummarySchema: z.ZodObject<{
     totalEarned: z.ZodString;
     level1Earned: z.ZodString;
     level2Earned: z.ZodString;
     level3Earned: z.ZodString;
+    byLevel: z.ZodArray<z.ZodObject<{
+        level: z.ZodNumber;
+        earned: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Query parameters for reading the caller's downline. */
+export declare const GetMyReferralDownlineParamsSchema: z.ZodObject<{
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** The caller's own downline: who they earn from, their L1 roster, and a summary. */
 export declare const GetMyReferralDownlineResponseSchema: z.ZodObject<{
@@ -145,7 +159,12 @@ export declare const GetMyReferralDownlineResponseSchema: z.ZodObject<{
         level1Earned: z.ZodString;
         level2Earned: z.ZodString;
         level3Earned: z.ZodString;
+        byLevel: z.ZodArray<z.ZodObject<{
+            level: z.ZodNumber;
+            earned: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
+    nextPageToken: z.ZodString;
 }, z.core.$strip>;
 /** Query parameters for reading one level of the caller's referral tree. */
 export declare const GetMyReferralTreeParamsSchema: z.ZodObject<{
@@ -192,6 +211,8 @@ export type GetMyReferralPositionResponse = z.infer<typeof GetMyReferralPosition
 export type ReferralEarningsSource = z.infer<typeof ReferralEarningsSourceSchema>;
 export type ReferralDirectReferee = z.infer<typeof ReferralDirectRefereeSchema>;
 export type ReferralEarningsSummary = z.infer<typeof ReferralEarningsSummarySchema>;
+export type LevelEarnings = z.infer<typeof LevelEarningsSchema>;
+export type GetMyReferralDownlineParams = z.infer<typeof GetMyReferralDownlineParamsSchema>;
 export type GetMyReferralDownlineResponse = z.infer<typeof GetMyReferralDownlineResponseSchema>;
 export type ReferralUplineEntry = z.infer<typeof ReferralUplineEntrySchema>;
 export type GetMyReferralTreeParams = z.infer<typeof GetMyReferralTreeParamsSchema>;

package/dist/pitpass/responses.js

@@ -141,9 +141,10 @@ export const GetMyReferralPositionResponseSchema = z.object({
     /** 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, then L3. At most
-     * three entries; empty when the caller was not referred. These are the
-     * wallets the caller's own trades pay referral rewards to.
+     * 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),
 });
@@ -153,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(),
@@ -171,34 +172,62 @@ 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 L1 or L2 referees to expand that node.
+     * one of your referees above the deepest rewarded level to expand that node.
      */
     parent: z.string().optional(),
     /** Nodes per page (1-200, default 50). */
@@ -212,13 +241,13 @@ export const ReferralTreeNodeSchema = z.object({
     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, or 3. */
+    /** 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 level 3. */
+    /** 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(),
@@ -227,7 +256,7 @@ export const ReferralTreeNodeSchema = z.object({
 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, 1 or 2 for an expanded referee. */
+    /** 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),

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