@0xmonaco/types 1.0.58-develop.f12e78b → 1.0.59

package/dist/positions/index.d.ts

@@ -125,9 +125,13 @@ export interface Position {
      * independent live matching-engine read rather than from the versioned row,
      * so it can reflect a later command than the version names and must be
      * taken from the newer payload. Also still take
-     * `markPrice`, `unrealizedPnl`, `liquidationPrice` and `leverage` from the
-     * newer payload: those four are re-derived from the oracle mark on every
-     * read, carry no version, and the version does not advance for them.
+     * `markPrice`, `unrealizedPnl`, `liquidationPrice`, `leverage`,
+     * `maintenanceMarginRequired` and `initialMarginRequired` from the newer
+     * payload: those six are re-derived on every read rather than served from
+     * the versioned row, carry no version, and the version does not advance for
+     * them. Five move with the oracle mark; `leverage` does not, but the live
+     * surfaces derive it while the persisted row serves its stored column, so it
+     * can still disagree at an unchanged version.
      * Discarding a whole payload on an equal version freezes displayed PnL
      * until the position's next real mutation.
      *

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

@@ -8,6 +8,7 @@
  * Detected broadcast lag closes the connection with 1013 and requires resync.
  * A lost terminal position update need not have a later replacement.
  */
+import type { MarginMode } from "../../margin-accounts";
 /**
  * Position side. The server emits `LONG` or `SHORT` for an open position.
  */
@@ -55,6 +56,50 @@ export interface PositionEventData {
     isolatedMargin: string;
     /** Effective leverage (decimal string) */
     leverage: string;
+    /**
+     * Risk bucket that scopes this position's margin (UUID) — the same
+     * `riskBucketId` REST returns (0XM-2668). Omitted only for a legacy
+     * unbucketed position, and on a terminal frame whose close came back through
+     * the durable log rather than in-band.
+     */
+    riskBucketId?: string;
+    /**
+     * Margin mode of `riskBucketId`: `CROSS` or `ISOLATED`, the same `marginMode`
+     * REST returns (0XM-2668). Omitted for a position with no risk bucket, since
+     * there is then no mode to report.
+     *
+     * Do NOT infer it from `riskBucketId` in either direction. The two are
+     * resolved from different sources — the bucket id from the position, the mode
+     * from the risk engine when it holds the position and from the bucket row
+     * otherwise — so an id can arrive with no mode: a terminal row whose bucket
+     * record is unavailable, a read taken while the engine is unreachable, or a
+     * producer older than this field. Treat a missing mode as unknown and leave
+     * the position's mode unchanged; defaulting it to `CROSS` mis-renders an
+     * isolated position's backing.
+     *
+     * VERSIONED: a position's mode changes only on a real mutation, never on an
+     * oracle tick. See `version`.
+     */
+    marginMode?: MarginMode | (string & {});
+    /**
+     * Maintenance margin this position requires at `markPrice` (decimal string),
+     * the same `maintenanceMarginRequired` REST returns (0XM-2668). `"0"` when
+     * the position has no open exposure, so a terminal frame reports zero rather
+     * than omitting it.
+     *
+     * UNVERSIONED: re-derived from the oracle mark on every frame. See `version`
+     * for the whole unversioned group.
+     */
+    maintenanceMarginRequired?: string;
+    /**
+     * Initial margin this position requires at `markPrice` (decimal string),
+     * honoring both its effective leverage and the market initial-margin floor —
+     * the same `initialMarginRequired` REST returns (0XM-2668). `"0"` when the
+     * position has no open exposure.
+     *
+     * UNVERSIONED, for the same reason as `maintenanceMarginRequired`.
+     */
+    initialMarginRequired?: string;
     /** Trade that caused the update, when driven by a fill (UUID). Omitted otherwise. */
     tradeId?: string;
     /** Order that caused the update, when driven by an order (UUID). Omitted otherwise. */
@@ -65,7 +110,29 @@ export interface PositionEventData {
      * `margin_reduced`, `margin_collateral_transfer`.
      */
     reason: string;
-    /** Timestamp when the position state was updated (ISO 8601) */
+    /**
+     * When the position was last MUTATED (ISO 8601) — a fill, collateral
+     * transfer, funding settlement or close.
+     *
+     * Read from the producer's own record of the mutation, never stamped while
+     * the frame is serialized (0XM-2668), so two frames for a position nothing
+     * has changed repeat one timestamp and a valuation-only oracle reprice does
+     * 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.
+     *
+     * 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
+     * lifecycle timestamps and can report the position's opening instant until
+     * funding settles. This frame is unaffected — it is built from engine state
+     * — so a REST value OLDER than a frame you already hold is expected during
+     * that window, and the frame is the fresher one.
+     */
     updatedAt: string;
     /**
      * Opaque, non-negative producer-owned row version for this position
@@ -94,10 +161,14 @@ export interface PositionEventData {
      * than from the versioned row, so it can reflect a later command than the
      * version names and must be taken from the newer payload or you retain
      * stale backing. Also still take `markPrice`, `unrealizedPnl`,
-     * `liquidationPrice` and `leverage` from the newer frame: those four are
-     * re-derived from the oracle mark on every frame, carry no version, and the
-     * version does not advance for them. Discarding an equal-version frame
-     * wholesale freezes displayed unrealized PnL until the position's next real
+     * `liquidationPrice`, `leverage`, `maintenanceMarginRequired` and
+     * `initialMarginRequired` from the newer frame: those six are re-derived
+     * per frame rather than served from the versioned row, carry no version,
+     * and the version does not advance for them. Five move with the oracle
+     * mark; `leverage` does not — it is opening notional over posted margin —
+     * but the live surfaces derive it while a persisted read serves the row's
+     * stored column, so it can still disagree at an unchanged version. Discarding an equal-version frame wholesale
+     * freezes displayed unrealized PnL until the position's next real
      * mutation — up to the one-hour funding interval.
      *
      * A frame is ranked only when it is a faithful projection of the row

package/dist/wire/schema.d.ts

@@ -5321,6 +5321,30 @@ export interface components {
              */
             liquidationPrice?: string | null;
             status?: string | null;
+            /**
+             * @description RFC 3339 instant at which this position was last MUTATED — a fill,
+             *      collateral transfer, funding settlement or close — as the producer that
+             *      owns the position recorded it. It is NOT the instant the response was
+             *      built: polling an unchanged position returns the same value, and an oracle
+             *      reprice does not move it. For an OPEN position every surface reports the
+             *      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 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
+             *      (close, then last funding, then open), so a position filled repeatedly
+             *      since it opened reports its opening instant until funding settles. The
+             *      live position_update frame is unaffected.
+             *
+             *      Display metadata. `version` is the reconciliation key; ordering position
+             *      state by this field is never correct.
+             */
             updatedAt?: string | null;
             riskBucketId?: string | null;
             marginMode?: string | null;
@@ -5374,7 +5398,7 @@ export interface components {
             cumFees?: string | null;
             /**
              * Format: int64
-             * @description Opaque, non-negative producer-owned version for this position row. Compare only within the same position; higher is newer. 0 is the unranked legacy sentinel and never participates in ordering: treat it exactly as an absent version and fall back to a full field comparison rather than ranking it as oldest. It advances on sequenced position mutations (open, add, reduce, close, funding, margin transfer, liquidation, ADL) and is shared by the persisted read, the WebSocket positions snapshot and a RANKED live position_update frame. A live frame is ranked only when it is a faithful projection of the row persisted at that sequence: in practice the fills that leave a position open. Frames that re-read live risk state after sequencing (funding, margin_added/margin_reduced) and terminal frames (which report size 0 and LIQUIDATED, while the stored row keeps its size and records CLOSED) omit the version even though the mutation did advance the persisted one, so an absent version never implies that nothing was persisted. mark_price, unrealized_pnl, liquidation_price and leverage are UNVERSIONED valuation fields re-derived from the oracle mark on every frame: the version does not advance for them (a valuation-only oracle tick persists nothing; a state-transitioning one, a breach or recovery, does restamp the account's open positions), so the merge rule is per field group — on an equal version skip the versioned fields but still take those four from the newer payload, because discarding a whole payload on an equal version freezes displayed PnL. isolated_margin is the one exception among the versioned fields: the WebSocket positions snapshot overlays it from an independent live matching-engine read rather than the versioned row, so take it from the newest payload on an equal version too or a consumer can retain stale backing. A response served from live matching-engine state reports 0 (unranked): the engine holds the state but not the version.
+             * @description Opaque, non-negative producer-owned version for this position row. Compare only within the same position; higher is newer. 0 is the unranked legacy sentinel and never participates in ordering: treat it exactly as an absent version and fall back to a full field comparison rather than ranking it as oldest. It advances on sequenced position mutations (open, add, reduce, close, funding, margin transfer, liquidation, ADL) and is shared by the persisted read, the WebSocket positions snapshot and a RANKED live position_update frame. A live frame is ranked only when it is a faithful projection of the row persisted at that sequence: in practice the fills that leave a position open. Frames that re-read live risk state after sequencing (funding, margin_added/margin_reduced) and terminal frames (which report size 0 and LIQUIDATED, while the stored row keeps its size and records CLOSED) omit the version even though the mutation did advance the persisted one, so an absent version never implies that nothing was persisted. mark_price, unrealized_pnl, liquidation_price, leverage, maintenance_margin_required and initial_margin_required are UNVERSIONED valuation fields, re-derived per payload rather than served from the versioned row: the version does not advance for them (five move with the oracle mark; leverage does not, being opening notional over posted margin, but the live surfaces derive it while the persisted row serves its stored column, so it can still disagree at an unchanged version) (a valuation-only oracle tick persists nothing; a state-transitioning one, a breach or recovery, does restamp the account's open positions), so the merge rule is per field group — on an equal version skip the versioned fields but still take all six from the newer payload, because discarding a whole payload on an equal version freezes displayed PnL and can leave a stale margin requirement on screen. isolated_margin is the one exception among the versioned fields: the WebSocket positions snapshot overlays it from an independent live matching-engine read rather than the versioned row, so take it from the newest payload on an equal version too or a consumer can retain stale backing. A response served from live matching-engine state reports 0 (unranked): the engine holds the state but not the version.
              * @example 918342
              */
             version?: number | null;
@@ -5414,6 +5438,30 @@ export interface components {
              *      position has no open exposure.
              */
             initialMarginRequired?: string | null;
+            /**
+             * @description RFC 3339 instant at which this position was last MUTATED — a fill,
+             *      collateral transfer, funding settlement or close — as the producer that
+             *      owns the position recorded it. It is NOT the instant the response was
+             *      built: polling an unchanged position returns the same value, and an oracle
+             *      reprice does not move it. For an OPEN position every surface reports the
+             *      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 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
+             *      (close, then last funding, then open), so a position filled repeatedly
+             *      since it opened reports its opening instant until funding settles. The
+             *      live position_update frame is unaffected.
+             *
+             *      Display metadata. `version` is the reconciliation key; ordering position
+             *      state by this field is never correct.
+             */
             updatedAt?: string | null;
         };
         GetProfileResponse: {
@@ -6829,6 +6877,30 @@ export interface components {
              */
             liquidationPrice?: string | null;
             status?: string | null;
+            /**
+             * @description RFC 3339 instant at which this position was last MUTATED — a fill,
+             *      collateral transfer, funding settlement or close — as the producer that
+             *      owns the position recorded it. It is NOT the instant the response was
+             *      built: polling an unchanged position returns the same value, and an oracle
+             *      reprice does not move it. For an OPEN position every surface reports the
+             *      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 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
+             *      (close, then last funding, then open), so a position filled repeatedly
+             *      since it opened reports its opening instant until funding settles. The
+             *      live position_update frame is unaffected.
+             *
+             *      Display metadata. `version` is the reconciliation key; ordering position
+             *      state by this field is never correct.
+             */
             updatedAt?: string | null;
             riskBucketId?: string | null;
             marginMode?: string | null;
@@ -6882,7 +6954,7 @@ export interface components {
             cumFees?: string | null;
             /**
              * Format: int64
-             * @description Opaque, non-negative producer-owned version for this position row. Compare only within the same position; higher is newer. 0 is the unranked legacy sentinel and never participates in ordering: it means the row predates this field or came from a producer that does not stamp it, so treat it exactly as an absent version and fall back to a full field comparison rather than ranking it as oldest. It advances on sequenced position mutations (open, add, reduce, close, funding, margin transfer, liquidation, ADL) and is shared by the persisted read, the WebSocket positions snapshot and a RANKED live position_update frame. A live frame is ranked only when it is a faithful projection of the row persisted at that sequence: in practice the fills that leave a position open. Frames that re-read live risk state after sequencing (funding, margin_added/margin_reduced) and terminal frames (which report size 0 and LIQUIDATED, while the stored row keeps its size and records CLOSED) omit the version even though the mutation did advance the persisted one, so an absent version never implies that nothing was persisted. mark_price, unrealized_pnl, liquidation_price and leverage are UNVERSIONED valuation fields re-derived from the oracle mark on every frame: the version does not advance for them (a valuation-only oracle tick persists nothing; a state-transitioning one, a breach or recovery, does restamp the account's open positions), so the merge rule is per field group — on an equal version skip the versioned fields but still take those four from the newer payload, because discarding a whole payload on an equal version freezes displayed PnL. isolated_margin is the one exception among the versioned fields: the WebSocket positions snapshot overlays it from an independent live matching-engine read rather than the versioned row, so take it from the newest payload on an equal version too or a consumer can retain stale backing. A response served from live matching-engine state reports 0 (unranked): the engine holds the state but not the version.
+             * @description Opaque, non-negative producer-owned version for this position row. Compare only within the same position; higher is newer. 0 is the unranked legacy sentinel and never participates in ordering: it means the row predates this field or came from a producer that does not stamp it, so treat it exactly as an absent version and fall back to a full field comparison rather than ranking it as oldest. It advances on sequenced position mutations (open, add, reduce, close, funding, margin transfer, liquidation, ADL) and is shared by the persisted read, the WebSocket positions snapshot and a RANKED live position_update frame. A live frame is ranked only when it is a faithful projection of the row persisted at that sequence: in practice the fills that leave a position open. Frames that re-read live risk state after sequencing (funding, margin_added/margin_reduced) and terminal frames (which report size 0 and LIQUIDATED, while the stored row keeps its size and records CLOSED) omit the version even though the mutation did advance the persisted one, so an absent version never implies that nothing was persisted. mark_price, unrealized_pnl, liquidation_price, leverage, maintenance_margin_required and initial_margin_required are UNVERSIONED valuation fields, re-derived per payload rather than served from the versioned row: the version does not advance for them (five move with the oracle mark; leverage does not, being opening notional over posted margin, but the live surfaces derive it while the persisted row serves its stored column, so it can still disagree at an unchanged version) (a valuation-only oracle tick persists nothing; a state-transitioning one, a breach or recovery, does restamp the account's open positions), so the merge rule is per field group — on an equal version skip the versioned fields but still take all six from the newer payload, because discarding a whole payload on an equal version freezes displayed PnL and can leave a stale margin requirement on screen. isolated_margin is the one exception among the versioned fields: the WebSocket positions snapshot overlays it from an independent live matching-engine read rather than the versioned row, so take it from the newest payload on an equal version too or a consumer can retain stale backing. A response served from live matching-engine state reports 0 (unranked): the engine holds the state but not the version.
              * @example 918342
              */
             version?: number | null;
@@ -9996,6 +10068,13 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description Authentication rate limit exceeded — challenge and verify share one per-client-address budget (60 requests/min sustained, burst 120); retry after the interval in details.retryAfter */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             /** @description Internal server error */
             500: {
                 headers: {
@@ -10152,6 +10231,13 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description Authentication rate limit exceeded — challenge and verify share one per-client-address budget (60 requests/min sustained, burst 120), checked before the signature; retry after the interval in details.retryAfter */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             /** @description Internal server error */
             500: {
                 headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.58-develop.f12e78b",
+	"version": "1.0.59",
 	"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.58-develop.f12e78b",
+		"@0xmonaco/contracts": "1.0.59",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {