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

package/dist/validation/profile.d.ts

@@ -48,8 +48,13 @@ export declare const SetSelfTradePreventionDefaultSchema: z.ZodObject<{
  * All fields are optional — an empty object or undefined is valid.
  */
 export declare const GetUserMovementsSchema: z.ZodObject<{
-    page: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodOptional<z.ZodNever>;
     pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodEnum<{
+        ASC: "ASC";
+        DESC: "DESC";
+    }>>;
     entryType: z.ZodOptional<z.ZodEnum<{
         CREDIT: "CREDIT";
         DEBIT: "DEBIT";
@@ -81,9 +86,21 @@ export declare const GetUserTradesSchema: z.ZodObject<{
     tradingPairId: z.ZodOptional<z.ZodUUID>;
     pageToken: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * Get User Balances validation schema
+ *
+ * Validates parameters for the cursor-paged balances listing. All fields are
+ * optional — an empty object or undefined is valid.
+ */
+export declare const GetUserBalancesSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodNever>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const ListFundingPaymentsSchema: z.ZodObject<{
-    page: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodOptional<z.ZodNever>;
     pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
     tradingPairId: z.ZodOptional<z.ZodUUID>;
     positionId: z.ZodOptional<z.ZodUUID>;
     marginAccountId: z.ZodOptional<z.ZodUUID>;

package/dist/validation/profile.js

@@ -33,8 +33,16 @@ export const SetSelfTradePreventionDefaultSchema = z.object({
  * All fields are optional — an empty object or undefined is valid.
  */
 export const GetUserMovementsSchema = z.object({
-    page: z.number().int("Page must be an integer").min(1, "Page must be at least 1").optional(),
-    pageSize: z.number().int("Page size must be an integer").min(1, "Page size must be at least 1").max(100, "Page size cannot exceed 100").optional(),
+    /**
+     * Rejected, not ignored. A non-strict object would let a JS or `any` caller
+     * keep passing `page`, and the request would come back as the first cursor
+     * page every time — the same silent duplicate-page failure the REST 400
+     * guard exists to prevent (0XM-2788).
+     */
+    page: z.never().optional(),
+    pageSize: z.number().int("Page size must be an integer").min(1, "Page size must be at least 1").max(1000, "Page size cannot exceed 1000").optional(),
+    pageToken: z.string().optional(),
+    orderBy: z.enum(["ASC", "DESC"]).optional(),
     entryType: LedgerEntryTypeSchema.optional(),
     transactionType: TransactionTypeSchema.optional(),
     assetId: UUIDSchema.optional(),
@@ -57,9 +65,33 @@ export const GetUserTradesSchema = z.object({
     tradingPairId: UUIDSchema.optional(),
     pageToken: z.string().optional(),
 });
+/**
+ * Get User Balances validation schema
+ *
+ * Validates parameters for the cursor-paged balances listing. All fields are
+ * optional — an empty object or undefined is valid.
+ */
+export const GetUserBalancesSchema = z.object({
+    /**
+     * Rejected, not ignored. Without a schema at all a JS or `any` caller's
+     * `page` was silently dropped while building the query string, so the call
+     * resolved with the FIRST cursor page on every request — the quiet
+     * duplicate-page failure the REST 400 guard exists to prevent (0XM-2821).
+     */
+    page: z.never().optional(),
+    pageSize: z.number().int("Page size must be an integer").min(1, "Page size must be at least 1").max(1000, "Page size cannot exceed 1000").optional(),
+    pageToken: z.string().optional(),
+});
 export const ListFundingPaymentsSchema = z.object({
-    page: z.number().int("Page must be an integer").min(1, "Page must be at least 1").optional(),
-    pageSize: z.number().int("Page size must be an integer").min(1, "Page size must be at least 1").max(100, "Page size cannot exceed 100").optional(),
+    /**
+     * Rejected, not ignored. A non-strict object would let a JS or `any` caller
+     * keep passing `page`, and the request would come back as the first cursor
+     * page every time — the same silent duplicate-page failure the REST 400
+     * guard exists to prevent (0XM-2788).
+     */
+    page: z.never().optional(),
+    pageSize: z.number().int("Page size must be an integer").min(1, "Page size must be at least 1").max(1000, "Page size cannot exceed 1000").optional(),
+    pageToken: z.string().optional(),
     tradingPairId: UUIDSchema.optional(),
     positionId: UUIDSchema.optional(),
     marginAccountId: UUIDSchema.optional(),

package/dist/validation/trading.d.ts

@@ -375,11 +375,11 @@ export declare const ConditionalOrderTriggerSourceSchema: z.ZodEnum<{
 export declare const ConditionalOrderStateSchema: z.ZodEnum<{
     CANCELLED: "CANCELLED";
     EXPIRED: "EXPIRED";
-    FAILED: "FAILED";
     PENDING_PARENT: "PENDING_PARENT";
     ACTIVE: "ACTIVE";
     TRIGGERING: "TRIGGERING";
     TRIGGERED: "TRIGGERED";
+    FAILED: "FAILED";
 }>;
 export declare const ClosePositionSideSchema: z.ZodEnum<{
     LONG: "LONG";
@@ -395,11 +395,11 @@ export declare const ListConditionalOrdersSchema: z.ZodObject<{
     state: z.ZodOptional<z.ZodEnum<{
         CANCELLED: "CANCELLED";
         EXPIRED: "EXPIRED";
-        FAILED: "FAILED";
         PENDING_PARENT: "PENDING_PARENT";
         ACTIVE: "ACTIVE";
         TRIGGERING: "TRIGGERING";
         TRIGGERED: "TRIGGERED";
+        FAILED: "FAILED";
     }>>;
     pageSize: z.ZodOptional<z.ZodNumber>;
     pageToken: z.ZodOptional<z.ZodString>;

package/dist/validation/vault.d.ts

@@ -75,3 +75,17 @@ export declare const WithdrawSchema: z.ZodObject<{
 export declare const GetBalanceSchema: z.ZodObject<{
     assetId: z.ZodUUID;
 }, z.core.$strip>;
+/**
+ * Pending-withdrawals listing validation schema.
+ *
+ * Cursor paged (0XM-2821). `page` is REJECTED rather than omitted: the client
+ * forwards the params field by field, which would drop a stray `page` before it
+ * reached the wire, so a JavaScript or `any` caller looping on `{ page: n }`
+ * would be handed the FIRST cursor page on every call and would never advance —
+ * the exact failure the REST 400 exists to surface.
+ */
+export declare const ListPendingWithdrawalsSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodNever>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/validation/vault.js

@@ -86,3 +86,17 @@ export const WithdrawSchema = z.object({
 export const GetBalanceSchema = z.object({
     assetId: UUIDSchema,
 });
+/**
+ * Pending-withdrawals listing validation schema.
+ *
+ * Cursor paged (0XM-2821). `page` is REJECTED rather than omitted: the client
+ * forwards the params field by field, which would drop a stray `page` before it
+ * reached the wire, so a JavaScript or `any` caller looping on `{ page: n }`
+ * would be handed the FIRST cursor page on every call and would never advance —
+ * the exact failure the REST 400 exists to surface.
+ */
+export const ListPendingWithdrawalsSchema = z.object({
+    page: z.never().optional(),
+    pageSize: z.number().int("Page size must be an integer").min(1, "Page size must be at least 1").max(1000, "Page size cannot exceed 1000").optional(),
+    pageToken: z.string().optional(),
+});

package/dist/websocket/base.d.ts

@@ -7,8 +7,40 @@
  * WebSocket connection status
  */
 export type WebSocketStatus = "connected" | "connecting" | "disconnected" | "reconnecting";
-/** Handler invoked whenever the WebSocket connection status changes. */
-export type StatusHandler = (status: WebSocketStatus) => void;
+/**
+ * Connection-attempt context delivered with every status change.
+ *
+ * `"reconnecting"` with `hasConnected: false` means the client has never
+ * reached the server and is still trying (the first connect failed);
+ * `hasConnected: true` means a working connection was lost.
+ */
+export interface WebSocketStatusInfo {
+    /**
+     * The retry this status refers to. `0` for `"connecting"` and
+     * `"connected"`; `1`, `2`, … for `"reconnecting"` (the retry just
+     * scheduled); for `"disconnected"`, the number of retries scheduled in the
+     * outage before it, counting one still in backoff when `disconnect()` is
+     * called (`0` after a clean close of a working connection).
+     */
+    attempt: number;
+    /**
+     * Whether this client has reached the server at least once since it was
+     * created or since the last `disconnect()`.
+     */
+    hasConnected: boolean;
+    /**
+     * Set only on `"reconnecting"`: the delay, in milliseconds, before the
+     * scheduled retry opens its connection.
+     */
+    nextRetryDelayMs?: number;
+}
+/**
+ * Handler invoked whenever the WebSocket connection status changes.
+ *
+ * Inside the handler, `getStatus()` returns the status being reported. A
+ * handler that takes only `status` remains valid.
+ */
+export type StatusHandler = (status: WebSocketStatus, info: WebSocketStatusInfo) => void;
 /**
  * Why the connection was re-established. Delivered by
  * {@link MonacoWebSocketConfig.onResync} after the socket reopens and sends its
@@ -129,9 +161,11 @@ export interface MonacoWebSocketConfig {
     /** Enable auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
     /**
-     * Maximum reconnection attempts (default: unlimited). Retry delay is
-     * full-jitter exponential backoff capped at 30s, so unlimited retries are
-     * capped-rate, not a tight loop.
+     * Maximum reconnection attempts per outage (default: unlimited). Retry
+     * delay is full-jitter exponential backoff capped at 30s, so unlimited
+     * retries are capped-rate, not a tight loop. Once the attempts run out the
+     * client reports `"disconnected"`; a later `connect()` starts a fresh
+     * budget.
      */
     maxReconnectAttempts?: number;
     /** Base delay for the exponential backoff in milliseconds (default: 1000) */
@@ -141,7 +175,23 @@ export interface MonacoWebSocketConfig {
      * retried, in milliseconds (default: 10000)
      */
     connectionTimeoutMs?: number;
-    /** Callback for connection status changes */
+    /**
+     * Called on every connection status change, with the attempt context in
+     * {@link WebSocketStatusInfo}:
+     *
+     * - `"connecting"` — a connection is opening outside a retry cycle: the
+     *   first connect, a `connect()` after a terminal `"disconnected"`, or a
+     *   fresh session's reconnect after terminal authentication loss.
+     * - `"connected"` — the connection opened.
+     * - `"reconnecting"` — a retry is scheduled, once per retry. It holds until
+     *   a retry connects or the retries run out; retries do not report
+     *   `"connecting"`.
+     * - `"disconnected"` — terminal: a clean close, retries exhausted, terminal
+     *   authentication loss, or `disconnect()`.
+     *
+     * An error thrown by this callback, or a rejection of the promise an async
+     * callback returns, is logged and does not affect the connection.
+     */
     onStatusChange?: StatusHandler;
     /**
      * Called after every automatic reconnect sends authentication/subscription

package/dist/websocket/client.d.ts

@@ -52,7 +52,7 @@ 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, 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, TwapOrderEvent, TwapOrderEventData, UserBalanceEvent, UserBalanceEventData, UserMovementEvent } from "./events";
 import type { OrderSnapshotItem, SnapshotHandler } from "./snapshots";
 export type MessageHandler<T> = (data: T) => void;
 export interface MonacoWebSocket {
@@ -84,8 +84,13 @@ export interface MonacoWebSocket {
     conditionalOrders: (handler: MessageHandler<ConditionalOrderEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<ConditionalOrderEventData>) => () => void;
     /** Subscribe to TWAP parent-order lifecycle events (requires authentication) */
     twapOrders: (handler: MessageHandler<TwapOrderEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<TwapOrderEventData>) => () => void;
-    /** Subscribe to position state updates (requires authentication); omit `tradingPairId` for all pairs. `onSnapshot` receives every open position */
-    positions: (handler: MessageHandler<PositionEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<PositionEventData>) => () => void;
+    /**
+     * Subscribe to position state updates (requires authentication); omit `tradingPairId` for all pairs. `onSnapshot` receives every open position.
+     *
+     * `handler` receives lifecycle `position_update` frames only. `onValuation`, when given, receives the periodic `position_valuation`
+     * frames carried on the same channel; without it they are ignored. Apply a valuation only to a position already held as `OPEN`.
+     */
+    positions: (handler: MessageHandler<PositionEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<PositionEventData>, onValuation?: MessageHandler<PositionValuationEvent>) => () => void;
     /** Subscribe to liquidation alerts (requires authentication); omit `tradingPairId` for all pairs */
     liquidations: (handler: MessageHandler<LiquidationEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<LiquidationEventData>) => () => void;
     /** Subscribe to account-level margin health updates for the authenticated user (requires authentication) */

package/dist/websocket/events/index.d.ts

@@ -10,5 +10,6 @@ export * from "./ohlcv-events";
 export * from "./orderbook-events";
 export * from "./orders-events";
 export * from "./position-events";
+export * from "./position-valuation-events";
 export * from "./trade-events";
 export * from "./twap-order-events";

package/dist/websocket/events/index.js

@@ -10,5 +10,6 @@ export * from "./ohlcv-events";
 export * from "./orderbook-events";
 export * from "./orders-events";
 export * from "./position-events";
+export * from "./position-valuation-events";
 export * from "./trade-events";
 export * from "./twap-order-events";

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

@@ -12,7 +12,7 @@
 /**
  * Liquidation alert event data.
  *
- * `status` and `accountState` are free-form strings on the wire (they mirror
+ * `status` and `riskBucketState` are free-form strings on the wire (they mirror
  * server-side enums that carry no wire-level rename), so they are typed as
  * `string` rather than a closed union to avoid dropping a risk-critical alert
  * on an unexpected value.
@@ -28,8 +28,8 @@ export interface LiquidationEventData {
     tradingPairId?: string;
     /** Liquidation record status (e.g. "UNRESOLVED", free-form) */
     status: string;
-    /** Margin-account risk state at alert time (e.g. "PENDING", free-form) */
-    accountState: string;
+    /** The liquidated risk bucket's state at alert time (e.g. "PENDING_LIQUIDATION", free-form) */
+    riskBucketState: string;
     /** Position liquidation price, when known (decimal string) */
     liquidationPrice?: string;
     /** Mark price at alert time, when known (decimal string) */

package/dist/websocket/events/market-stats-events.d.ts

@@ -13,8 +13,9 @@
  *
  * Perp-only fields (index/mark price, open interest, funding) are optional and
  * omitted on the wire for spot markets, which have no positions or funding.
- * All numeric quantities are decimal strings except `fundingTimestamp`, which
- * is a millisecond epoch number.
+ * All numeric quantities are decimal strings except `fundingTimestamp` and
+ * `lastFundingTime` (millisecond epoch numbers) and `fundingIntervalSeconds`
+ * (whole seconds).
  */
 /**
  * Market tradability label, derived from the oracle market status. Spot markets
@@ -23,6 +24,10 @@
 export type MarketStatus = "TRADABLE" | "POST_ONLY" | "HALTED" | "NOT_READY" | "UNKNOWN";
 /**
  * Full per-market statistics for the `market_stats:<tradingPairId>` channel.
+ *
+ * `marketStatus` is typed `MarketStatus | (string & {})` for the same reason as
+ * on {@link MarketStatsSummary}: an unrecognized status is passed through
+ * rather than dropping the frame. Match it with a `default` branch.
  */
 export interface MarketStatsData {
     /** Market symbol, e.g. "BTC/USDC" */
@@ -41,8 +46,19 @@ export interface MarketStatsData {
     bestAskPrice?: string;
     /** Open interest (decimal string). Perp-only; omitted for spot. */
     openInterest?: string;
-    /** Open interest limit (decimal string). Perp-only; omitted for spot. */
+    /**
+     * The market's gross open-interest cap, in quote (USD) notional (decimal
+     * string). `openInterest` is in base units: multiply it by `markPrice` to
+     * compare. Perp-only; omitted for spot.
+     */
     openInterestLimit?: string;
+    /**
+     * What is left of `openInterestLimit` at the mark, in quote (USD) notional,
+     * never below zero (decimal string). At zero, orders that open exposure are
+     * refused until open interest or the mark falls. Perp-only; omitted for spot
+     * and when there is no mark.
+     */
+    openInterestHeadroom?: string;
     /** Last trade price (decimal string) */
     lastTradePrice?: string;
     /** 24h base-token volume (decimal string) */
@@ -71,6 +87,20 @@ export interface MarketStatsData {
     fundingClampSmall?: string;
     /** Live funding cap, upper bound (decimal string). Perp-only; omitted for spot. */
     fundingClampBig?: string;
+    /**
+     * Tradability label, the same value the all-markets summary carries for this
+     * market. Perp markets report any {@link MarketStatus}; spot markets report
+     * `TRADABLE` or `HALTED`. Always present on frames from current servers.
+     */
+    marketStatus?: MarketStatus | (string & {});
+    /** Funding settlement interval in whole seconds. Perp-only; omitted for spot. */
+    fundingIntervalSeconds?: number;
+    /**
+     * When the latest funding window settled, as a millisecond epoch number
+     * (REST `getFundingState` returns the same instant as an RFC 3339 string).
+     * Perp-only; omitted for spot and for a market that has not settled yet.
+     */
+    lastFundingTime?: number;
 }
 /**
  * Per-market statistics event on the `market_stats:<tradingPairId>` channel.

package/dist/websocket/events/market-stats-events.js

@@ -13,6 +13,7 @@
  *
  * Perp-only fields (index/mark price, open interest, funding) are optional and
  * omitted on the wire for spot markets, which have no positions or funding.
- * All numeric quantities are decimal strings except `fundingTimestamp`, which
- * is a millisecond epoch number.
+ * All numeric quantities are decimal strings except `fundingTimestamp` and
+ * `lastFundingTime` (millisecond epoch numbers) and `fundingIntervalSeconds`
+ * (whole seconds).
  */

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

@@ -179,6 +179,12 @@ export interface CommonOrderEventData {
      * Wire: `parent_order_id`.
      */
     parentOrderId?: string;
+    /**
+     * The margin account the order trades on: the default margin account or one
+     * of your sub-accounts, so an owner can route events per account. Omitted for
+     * a spot order and by servers predating the field. Wire: `margin_account_id`.
+     */
+    marginAccountId?: string;
     /**
      * The margin position this order is bound to: the same id REST `getOrder`
      * returns as `positionId`. A margin order placed while its margin account
@@ -221,6 +227,21 @@ export interface OrderPlacedEvent extends OrderEvent {
          * spot. Wire: `reduce_only`.
          */
         reduceOnly?: boolean;
+        /**
+         * The fill an edit carried over from the original order (decimal string).
+         * Sent only when the order is a replacement of a partly filled order; its
+         * `quantity` is then the order's total and its `status` is
+         * `PARTIALLY_FILLED`, as REST reports the edited order. Omitted on any
+         * other `OrderPlaced`. Wire: `filled_quantity`.
+         */
+        filledQuantity?: string;
+        /** `filledQuantity` in RAW (integer, base-unit) precision. Wire: `filled_quantity_raw`. */
+        filledQuantityRaw?: string;
+        /**
+         * Average fill price of the carried fill (decimal string). Sent with
+         * `filledQuantity`, omitted otherwise. Wire: `average_fill_price`.
+         */
+        averageFillPrice?: string;
     };
 }
 /**
@@ -305,7 +326,11 @@ export interface OrderMatchedEvent extends OrderEvent {
         tradesCount: number;
         /** Remaining quantity to be filled. */
         remainingQuantity: string;
-        /** Average fill price across all trades. `null` when there is none. */
+        /**
+         * The order's cumulative average fill price, across every fill — those an
+         * edit carried over from the original order included, matching REST.
+         * `null` when there is none. This match's own price is `executionPrice`.
+         */
         averageFillPrice: string | null;
         /** Order status. */
         status: OrderStatus | (string & {});
@@ -339,7 +364,11 @@ export interface OrderPartiallyFilledEvent extends OrderEvent {
         tradesCount?: number;
         /** Remaining quantity (present for both taker and maker) */
         remainingQuantity?: string;
-        /** Average fill price (taker orders only) */
+        /**
+         * The order's cumulative average fill price, on both roles: the average
+         * across every fill of the order (an edit's carried fills included), as
+         * REST reports it — not this trade's price, which is `executionPrice`.
+         */
         averageFillPrice?: string;
         /** Order status (taker orders only) */
         status?: OrderStatus | (string & {});
@@ -433,7 +462,11 @@ export interface OrderFilledEvent extends OrderEvent {
         tradesCount?: number;
         /** Remaining quantity (present for both, should be 0 for filled orders) */
         remainingQuantity?: string;
-        /** Average fill price (taker orders only) */
+        /**
+         * The order's cumulative average fill price, on both roles: the average
+         * across every fill of the order (an edit's carried fills included), as
+         * REST reports it — not this trade's price, which is `executionPrice`.
+         */
         averageFillPrice?: string;
         /** Order status (taker orders only) */
         status?: OrderStatus | (string & {});

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

@@ -42,7 +42,14 @@ export interface PositionEventData {
     side: PositionEventSide | (string & {});
     /** Position lifecycle status (SCREAMING_SNAKE_CASE on the wire, e.g. "OPEN") */
     status: PositionEventStatus | (string & {});
-    /** Absolute position size (decimal string) */
+    /**
+     * Absolute position size (decimal string). Open frames carry current size;
+     * terminal frames normally carry lifetime reduced quantity — the sum of
+     * every reducing execution, not only the exposure before the final close.
+     * After restart, incomplete legacy size history carries the known partial
+     * quantity and leaves the frame unranked. Detect closure from `status`,
+     * never from `size === "0"`.
+     */
     size: string;
     /** Average entry price (decimal string) */
     entryPrice: string;
@@ -134,6 +141,21 @@ export interface PositionEventData {
      * that window, and the frame is the fresher one.
      */
     updatedAt: string;
+    /**
+     * When the position OPENED (ISO 8601): the fill that took its exposure from
+     * zero to non-zero. It never changes for the life of `positionId`, so time
+     * held is now minus `openedAt` while open, and `updatedAt` minus `openedAt`
+     * on a terminal frame. A flip closes the position and opens a new one with
+     * a new `positionId` and its own `openedAt`.
+     *
+     * Absent when the server does not know it — never filled with the time the
+     * frame was sent. A REST read of the same position reports the same
+     * instant, normally to within one matching-engine step; after a server
+     * restart it can move by the server's own clock drift. Clamp a computed time
+     * held at zero. Not versioned: take it from the newest payload (frame or
+     * REST read) rather than skipping it on an equal `version`.
+     */
+    openedAt?: string;
     /**
      * Opaque, non-negative producer-owned row version for this position
      * (0XM-2673). Compare only within the same `positionId`; higher is newer.
@@ -144,14 +166,10 @@ export interface PositionEventData {
      * an unranked frame is not comparable with a snapshot row even when their
      * state matches.
      * Absent means UNRANKED, never "oldest", and it does NOT tell you whether
-     * anything was persisted. Four cases reach it: the frame came from a
-     * producer that predates this field; the emit path wrote no row;
-     * the path DID write the row but re-reads live risk state after sequencing
-     * (`funding`), so the mutation did advance the persisted version; or the
-     * frame is a different projection of the row
-     * than persistence stores (terminal frames report `size` 0 and
-     * `LIQUIDATED`, while the stored row keeps its size and records `CLOSED`).
-     * In the last two, a REST read or a fresh snapshot ranks the mutation.
+     * anything was persisted. Current cases are a producer predating this field,
+     * an emit path whose command wrote no position row, or a terminal frame
+     * rebuilt after restart from legacy reduction history that lacks the size or
+     * margin fields needed to reconstruct complete lifetime values.
      * Fall back to a full field comparison rather than ranking it lowest.
      *
      * The merge rule is PER FIELD GROUP, never per frame. On a higher version
@@ -172,15 +190,15 @@ export interface PositionEventData {
      * mutation — up to the one-hour funding interval.
      *
      * A frame is ranked only when it is a faithful projection of the row
-     * persisted at that sequence: fills that leave a position OPEN, direct
-     * isolated-position margin adds/reductions, and copy-position margin adds.
+     * persisted at that sequence: fills, non-zero funding settlements, terminal
+     * closes/liquidations/ADL, direct isolated-position margin adds/reductions,
+     * and copy-position margin adds. Funding carries state captured inside its
+     * sequencer command; terminal frames retain lifetime reduced quantity and
+     * exact CLOSED/LIQUIDATED classification.
      * The copy add refreshes the isolated child and its copy-cross siblings at
      * the same version. Cross-risk-bucket ALLOCATE/RELEASE and copy follow/stop
      * refreshes use `margin_added`/`margin_reduced` but are UNRANKED because
-     * those commands write no position rows. Funding re-reads live state after
-     * sequencing and is also unranked. TERMINAL frames are unranked because
-     * they report `size` 0 and `LIQUIDATED` while the stored row keeps its size
-     * and records `CLOSED`. Wallet IN/OUT and plain isolated allocation emit no
+     * those commands write no position rows. Wallet IN/OUT and plain isolated allocation emit no
      * position frame. Transfer frames use captured post-command state and are
      * released only after durable acknowledgement.
      */

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

@@ -0,0 +1,60 @@
+/**
+ * Position Valuation WebSocket Event Types
+ *
+ * Periodic mark-derived valuation of one OPEN position, delivered on the same
+ * authenticated `positions` / `positions:<tradingPairId>` channel as lifecycle
+ * `position_update` frames, with `eventType: "position_valuation"`.
+ *
+ * Valuation data only: it carries no size, side, status or version, and never
+ * creates, reopens, closes or resizes a position. Apply it only to a position
+ * you already hold as `OPEN` whose `updatedAt` is earlier than the frame's
+ * `valuedAt`, and ignore it otherwise: valuations are spread over each
+ * interval, so one can arrive after a newer `position_update` (a fill, a close,
+ * a funding settlement) for the same position. `@0xmonaco/core` delivers these to the `onValuation` callback of
+ * `positions(...)`, never to its lifecycle handler.
+ */
+/**
+ * The five mark-derived figures of one open position, from the same
+ * derivation as a lifecycle frame's figures for that position.
+ */
+export interface PositionValuationEventData {
+    /** Position identifier (UUID) */
+    positionId: string;
+    /** Margin account that owns the position (UUID) */
+    marginAccountId: string;
+    /** Trading pair identifier (UUID) */
+    tradingPairId: string;
+    /** Current mark price (decimal string) */
+    markPrice: string;
+    /** Unrealized PnL at the mark price (decimal string) */
+    unrealizedPnl: string;
+    /**
+     * Liquidation price (decimal string), or `null` when the server cannot
+     * derive one for this position (for example an isolated risk bucket shared
+     * by several positions, or one whose collateral basis is not positive).
+     */
+    liquidationPrice: string | null;
+    /** Initial margin this position requires at the mark price (decimal string) */
+    initialMarginRequired: string;
+    /** Maintenance margin this position requires at the mark price (decimal string) */
+    maintenanceMarginRequired: string;
+    /**
+     * When the server read the position (RFC 3339). Not the oracle publish time
+     * and not the position's last mutation (`updatedAt` on lifecycle frames),
+     * but on the same server clock as `updatedAt`: a valuation whose `valuedAt`
+     * is not later than the held position's `updatedAt` was read before that
+     * state and is stale.
+     */
+    valuedAt: string;
+}
+/**
+ * Periodic valuation frame for one open position.
+ */
+export interface PositionValuationEvent {
+    /** Event type identifier */
+    eventType: "position_valuation";
+    /** User ID (UUID) */
+    userId: string;
+    /** Valuation data */
+    data: PositionValuationEventData;
+}

package/dist/websocket/events/position-valuation-events.js

@@ -0,0 +1,15 @@
+/**
+ * Position Valuation WebSocket Event Types
+ *
+ * Periodic mark-derived valuation of one OPEN position, delivered on the same
+ * authenticated `positions` / `positions:<tradingPairId>` channel as lifecycle
+ * `position_update` frames, with `eventType: "position_valuation"`.
+ *
+ * Valuation data only: it carries no size, side, status or version, and never
+ * creates, reopens, closes or resizes a position. Apply it only to a position
+ * you already hold as `OPEN` whose `updatedAt` is earlier than the frame's
+ * `valuedAt`, and ignore it otherwise: valuations are spread over each
+ * interval, so one can arrive after a newer `position_update` (a fill, a close,
+ * a funding settlement) for the same position. `@0xmonaco/core` delivers these to the `onValuation` callback of
+ * `positions(...)`, never to its lifecycle handler.
+ */

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 ["add_follow_position_margin", "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_all_copy_positions", "close_follow_positions", "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_follow", "get_funding_state", "get_index_price", "get_lead_trader", "get_margin_account_movements", "get_margin_account_summary", "get_mark_price", "get_market_metadata", "get_market_stats", "get_my_fee_tier", "get_my_lead_trader", "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_builder_fee_changes", "list_buildercode_payouts", "list_conditional_orders", "list_delegated_agent_owners", "list_delegated_agents", "list_follow_leader_positions", "list_funding_history", "list_funding_payments", "list_lead_trader_closed_trades", "list_lead_trader_open_positions", "list_lead_traders", "list_managed_market_assignments", "list_margin_accounts", "list_my_followers", "list_my_follows", "list_pending_withdrawals", "list_position_history", "list_positions", "list_sub_accounts_with_balances", "list_trading_pairs", "list_twap_orders", "mint_tokens", "preview_follow", "refresh_managed_market_quotes", "refresh_session", "register_deposit_address", "replace_order", "revoke_delegated_agent", "revoke_session", "set_builder_fee", "set_self_trade_prevention_default", "set_trader_code", "simulate_fees", "simulate_order_risk", "simulate_parent_margin_order_risk", "simulate_risk_bucket_order_risk", "stop_follow", "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", "upsert_follow", "upsert_lead_trader", "verify_signature"];
+export declare const OPERATION_IDS: readonly ["add_follow_position_margin", "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_all_copy_positions", "close_follow_positions", "close_position", "close_sub_account", "create_challenge", "create_delegated_session", "create_order", "create_sub_account", "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_follow", "get_funding_state", "get_index_price", "get_lead_trader", "get_margin_account_movements", "get_margin_account_pnl", "get_margin_account_summary", "get_mark_price", "get_market_metadata", "get_market_stats", "get_my_fee_tier", "get_my_lead_trader", "get_my_referral_downline", "get_my_referral_position", "get_my_referral_tree", "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_builder_fee_changes", "list_buildercode_payouts", "list_conditional_orders", "list_delegated_agent_owners", "list_delegated_agents", "list_follow_leader_positions", "list_funding_history", "list_funding_payments", "list_lead_trader_closed_trades", "list_lead_trader_open_positions", "list_lead_traders", "list_managed_market_assignments", "list_margin_accounts", "list_my_followers", "list_my_follows", "list_pending_withdrawals", "list_position_history", "list_positions", "list_sub_accounts_with_balances", "list_trading_pairs", "list_twap_orders", "mint_tokens", "preview_follow", "refresh_managed_market_quotes", "refresh_session", "register_deposit_address", "replace_order", "revoke_delegated_agent", "revoke_session", "set_builder_fee", "set_self_trade_prevention_default", "set_trader_code", "simulate_fees", "simulate_order_risk", "simulate_parent_margin_order_risk", "simulate_risk_bucket_order_risk", "stop_follow", "submit_whitelist", "transfer_collateral", "transfer_collateral_from_margin_account", "transfer_collateral_from_parent_margin_account", "transfer_collateral_from_sub_account", "transfer_collateral_to_margin_account", "transfer_collateral_to_parent_margin_account", "transfer_collateral_to_risk_bucket", "transfer_collateral_to_sub_account", "transfer_rewards", "update_sub_account_limit", "upsert_delegated_agent", "upsert_follow", "upsert_lead_trader", "verify_signature"];
 /** Union of every OpenAPI operationId in the spec. */
 export type OperationId = (typeof OPERATION_IDS)[number];