@0xmonaco/types 1.0.61 → 1.0.64

package/dist/applications/requests.d.ts

@@ -9,7 +9,7 @@
  * Query parameters for listing application orders.
  */
 export interface ListAppOrdersParams {
-    /** Page number (starts from 1) */
+    /** Page number (starts from 1, at most 10,000 — the last page the listing counts towards) */
     page?: number;
     /** Items per page (max 100) */
     pageSize?: number;
@@ -43,7 +43,7 @@ export interface ListAppUsersParams {
  * Query parameters for listing application movements.
  */
 export interface ListAppMovementsParams {
-    /** Page number (starts from 1) */
+    /** Page number (starts from 1, at most 10,000 — the last page the listing counts towards) */
     page?: number;
     /** Items per page (max 100) */
     pageSize?: number;

package/dist/applications/responses.d.ts

@@ -162,13 +162,21 @@ export interface AppBalance {
  */
 export interface ListAppOrdersResponse {
     orders: AppOrder[];
-    /** Total matching orders */
+    /**
+     * Matching orders. Exact up to 10,000 pages of the requested page size
+     * (`pageSize` x 10,000 rows) and saturates there, so an application with
+     * more matching orders than the listing can page through reads the cap,
+     * not its lifetime total.
+     */
     total: number;
     /** Current page number */
     page: number;
     /** Items per page */
     pageSize: number;
-    /** Total number of pages */
+    /**
+     * Number of pages at the requested page size. Exact up to 10,000 and
+     * saturates there, the last page this listing can reach.
+     */
     totalPages: number;
 }
 /**
@@ -190,13 +198,21 @@ export interface ListAppUsersResponse {
  */
 export interface ListAppMovementsResponse {
     movements: AppMovement[];
-    /** Total matching movements */
+    /**
+     * Matching movements. Exact up to 10,000 pages of the requested page size
+     * (`pageSize` x 10,000 rows) and saturates there, so an application with
+     * more matching movements than the listing can page through reads the cap,
+     * not its lifetime total.
+     */
     total: number;
     /** Current page number */
     page: number;
     /** Items per page */
     pageSize: number;
-    /** Total number of pages */
+    /**
+     * Number of pages at the requested page size. Exact up to 10,000 and
+     * saturates there, the last page this listing can reach.
+     */
     totalPages: number;
 }
 /**

package/dist/auth/responses.d.ts

@@ -43,6 +43,21 @@ export interface AuthState {
     expiresAt: number;
     /** Information about the authenticated user */
     user: User;
+    /**
+     * True when this verify created the user — the wallet's first-ever sign-in on
+     * this application. Gate first-time UX (e.g. the optional "have a referral
+     * code?" input) on it. Absent on responses from a server that predates the
+     * field.
+     */
+    isNewUser?: boolean;
+    /**
+     * True when a PitPass referral relationship was recorded on this verify: a
+     * valid, non-self TraderCode was presented on the wallet's first-ever sign-in
+     * and resolved to a known referrer. Use it to confirm the referral landed on
+     * the signup-success screen. Absent on responses from a server that predates
+     * the field.
+     */
+    referralApplied?: boolean;
 }
 export interface ApplicationInfo {
     /** Unique identifier for the application */

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 { GetRewardsBalanceResponse, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse } from "./responses";
+import type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetRewardsBalanceResponse, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse } from "./responses";
 /**
  * PitPass TraderCode API interface.
  *
@@ -91,6 +91,30 @@ export interface PitpassAPI extends BaseAPI {
      * @returns Promise resolving to the post-transfer rewards and trading balances
      */
     transferRewards(params: TransferRewardsParams): Promise<TransferRewardsResponse>;
+    /**
+     * Read your own referral position: your direct (L1) referrer, total earned,
+     * and most recent reward rows.
+     *
+     * Self-scoped — the server derives your identity from the session, so you can
+     * only ever read your own chain. `referrer` is the empty string when you were
+     * not referred (use it to gate the "already referred" UX). Every other user is
+     * identified by their public wallet address (with a `display` handle-or-wallet
+     * variant), never an internal id.
+     *
+     * @returns Promise resolving to your referrer, total earned, and recent rewards
+     */
+    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.
+     *
+     * 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
+     */
+    getMyReferralDownline(): Promise<GetMyReferralDownlineResponse>;
 }
-export type { GetRewardsBalanceResponse, RewardsBalanceEntry, SetTraderCodeParams, TraderCodeAvailabilityReason, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse, } from "./responses";
-export { GetRewardsBalanceResponseSchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";
+export type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetRewardsBalanceResponse, ReferralDirectReferee, ReferralEarningsSource, ReferralEarningsSummary, ReferralRewardEntry, RewardsBalanceEntry, SetTraderCodeParams, TraderCodeAvailabilityReason, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse, } from "./responses";
+export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, 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 { GetRewardsBalanceResponseSchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";
+export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";

package/dist/pitpass/responses.d.ts

@@ -67,6 +67,75 @@ export declare const TransferRewardsResponseSchema: z.ZodObject<{
     rewardsBalance: z.ZodString;
     tradingBalance: z.ZodString;
 }, z.core.$strip>;
+/** A single reward the caller has earned (one row per referred trade × level). */
+export declare const ReferralRewardEntrySchema: z.ZodObject<{
+    source: z.ZodString;
+    sourceDisplay: z.ZodString;
+    level: z.ZodNumber;
+    amount: z.ZodString;
+    token: z.ZodString;
+    rateApplied: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+/** The caller's own referral position: who referred them and what they've earned. */
+export declare const GetMyReferralPositionResponseSchema: z.ZodObject<{
+    referrer: z.ZodString;
+    referrerDisplay: z.ZodString;
+    totalEarned: z.ZodString;
+    rewards: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        sourceDisplay: z.ZodString;
+        level: z.ZodNumber;
+        amount: z.ZodString;
+        token: z.ZodString;
+        rateApplied: z.ZodString;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** One aggregated earnings row per (source trader, level, token) the caller earns from. */
+export declare const ReferralEarningsSourceSchema: z.ZodObject<{
+    source: z.ZodString;
+    sourceDisplay: z.ZodString;
+    level: z.ZodNumber;
+    totalEarned: z.ZodString;
+    token: z.ZodString;
+}, z.core.$strip>;
+/** One direct (L1) referee of the caller, whether or not they have traded yet. */
+export declare const ReferralDirectRefereeSchema: z.ZodObject<{
+    wallet: z.ZodString;
+    display: z.ZodString;
+    referredAt: z.ZodString;
+    totalEarned: 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;
+}, z.core.$strip>;
+/** The caller's own downline: who they earn from, their L1 roster, and a summary. */
+export declare const GetMyReferralDownlineResponseSchema: z.ZodObject<{
+    earningsBySource: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        sourceDisplay: z.ZodString;
+        level: z.ZodNumber;
+        totalEarned: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+    directReferees: z.ZodArray<z.ZodObject<{
+        wallet: z.ZodString;
+        display: z.ZodString;
+        referredAt: z.ZodString;
+        totalEarned: z.ZodString;
+    }, z.core.$strip>>;
+    summary: z.ZodObject<{
+        totalEarned: z.ZodString;
+        level1Earned: z.ZodString;
+        level2Earned: z.ZodString;
+        level3Earned: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export type RewardsBalanceEntry = z.infer<typeof RewardsBalanceEntrySchema>;
 export type GetRewardsBalanceResponse = z.infer<typeof GetRewardsBalanceResponseSchema>;
 export type TraderCodeResponse = z.infer<typeof TraderCodeResponseSchema>;
@@ -76,3 +145,9 @@ export type SetTraderCodeParams = z.infer<typeof SetTraderCodeParamsSchema>;
 export type TraderCodeInfoResponse = z.infer<typeof TraderCodeInfoResponseSchema>;
 export type TransferRewardsParams = z.infer<typeof TransferRewardsParamsSchema>;
 export type TransferRewardsResponse = z.infer<typeof TransferRewardsResponseSchema>;
+export type ReferralRewardEntry = z.infer<typeof ReferralRewardEntrySchema>;
+export type GetMyReferralPositionResponse = z.infer<typeof GetMyReferralPositionResponseSchema>;
+export type ReferralEarningsSource = z.infer<typeof ReferralEarningsSourceSchema>;
+export type ReferralDirectReferee = z.infer<typeof ReferralDirectRefereeSchema>;
+export type ReferralEarningsSummary = z.infer<typeof ReferralEarningsSummarySchema>;
+export type GetMyReferralDownlineResponse = z.infer<typeof GetMyReferralDownlineResponseSchema>;

package/dist/pitpass/responses.js

@@ -101,3 +101,81 @@ export const TransferRewardsResponseSchema = z.object({
     /** Your trading balance for the token after the transfer, RAW atomic units. */
     tradingBalance: z.string(),
 });
+/** A single reward the caller has earned (one row per referred trade × level). */
+export const ReferralRewardEntrySchema = z.object({
+    /** Public wallet address of the trader (taker) whose trade generated this reward. */
+    source: z.string(),
+    /** Human-facing name for the source: their custom handle if claimed, else the wallet. */
+    sourceDisplay: z.string(),
+    /** Referral level (1 = direct/30%, 2 = 15%, 3 = 5%). */
+    level: z.number(),
+    /** Reward amount, in RAW atomic units of the token. */
+    amount: z.string(),
+    /** Reward token contract address (0x-prefixed). */
+    token: z.string(),
+    /** The referral rate applied, as a decimal fraction (e.g. `0.30` for L1). */
+    rateApplied: z.string(),
+    /** RFC 3339 timestamp when the reward row was recorded. */
+    createdAt: z.string(),
+});
+/** 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.
+     */
+    referrer: z.string(),
+    /** Human-facing name for the referrer: their custom handle if claimed, else the wallet (empty when not referred). */
+    referrerDisplay: z.string(),
+    /** Total reward amount earned across every level and token, in RAW atomic units. */
+    totalEarned: z.string(),
+    /** The caller's most recent reward rows, newest first (bounded server-side). */
+    rewards: z.array(ReferralRewardEntrySchema),
+});
+/** One aggregated earnings row per (source trader, level, token) the caller earns from. */
+export const ReferralEarningsSourceSchema = z.object({
+    /** Public wallet address of the trader (taker) the caller earns from. */
+    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). */
+    level: z.number(),
+    /** Total earned from this source at this level and token, in RAW atomic units. */
+    totalEarned: z.string(),
+    /** Reward token contract address (0x-prefixed). */
+    token: z.string(),
+});
+/** One direct (L1) referee of the caller, whether or not they have traded yet. */
+export const ReferralDirectRefereeSchema = z.object({
+    /** Public wallet address of the direct referee. */
+    wallet: z.string(),
+    /** Human-facing name for the referee: their custom handle if claimed, else the wallet. */
+    display: z.string(),
+    /** RFC 3339 timestamp when the referral relationship was recorded. */
+    referredAt: z.string(),
+    /** Total the caller has earned from this referee's own (L1) trades, RAW units. `0` if they haven't traded. */
+    totalEarned: 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. */
+    level1Earned: z.string(),
+    /** Total earned from L2 downline, in RAW atomic units. */
+    level2Earned: z.string(),
+    /** Total earned from L3 downline, in RAW atomic units. */
+    level3Earned: z.string(),
+});
+/** 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. */
+    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.
+     */
+    summary: ReferralEarningsSummarySchema,
+});

package/dist/trading/responses.d.ts

@@ -170,12 +170,13 @@ export interface GetPaginatedOrdersParams {
      * - Non-empty: an opaque cursor from a previous response's
      *   `nextPageToken`; results resume immediately after that position.
      *
-     * In either cursor-walk state (empty or non-empty), `page` is ignored, the
-     * response omits exact totals (`total`/`totalPages`/`page` are 0), and
-     * results cover full order history — hot and archived rows merged —
-     * unlike page-number mode, which only ever sees recent history. Clients
-     * that need complete order history must use the cursor form (pass `""` to
-     * start, then follow `nextPageToken`) rather than `page`.
+     * In either cursor-walk state (empty or non-empty), `page` is ignored (it
+     * comes back as 0), but `total` and `totalPages` ARE populated — bounded by
+     * the server count ceiling, see `totalCapped`. Results cover full order
+     * history — hot and archived rows merged — unlike page-number mode, which
+     * only ever sees recent history. Clients that need complete order history
+     * must use the cursor form (pass `""` to start, then follow `nextPageToken`)
+     * rather than `page`.
      */
     pageToken?: string;
 }
@@ -186,10 +187,9 @@ export interface GetPaginatedOrdersResponse {
     /** Array of historical orders from PostgreSQL (paginated) */
     orders: Order[];
     /**
-     * Total number of orders matching the query.
-     *
-     * @deprecated Only populated by legacy page-number (offset) responses; 0 in
-     * cursor mode, which has no exact total. Walk `nextPageToken` instead.
+     * Total number of orders matching the query, populated in BOTH pagination
+     * modes and bounded by the server count ceiling — see `totalCapped`. When
+     * `totalCapped` is `true` this is a lower bound (at least this many exist).
      */
     total: number;
     /**
@@ -202,10 +202,9 @@ export interface GetPaginatedOrdersResponse {
     /** Number of orders per page */
     pageSize: number;
     /**
-     * Total number of pages.
-     *
-     * @deprecated Only populated by legacy page-number (offset) responses; 0 in
-     * cursor mode, which has no exact total. Walk `nextPageToken` instead.
+     * Total number of pages at this `pageSize`, populated in BOTH pagination
+     * modes and bounded by the server count ceiling — see `totalCapped`. A lower
+     * bound when `totalCapped` is `true`.
      */
     totalPages: number;
     /**
@@ -223,6 +222,13 @@ export interface GetPaginatedOrdersResponse {
      * history.
      */
     nextPageToken: string;
+    /**
+     * `true` when MORE than the server ceiling of orders matched, so the count
+     * stopped at the ceiling and `total` / `totalPages` are a lower bound (more
+     * than `total` orders exist). `false` when `total` is the exact count —
+     * including exactly the ceiling, which is still reported exactly.
+     */
+    totalCapped: boolean;
 }
 /**
  * Response from getting a single order by ID

package/dist/websocket/events/account-events.d.ts

@@ -9,6 +9,22 @@
  * A lost key or terminal update need not have a later replacement. Each
  * frame carries the account's full current health, so consume it as a
  * terminal-state snapshot per margin account, never as an additive delta.
+ *
+ * A subscribe-time snapshot arrives ahead of the live diffs, carrying one row
+ * per margin account you own IN THE APPLICATION YOU AUTHENTICATED UNDER -
+ * including FLAT accounts, which the live producer never emits for. Live
+ * delivery is wider: it is per user and carries no application filter, so if
+ * the same wallet trades through more than one application you also receive
+ * live frames for those accounts. Do NOT treat an account absent from the
+ * snapshot as deleted - merge per `marginAccountId` rather than replacing your
+ * whole map. Snapshot rows are this same payload with `sequence` absent; see
+ * that field.
+ *
+ * Live frames emitted before your subscription activated are buffered during
+ * the snapshot read and delivered after it, so one can supersede a newer
+ * snapshot row. A later frame normally corrects that within the ~30s
+ * keepalive; if the account went flat in that window and its final frame never
+ * arrived, reconnect to re-seed.
  */
 /**
  * Account event data carrying the current margin health of a single account.
@@ -17,23 +33,33 @@ export interface AccountEventData {
     /** Margin account this update describes (UUID) */
     marginAccountId: string;
     /**
-     * Monotonic per-account counter within one producer run. It advances only on
-     * published frames, may SKIP values (at-most-once publishing/delivery), and
-     * resets to zero when the producer restarts — which can happen while your
-     * WebSocket stays connected, because the socket is owned by a different
-     * service. It is therefore never a gap detector and never a cross-restart
-     * total order.
+     * Monotonic per-account counter within one producer run, on LIVE frames
+     * only. It advances only on published frames, may SKIP values (at-most-once
+     * publishing/delivery), and resets to zero when the producer restarts —
+     * which can happen while your WebSocket stays connected, because the socket
+     * is owned by a different service. It is therefore never a gap detector and
+     * never a cross-restart total order.
+     *
+     * Dedupe rule, LIVE FRAMES ONLY: order them per account by `updatedAt`,
+     * newest wins, and use `sequence` only to break ties between frames carrying
+     * the SAME `updatedAt` (those come from the same producer run). A snapshot
+     * row is not ranked this way — see below.
      *
-     * Dedupe rule: order frames per account by `updatedAt`, newest wins; use
-     * `sequence` only to break ties between frames carrying the SAME `updatedAt`
-     * (those come from the same producer run).
+     * **Absent on a subscribe-time snapshot row.** The counter belongs to the
+     * matching engine's own producer process and the snapshot is served by a
+     * different service, which cannot mint one; a `0` would be worse than
+     * absent, because it is indistinguishable from a restarted producer's first
+     * frame and would make you drop live frames behind the baseline.
      *
-     * There is no subscribe-time snapshot: an account with active exposure
-     * delivers a baseline within ~30s (keepalive republish), but a FLAT account
-     * is silent until it re-activates — fetch the margin-accounts REST endpoint
-     * when an immediate flat baseline is needed.
+     * A snapshot row's `updatedAt` is the instant that account's state was
+     * PERSISTED (a database write), while a live frame's is when the engine
+     * SAMPLED it. Those clocks are not comparable under persistence lag, so the
+     * rule is simply that **a live frame always supersedes a snapshot row for the
+     * same `marginAccountId`** — rank `updatedAt` only between live frames, with
+     * `sequence` breaking ties inside one producer run, which a snapshot is not
+     * part of. Treat `undefined` as "unknown", never as zero.
      */
-    sequence: number;
+    sequence?: number;
     /** Mark-inclusive account equity: collateral + unrealized PnL + funding (decimal string) */
     equity: string;
     /** Raw deposited collateral in USD (decimal string) */

package/dist/websocket/events/account-events.js

@@ -9,4 +9,20 @@
  * A lost key or terminal update need not have a later replacement. Each
  * frame carries the account's full current health, so consume it as a
  * terminal-state snapshot per margin account, never as an additive delta.
+ *
+ * A subscribe-time snapshot arrives ahead of the live diffs, carrying one row
+ * per margin account you own IN THE APPLICATION YOU AUTHENTICATED UNDER -
+ * including FLAT accounts, which the live producer never emits for. Live
+ * delivery is wider: it is per user and carries no application filter, so if
+ * the same wallet trades through more than one application you also receive
+ * live frames for those accounts. Do NOT treat an account absent from the
+ * snapshot as deleted - merge per `marginAccountId` rather than replacing your
+ * whole map. Snapshot rows are this same payload with `sequence` absent; see
+ * that field.
+ *
+ * Live frames emitted before your subscription activated are buffered during
+ * the snapshot read and delivered after it, so one can supersede a newer
+ * snapshot row. A later frame normally corrects that within the ~30s
+ * keepalive; if the account went flat in that window and its final frame never
+ * arrived, reconnect to re-seed.
  */

package/dist/wire/operations.d.ts

@@ -10,6 +10,6 @@
  * hand-written SDK surface. CI regenerates it and fails on a diff, identical to
  * the `schema.ts` wire-types tripwire (MON-1476), so it can never go stale.
  */
-export declare const OPERATION_IDS: readonly ["attach_position_tp_sl", "batch_cancel_all", "batch_cancel_all_by_pair", "batch_cancel_orders", "batch_close_all_positions", "batch_create_orders", "batch_replace_orders", "cancel_conditional_order", "cancel_order", "cancel_twap_order", "check_trader_code_availability", "claim_buildercode_rewards", "claim_managed_market_lease", "clear_trader_code", "close_position", "create_challenge", "create_delegated_session", "create_order", "create_sub_account_limit", "create_twap_order", "delete_sub_account_limit", "get_application_config", "get_application_stats", "get_available_collateral", "get_buildercode_payout_summary", "get_buildercode_rewards_balance", "get_buildercodes_config", "get_candles", "get_conditional_order", "get_faucet_info", "get_funding_state", "get_index_price", "get_margin_account_movements", "get_margin_account_summary", "get_mark_price", "get_market_metadata", "get_market_stats", "get_my_fee_tier", "get_my_trader_code", "get_open_interest", "get_order_by_id", "get_orderbook_snapshot", "get_orders", "get_parent_margin_account_movements", "get_parent_margin_account_summary", "get_perp_market_config", "get_perp_market_summary", "get_portfolio_assets", "get_portfolio_chart", "get_portfolio_margin", "get_portfolio_performance", "get_portfolio_realized_pnl", "get_portfolio_stats", "get_portfolio_summary", "get_position", "get_position_pnl_history", "get_position_risk", "get_pulse", "get_rewards_balance", "get_screener", "get_self_trade_prevention_default", "get_sub_account_limits", "get_sweeper_chains", "get_trade_by_id", "get_trader_code_info", "get_trades", "get_trading_pair_by_id", "get_twap_order", "get_twap_order_tca", "get_user_balance_by_asset", "get_user_balances", "get_user_movements", "get_user_profile", "get_user_trades", "get_withdrawal", "health_check", "initiate_withdrawal", "list_all_funding_history", "list_application_balances", "list_application_movements", "list_application_orders", "list_application_users", "list_buildercode_payouts", "list_conditional_orders", "list_delegated_agent_owners", "list_delegated_agents", "list_funding_history", "list_funding_payments", "list_managed_market_assignments", "list_margin_accounts", "list_pending_withdrawals", "list_position_history", "list_positions", "list_sub_accounts_with_balances", "list_trading_pairs", "list_twap_orders", "mint_tokens", "refresh_managed_market_quotes", "refresh_session", "register_deposit_address", "replace_order", "revoke_delegated_agent", "revoke_session", "set_self_trade_prevention_default", "set_trader_code", "simulate_fees", "simulate_order_risk", "simulate_parent_margin_order_risk", "simulate_risk_bucket_order_risk", "submit_whitelist", "transfer_collateral_from_margin_account", "transfer_collateral_from_parent_margin_account", "transfer_collateral_to_margin_account", "transfer_collateral_to_parent_margin_account", "transfer_collateral_to_risk_bucket", "transfer_rewards", "update_sub_account_limit", "upsert_delegated_agent", "verify_signature"];
+export declare const OPERATION_IDS: readonly ["attach_position_tp_sl", "batch_cancel_all", "batch_cancel_all_by_pair", "batch_cancel_orders", "batch_close_all_positions", "batch_create_orders", "batch_replace_orders", "cancel_conditional_order", "cancel_order", "cancel_twap_order", "check_trader_code_availability", "claim_buildercode_rewards", "claim_managed_market_lease", "clear_trader_code", "close_position", "create_challenge", "create_delegated_session", "create_order", "create_sub_account_limit", "create_twap_order", "delete_sub_account_limit", "get_application_config", "get_application_stats", "get_available_collateral", "get_buildercode_payout_summary", "get_buildercode_rewards_balance", "get_buildercodes_config", "get_candles", "get_conditional_order", "get_faucet_info", "get_funding_state", "get_index_price", "get_margin_account_movements", "get_margin_account_summary", "get_mark_price", "get_market_metadata", "get_market_stats", "get_my_fee_tier", "get_my_referral_downline", "get_my_referral_position", "get_my_trader_code", "get_open_interest", "get_order_by_id", "get_orderbook_snapshot", "get_orders", "get_parent_margin_account_movements", "get_parent_margin_account_summary", "get_perp_market_config", "get_perp_market_summary", "get_portfolio_assets", "get_portfolio_chart", "get_portfolio_margin", "get_portfolio_performance", "get_portfolio_realized_pnl", "get_portfolio_stats", "get_portfolio_summary", "get_position", "get_position_pnl_history", "get_position_risk", "get_pulse", "get_rewards_balance", "get_screener", "get_self_trade_prevention_default", "get_sub_account_limits", "get_sweeper_chains", "get_trade_by_id", "get_trader_code_info", "get_trades", "get_trading_pair_by_id", "get_twap_order", "get_twap_order_tca", "get_user_balance_by_asset", "get_user_balances", "get_user_movements", "get_user_profile", "get_user_trades", "get_withdrawal", "health_check", "initiate_withdrawal", "list_all_funding_history", "list_application_balances", "list_application_movements", "list_application_orders", "list_application_users", "list_buildercode_payouts", "list_conditional_orders", "list_delegated_agent_owners", "list_delegated_agents", "list_funding_history", "list_funding_payments", "list_managed_market_assignments", "list_margin_accounts", "list_pending_withdrawals", "list_position_history", "list_positions", "list_sub_accounts_with_balances", "list_trading_pairs", "list_twap_orders", "mint_tokens", "refresh_managed_market_quotes", "refresh_session", "register_deposit_address", "replace_order", "revoke_delegated_agent", "revoke_session", "set_self_trade_prevention_default", "set_trader_code", "simulate_fees", "simulate_order_risk", "simulate_parent_margin_order_risk", "simulate_risk_bucket_order_risk", "submit_whitelist", "transfer_collateral_from_margin_account", "transfer_collateral_from_parent_margin_account", "transfer_collateral_to_margin_account", "transfer_collateral_to_parent_margin_account", "transfer_collateral_to_risk_bucket", "transfer_rewards", "update_sub_account_limit", "upsert_delegated_agent", "verify_signature"];
 /** Union of every OpenAPI operationId in the spec. */
 export type OperationId = (typeof OPERATION_IDS)[number];

package/dist/wire/operations.js

@@ -49,6 +49,8 @@ export const OPERATION_IDS = [
     "get_market_metadata",
     "get_market_stats",
     "get_my_fee_tier",
+    "get_my_referral_downline",
+    "get_my_referral_position",
     "get_my_trader_code",
     "get_open_interest",
     "get_order_by_id",

package/dist/wire/schema.d.ts

@@ -2166,6 +2166,61 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/pitpass/referrals/me": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get your referral position
+         * @description Read your own referral position (self-scoped).
+         *
+         *      Return the authenticated caller's referral position: their direct (L1)
+         *      referrer, the total rewards they have earned, and their most recent reward
+         *      rows. Self-scoped — identity comes only from the session, never a path id,
+         *      so a caller can only ever read their own chain. Every other user is
+         *      identified by their public wallet address, never an internal id. An empty
+         *      `referrer` means the caller was not referred.
+         */
+        get: operations["get_my_referral_position"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/pitpass/referrals/me/downline": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get your referral downline and earnings
+         * @description Read your own downline earnings (self-scoped).
+         *
+         *      Return who the authenticated caller earns from and how much: an
+         *      earnings-by-source breakdown aggregated from the caller's reward rows across
+         *      all three reward levels (L1/L2/L3), their L1 direct-referee roster (including
+         *      referees who have not traded yet), and a per-level earnings summary.
+         *      Self-scoped — identity comes only from the session, never a path id. Every
+         *      source and referee is identified by their public wallet address, never an
+         *      internal id.
+         */
+        get: operations["get_my_referral_downline"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/pitpass/rewards/balance": {
         parameters: {
             query?: never;
@@ -4811,6 +4866,33 @@ export interface components {
             /** @description Six-row fee schedule for the requested pair, ascending by tier */
             feeSchedule?: components["schemas"]["FeeTierScheduleRow"][] | null;
         };
+        GetMyReferralDownlineResponse: {
+            /** @description One row per (source trader, level, token) the caller earns from, across all three reward levels. Comes straight from the caller's reward rows — no tree walk. */
+            earningsBySource?: components["schemas"]["ReferralEarningsSource"][] | null;
+            /** @description The caller's direct (L1) referees, newest first, including referees who have not traded yet (0 earned). Bounded to the most recent 500 EFFECTIVE referees (after per-wallet dedupe and the winning-edge filter). The earnings views (`earnings_by_source` and the summary) are unbounded and count every level, so a caller past the roster cap still sees their full earnings; only this roster listing is capped. */
+            directReferees?: components["schemas"]["ReferralDirectReferee"][] | null;
+            /** @description Total earned broken down by level (L1/L2/L3). */
+            summary?: components["schemas"]["ReferralEarningsSummary"] | null;
+        };
+        GetMyReferralPositionResponse: {
+            /**
+             * @description Public wallet address of the caller's direct (L1) referrer — who referred them. Empty when the caller was not referred. Never exposes L2/L3 upline or any internal id.
+             * @example 0x0000000000000000000000000000000000000002
+             */
+            referrer?: string | null;
+            /**
+             * @description Total reward amount the caller has earned, summed across every level and token, in RAW atomic units.
+             * @example 1400000
+             */
+            totalEarned?: string | null;
+            /**
+             * @description Human-facing name for the referrer: their custom TraderCode handle when they have claimed one, otherwise the wallet address (same as `referrer`). Empty when the caller was not referred. Render this instead of raw hex.
+             * @example cooltrader123
+             */
+            referrerDisplay?: string | null;
+            /** @description The caller's most recent reward rows, newest first. Bounded server-side — not the full history. */
+            rewards?: components["schemas"]["ReferralRewardEntry"][] | null;
+        };
         /** @description Latest public open interest for a trading pair. */
         GetOpenInterestResponse: {
             /**
@@ -6028,7 +6110,7 @@ export interface components {
             movements?: components["schemas"]["ApplicationMovement"][] | null;
             /**
              * Format: uint32
-             * @description Total matching movements
+             * @description Matching movements. Exact up to 10,000 pages of the requested page size (page_size x 10,000 rows) and saturates there, so an application with more matching movements than the listing can page through reads the cap, not its lifetime total.
              * @example 150
              */
             total?: number | null;
@@ -6046,7 +6128,7 @@ export interface components {
             pageSize?: number | null;
             /**
              * Format: uint32
-             * @description Total number of pages
+             * @description Number of pages at the requested page size. Exact up to 10,000 and saturates there, the last page this listing can reach.
              * @example 8
              */
             totalPages?: number | null;
@@ -6055,7 +6137,7 @@ export interface components {
             orders?: components["schemas"]["ApplicationOrder"][] | null;
             /**
              * Format: uint32
-             * @description Total matching orders
+             * @description Matching orders. Exact up to 10,000 pages of the requested page size (page_size x 10,000 rows) and saturates there, so an application with more matching orders than the listing can page through reads the cap, not its lifetime total.
              * @example 150
              */
             total?: number | null;
@@ -6073,7 +6155,7 @@ export interface components {
             pageSize?: number | null;
             /**
              * Format: uint32
-             * @description Total number of pages
+             * @description Number of pages at the requested page size. Exact up to 10,000 and saturates there, the last page this listing can reach.
              * @example 8
              */
             totalPages?: number | null;
@@ -6206,8 +6288,7 @@ export interface components {
             orders?: components["schemas"]["GetOrderResponse"][] | null;
             /**
              * Format: uint32
-             * @deprecated
-             * @description Deprecated: total number of orders matching the filter (legacy offset mode only; 0 in cursor mode)
+             * @description Total number of orders matching the filter, populated in both pagination modes; bounded by the server ceiling — a lower bound when totalCapped is true.
              * @example 150
              */
             total?: number | null;
@@ -6226,8 +6307,7 @@ export interface components {
             pageSize?: number | null;
             /**
              * Format: uint32
-             * @deprecated
-             * @description Deprecated: total number of pages (legacy offset mode only; 0 in cursor mode)
+             * @description Total number of pages at this pageSize, populated in both pagination modes; bounded by the server ceiling — a lower bound when totalCapped is true.
              * @example 8
              */
             totalPages?: number | null;
@@ -6247,6 +6327,11 @@ export interface components {
              *      means page-number mode does not participate in cursor continuation.
              */
             nextPageToken?: string | null;
+            /**
+             * @description True when more than the server ceiling of orders matched, so the count stopped at the ceiling and total/totalPages are a lower bound (more than total exist). False when total is the exact count, including exactly the ceiling.
+             * @example false
+             */
+            totalCapped?: boolean | null;
         };
         ListPendingWithdrawalsResponse: {
             withdrawals?: components["schemas"]["PendingWithdrawal"][] | null;
@@ -7295,6 +7380,136 @@ export interface components {
              */
             relevance?: number | null;
         };
+        /** @description One direct (L1) referee of the caller, whether or not they have traded yet. */
+        ReferralDirectReferee: {
+            /**
+             * @description Public wallet address of the direct referee. Never an internal id.
+             * @example 0x0000000000000000000000000000000000000002
+             */
+            wallet?: string | null;
+            /**
+             * @description RFC 3339 timestamp when the referral relationship was recorded (the referee's sign-up under the caller).
+             * @example 2026-07-07T18:00:00Z
+             */
+            referredAt?: string | null;
+            /**
+             * @description Total the caller has earned from this referee's own (L1) trades, in RAW atomic units. `0` for a referee who has not traded yet.
+             * @example 900000
+             */
+            totalEarned?: string | null;
+            /**
+             * @description Human-facing name for the referee: their custom TraderCode handle when they have claimed one, otherwise the wallet address (same as `wallet`). Render this instead of raw hex.
+             * @example cooltrader123
+             */
+            display?: string | null;
+        };
+        /**
+         * @description One aggregated earnings row per (source trader, level, token) the caller
+         *      earns from.
+         */
+        ReferralEarningsSource: {
+            /**
+             * @description Public wallet address of the trader (taker) the caller earns from. Never an internal id.
+             * @example 0x0000000000000000000000000000000000000002
+             */
+            source?: string | null;
+            /**
+             * Format: int32
+             * @description Referral level the caller earns from this source at: 1 (direct), 2, or 3.
+             * @example 1
+             */
+            level?: number | null;
+            /**
+             * @description Total earned from this source at this level and token, in RAW atomic units.
+             * @example 900000
+             */
+            totalEarned?: string | null;
+            /**
+             * @description Reward token contract address (0x-prefixed).
+             * @example 0x0000000000000000000000000000000000000002
+             */
+            token?: string | null;
+            /**
+             * @description Human-facing name for the source: their custom TraderCode handle when they have claimed one, otherwise the wallet address (same as `source`). Render this instead of raw hex.
+             * @example cooltrader123
+             */
+            sourceDisplay?: string | null;
+        };
+        /**
+         * @description Per-level breakdown of the caller's total referral earnings.
+         *
+         *      These are ALL-TIME CREDITED earnings — a raw sum of the immutable
+         *      `referral_rewards` audit rows — and match the `total_earned` on the referral
+         *      position. They are NOT the caller's current spendable rewards balance:
+         *      `GetRewardsBalance` reports the live bucket, which `TransferRewards` draws
+         *      down, so the two diverge after any transfer. Read the rewards balance for
+         *      current availability. Denominated in the single reward token's atomic units
+         *      (Monaco pays PitPass rewards in one token — the quote asset); if a deployment
+         *      ever pays in more than one reward token, atomic units across tokens are not
+         *      additive, so read the per-token `earnings_by_source` rows for a correct
+         *      breakdown.
+         */
+        ReferralEarningsSummary: {
+            /**
+             * @description All-time credited earnings across all levels, in the reward token's RAW atomic units (see the message note — this is not the spendable rewards balance).
+             * @example 1400000
+             */
+            totalEarned?: string | null;
+            /**
+             * @description Total earned from direct (L1) referees, in RAW atomic units.
+             * @example 900000
+             */
+            level1Earned?: string | null;
+            /**
+             * @description Total earned from L2 downline, in RAW atomic units.
+             * @example 400000
+             */
+            level2Earned?: string | null;
+            /**
+             * @description Total earned from L3 downline, in RAW atomic units.
+             * @example 100000
+             */
+            level3Earned?: string | null;
+        };
+        /** @description A single reward the caller has earned, one row per referred trade × level. */
+        ReferralRewardEntry: {
+            /**
+             * @description Public wallet address of the trader (taker) whose trade generated this reward. Never an internal id.
+             * @example 0x0000000000000000000000000000000000000002
+             */
+            source?: string | null;
+            /**
+             * Format: int32
+             * @description Referral level this reward was paid at: 1 (direct, 30%), 2 (15%), or 3 (5%).
+             * @example 1
+             */
+            level?: number | null;
+            /**
+             * @description Reward amount, in RAW atomic units of the token.
+             * @example 1200000
+             */
+            amount?: string | null;
+            /**
+             * @description Reward token contract address (0x-prefixed).
+             * @example 0x0000000000000000000000000000000000000002
+             */
+            token?: string | null;
+            /**
+             * @description The referral rate applied to the source's fee for this reward, as a decimal fraction (e.g. `0.30` for L1).
+             * @example 0.30
+             */
+            rateApplied?: string | null;
+            /**
+             * @description RFC 3339 timestamp when the reward row was recorded.
+             * @example 2026-07-07T18:00:00Z
+             */
+            createdAt?: string | null;
+            /**
+             * @description Human-facing name for the source: their custom TraderCode handle when they have claimed one, otherwise the wallet address (same as `source`). Render this instead of raw hex.
+             * @example cooltrader123
+             */
+            sourceDisplay?: string | null;
+        };
         RefreshManagedMarketQuotesRequest: {
             launchId?: string | null;
             ownerId?: string | null;
@@ -8853,6 +9068,16 @@ export interface components {
              */
             expiresAt?: number | null;
             user?: components["schemas"]["UserInfo"];
+            /**
+             * @description True when this verify created the user row — the wallet's first sign-in to THIS application. Identity is per `(wallet, application)`, so a wallet already registered on another application is still `is_new_user` on its first sign-in to a new one. Use it to gate first-time UX (e.g. showing the optional "have a referral code?" input only to new users) and to confirm a fresh sign-up. False for every returning verify on this application.
+             * @example true
+             */
+            isNewUser?: boolean | null;
+            /**
+             * @description True when a PitPass referral relationship was recorded on this verify: a valid, non-self TraderCode presented on the wallet's first sign-in to THIS application resolved to a known referrer. Scoped like `is_new_user` (per `(wallet, application)`), so a wallet already registered on another application can still see this on its first sign-in to a new one. False for a returning user of this application, an absent or unknown code, or a self-referral. Confirms the referral landed for the signup success screen.
+             * @example true
+             */
+            referralApplied?: boolean | null;
         };
         Withdrawal: {
             /**
@@ -12428,13 +12653,14 @@ export interface operations {
                  *       - Non-empty: an opaque cursor from a previous response's
                  *         `next_page_token`; results resume immediately after that position.
                  *
-                 *      In either cursor-walk state (empty or non-empty), `page` is ignored, the
-                 *      response omits exact totals (total/total_pages/page are 0), and results
-                 *      cover full order history — hot and archived rows merged — unlike
-                 *      page-number mode, which only ever sees recent history. Clients that need
-                 *      complete order history must use the cursor form (start with an empty
-                 *      string, then follow next_page_token) rather than `page`. Filters and
-                 *      orderBy must match the request that produced the token.
+                 *      In either cursor-walk state (empty or non-empty), `page` is ignored (it
+                 *      comes back as 0), but `total` and `total_pages` ARE populated — bounded by
+                 *      the server count ceiling, see `total_capped`. Results cover full order
+                 *      history — hot and archived rows merged — unlike page-number mode, which
+                 *      only ever sees recent history. Clients that need complete order history
+                 *      must use the cursor form (start with an empty string, then follow
+                 *      next_page_token) rather than `page`. Filters and orderBy must match the
+                 *      request that produced the token.
                  */
                 pageToken?: string;
             };
@@ -13600,6 +13826,88 @@ export interface operations {
             };
         };
     };
+    get_my_referral_position: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetMyReferralPositionResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Read rate limit exceeded — every authenticated read draws one request from the account's read budget; retry after the interval in details.retryAfter */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Internal server error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    get_my_referral_downline: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetMyReferralDownlineResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Read rate limit exceeded — every authenticated read draws one request from the account's read budget; retry after the interval in details.retryAfter */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Internal server error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     get_rewards_balance: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.61",
+	"version": "1.0.64",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -16,7 +16,7 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.61",
+		"@0xmonaco/contracts": "1.0.64",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {