@0xmonaco/types 1.0.36 → 1.0.38

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

@@ -13,7 +13,20 @@ export interface MarginAccountSummary {
     equity: string;
     initialMarginRequired: string;
     maintenanceMarginRequired: string;
+    /** Equity headroom: equity less the initial margin requirement. */
     freeCollateral: string;
+    /**
+     * The largest amount a transfer-out of this scope will actually accept.
+     *
+     * Not a clamped `freeCollateral`. Free collateral is equity headroom, and
+     * equity includes realized PnL, accrued funding and mark-to-market gains
+     * that are not principal a transfer can move — so the two can differ
+     * without limit. An unrealized gain never counts toward this figure.
+     *
+     * For a risk bucket this is capped by the bucket's allocated collateral;
+     * for a parent margin account, by deposited collateral that no risk bucket
+     * has earmarked. Size transfers against this field, not `freeCollateral`.
+     */
     withdrawableCollateral: string;
     totalPositionNotional: string;
     unrealizedPnl: string;
@@ -44,10 +57,21 @@ export interface GetAvailableCollateralResponse {
     walletLocked: string;
     marginTransferable?: string;
     /**
-     * Free collateral held in the user's parent margin account for this asset
-     * (equity minus initial margin required) — collateral already inside margin
-     * and available to open new positions or transfer back out. Absent when the
-     * user has no margin account yet.
+     * The largest amount that can currently leave the user's parent margin
+     * account for this asset — the same bound as
+     * `MarginAccountSummary.withdrawableCollateral`, and served from the same
+     * value, so the two surfaces cannot disagree. Absent when the user has no
+     * margin account yet.
+     *
+     * This is **not** trading headroom. It is bounded by allocation (principal
+     * not earmarked by risk buckets) as well as by margin requirements, and an
+     * unrealized gain does not raise it: a mark-to-market gain is initial margin
+     * for new positions but may not fund an exit. Size new positions from
+     * `MarginAccountSummary.freeCollateral`, which credits that gain in full.
+     *
+     * Note the two `margin*` fields answer opposite questions:
+     * {@link marginTransferable} is wallet-to-margin capacity, this is the
+     * amount that can come back out.
      */
     marginAvailableCollateral?: string;
 }

package/dist/sdk/index.d.ts

@@ -15,7 +15,7 @@ import type { SubAccountsAPI } from "../sub-accounts";
 import type { SweeperAPI } from "../sweeper";
 import type { TradingAPI, TradingMode } from "../trading";
 import type { VaultAPI } from "../vault";
-import type { ConditionalOrderEvent, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, TradeEvent, UserBalanceEvent, UserMovementEvent } from "../websocket";
+import type { ConditionalOrderEvent, MonacoWebSocketConfig, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, TradeEvent, UserBalanceEvent, UserMovementEvent } from "../websocket";
 import type { WhitelistAPI } from "../whitelist";
 import type { WithdrawalsAPI } from "../withdrawals";
 import type { Network } from "./network";
@@ -66,6 +66,16 @@ export interface SDKConfig {
      * 750ms when omitted. Must be a positive finite number when provided.
      */
     pollingInterval?: number;
+    /**
+     * WebSocket reconnect/resync configuration. The `onStatusChange` /
+     * `onResync` callbacks and the reconnect knobs (`autoReconnect`,
+     * `maxReconnectAttempts`, `reconnectBaseDelayMs`, `connectionTimeoutMs`) are
+     * threaded into the WebSocket client the SDK builds internally, so an app can
+     * observe connection status and drive snapshot resyncs without dropping to
+     * the low-level `createMonacoWebSocket` factory. The session keypair is not
+     * part of this surface — it flows from {@link MonacoSDK.login}.
+     */
+    ws?: MonacoWebSocketConfig;
 }
 /**
  * Core SDK interface providing access to all Monaco functionality.

package/dist/trading/index.d.ts

@@ -38,6 +38,13 @@ export interface TradingAPI extends BaseAPI {
         positionSide?: PositionSide;
         leverage?: string;
         reduceOnly?: boolean;
+        /**
+         * Maker-only: rejected with a 400 carrying the structured error code
+         * `POST_ONLY_WOULD_CROSS` if this limit order would cross the book.
+         * LIMIT orders with GTC/GTD only; rejected together with IOC/FOK.
+         * Echoed back as `postOnly` on order detail and list reads.
+         */
+        postOnly?: boolean;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
     }): Promise<CreateOrderResponse>;
@@ -104,12 +111,14 @@ export interface TradingAPI extends BaseAPI {
      * @param newOrder.price - New order price as string (optional)
      * @param newOrder.quantity - New order quantity as string
      * @param newOrder.useMasterBalance - Whether to use master balance (optional, defaults to false)
+     * @param newOrder.postOnly - Re-states post-only intent for the replacement (nothing is inherited from the original order)
      * @returns Promise resolving to a `ReplaceOrderResponse`
      */
     replaceOrder(orderId: string, newOrder: {
         price?: string;
         quantity?: string;
         useMasterBalance?: boolean;
+        postOnly?: boolean;
     }): Promise<ReplaceOrderResponse>;
     /**
      * Batch creates multiple orders in a single request.

package/dist/trading/orders.d.ts

@@ -68,6 +68,8 @@ export interface Order {
     leverage?: string;
     /** Whether the order can only reduce existing exposure */
     reduceOnly?: boolean;
+    /** Whether the order was placed post-only (maker-only). Absent for orders placed before the flag was persisted. */
+    postOnly?: boolean;
     /** Position ID linked to the order, when available */
     positionId?: string;
     /** Stable cause when status is CANCELLED */

package/dist/trading/responses.d.ts

@@ -356,6 +356,14 @@ export interface BatchCreateOrderParams {
     leverage?: string;
     /** Whether the order can only reduce existing exposure */
     reduceOnly?: boolean;
+    /**
+     * Maker-only: rejected with a structured `error.code` of
+     * `POST_ONLY_WOULD_CROSS` on this item's result if the limit order would
+     * cross the book. LIMIT orders with GTC/GTD only; rejected on MARKET
+     * orders and combined with IOC/FOK. Echoed back as `postOnly` on order
+     * detail and list reads.
+     */
+    postOnly?: boolean;
 }
 /**
  * Parameters for a single order in a batch replace request
@@ -369,6 +377,11 @@ export interface BatchReplaceOrderParams {
     quantity?: string;
     /** For sub-accounts: use master's balance (optional) */
     useMasterBalance?: boolean;
+    /**
+     * Re-states post-only intent for the replacement (optional). Nothing is
+     * inherited from the original order — see `TradingAPI.replaceOrder`.
+     */
+    postOnly?: boolean;
 }
 export interface CancelConditionalOrderResponse {
     conditionalOrderId: string;

package/dist/validation/trading.d.ts

@@ -119,6 +119,7 @@ export declare const PlaceLimitOrderSchema: z.ZodObject<{
         }>>;
         leverage: z.ZodOptional<z.ZodString>;
         reduceOnly: z.ZodOptional<z.ZodBoolean>;
+        postOnly: z.ZodOptional<z.ZodBoolean>;
         takeProfit: z.ZodOptional<z.ZodObject<{
             triggerPrice: z.ZodString;
             orderType: z.ZodEnum<{
@@ -230,6 +231,7 @@ export declare const ReplaceOrderSchema: z.ZodObject<{
         price: z.ZodOptional<z.ZodString>;
         quantity: z.ZodOptional<z.ZodString>;
         useMasterBalance: z.ZodOptional<z.ZodBoolean>;
+        postOnly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 /**
@@ -356,6 +358,7 @@ export declare const BatchCreateOrderItemSchema: z.ZodObject<{
     }>>;
     leverage: z.ZodOptional<z.ZodString>;
     reduceOnly: z.ZodOptional<z.ZodBoolean>;
+    postOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Batch Create Orders validation schema
@@ -402,6 +405,7 @@ export declare const BatchCreateOrdersSchema: z.ZodObject<{
         }>>;
         leverage: z.ZodOptional<z.ZodString>;
         reduceOnly: z.ZodOptional<z.ZodBoolean>;
+        postOnly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
@@ -415,6 +419,7 @@ export declare const BatchReplaceOrderItemSchema: z.ZodObject<{
     price: z.ZodOptional<z.ZodString>;
     quantity: z.ZodOptional<z.ZodString>;
     useMasterBalance: z.ZodOptional<z.ZodBoolean>;
+    postOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Batch Replace Orders validation schema
@@ -427,5 +432,6 @@ export declare const BatchReplaceOrdersSchema: z.ZodObject<{
         price: z.ZodOptional<z.ZodString>;
         quantity: z.ZodOptional<z.ZodString>;
         useMasterBalance: z.ZodOptional<z.ZodBoolean>;
+        postOnly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/validation/trading.js

@@ -128,6 +128,7 @@ export const PlaceLimitOrderSchema = z
         positionSide: PositionSideSchema.optional(),
         leverage: PositiveDecimalStringSchema.optional(),
         reduceOnly: z.boolean().optional(),
+        postOnly: z.boolean().optional(),
         takeProfit: ParentTpSlLegSchema.optional(),
         stopLoss: ParentTpSlLegSchema.optional(),
     })
@@ -180,6 +181,10 @@ export const PlaceLimitOrderSchema = z
     .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.reduceOnly !== true, {
     message: "reduceOnly orders cannot create a new risk bucket",
     path: ["options", "reduceOnly"],
+})
+    .refine((data) => data.options?.postOnly !== true || data.options?.timeInForce === undefined || (data.options.timeInForce !== "IOC" && data.options.timeInForce !== "FOK"), {
+    message: "postOnly cannot be combined with IOC/FOK time in force",
+    path: ["options", "timeInForce"],
 });
 /**
  * Place Market Order validation schema
@@ -274,6 +279,10 @@ export const ReplaceOrderSchema = z.object({
         price: PositiveDecimalStringSchema.optional(),
         quantity: PositiveDecimalStringSchema.optional(),
         useMasterBalance: z.boolean().optional(),
+        // No MARKET/IOC-FOK refine here: order type and time-in-force are not
+        // replaceable fields — the server validates postOnly against the
+        // persisted original order, which this client-side schema cannot see.
+        postOnly: z.boolean().optional(),
     }),
 });
 /**
@@ -358,6 +367,7 @@ export const BatchCreateOrderItemSchema = z
     positionSide: PositionSideSchema.optional(),
     leverage: PositiveDecimalStringSchema.optional(),
     reduceOnly: z.boolean().optional(),
+    postOnly: z.boolean().optional(),
 })
     .refine((data) => data.orderType !== "LIMIT" || data.price !== undefined, {
     message: "Price is required for LIMIT orders",
@@ -370,6 +380,14 @@ export const BatchCreateOrderItemSchema = z
     .refine((data) => data.orderType !== "MARKET" || data.timeInForce === undefined, {
     message: "timeInForce must not be provided for MARKET orders",
     path: ["timeInForce"],
+})
+    .refine((data) => data.orderType !== "MARKET" || data.postOnly !== true, {
+    message: "postOnly must not be provided for MARKET orders",
+    path: ["postOnly"],
+})
+    .refine((data) => data.postOnly !== true || data.timeInForce === undefined || (data.timeInForce !== "IOC" && data.timeInForce !== "FOK"), {
+    message: "postOnly cannot be combined with IOC/FOK time in force",
+    path: ["postOnly"],
 })
     .refine((data) => data.riskBucketCollateral === undefined || data.tradingMode === "MARGIN", {
     message: "riskBucketCollateral is only supported for MARGIN orders",
@@ -431,6 +449,10 @@ export const BatchReplaceOrderItemSchema = z
     price: PositiveDecimalStringSchema.optional(),
     quantity: PositiveDecimalStringSchema.optional(),
     useMasterBalance: z.boolean().optional(),
+    // No MARKET/IOC-FOK refine here: order type and time-in-force are not
+    // replaceable fields — the server validates postOnly against the
+    // persisted original order, which this client-side schema cannot see.
+    postOnly: z.boolean().optional(),
 })
     .refine((data) => data.price !== undefined || data.quantity !== undefined, {
     message: "At least one of price or quantity must be provided",

package/dist/websocket/base.d.ts

@@ -7,6 +7,62 @@
  * WebSocket connection status
  */
 export type WebSocketStatus = "connected" | "connecting" | "disconnected" | "reconnecting";
+/** Handler invoked whenever the WebSocket connection status changes. */
+export type StatusHandler = (status: WebSocketStatus) => void;
+/**
+ * Why the connection was re-established. Delivered by
+ * {@link MonacoWebSocketConfig.onResync} after the client has reconnected,
+ * re-authenticated, and re-subscribed — the point where the app should refetch
+ * REST snapshots and reconcile by `(id, updatedAt)`.
+ */
+export interface WebSocketResyncInfo {
+    /** WebSocket close code of the connection that was lost. */
+    code: number;
+    /**
+     * True when the server closed with 1013 (try again later): the client fell
+     * behind a sequential stream (orders, conditional orders, liquidations,
+     * trades, movements) and the stream has a gap. There is no wire sequence
+     * number — the 1013 close is the gap signal, and a snapshot refetch is the
+     * only safe repair.
+     */
+    slowClient: boolean;
+}
+/** Handler invoked after a reconnect resumes the live stream. */
+export type ResyncHandler = (info: WebSocketResyncInfo) => void;
+/**
+ * Reconnect/resync knobs and callbacks for the Monaco WebSocket client.
+ *
+ * These are settable from the main SDK config ({@link SDKConfig.ws}) so an app
+ * can observe connection status and drive snapshot resyncs without reaching for
+ * the low-level `createMonacoWebSocket` factory. The session keypair is not
+ * part of this surface — it flows from {@link MonacoSDK.login}.
+ */
+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.
+     */
+    maxReconnectAttempts?: number;
+    /** Base delay for the exponential backoff in milliseconds (default: 1000) */
+    reconnectBaseDelayMs?: number;
+    /**
+     * How long a connection attempt may stay CONNECTING before it is failed and
+     * retried, in milliseconds (default: 10000)
+     */
+    connectionTimeoutMs?: number;
+    /** Callback for connection status changes */
+    onStatusChange?: StatusHandler;
+    /**
+     * Called after every automatic reconnect once the live stream is resumed
+     * (re-authenticated and re-subscribed). Refetch REST snapshots here and
+     * reconcile by `(id, updatedAt)`, last-writer-wins; events that arrived while
+     * the snapshot was in flight are newer than the snapshot rows they duplicate.
+     */
+    onResync?: ResyncHandler;
+}
 /**
  * Raw event message interface
  * This is the raw message received from the backend

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

@@ -1,7 +1,9 @@
 export * from "./balance-events";
 export * from "./conditional-order-events";
+export * from "./liquidation-events";
 export * from "./movement-events";
 export * from "./ohlcv-events";
 export * from "./orderbook-events";
 export * from "./orders-events";
+export * from "./position-events";
 export * from "./trade-events";

package/dist/websocket/events/index.js

@@ -1,7 +1,9 @@
 export * from "./balance-events";
 export * from "./conditional-order-events";
+export * from "./liquidation-events";
 export * from "./movement-events";
 export * from "./ohlcv-events";
 export * from "./orderbook-events";
 export * from "./orders-events";
+export * from "./position-events";
 export * from "./trade-events";

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

@@ -0,0 +1,54 @@
+/**
+ * Liquidation WebSocket Event Types
+ *
+ * Types for real-time liquidation alerts (an account crossed a maintenance
+ * threshold and a liquidation record was opened / advanced).
+ *
+ * This is an authenticated channel - requires the signed session-key handshake.
+ * Lag policy is Disconnect: a subscriber that falls behind is closed with
+ * `1013` (try again later). There is no wire sequence number, so the `1013`
+ * close is the gap signal - resync by refetching a REST/SDK snapshot.
+ */
+/**
+ * Liquidation alert event data.
+ *
+ * `status` and `accountState` 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.
+ */
+export interface LiquidationEventData {
+    /** Liquidation record identifier (UUID) */
+    liquidationId: string;
+    /** Margin account under liquidation (UUID) */
+    marginAccountId: string;
+    /** Position being liquidated, when the alert is position-scoped (UUID) */
+    positionId?: string;
+    /** Trading pair of the liquidated position, when position-scoped (UUID) */
+    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;
+    /** Position liquidation price, when known (decimal string) */
+    liquidationPrice?: string;
+    /** Mark price at alert time, when known (decimal string) */
+    markPrice?: string;
+    /** Estimated collateral shortfall (decimal string) */
+    estimatedShortfall: string;
+    /** Human-readable alert message */
+    message: string;
+    /** Timestamp when the alert was triggered (ISO 8601) */
+    triggeredAt: string;
+}
+/**
+ * Liquidation alert event emitted when a user's account is being liquidated.
+ */
+export interface LiquidationEvent {
+    /** Event type identifier */
+    eventType: "liquidation_alert";
+    /** User ID (UUID) */
+    userId: string;
+    /** Liquidation data */
+    data: LiquidationEventData;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Liquidation WebSocket Event Types
+ *
+ * Types for real-time liquidation alerts (an account crossed a maintenance
+ * threshold and a liquidation record was opened / advanced).
+ *
+ * This is an authenticated channel - requires the signed session-key handshake.
+ * Lag policy is Disconnect: a subscriber that falls behind is closed with
+ * `1013` (try again later). There is no wire sequence number, so the `1013`
+ * close is the gap signal - resync by refetching a REST/SDK snapshot.
+ */

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

@@ -37,8 +37,14 @@ export interface CommonOrderEventData {
     tradingPairId?: string;
     /** Application ID (UUID) - present in several events */
     applicationId?: string;
-    /** Trading pair symbol (e.g., "BTC/USDC") */
-    symbol: string;
+    /**
+     * Trading pair symbol (e.g., "BTC/USDC").
+     *
+     * The wire field is `trading_pair` (→ `tradingPair` after camelCasing), not
+     * `symbol`; the previous `symbol` declaration never matched what the matching
+     * engine emits.
+     */
+    tradingPair: string;
     /** Trading mode (e.g., "SPOT", "MARGIN") */
     tradingMode: TradingMode;
     /** Order type - present in most events */
@@ -49,6 +55,8 @@ export interface CommonOrderEventData {
     price?: string;
     /** Order quantity - present in most events */
     quantity?: string;
+    /** Order quantity in RAW (integer, base-unit) precision. Wire: `quantity_raw`. */
+    quantityRaw?: string;
     /** Time in force - present in most events */
     timeInForce?: TimeInForce;
 }
@@ -131,10 +139,22 @@ export interface OrderPartiallyFilledEvent extends OrderEvent {
         tradeId?: string;
         /** Execution price (maker orders only) */
         executionPrice?: string;
-        /** Execution quantity (maker orders only) */
-        executionQuantity?: string;
-        /** Maker fee (maker orders only) */
-        makerFee?: string;
+        /**
+         * Quantity filled in this event (maker orders only). The wire field is
+         * `filled_quantity` (→ `filledQuantity`); for a maker this is the current
+         * trade's quantity. The previous `executionQuantity` never matched the
+         * wire. For a taker the same-named field carries the cumulative order fill.
+         */
+        filledQuantity?: string;
+        /** `filledQuantity` in RAW (integer, base-unit) precision. Wire: `filled_quantity_raw`. */
+        filledQuantityRaw?: string;
+        /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
+        remainingQuantityRaw?: string;
+        /**
+         * Fee charged for this fill (maker orders only). The wire field is `fee`
+         * (→ `fee`), not `makerFee`; taker fills carry the same `fee` field.
+         */
+        fee?: string;
         /** Trade execution timestamp (maker orders only) */
         executedAt?: string;
         /** Role of the order in the trade (taker or maker) */
@@ -179,10 +199,22 @@ export interface OrderFilledEvent extends OrderEvent {
         tradeId?: string;
         /** Execution price (maker orders only) */
         executionPrice?: string;
-        /** Execution quantity (maker orders only) */
-        executionQuantity?: string;
-        /** Maker fee (maker orders only) */
-        makerFee?: string;
+        /**
+         * Quantity filled in this event (maker orders only). The wire field is
+         * `filled_quantity` (→ `filledQuantity`); for a maker this is the current
+         * trade's quantity. The previous `executionQuantity` never matched the
+         * wire. For a taker the same-named field carries the cumulative order fill.
+         */
+        filledQuantity?: string;
+        /** `filledQuantity` in RAW (integer, base-unit) precision. Wire: `filled_quantity_raw`. */
+        filledQuantityRaw?: string;
+        /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
+        remainingQuantityRaw?: string;
+        /**
+         * Fee charged for this fill (maker orders only). The wire field is `fee`
+         * (→ `fee`), not `makerFee`; taker fills carry the same `fee` field.
+         */
+        fee?: string;
         /** Trade execution timestamp (maker orders only) */
         executedAt?: string;
         /** Role of the order in the trade (taker or maker) */
@@ -201,8 +233,12 @@ export interface OrderCancelledEvent extends OrderEvent {
         terminalReason?: OrderTerminalReason;
         /** Total filled quantity before cancellation */
         totalFilled?: string;
+        /** `totalFilled` in RAW (integer, base-unit) precision. Wire: `total_filled_raw`. */
+        totalFilledRaw?: string;
         /** Remaining quantity when canceled */
         remainingQuantity?: string;
+        /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
+        remainingQuantityRaw?: string;
         /** Number of trades executed before cancellation */
         tradesCount?: number;
     };
@@ -279,8 +315,8 @@ export interface BackendCommonOrderEventData {
     user_id: string;
     /** Trading pair ID (UUID) */
     trading_pair_id?: string;
-    /** Trading pair symbol (e.g., "BTC/USDC") */
-    symbol: string;
+    /** Trading pair symbol (e.g., "BTC/USDC"), from the wire `trading_pair` field. */
+    trading_pair: string;
     /** Trading mode (e.g., "Spot", "Margin") */
     trading_mode: string;
 }

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

@@ -0,0 +1,66 @@
+/**
+ * Position WebSocket Event Types
+ *
+ * Types for real-time position state updates (open/close, mark price, PnL,
+ * liquidation price, isolated margin, leverage).
+ *
+ * This is an authenticated channel - requires the signed session-key handshake.
+ * Lag policy is Conflate: a lagging subscriber is fast-forwarded to the latest
+ * state rather than disconnected, so there is no gap signal to reconcile.
+ */
+/**
+ * Position side. The server emits `LONG` or `SHORT` for an open position.
+ */
+export type PositionEventSide = "LONG" | "SHORT";
+/**
+ * Position lifecycle status.
+ *
+ * NOTE: this is PascalCase on the wire (`Open`, not `OPEN`) - the underlying
+ * enum has no serde rename, unlike side/trading-mode fields. That asymmetry is
+ * the live wire format and is preserved verbatim here.
+ */
+export type PositionEventStatus = "Open" | "Closing" | "Closed" | "Liquidated" | "Expired";
+/**
+ * Position event data containing the current state of a single position.
+ */
+export interface PositionEventData {
+    /** Position identifier (UUID) */
+    positionId: string;
+    /** Margin account that owns the position (UUID) */
+    marginAccountId: string;
+    /** Trading pair identifier (UUID) */
+    tradingPairId: string;
+    /** Position side */
+    side: PositionEventSide;
+    /** Position lifecycle status (PascalCase on the wire) */
+    status: PositionEventStatus;
+    /** Absolute position size (decimal string) */
+    size: string;
+    /** Average entry price (decimal string) */
+    entryPrice: string;
+    /** Current mark price (decimal string) */
+    markPrice?: string;
+    /** Unrealized PnL at the current mark price (decimal string) */
+    unrealizedPnl?: string;
+    /** Estimated liquidation price (decimal string) */
+    liquidationPrice?: string;
+    /** Isolated margin / collateral backing the position (decimal string) */
+    isolatedMargin: string;
+    /** Effective leverage (decimal string) */
+    leverage: string;
+    /** What triggered the update (e.g. "trade", free-form) */
+    reason: string;
+    /** Timestamp when the position state was updated (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * Position event emitted when a user's position state changes.
+ */
+export interface PositionEvent {
+    /** Event type identifier */
+    eventType: "position_update";
+    /** User ID (UUID) */
+    userId: string;
+    /** Position data */
+    data: PositionEventData;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Position WebSocket Event Types
+ *
+ * Types for real-time position state updates (open/close, mark price, PnL,
+ * liquidation price, isolated margin, leverage).
+ *
+ * This is an authenticated channel - requires the signed session-key handshake.
+ * Lag policy is Conflate: a lagging subscriber is fast-forwarded to the latest
+ * state rather than disconnected, so there is no gap signal to reconcile.
+ */

package/dist/wire/schema.d.ts

@@ -2714,6 +2714,11 @@ export interface components {
              * @enum {string|null}
              */
             marginMode?: "ISOLATED" | "CROSS" | null;
+            /**
+             * @description Post-only: reject instead of matching if this limit order would cross the book — rejected with HTTP 400 / gRPC INVALID_ARGUMENT carrying the structured error code POST_ONLY_WOULD_CROSS (REST error-envelope 'code' field; gRPC google.rpc.ErrorInfo reason; batch per-item error.code). Matching the 'post-only order would cross' message substring is a legacy fallback. LIMIT orders with GTC/GTD only; rejected on MARKET orders and IOC/FOK.
+             * @example false
+             */
+            postOnly?: boolean | null;
         };
         BatchCreateOrdersRequest: {
             orders: components["schemas"]["BatchCreateOrderItem"][];
@@ -2783,6 +2788,11 @@ export interface components {
              * @example false
              */
             useMasterBalance?: boolean | null;
+            /**
+             * @description Post-only: reject instead of matching if this limit order would cross the book — rejected with HTTP 400 / gRPC INVALID_ARGUMENT carrying the structured error code POST_ONLY_WOULD_CROSS (REST error-envelope 'code' field; gRPC google.rpc.ErrorInfo reason; batch per-item error.code). Matching the 'post-only order would cross' message substring is a legacy fallback. LIMIT orders with GTC/GTD only; rejected on MARKET orders and IOC/FOK.
+             * @example false
+             */
+            postOnly?: boolean | null;
         };
         BatchReplaceOrdersRequest: {
             orders: components["schemas"]["BatchReplaceOrderItem"][];
@@ -3177,6 +3187,11 @@ export interface components {
              * @enum {string|null}
              */
             marginMode?: "ISOLATED" | "CROSS" | null;
+            /**
+             * @description Post-only: reject instead of matching if this limit order would cross the book — rejected with HTTP 400 / gRPC INVALID_ARGUMENT carrying the structured error code POST_ONLY_WOULD_CROSS (REST error-envelope 'code' field; gRPC google.rpc.ErrorInfo reason; batch per-item error.code). Matching the 'post-only order would cross' message substring is a legacy fallback. LIMIT orders with GTC/GTD only; rejected on MARKET orders and IOC/FOK.
+             * @example false
+             */
+            postOnly?: boolean | null;
         };
         CreateOrderResponse: {
             /**
@@ -3515,10 +3530,21 @@ export interface components {
             walletLocked?: string | null;
             marginTransferable?: string | null;
             /**
-             * @description Free collateral currently held in the user's parent margin account for this
-             *      asset (equity minus initial margin required), i.e. collateral already inside
-             *      margin and available to open new positions or transfer back out. Absent when
-             *      the user has no margin account yet.
+             * @description The largest amount that can currently leave the user's parent margin
+             *      account for this asset — the same bound as
+             *      `MarginAccountSummary.withdrawable_collateral`, and served from the same
+             *      value, so the two surfaces cannot disagree. Absent when the user has no
+             *      margin account yet.
+             *
+             *      This is NOT trading headroom. It is bounded by allocation (principal not
+             *      earmarked by risk buckets) as well as by margin requirements, and an
+             *      unrealized gain does not raise it: a mark-to-market gain is initial margin
+             *      for new positions but may not fund an exit. Size new positions from
+             *      `MarginAccountSummary.free_collateral`, which credits that gain in full.
+             *
+             *      Note the two `margin_*` fields answer opposite questions:
+             *      `margin_transferable` is wallet-to-margin capacity, this is the amount that
+             *      can come back out.
              */
             marginAvailableCollateral?: string | null;
         };
@@ -3711,6 +3737,28 @@ export interface components {
             initialMarginRequired?: string | null;
             maintenanceMarginRequired?: string | null;
             freeCollateral?: string | null;
+            /**
+             * @description The largest amount a transfer-out of this scope will actually accept.
+             *
+             *      NOT a clamped `free_collateral`. Free collateral is equity headroom, and
+             *      equity includes realized PnL, accrued funding and mark-to-market gains
+             *      that are not principal a transfer can move — so the two can differ
+             *      without limit. An unrealized gain never counts toward this figure.
+             *
+             *      For a risk bucket this is capped by the bucket's allocated collateral;
+             *      for a parent margin account, by deposited collateral that no risk bucket
+             *      has earmarked.
+             *
+             *      This is the largest accepted transfer-out, NOT a promise that every
+             *      smaller one is accepted. Acceptance is not monotone in the amount: a risk
+             *      bucket whose realized loss exceeds its remaining value accepts the full
+             *      close-out reported here — which settles that loss to the parent margin
+             *      account — while refusing a partial withdrawal that would leave the bucket
+             *      holding less collateral than the loss it has already taken. For such a
+             *      bucket the accepted amounts are everything up to its equity, plus this
+             *      figure itself, with a gap in between. Size a transfer directly from this
+             *      field rather than shaving a margin off it.
+             */
             withdrawableCollateral?: string | null;
             totalPositionNotional?: string | null;
             unrealizedPnl?: string | null;
@@ -4139,6 +4187,11 @@ export interface components {
              * @example REDUCE_ONLY_EXHAUSTED
              */
             terminalReason?: string | null;
+            /**
+             * @description Whether the order was placed post-only (maker-only). Absent for orders placed before the flag was persisted.
+             * @example false
+             */
+            postOnly?: boolean | null;
         };
         /** @description Orderbook snapshot with token metadata and sequence number. */
         GetOrderbookResponse: {
@@ -5172,6 +5225,28 @@ export interface components {
             initialMarginRequired?: string | null;
             maintenanceMarginRequired?: string | null;
             freeCollateral?: string | null;
+            /**
+             * @description The largest amount a transfer-out of this scope will actually accept.
+             *
+             *      NOT a clamped `free_collateral`. Free collateral is equity headroom, and
+             *      equity includes realized PnL, accrued funding and mark-to-market gains
+             *      that are not principal a transfer can move — so the two can differ
+             *      without limit. An unrealized gain never counts toward this figure.
+             *
+             *      For a risk bucket this is capped by the bucket's allocated collateral;
+             *      for a parent margin account, by deposited collateral that no risk bucket
+             *      has earmarked.
+             *
+             *      This is the largest accepted transfer-out, NOT a promise that every
+             *      smaller one is accepted. Acceptance is not monotone in the amount: a risk
+             *      bucket whose realized loss exceeds its remaining value accepts the full
+             *      close-out reported here — which settles that loss to the parent margin
+             *      account — while refusing a partial withdrawal that would leave the bucket
+             *      holding less collateral than the loss it has already taken. For such a
+             *      bucket the accepted amounts are everything up to its equity, plus this
+             *      figure itself, with a gap in between. Size a transfer directly from this
+             *      field rather than shaving a margin off it.
+             */
             withdrawableCollateral?: string | null;
             totalPositionNotional?: string | null;
             unrealizedPnl?: string | null;
@@ -5902,10 +5977,10 @@ export interface components {
         };
         ReplaceOrderRequest: {
             /**
-             * @description Use master account balance for sub-account orders
+             * @description Post-only: reject instead of matching if this limit order would cross the book — rejected with HTTP 400 / gRPC INVALID_ARGUMENT carrying the structured error code POST_ONLY_WOULD_CROSS (REST error-envelope 'code' field; gRPC google.rpc.ErrorInfo reason; batch per-item error.code). Matching the 'post-only order would cross' message substring is a legacy fallback. LIMIT orders with GTC/GTD only; rejected on MARKET orders and IOC/FOK.
              * @example false
              */
-            useMasterBalance?: boolean | null;
+            postOnly?: boolean | null;
             /**
              * @description New limit price (if changing)
              * @example 35500.00
@@ -5916,6 +5991,11 @@ export interface components {
              * @example 0.7
              */
             quantity?: string | null;
+            /**
+             * @description Use master account balance for sub-account orders
+             * @example false
+             */
+            useMasterBalance?: boolean | null;
         };
         ReplaceOrderResponse: {
             /**
@@ -6632,6 +6712,11 @@ export interface components {
             status?: string | null;
             newEquity?: string | null;
             newTotalCollateralValue?: string | null;
+            /**
+             * @description The largest amount a further transfer-out will accept after this one.
+             *      See `MarginAccountSummary.withdrawable_collateral`: this is an
+             *      allocation-bounded figure, not clamped equity headroom.
+             */
             newWithdrawableCollateral?: string | null;
             strategyKey?: string | null;
         };
@@ -6662,6 +6747,11 @@ export interface components {
             status?: string | null;
             newEquity?: string | null;
             newTotalCollateralValue?: string | null;
+            /**
+             * @description The largest amount a further transfer-out will accept after this one.
+             *      See `MarginAccountSummary.withdrawable_collateral`: this is an
+             *      allocation-bounded figure, not clamped equity headroom.
+             */
             newWithdrawableCollateral?: string | null;
             strategyKey?: string | null;
             /** @description Present when collateral was allocated to a risk bucket. */
@@ -7941,7 +8031,7 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Unauthorized - Invalid or missing JWT */
+            /** @description Authentication required */
             401: {
                 headers: {
                     [name: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.36",
+	"version": "1.0.38",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -20,7 +20,7 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.36",
+		"@0xmonaco/contracts": "1.0.38",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {