@0xmonaco/types 1.0.77 → 1.0.80

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

@@ -26,7 +26,11 @@ export interface MarginAccountSummary {
     /** Equity headroom: equity less the initial margin requirement. */
     freeCollateral: string;
     /**
-     * The largest amount a transfer-out of this scope will actually accept.
+     * The largest amount a transfer-out of this scope accepts without lowering
+     * any position's posted margin, so without moving a leverage or a
+     * liquidation price. A removal from an isolated risk bucket with one open
+     * position can take more, out of that position's margin: see
+     * `maxRemovableCollateral`.
      *
      * Not a clamped `freeCollateral`. Free collateral is equity headroom, and
      * equity includes mark-to-market gains that a transfer cannot move — so the
@@ -93,6 +97,24 @@ export interface MarginAccountSummary {
      * precision, like `withdrawableCollateral`.
      */
     availableOrderCollateral?: string;
+    /**
+     * The largest removal from this risk bucket the risk engine accepts when the
+     * removal may also lower the posted margin of the bucket's one open
+     * position: `withdrawableCollateral` plus the position's margin above its
+     * initial margin at the mark, capped by what the parent margin account
+     * accepts. Everything past `withdrawableCollateral` comes out of the
+     * position's margin, so it raises the position's leverage and moves its
+     * liquidation price toward the mark.
+     *
+     * Equal to `withdrawableCollateral` on a cross risk bucket and on an
+     * isolated one with no open position or several.
+     *
+     * 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. Truncated toward zero at the quote asset's
+     * precision, like `withdrawableCollateral`.
+     */
+    maxRemovableCollateral?: string;
     /**
      * Copy trading: present only on a copy risk bucket row (a follow's copy
      * account — its cross risk bucket and any isolated children). The id of the

package/dist/pitpass/index.d.ts

@@ -93,7 +93,8 @@ export interface PitpassAPI extends BaseAPI {
     transferRewards(params: TransferRewardsParams): Promise<TransferRewardsResponse>;
     /**
      * Read your own referral position: your referral chain upward (`upline`, L1
-     * then L2 then L3), your direct referrer, total earned, and most recent
+     * then L2 and onward, as many levels as your trades on this client
+     * application pay), your direct referrer, total earned, and most recent
      * reward rows.
      *
      * Self-scoped — the server derives your identity from the session, so you can
@@ -125,7 +126,8 @@ export interface PitpassAPI extends BaseAPI {
      * 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 the deepest level
-     * PitPass rewards (configured by Monaco, at most 10).
+     * any client application rewards (at most 10). Your direct referees (L1)
+     * are always listed.
      *
      * 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

package/dist/pitpass/responses.js

@@ -107,13 +107,13 @@ export const ReferralRewardEntrySchema = z.object({
     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%). */
+    /** Referral level: 1 (direct), 2, and so on (at most 10). */
     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). */
+    /** The referral rate applied, as a decimal fraction (e.g. `0.30`). */
     rateApplied: z.string(),
     /** RFC 3339 timestamp when the reward row was recorded. */
     createdAt: z.string(),
@@ -124,14 +124,15 @@ export const ReferralUplineEntrySchema = z.object({
     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. */
+    /** How far above the caller this ancestor is: 1 (direct referrer), 2, and so on (at most 10). */
     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. Same wallet as the first `upline` entry.
+     * when the caller was not referred. Same wallet as the first `upline` entry
+     * whenever `upline` is not empty.
      */
     referrer: z.string(),
     /** Human-facing name for the referrer: their custom handle if claimed, else the wallet (empty when not referred). */
@@ -141,10 +142,12 @@ 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, 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.
+     * The caller's referral chain upward, nearest first: L1, L2, and so on, as
+     * many levels as the caller's trades on this client application pay (at
+     * most 10). Shorter when the chain ends; empty when the caller was not
+     * referred or this client application pays no referral levels. These are the
+     * wallets the caller's own trades on this client application pay referral
+     * rewards to.
      */
     upline: z.array(ReferralUplineEntrySchema),
 });
@@ -241,7 +244,7 @@ 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, and so on up to the configured reward depth (at most 10). */
+    /** Depth below the caller: 1 (you referred them), 2, and so on, as deep as any client application rewards (at most 10). */
     level: z.number(),
     /** Wallet address of this node's referrer — your own wallet for a level-1 node. */
     parent: z.string(),

package/dist/portfolio/index.d.ts

@@ -195,8 +195,10 @@ export interface PortfolioRiskBucket {
     unrealizedPnl: string;
     positionCount: number;
     /**
-     * The largest transfer-out of this risk bucket the engine will actually
-     * accept. NOT a clamped `freeCollateral`: the bucket's allocated
+     * The largest transfer-out of this risk bucket the engine accepts without
+     * lowering a position's posted margin; a removal from an isolated risk
+     * bucket with one open position can take more (`maxRemovableCollateral`).
+     * 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
@@ -218,6 +220,18 @@ export interface PortfolioRiskBucket {
      * (the key is omitted, never null) on persisted-fallback reads.
      */
     availableOrderCollateral?: string;
+    /**
+     * The largest removal from this risk bucket the engine accepts when the
+     * removal may also lower the posted margin of the bucket's one open
+     * position, down to its initial margin at the mark — the same figure as
+     * `MarginAccountSummary.maxRemovableCollateral`. Equal to
+     * `withdrawableCollateral` for a cross risk bucket and for an isolated one
+     * with no open position or several.
+     *
+     * Present only when a live risk engine snapshot served it; absent (the key
+     * is omitted, never null) on persisted-fallback reads.
+     */
+    maxRemovableCollateral?: string;
     /**
      * The mode this bucket is margined under.
      *

package/dist/positions/index.d.ts

@@ -13,6 +13,37 @@ export type PositionStatus = "OPEN" | "CLOSED" | "LIQUIDATING" | "LIQUIDATED" |
  */
 export type PositionStatusFilter = "OPEN" | "CLOSED" | "LIQUIDATING" | "LIQUIDATED";
 export type ClosePositionType = "MARKET" | "LIMIT" | "IOC";
+/**
+ * Whether a position's lifetime totals (`exitPrice`, `realizedRoe`,
+ * `feesPaid`, `fundingPaid`, `cumFees`, `netRealizedPnl`) are served, and if
+ * not, whether they will be. The server never sends
+ * `LIFETIME_TOTALS_STATUS_UNSPECIFIED`.
+ *
+ * - `LIFETIME_TOTALS_STATUS_COMPLETE`: the position's history covers its whole
+ *   lifetime. The lifetime fields are served under their own rules (a
+ *   terminal row's `netRealizedPnl`, `realizedRoe` and `cumFees` can still wait
+ *   on the position's PnL sample).
+ * - `LIFETIME_TOTALS_STATUS_PENDING`: the position's history is still being
+ *   written up to this row's `version`, or the row changed while it was being
+ *   read. Every lifetime field is absent.
+ *   Temporary: retry the read after a short backoff (seconds). Until the
+ *   position-history checkpoint is seeded, PENDING arises only when the
+ *   position row changed between the row read and the totals read.
+ * - `LIFETIME_TOTALS_STATUS_INCOMPLETE`: the lifetime totals are not complete
+ *   now, and a quick retry will not change that. A gap in legacy history (or
+ *   reducing executions that do not reconcile with `realizedPnl`) is
+ *   permanent; a maintained-totals row that is missing or has drifted is
+ *   repaired by the background reconcile (at startup and daily), after which
+ *   the row reads COMPLETE. Every lifetime field that is present comes from
+ *   the maintained totals, which are cross-checked against each other and
+ *   repaired by the background reconcile (e.g. `exitPrice` can be present
+ *   while `cumFees` is absent). `OPEN` and `LIQUIDATING` positions are
+ *   checked against realized PnL too: an `OPEN` or `LIQUIDATING` row whose
+ *   reductions do not account for it is INCOMPLETE with no `cumFees`.
+ *
+ * Never read an absent lifetime field as zero.
+ */
+export type LifetimeTotalsStatus = "LIFETIME_TOTALS_STATUS_UNSPECIFIED" | "LIFETIME_TOTALS_STATUS_COMPLETE" | "LIFETIME_TOTALS_STATUS_PENDING" | "LIFETIME_TOTALS_STATUS_INCOMPLETE";
 export interface Position {
     positionId: string;
     marginAccountId: string;
@@ -108,6 +139,9 @@ export interface Position {
      * of PnL retention, or for positions predating the PnL service — rather than
      * an understated partial. On a terminal row it is also null until the
      * final close is recorded in its PnL sample, or while fee data is incomplete.
+     * On an `OPEN` or `LIQUIDATING` row it is also null when the position's reductions do not
+     * account for its `realizedPnl` (`lifetimeTotalsStatus` INCOMPLETE), rather
+     * than an understated total.
      */
     cumFees?: string;
     /**
@@ -162,6 +196,14 @@ export interface Position {
      * version.
      */
     openedAt?: string | null;
+    /**
+     * Whether this row's lifetime totals are served — see
+     * {@link LifetimeTotalsStatus}. Set on every REST read row; `null` or absent
+     * from a server that predates the field. WebSocket position frames do not
+     * carry it. Widened with `string` so a status this SDK version predates is
+     * passed through rather than mistyped; handle the unknown case.
+     */
+    lifetimeTotalsStatus?: LifetimeTotalsStatus | (string & {}) | null;
 }
 export interface ListPositionsParams {
     marginAccountId?: string;
@@ -179,9 +221,12 @@ export interface ListPositionsParams {
      * **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
+     * UUID order, NOT newest-first. `status: "CLOSED"` and
+     * `status: "LIQUIDATED"` read persisted rows newest-closed first, so a
+     * position held for weeks and closed today leads the list. Every other
+     * filter reads persisted rows newest-opened first. Each is a separate
+     * cursor space, so a token is only valid in the one that minted it, and
+     * crossing between the live and persisted walks 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

package/dist/trading/orders.d.ts

@@ -44,7 +44,10 @@ export interface Order {
     averageFillPrice?: string;
     /** Trading mode (SPOT or MARGIN) */
     tradingMode: TradingMode;
-    /** Time in force - GTC, IOC, or FOK (GTD is deprecated and rejected) */
+    /**
+     * Time in force - GTC, IOC, or FOK (GTD is deprecated and rejected).
+     * Absent on a MARKET order, which has none.
+     */
     timeInForce?: TimeInForce;
     /** Order creation timestamp (ISO 8601) */
     createdAt: string;

package/dist/websocket/client.d.ts

@@ -42,17 +42,20 @@
  * baseline over REST for the extra consumer.
  *
  * Where the server has no snapshot arm for a channel yet, the callback is
- * simply never invoked — a silent no-op, not an error. `orderbook`, `ohlcv`,
- * `trades` and `movements` take no `onSnapshot` at all: they stream events
- * rather than state, and the channel-coverage lock pins that classification
- * against the server's own snapshot dispatch.
+ * simply never invoked — a silent no-op, not an error. `orderbook`, `ohlcv`
+ * and `movements` take no `onSnapshot` at all: they stream events rather than
+ * state, and the channel-coverage lock pins that classification against the
+ * server's own snapshot dispatch. `trades` is also an event stream, but its
+ * `onSnapshot` delivers the pair's newest trades as a recent-history baseline:
+ * it can overlap the first live trades, or miss one executed just before the
+ * subscribe, so a consumer dedupes on `tradeId`.
  */
 import type { SessionCredentials } from "../auth/index";
 import type { Interval } from "../market";
 import type { TradingMode } from "../trading";
 import type { WebSocketStatus } from "./base";
 import type { OrderbookQuotationMode } from "./clients/orderbook-client";
-import type { AccountEvent, AccountEventData, ConditionalOrderEvent, ConditionalOrderEventData, CopyEvent, CopyRelationshipEventData, InstrumentEvent, InstrumentEventData, LiquidationEvent, LiquidationEventData, MarketStatsAllEvent, MarketStatsData, MarketStatsEvent, MarketStatsSummary, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderEvent, PositionEvent, PositionEventData, PositionValuationEvent, TradeEvent, TwapOrderEvent, TwapOrderEventData, UserBalanceEvent, UserBalanceEventData, UserMovementEvent } from "./events";
+import type { AccountEvent, AccountEventData, ConditionalOrderEvent, ConditionalOrderEventData, CopyEvent, CopyRelationshipEventData, InstrumentEvent, InstrumentEventData, LiquidationEvent, LiquidationEventData, MarketStatsAllEvent, MarketStatsData, MarketStatsEvent, MarketStatsSummary, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderEvent, PositionEvent, PositionEventData, PositionValuationEvent, TradeEvent, TradeEventData, TwapOrderEvent, TwapOrderEventData, UserBalanceEvent, UserBalanceEventData, UserMovementEvent } from "./events";
 import type { OrderSnapshotItem, SnapshotHandler } from "./snapshots";
 export type MessageHandler<T> = (data: T) => void;
 export interface MonacoWebSocket {
@@ -72,8 +75,11 @@ export interface MonacoWebSocket {
     orderbook: (tradingPairId: string, tradingMode: TradingMode, magnitude: number, quotationMode: OrderbookQuotationMode, handler: MessageHandler<OrderbookEvent>) => () => void;
     /** Subscribe to OHLCV candlestick events (public) */
     ohlcv: (tradingPairId: string, tradingMode: TradingMode, interval: Interval, handler: MessageHandler<OHLCVEvent>, priceType?: OHLCVPriceType) => () => void;
-    /** Subscribe to trade events (public) */
-    trades: (tradingPairId: string, handler: MessageHandler<TradeEvent>) => () => void;
+    /**
+     * Subscribe to trade events (public); `onSnapshot` receives the pair's newest 50 trades, newest first.
+     * The snapshot can overlap the first live trades or miss one executed just before subscribing, so dedupe on `tradeId`.
+     */
+    trades: (tradingPairId: string, handler: MessageHandler<TradeEvent>, onSnapshot?: SnapshotHandler<TradeEventData>) => () => void;
     /** Subscribe to user movement events (requires authentication) */
     movements: (handler: MessageHandler<UserMovementEvent>) => () => void;
     /** Subscribe to user order events for all trading pairs (requires authentication); `onSnapshot` receives every resting order */

package/dist/websocket/client.js

@@ -42,8 +42,11 @@
  * baseline over REST for the extra consumer.
  *
  * Where the server has no snapshot arm for a channel yet, the callback is
- * simply never invoked — a silent no-op, not an error. `orderbook`, `ohlcv`,
- * `trades` and `movements` take no `onSnapshot` at all: they stream events
- * rather than state, and the channel-coverage lock pins that classification
- * against the server's own snapshot dispatch.
+ * simply never invoked — a silent no-op, not an error. `orderbook`, `ohlcv`
+ * and `movements` take no `onSnapshot` at all: they stream events rather than
+ * state, and the channel-coverage lock pins that classification against the
+ * server's own snapshot dispatch. `trades` is also an event stream, but its
+ * `onSnapshot` delivers the pair's newest trades as a recent-history baseline:
+ * it can overlap the first live trades, or miss one executed just before the
+ * subscribe, so a consumer dedupes on `tradeId`.
  */

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

@@ -12,7 +12,11 @@
  *
  * 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
+ * including FLAT accounts. A flat account sends no periodic frame; it gets a
+ * live frame (on the same per-account `sequence`) only after its collateral
+ * moves. Moves before the producer's next tick collapse into one frame with
+ * the latest state, normally within ~2s; a burst wider than 512 flat accounts
+ * spreads over the following ticks. 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

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

@@ -12,7 +12,11 @@
  *
  * 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
+ * including FLAT accounts. A flat account sends no periodic frame; it gets a
+ * live frame (on the same per-account `sequence`) only after its collateral
+ * moves. Moves before the producer's next tick collapse into one frame with
+ * the latest state, normally within ~2s; a burst wider than 512 flat accounts
+ * spreads over the following ticks. 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

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

@@ -30,7 +30,13 @@
  * `quoteAssetId`, `baseToken`, `quoteToken`, `baseAssetName`, `quoteAssetName`,
  * `baseDecimals` and `quoteDecimals`. Perp frames add `minLeverage`. These are
  * declared optional because a server that predates them omits them.
+ *
+ * Perp frames also carry `riskTiers`, the market's whole margin ladder in the
+ * same {@link RiskTier} shape and values as the REST perp config's
+ * `riskTiers`. An edit to any tier emits a `config_change` whose
+ * `changedFields` names `risk_tiers`.
  */
+import type { RiskTier } from "../../market";
 /**
  * The kind of instrument change a frame reports.
  *
@@ -118,6 +124,13 @@ export interface InstrumentEventData {
     initialMarginRate?: string;
     /** Maintenance margin rate (decimal string). Perp-only; omitted for spot. */
     maintenanceMarginRate?: string;
+    /**
+     * The market's whole margin ladder, ascending by `tierLevel`, with the same
+     * fields and values as the REST perp config's `riskTiers` (no
+     * `maxPositionSize`). Perp-only; omitted for spot, and declared optional
+     * because a server that predates it omits it.
+     */
+    riskTiers?: RiskTier[];
     /** Names of the fields this mutation touched (snake_case wire field names) */
     changedFields: string[];
     /** Timestamp when the configuration was last updated (ISO 8601) */

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

@@ -30,4 +30,9 @@
  * `quoteAssetId`, `baseToken`, `quoteToken`, `baseAssetName`, `quoteAssetName`,
  * `baseDecimals` and `quoteDecimals`. Perp frames add `minLeverage`. These are
  * declared optional because a server that predates them omits them.
+ *
+ * Perp frames also carry `riskTiers`, the market's whole margin ladder in the
+ * same {@link RiskTier} shape and values as the REST perp config's
+ * `riskTiers`. An edit to any tier emits a `config_change` whose
+ * `changedFields` names `risk_tiers`.
  */

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

@@ -57,8 +57,11 @@ export interface CommonOrderEventData {
     quantity?: string;
     /** Order quantity in RAW (integer, base-unit) precision. Wire: `quantity_raw`. */
     quantityRaw?: string;
-    /** Time in force - present in most events */
-    timeInForce?: TimeInForce | (string & {});
+    /**
+     * Time in force. `null` on every event of a MARKET order, which has none,
+     * and on a maker fill, which does not carry the maker's value.
+     */
+    timeInForce?: TimeInForce | (string & {}) | null;
     /**
      * Client-assigned correlation handle, echoed so an event can be matched to
      * the request that placed the order without a round trip to `getOrder`.

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

@@ -127,11 +127,13 @@ export interface PositionEventData {
      * not move it. Do not use it as a reconciliation key — that is `version`'s
      * job; this is display metadata.
      *
-     * It matches a REST read of the same OPEN position exactly. Two cases come
-     * from the server's persistence clock instead and differ by the persistence
-     * lag: a TERMINAL row (this frame carries the engine's close instant, a
-     * terminal REST read carries the stored one), and any position read after a
-     * matching-engine restart. Accurate to that lag, not to the microsecond.
+     * It matches a REST read of the same OPEN position exactly. A TERMINAL REST
+     * read carries the instant the matching engine emitted the close, which can
+     * differ slightly from this frame's close instant; older terminal rows may
+     * instead carry the server's persistence clock, trailing the close by the
+     * persistence lag. Any position read after a matching-engine restart also
+     * comes from the persistence clock and differs by that lag. Accurate to that
+     * lag, not to the microsecond.
      *
      * A third case is not lag-bounded: while the server's matching engine is
      * unreachable, a REST read of an OPEN position falls back to that row's

package/dist/websocket/snapshots.d.ts

@@ -4,7 +4,10 @@
  * The server injects one `Snapshot` frame per subscription, after the
  * `Subscribed` ack and before that subscription's first live diff. Its `data`
  * is the channel's COMPLETE current state as a flat array — a consumer that
- * applies it wholesale needs no REST baseline read for that channel.
+ * applies it wholesale needs no REST baseline read for that channel. `trades`
+ * is the exception: its array is the pair's newest trades, a recent-history
+ * baseline rather than complete state, which can overlap the first live trades
+ * or miss one executed just before the subscribe — dedupe on `tradeId`.
  *
  * Two rules hold across every channel:
  *
@@ -102,7 +105,7 @@ export interface OrderSnapshotItem {
     remainingQuantityRaw: string | null;
     /** Order status; the snapshot carries only resting statuses */
     status: string;
-    /** Time in force */
+    /** Time in force; `null` on a MARKET order, which has none */
     timeInForce: TimeInForce | (string & {}) | null;
     /** Average fill price (decimal string); `null` before the first fill */
     averageFillPrice: string | null;

package/dist/websocket/snapshots.js

@@ -4,7 +4,10 @@
  * The server injects one `Snapshot` frame per subscription, after the
  * `Subscribed` ack and before that subscription's first live diff. Its `data`
  * is the channel's COMPLETE current state as a flat array — a consumer that
- * applies it wholesale needs no REST baseline read for that channel.
+ * applies it wholesale needs no REST baseline read for that channel. `trades`
+ * is the exception: its array is the pair's newest trades, a recent-history
+ * baseline rather than complete state, which can overlap the first live trades
+ * or miss one executed just before the subscribe — dedupe on `tradeId`.
  *
  * Two rules hold across every channel:
  *

package/dist/wire/schema.d.ts

@@ -2804,12 +2804,12 @@ export interface paths {
          *
          *      Return the authenticated caller's referral position: their referral chain
          *      upward (L1, L2 and onward — who referred them, who referred that wallet, and
-         *      so on, as many levels as PitPass currently rewards), the total rewards they
-         *      have earned, and their most recent reward rows.
+         *      so on, as many levels as their trades on this client application pay), 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` and `upline` mean the caller was not referred.
+         *      `referrer` means the caller was not referred.
          */
         get: operations["get_my_referral_position"];
         put?: never;
@@ -2867,8 +2867,9 @@ export interface paths {
          *      relative to the caller, its parent, how many wallets it has referred (so the
          *      client knows whether it can be expanded), and what the caller has earned
          *      from that wallet's own trades. Expanding a node is another call with
-         *      `parent` set to that node's wallet; the tree stops at the deepest level that
-         *      pays referral rewards, which an admin configures (at most 10).
+         *      `parent` set to that node's wallet; the tree always lists the caller's
+         *      direct referees (L1) and goes as deep as any client application rewards,
+         *      at most 10 levels.
          *
          *      Self-scoped — identity comes only from the session. A `parent` that is not
          *      the caller or a referee the caller can expand returns 404, the same
@@ -4137,7 +4138,7 @@ export interface components {
             amount?: string | null;
             /**
              * Format: int32
-             * @description Basis-point rate applied to this credit. For `BUILDER_FEE`, this is the normalized builder-fee rate charged to the taker. For `REVENUE_SHARE`, it is the realized whole-basis-point rate after the Monaco-floor clamp and can be lower than the configured BuilderCodes budget.
+             * @description Basis-point rate applied to this credit. For `BUILDER_FEE`, this is the normalized builder-fee rate charged to the taker. For `REVENUE_SHARE`, it is the realized whole-basis-point rate for that fill and can be lower than the configured BuilderCodes budget.
              * @example 1000
              */
             appliedBps?: number | null;
@@ -5517,15 +5518,15 @@ export interface components {
              * @example 0x0000000000000000000000000000000000000001
              */
             payoutAddress?: string | null;
-            /** @description Whether the BuilderCodes revenue share is switched on. While false no new share accrues; balances already credited stay readable and claimable. */
+            /** @description Whether the BuilderCodes revenue share is switched on for this application. While false no new share accrues on this application's fills; balances already credited stay readable and claimable. */
             buildercodesEnabled?: boolean | null;
             /**
              * Format: uint32
-             * @description Target BuilderCodes share in basis points, computed from the fill's gross non-negative Monaco protocol take and capped by the remainder after Monaco's floor.
+             * @description This application's configured target BuilderCodes revenue share of Monaco's protocol fee on each taker fill, in basis points. The rate actually paid on a fill is the payout row's appliedBps, which can be lower.
              * @example 1000
              */
             buildercodesBudgetBps?: number | null;
-            /** @description Whether builder fees are currently charged. While false, `builderFeeBps` is stored but no builder fee is charged. */
+            /** @description Whether builder fees are currently charged on this application's orders. While false, `builderFeeBps` is stored but no builder fee is charged. */
             builderFeeEnabled?: boolean | null;
             /**
              * Format: uint32
@@ -5698,7 +5699,11 @@ export interface components {
             maintenanceMarginRequired?: string | null;
             freeCollateral?: string | null;
             /**
-             * @description The largest amount a transfer-out of this scope will actually accept.
+             * @description The largest amount a transfer-out of this scope accepts without lowering
+             *      any position's posted margin, so without moving a leverage or a
+             *      liquidation price. A removal from an isolated risk bucket with one open
+             *      position can take more, out of that position's margin: see
+             *      `max_removable_collateral`.
              *
              *      NOT a clamped `free_collateral`. Free collateral is equity headroom, and
              *      equity includes mark-to-market gains that a transfer cannot move — so
@@ -5765,6 +5770,12 @@ export interface components {
             subaccountKey?: string | null;
             /** @description See `MarginAccountSummary.margin_account_state`. */
             marginAccountState?: string | null;
+            /**
+             * @description See `MarginAccountSummary.max_removable_collateral`: the largest removal
+             *      the risk engine accepts when it may also lower the posted margin of the
+             *      bucket's one open position.
+             */
+            maxRemovableCollateral?: string | null;
         };
         GetMarkPriceResponse: {
             /** Format: uuid */
@@ -5970,7 +5981,7 @@ export interface components {
         };
         GetMyReferralPositionResponse: {
             /**
-             * @description Public wallet address of the caller's direct (L1) referrer — who referred them. Empty when the caller was not referred. The same wallet as the first `upline` entry; never an internal id.
+             * @description Public wallet address of the caller's direct (L1) referrer — who referred them. Empty when the caller was not referred. The same wallet as the first `upline` entry whenever `upline` is not empty; never an internal id.
              * @example 0x0000000000000000000000000000000000000002
              */
             referrer?: string | null;
@@ -5986,7 +5997,7 @@ export interface components {
             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 The caller's referral chain upward, nearest first: L1 (who referred the caller), then L2 (who referred them), and so on. At most as many entries as PitPass currently rewards levels (at most 10); shorter when the chain ends, empty when the caller was not referred. These are the wallets the caller's own trades pay referral rewards to. */
+            /** @description The caller's referral chain upward, nearest first: L1 (who referred the caller), then L2 (who referred them), and so on: the levels the caller's trades on this client application pay (at most 10). Shorter when the chain ends; empty when the caller was not referred or this client application pays no referral levels. These are the wallets the caller's own trades on this client application pay referral rewards to. */
             upline?: components["schemas"]["ReferralUplineEntry"][] | null;
         };
         GetMyReferralTreeResponse: {
@@ -6085,7 +6096,7 @@ export interface components {
              */
             tradingMode?: string | null;
             /**
-             * @description Time in force: GTC, IOC, or FOK
+             * @description Time in force: GTC, IOC, or FOK. Absent on MARKET orders, which have none.
              * @example GTC
              */
             timeInForce?: string | null;
@@ -6609,11 +6620,13 @@ export interface components {
              *      same instant — the list, the detail read, the risk read, the WebSocket
              *      positions snapshot, and the live position_update frames.
              *
-             *      Two cases come from the persistence clock instead and differ from the
-             *      matching engine's by the persistence lag: a TERMINAL row (the live
-             *      position_update frame carries the engine's close instant, this field
-             *      carries the stored one), and any position read after a matching-engine
-             *      restart. Accurate to that lag, not to the microsecond.
+             *      A TERMINAL row carries the instant the matching engine emitted the
+             *      close, which can differ slightly from the close instant on the live
+             *      position_update frame; older terminal rows may instead carry the
+             *      persistence clock, trailing the close by the persistence lag. Any
+             *      position read after a matching-engine restart also comes from the
+             *      persistence clock and differs from the matching engine's by that lag.
+             *      Accurate to that lag, not to the microsecond.
              *
              *      A third case is not lag-bounded: an OPEN row read while the matching
              *      engine is unreachable falls back to the row's own lifecycle columns
@@ -6680,6 +6693,9 @@ export interface components {
              *      for positions predating the PnL service — rather than an understated
              *      partial. On a terminal row it is also null until the final close is
              *      recorded in the position's PnL sample, or while fee data is incomplete.
+             *      On an OPEN or LIQUIDATING row it is also null when the position's reductions
+             *      do not account for its realized PnL (lifetime_totals_status INCOMPLETE),
+             *      rather than an understated total.
              */
             cumFees?: string | null;
             /**
@@ -6693,6 +6709,13 @@ export interface components {
              *      `Position.opened_at` above.
              */
             openedAt?: string | null;
+            /**
+             * Format: enum
+             * @description Whether this position's lifetime totals are served. Same contract as
+             *      `Position.lifetime_totals_status` above.
+             * @enum {string|null}
+             */
+            lifetimeTotalsStatus?: "LIFETIME_TOTALS_STATUS_UNSPECIFIED" | "LIFETIME_TOTALS_STATUS_COMPLETE" | "LIFETIME_TOTALS_STATUS_PENDING" | "LIFETIME_TOTALS_STATUS_INCOMPLETE" | null;
         };
         GetPositionRiskResponse: {
             positionId?: string | null;
@@ -6738,11 +6761,13 @@ export interface components {
              *      same instant — the list, the detail read, the risk read, the WebSocket
              *      positions snapshot, and the live position_update frames.
              *
-             *      Two cases come from the persistence clock instead and differ from the
-             *      matching engine's by the persistence lag: a TERMINAL row (the live
-             *      position_update frame carries the engine's close instant, this field
-             *      carries the stored one), and any position read after a matching-engine
-             *      restart. Accurate to that lag, not to the microsecond.
+             *      A TERMINAL row carries the instant the matching engine emitted the
+             *      close, which can differ slightly from the close instant on the live
+             *      position_update frame; older terminal rows may instead carry the
+             *      persistence clock, trailing the close by the persistence lag. Any
+             *      position read after a matching-engine restart also comes from the
+             *      persistence clock and differs from the matching engine's by that lag.
+             *      Accurate to that lag, not to the microsecond.
              *
              *      A third case is not lag-bounded: an OPEN row read while the matching
              *      engine is unreachable falls back to the row's own lifecycle columns
@@ -7835,7 +7860,11 @@ export interface components {
             maintenanceMarginRequired?: string | null;
             freeCollateral?: string | null;
             /**
-             * @description The largest amount a transfer-out of this scope will actually accept.
+             * @description The largest amount a transfer-out of this scope accepts without lowering
+             *      any position's posted margin, so without moving a leverage or a
+             *      liquidation price. A removal from an isolated risk bucket with one open
+             *      position can take more, out of that position's margin: see
+             *      `max_removable_collateral`.
              *
              *      NOT a clamped `free_collateral`. Free collateral is equity headroom, and
              *      equity includes mark-to-market gains that a transfer cannot move — so
@@ -7940,6 +7969,25 @@ export interface components {
              *      sub-account).
              */
             marginAccountState?: string | null;
+            /**
+             * @description The largest removal from this risk bucket the risk engine accepts when
+             *      the removal may also lower the posted margin of the bucket's one open
+             *      position: `withdrawable_collateral` plus the position's margin above its
+             *      initial margin at the mark, capped by what the parent margin account
+             *      accepts. Everything past `withdrawable_collateral` comes out of the
+             *      position's margin, so it raises the position's leverage and moves its
+             *      liquidation price toward the mark.
+             *
+             *      Equal to `withdrawable_collateral` on a cross risk bucket and on an
+             *      isolated one with no open position or several, where a removal never
+             *      reaches into posted margin.
+             *
+             *      Present only on risk-bucket rows served from a live risk engine snapshot;
+             *      absent on parent rows and on persisted-fallback reads. Printed truncated
+             *      toward zero at the quote asset's precision, like
+             *      `withdrawable_collateral`.
+             */
+            maxRemovableCollateral?: string | null;
         };
         MatchResult: {
             /**
@@ -8347,8 +8395,11 @@ export interface components {
             unrealizedPnl?: string | null;
             positionCount?: string | null;
             /**
-             * @description The largest transfer-out of this risk bucket the engine will actually
-             *      accept — the bound enforced on bucket collateral withdrawals.
+             * @description The largest transfer-out of this risk bucket the engine accepts without
+             *      lowering a position's posted margin — the bound enforced on bucket
+             *      collateral withdrawals that leave the positions' leverage alone. A removal
+             *      from an isolated risk bucket with one open position can take more: see
+             *      `max_removable_collateral`.
              *
              *      NOT a clamped `free_collateral`: free collateral is equity headroom and
              *      credits mark-to-market gains that a transfer-out cannot move. This bound
@@ -8410,6 +8461,16 @@ export interface components {
             copyFollowId?: string | null;
             /** @description On a copy risk bucket row, the followed leader's custom TraderCode handle, when they still hold one */
             copyLeaderHandle?: string | null;
+            /**
+             * @description The largest removal from this risk bucket the engine accepts when the
+             *      removal may also lower the posted margin of the bucket's one open
+             *      position, down to its initial margin at the mark — the same figure as
+             *      `MarginAccountSummary.max_removable_collateral`. Equal to
+             *      `withdrawable_collateral` for a cross risk bucket and for an isolated one
+             *      with no open position or several. Present only when a live risk engine
+             *      snapshot served it; truncated toward zero at quote decimals.
+             */
+            maxRemovableCollateral?: string | null;
         };
         PortfolioSeriesWindow: {
             /**
@@ -8532,11 +8593,13 @@ export interface components {
              *      same instant — the list, the detail read, the risk read, the WebSocket
              *      positions snapshot, and the live position_update frames.
              *
-             *      Two cases come from the persistence clock instead and differ from the
-             *      matching engine's by the persistence lag: a TERMINAL row (the live
-             *      position_update frame carries the engine's close instant, this field
-             *      carries the stored one), and any position read after a matching-engine
-             *      restart. Accurate to that lag, not to the microsecond.
+             *      A TERMINAL row carries the instant the matching engine emitted the
+             *      close, which can differ slightly from the close instant on the live
+             *      position_update frame; older terminal rows may instead carry the
+             *      persistence clock, trailing the close by the persistence lag. Any
+             *      position read after a matching-engine restart also comes from the
+             *      persistence clock and differs from the matching engine's by that lag.
+             *      Accurate to that lag, not to the microsecond.
              *
              *      A third case is not lag-bounded: an OPEN row read while the matching
              *      engine is unreachable falls back to the row's own lifecycle columns
@@ -8603,6 +8666,9 @@ export interface components {
              *      for positions predating the PnL service — rather than an understated
              *      partial. On a terminal row it is also null until the final close is
              *      recorded in the position's PnL sample, or while fee data is incomplete.
+             *      On an OPEN or LIQUIDATING row it is also null when the position's reductions
+             *      do not account for its realized PnL (lifetime_totals_status INCOMPLETE),
+             *      rather than an understated total.
              */
             cumFees?: string | null;
             /**
@@ -8639,6 +8705,28 @@ export interface components {
              *      equal version.
              */
             openedAt?: string | null;
+            /**
+             * Format: enum
+             * @description Whether this row's lifetime totals (exit_price, realized_roe, fees_paid,
+             *      funding_paid, cum_fees, net_realized_pnl) are served: COMPLETE when the
+             *      position's history covers its whole lifetime, PENDING while that history
+             *      is still being written up to this row's version or the row changed while
+             *      it was being read (every lifetime field is
+             *      absent; retry shortly), INCOMPLETE when the totals are not complete now
+             *      and a quick retry will not change that (a legacy-history gap is
+             *      permanent; a missing or drifted maintained-totals row is repaired by the
+             *      background reconcile at startup and daily; every field that is present
+             *      comes from the maintained totals, which are cross-checked against each
+             *      other and repaired by the background reconcile; an absent one is not
+             *      zero). Until the position-history
+             *      checkpoint is seeded, PENDING arises only when the position row changed
+             *      between the row read and the totals read. OPEN and LIQUIDATING positions
+             *      are checked against realized PnL too, and are INCOMPLETE without cum_fees
+             *      when their reductions do not account for it. Set on every row of the REST and
+             *      gRPC reads; WebSocket position frames do not carry it.
+             * @enum {string|null}
+             */
+            lifetimeTotalsStatus?: "LIFETIME_TOTALS_STATUS_UNSPECIFIED" | "LIFETIME_TOTALS_STATUS_COMPLETE" | "LIFETIME_TOTALS_STATUS_PENDING" | "LIFETIME_TOTALS_STATUS_INCOMPLETE" | null;
         };
         PositionHistoryEvent: {
             id?: string | null;
@@ -17611,19 +17699,33 @@ export interface operations {
                  *         carries no timestamps for a position the persistor has not written
                  *         yet. It is ordered by `(marginAccountId, tradingPairId, positionId)`
                  *         ascending — stable and total, but UUID order, NOT newest-first.
-                 *       - Every other filter reads persisted rows, ordered by the IMMUTABLE
-                 *         `(opened_at, id)` descending: newest-opened first. The removed
-                 *         page-number mode sorted on `COALESCE(closed_at, last_funding_at,
-                 *         opened_at)`, which *advances* whenever a position takes a funding
-                 *         payment or closes, so rows moved across a resume point mid-walk;
-                 *         `opened_at` never changes after the insert. Order therefore differs
-                 *         from the removed mode's. One exception: an operator correction may
-                 *         move an OPEN position's `opened_at` EARLIER, never later, to its
-                 *         opening fill. A walk in flight while that runs can return such a
-                 *         position a second time, but cannot skip one: dedupe on `positionId`.
+                 *       - `status=CLOSED` and `status=LIQUIDATED` read persisted terminal
+                 *         rows, ordered by `(closed_at, id)` descending: newest-closed first,
+                 *         so a position held for weeks and closed today leads the list. A
+                 *         terminal row's `closed_at` is the closing command's instant, stamped
+                 *         once. A legacy terminal row with no `closed_at` sorts by its
+                 *         `opened_at` instead (the epoch if that is missing too).
+                 *       - Every other persisted walk (no filter, `status=LIQUIDATING`, and
+                 *         `status=OPEN` when it falls back to persisted rows, see below) is
+                 *         ordered by the IMMUTABLE `(opened_at, id)` descending:
+                 *         newest-opened first. These filters admit live rows, whose close time
+                 *         is unset and changes when they close, so they cannot sort on it. The
+                 *         removed page-number mode sorted on `COALESCE(closed_at,
+                 *         last_funding_at, opened_at)`, which *advances* whenever a position
+                 *         takes a funding payment or closes, so rows moved across a resume
+                 *         point mid-walk; `opened_at` never changes after the insert. Order
+                 *         therefore differs from the removed mode's. One exception: an operator
+                 *         correction may move an OPEN position's `opened_at` EARLIER, never
+                 *         later, to its opening fill. A walk in flight while that runs can
+                 *         return such a position a second time, but cannot skip one: dedupe on
+                 *         `positionId`.
+                 *
+                 *      The two persisted orders are separate cursor spaces too: a token is
+                 *      pinned to its filter, so it only resumes the order that minted it.
                  *
-                 *      Those are two separate cursor spaces, so a token is only valid in the one
-                 *      that minted it, and crossing between them is ASYMMETRIC:
+                 *      The live and persisted walks 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` while the engine is
                  *         reachable is served: the live branch does not recognise it, declines,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.77",
+	"version": "1.0.80",
 	"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.77",
+		"@0xmonaco/contracts": "1.0.80",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {