@0xmonaco/types 1.0.39 → 1.0.41-develop.ebb62ed

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

@@ -80,6 +80,12 @@ export interface TransferCollateralRequest {
     amount: string;
     tradingPairId?: string;
     strategyKey?: string;
+    /**
+     * Risk bucket mode. Defaults to ISOLATED, which is selected by
+     * `tradingPairId`. Pass `"CROSS"` to release from the account's cross risk
+     * bucket, which has no trading pair and so cannot be named any other way.
+     */
+    marginMode?: MarginMode;
 }
 export interface TransferCollateralToParentMarginAccountRequest {
     asset: string;

package/dist/market/index.d.ts

@@ -123,6 +123,13 @@ export interface GetCandlesticksParams {
     endTime?: number;
     /** Maximum number of bars to return (max: 500, server defaults to 350 if omitted) */
     limit?: number;
+    /**
+     * Price series to chart. `"trade"` (default) returns the trade-derived OHLCV
+     * series; `"mark"` returns the mark-price series (margin pairs only), where
+     * each candle's open/high/low/close are the bucket's closing mark and volume
+     * is 0. Omit for the trade series.
+     */
+    priceType?: "trade" | "mark";
 }
 /**
  * Query parameters for fetching trading pairs
@@ -232,6 +239,18 @@ export interface ScreenerItem {
      * null for spot pairs and margin pairs with no settled funding window yet
      */
     lastFundingTime: string | null;
+    /**
+     * Open interest in base-asset units (e.g. BTC); null for spot pairs, "0" for
+     * a margin pair with no open positions
+     */
+    openInterestBase: string | null;
+    /**
+     * Open interest notional in quote units (openInterestBase × latest trade
+     * price); null for spot pairs. Valued at the pair's latest trade price (a
+     * snapshot); the mark-accurate notional lives on getPerpMarketSummary /
+     * getOpenInterest
+     */
+    openInterestNotional: string | null;
 }
 /**
  * Paginated screener response, sorted by quoteVolume24h desc (nulls last)
@@ -269,6 +288,8 @@ export interface MarketMetadata {
     low24h: string | null;
     /** 24h volume in base asset (null if <24h data) */
     volume24h: string | null;
+    /** Quote-token (notional) volume over the rolling 24h window; absent/null when unavailable */
+    quoteVolume24h?: string | null;
     /** Absolute price change in 24h (null if <24h data) */
     priceChange24h: string | null;
     /** Percentage price change in 24h (2 decimals, null if <24h data) */
@@ -319,10 +340,18 @@ export interface PerpMarketSummary {
     indexPrice: string;
     high24h?: string;
     low24h?: string;
+    /** 24h volume in base asset */
     volume24h?: string;
+    /** 24h quote-token (notional) volume */
+    quoteVolume24h?: string;
     priceChange24h?: string;
     priceChangePercent24h?: string;
+    /** Open interest in base-asset units (legacy alias of openInterestBase) */
     openInterest: string;
+    /** Open interest in base-asset units (e.g. BTC) */
+    openInterestBase?: string;
+    /** Open interest notional in quote units (openInterestBase × mark price, falling back to the last trade price when no mark is available) */
+    openInterestNotional?: string;
     currentFundingRate?: string;
     estimatedNextFundingRate?: string;
     nextFundingTime?: string;

package/dist/positions/index.d.ts

@@ -164,20 +164,6 @@ export interface PositionRisk {
     initialMarginRequired?: string;
     updatedAt: string;
 }
-export interface AddPositionMarginRequest {
-    amount: string;
-    asset: string;
-}
-export interface ReducePositionMarginRequest {
-    amount: string;
-}
-export interface PositionMarginResponse {
-    positionId: string;
-    marginAccountId: string;
-    newIsolatedMargin: string;
-    status: string;
-    message: string;
-}
 export interface TpSlLeg {
     triggerPrice: string;
     orderType: OrderType;
@@ -311,8 +297,6 @@ export interface PositionsAPI extends BaseAPI {
     closePosition(positionId: string, request: ClosePositionRequest): Promise<ClosePositionResponse>;
     batchCloseAllPositions(request?: BatchCloseAllRequest): Promise<BatchCloseAllResponse>;
     getPositionRisk(positionId: string): Promise<PositionRisk>;
-    addPositionMargin(positionId: string, request: AddPositionMarginRequest): Promise<PositionMarginResponse>;
-    reducePositionMargin(positionId: string, request: ReducePositionMarginRequest): Promise<PositionMarginResponse>;
     attachPositionTpSl(positionId: string, request: AttachPositionTpSlRequest): Promise<AttachPositionTpSlResponse>;
     listPositionHistory(params?: ListPositionHistoryParams): Promise<ListPositionHistoryResponse>;
     getPositionPnlHistory(positionId: string, params: GetPositionPnlHistoryParams): Promise<GetPositionPnlHistoryResponse>;

package/dist/trading/index.d.ts

@@ -41,10 +41,17 @@ export interface TradingAPI extends BaseAPI {
         /**
          * 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.
+         * LIMIT orders with GTC only; rejected together with IOC/FOK.
          * Echoed back as `postOnly` on order detail and list reads.
          */
         postOnly?: boolean;
+        /**
+         * Client-assigned correlation handle, echoed back on order reads and
+         * order WebSocket events. At most 64 characters from [A-Za-z0-9._:-].
+         * Not de-duplicated and not unique — a replacement re-states it and
+         * inherits nothing from the original order.
+         */
+        clientOrderId?: string;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
     }): Promise<CreateOrderResponse>;
@@ -70,6 +77,13 @@ export interface TradingAPI extends BaseAPI {
         positionSide?: PositionSide;
         leverage?: string;
         reduceOnly?: boolean;
+        /**
+         * Client-assigned correlation handle, echoed back on order reads and
+         * order WebSocket events. At most 64 characters from [A-Za-z0-9._:-].
+         * Not de-duplicated and not unique — a replacement re-states it and
+         * inherits nothing from the original order.
+         */
+        clientOrderId?: string;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
     }): Promise<CreateOrderResponse>;
@@ -119,6 +133,13 @@ export interface TradingAPI extends BaseAPI {
         quantity?: string;
         useMasterBalance?: boolean;
         postOnly?: boolean;
+        /**
+         * Client-assigned correlation handle, echoed back on order reads and
+         * order WebSocket events. At most 64 characters from [A-Za-z0-9._:-].
+         * Not de-duplicated and not unique — a replacement re-states it and
+         * inherits nothing from the original order.
+         */
+        clientOrderId?: string;
     }): Promise<ReplaceOrderResponse>;
     /**
      * Batch creates multiple orders in a single request.

package/dist/trading/orders.d.ts

@@ -40,13 +40,13 @@ export interface Order {
     averageFillPrice?: string;
     /** Trading mode (SPOT or MARGIN) */
     tradingMode: TradingMode;
-    /** Time in force - GTC, IOC, FOK, or GTD */
+    /** Time in force - GTC, IOC, or FOK (GTD is deprecated and rejected) */
     timeInForce?: TimeInForce;
     /** Order creation timestamp (ISO 8601) */
     createdAt: string;
     /** Order last update timestamp (ISO 8601) */
     updatedAt?: string;
-    /** Optional expiration date for GTD orders (ISO 8601, max 1 year) */
+    /** Optional expiry for a GTC order (ISO 8601, max 1 year) */
     expirationDate?: string;
     /** Application taker fee in basis points (e.g., "100" = 1%) - populated after fills */
     applicationTakerFee?: string;
@@ -70,6 +70,14 @@ export interface Order {
     reduceOnly?: boolean;
     /** Whether the order was placed post-only (maker-only). Absent for orders placed before the flag was persisted. */
     postOnly?: boolean;
+    /**
+     * Client-assigned correlation handle as stored: the value supplied on create
+     * or replace, with surrounding whitespace trimmed. Absent when the order
+     * carried none, including every order placed before the field was accepted on
+     * write. Not unique — several orders may share one value, so a lookup by it
+     * can be ambiguous.
+     */
+    clientOrderId?: string;
     /** Position ID linked to the order, when available */
     positionId?: string;
     /** Stable cause when status is CANCELLED */
@@ -134,7 +142,10 @@ export type TradingMode = "SPOT" | "MARGIN";
  * - GTC: Good Till Cancel - remains active until filled or canceled
  * - IOC: Immediate or Cancel - execute immediately and cancel unfilled portion
  * - FOK: Fill or Kill - execute completely or cancel entirely
- * - GTD: Good Till Date - remains active until specified expiration date
+ * - GTD: **deprecated, never implemented** - the server rejects it with HTTP
+ *   400 (`Time in force must be GTC, IOC, or FOK`). The variant is retained so
+ *   existing code keeps compiling. For an order that expires at a set time, use
+ *   `GTC` together with `expirationDate`.
  */
 export type TimeInForce = "GTC" | "IOC" | "FOK" | "GTD";
 /**

package/dist/trading/responses.d.ts

@@ -38,8 +38,12 @@ export interface MatchResult {
     } | null;
 }
 /**
- * Parent TP/SL follows the parent order quantity and becomes active once the
- * parent order creates or extends a position.
+ * A take-profit / stop-loss leg attached to an order at placement. It becomes
+ * active once the parent order creates or extends a position.
+ *
+ * Sizing is the leg's own, set by `quantity` / `closePosition` below — it does
+ * NOT follow the parent order's quantity. Sizing from the parent is what let a
+ * leg freeze at the order's size and under-cover a position that later grew.
  */
 export interface ParentTpSlLegParams {
     /** Mark price that arms the close order */
@@ -54,6 +58,18 @@ export interface ParentTpSlLegParams {
     slippageToleranceBps?: number;
     /** Optional conditional order expiry timestamp (ISO 8601) */
     expiresAt?: string;
+    /**
+     * Deliberate partial size: this leg closes exactly this much and never
+     * resizes, however the position grows. Mutually exclusive with
+     * `closePosition: true`; required when `closePosition: false`.
+     */
+    quantity?: string;
+    /**
+     * Resolve the full live position size when triggered, so the leg keeps
+     * covering the position as it grows. Mutually exclusive with `quantity`.
+     * Omitting both also means full-position close.
+     */
+    closePosition?: boolean;
 }
 /**
  * Response from creating an order.
@@ -354,11 +370,18 @@ export interface BatchCreateOrderParams {
     /**
      * 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
+     * cross the book. LIMIT orders with GTC only; rejected on MARKET
      * orders and combined with IOC/FOK. Echoed back as `postOnly` on order
      * detail and list reads.
      */
     postOnly?: boolean;
+    /**
+     * Client-assigned correlation handle, echoed back on order reads and on
+     * order WebSocket events. At most 64 characters from [A-Za-z0-9._:-].
+     * Monaco does not de-duplicate on it and does not enforce uniqueness —
+     * it correlates a response to a request, it does not make a retry safe.
+     */
+    clientOrderId?: string;
 }
 /**
  * Parameters for a single order in a batch replace request
@@ -377,6 +400,13 @@ export interface BatchReplaceOrderParams {
      * inherited from the original order — see `TradingAPI.replaceOrder`.
      */
     postOnly?: boolean;
+    /**
+     * Client-assigned correlation handle, echoed back on order reads and on
+     * order WebSocket events. At most 64 characters from [A-Za-z0-9._:-].
+     * Monaco does not de-duplicate on it and does not enforce uniqueness —
+     * it correlates a response to a request, it does not make a retry safe.
+     */
+    clientOrderId?: string;
 }
 export interface CancelConditionalOrderResponse {
     conditionalOrderId: string;

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

@@ -25,6 +25,10 @@ export declare const TransferCollateralSchema: z.ZodObject<{
         amount: z.ZodString;
         tradingPairId: z.ZodOptional<z.ZodUUID>;
         strategyKey: z.ZodOptional<z.ZodString>;
+        marginMode: z.ZodOptional<z.ZodEnum<{
+            ISOLATED: "ISOLATED";
+            CROSS: "CROSS";
+        }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const TransferCollateralToParentMarginAccountSchema: z.ZodObject<{

package/dist/validation/margin-accounts.js

@@ -25,11 +25,19 @@ export const GetAvailableCollateralSchema = z
     asset: z.string().trim().min(1, "Asset cannot be empty").optional(),
 })
     .optional();
-const TransferCollateralRequestSchema = z.object({
+const TransferCollateralRequestSchema = z
+    .object({
     asset: z.string().trim().min(1, "Asset cannot be empty"),
     amount: PositiveDecimalStringSchema,
     tradingPairId: UUIDSchema.optional(),
     strategyKey: z.string().trim().min(1, "Strategy key cannot be empty").optional(),
+    // A cross risk bucket has no trading pair, so CROSS is the only way to name
+    // one on the way out (0XM-2420). The two never combine.
+    marginMode: z.enum(["ISOLATED", "CROSS"]).optional(),
+})
+    .refine((request) => !(request.marginMode === "CROSS" && request.tradingPairId !== undefined), {
+    message: "tradingPairId is not supported for CROSS risk buckets",
+    path: ["tradingPairId"],
 });
 const ParentMarginAccountCollateralRequestSchema = z.object({
     asset: z.string().trim().min(1, "Asset cannot be empty"),

package/dist/validation/market.d.ts

@@ -171,6 +171,10 @@ export declare const GetCandlesticksByPairIdSchema: z.ZodObject<{
     startTime: z.ZodOptional<z.ZodNumber>;
     endTime: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
+    priceType: z.ZodOptional<z.ZodEnum<{
+        trade: "trade";
+        mark: "mark";
+    }>>;
 }, z.core.$strip>;
 /**
  * @deprecated Use GetCandlesticksByPairIdSchema instead. Symbol-based lookups are no longer supported.
@@ -191,6 +195,10 @@ export declare const GetCandlesticksBySymbolSchema: z.ZodObject<{
     startTime: z.ZodOptional<z.ZodNumber>;
     endTime: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
+    priceType: z.ZodOptional<z.ZodEnum<{
+        trade: "trade";
+        mark: "mark";
+    }>>;
 }, z.core.$strip>;
 /**
  * Get Trading Pair validation schema

package/dist/validation/market.js

@@ -188,6 +188,7 @@ export const GetCandlesticksByPairIdSchema = z
     startTime: TimestampSchema.optional(),
     endTime: TimestampSchema.optional(),
     limit: CandlestickLimitSchema,
+    priceType: z.enum(["trade", "mark"]).optional(),
 })
     .refine((data) => {
     // Only validate startTime < endTime if both are provided

package/dist/validation/positions.d.ts

@@ -37,19 +37,6 @@ export declare const BatchCloseAllSchema: z.ZodObject<{
 export declare const GetPositionRiskSchema: z.ZodObject<{
     positionId: z.ZodUUID;
 }, z.core.$strip>;
-export declare const AddPositionMarginSchema: z.ZodObject<{
-    positionId: z.ZodUUID;
-    request: z.ZodObject<{
-        amount: z.ZodString;
-        asset: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export declare const ReducePositionMarginSchema: z.ZodObject<{
-    positionId: z.ZodUUID;
-    request: z.ZodObject<{
-        amount: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
 export declare const AttachPositionTpSlSchema: z.ZodObject<{
     positionId: z.ZodUUID;
     request: z.ZodObject<{

package/dist/validation/positions.js

@@ -33,12 +33,14 @@ export const ClosePositionSchema = PositionIdSchema.extend({
         quantity: PositiveDecimalStringSchema.optional(),
     }),
 })
-    .refine((data) => data.request.closeType !== "LIMIT" || data.request.limitPrice !== undefined, {
-    message: "limitPrice is required for LIMIT close requests",
+    // An IOC close is a LIMIT+IOC order server-side (`close_order_shape`), so it
+    // needs a price exactly like a LIMIT close does; only MARKET forbids one.
+    .refine((data) => data.request.closeType === "MARKET" || data.request.limitPrice !== undefined, {
+    message: "limitPrice is required for LIMIT and IOC close requests",
     path: ["request", "limitPrice"],
 })
-    .refine((data) => data.request.closeType === "LIMIT" || data.request.limitPrice === undefined, {
-    message: "limitPrice is only allowed for LIMIT close requests",
+    .refine((data) => data.request.closeType !== "MARKET" || data.request.limitPrice === undefined, {
+    message: "limitPrice is not allowed for MARKET close requests",
     path: ["request", "limitPrice"],
 });
 export const BatchCloseAllSchema = z.object({
@@ -46,17 +48,6 @@ export const BatchCloseAllSchema = z.object({
     slippageToleranceBps: SlippageToleranceBpsSchema.optional(),
 });
 export const GetPositionRiskSchema = PositionIdSchema;
-export const AddPositionMarginSchema = PositionIdSchema.extend({
-    request: z.object({
-        amount: PositiveDecimalStringSchema,
-        asset: z.string().trim().min(1, "Asset cannot be empty"),
-    }),
-});
-export const ReducePositionMarginSchema = PositionIdSchema.extend({
-    request: z.object({
-        amount: PositiveDecimalStringSchema,
-    }),
-});
 const TpSlLegSchema = z
     .object({
     triggerPrice: PositiveDecimalStringSchema,

package/dist/validation/trading.d.ts

@@ -74,6 +74,8 @@ export declare const ParentTpSlLegSchema: z.ZodObject<{
         MARKET: "MARKET";
     }>;
     limitPrice: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodOptional<z.ZodString>;
+    closePosition: z.ZodOptional<z.ZodBoolean>;
     timeInForce: z.ZodOptional<z.ZodEnum<{
         GTC: "GTC";
         IOC: "IOC";
@@ -127,6 +129,8 @@ export declare const PlaceLimitOrderSchema: z.ZodObject<{
                 MARKET: "MARKET";
             }>;
             limitPrice: z.ZodOptional<z.ZodString>;
+            quantity: z.ZodOptional<z.ZodString>;
+            closePosition: z.ZodOptional<z.ZodBoolean>;
             timeInForce: z.ZodOptional<z.ZodEnum<{
                 GTC: "GTC";
                 IOC: "IOC";
@@ -141,6 +145,8 @@ export declare const PlaceLimitOrderSchema: z.ZodObject<{
                 MARKET: "MARKET";
             }>;
             limitPrice: z.ZodOptional<z.ZodString>;
+            quantity: z.ZodOptional<z.ZodString>;
+            closePosition: z.ZodOptional<z.ZodBoolean>;
             timeInForce: z.ZodOptional<z.ZodEnum<{
                 GTC: "GTC";
                 IOC: "IOC";
@@ -188,6 +194,8 @@ export declare const PlaceMarketOrderSchema: z.ZodObject<{
                 MARKET: "MARKET";
             }>;
             limitPrice: z.ZodOptional<z.ZodString>;
+            quantity: z.ZodOptional<z.ZodString>;
+            closePosition: z.ZodOptional<z.ZodBoolean>;
             timeInForce: z.ZodOptional<z.ZodEnum<{
                 GTC: "GTC";
                 IOC: "IOC";
@@ -202,6 +210,8 @@ export declare const PlaceMarketOrderSchema: z.ZodObject<{
                 MARKET: "MARKET";
             }>;
             limitPrice: z.ZodOptional<z.ZodString>;
+            quantity: z.ZodOptional<z.ZodString>;
+            closePosition: z.ZodOptional<z.ZodBoolean>;
             timeInForce: z.ZodOptional<z.ZodEnum<{
                 GTC: "GTC";
                 IOC: "IOC";
@@ -360,6 +370,12 @@ export declare const BatchCreateOrderItemSchema: z.ZodObject<{
     reduceOnly: z.ZodOptional<z.ZodBoolean>;
     postOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * Maximum items per batch create/replace/cancel request. Mirrors the server's
+ * cap (Zenith #11): a batch is one matching-engine sequencer command, so its
+ * item count is bounded independent of the transport message-size limit.
+ */
+export declare const MAX_BATCH_ORDER_ITEMS = 100;
 /**
  * Batch Create Orders validation schema
  *

package/dist/validation/trading.js

@@ -83,6 +83,8 @@ export const ParentTpSlLegSchema = z
     triggerPrice: PositiveDecimalStringSchema,
     orderType: OrderTypeSchema,
     limitPrice: PositiveDecimalStringSchema.optional(),
+    quantity: PositiveDecimalStringSchema.optional(),
+    closePosition: z.boolean().optional(),
     timeInForce: ConditionalTimeInForceSchema.optional(),
     slippageToleranceBps: SlippageToleranceBpsSchema.optional(),
     expiresAt: ISO8601DateSchema.optional(),
@@ -102,6 +104,16 @@ export const ParentTpSlLegSchema = z
     .refine((data) => data.orderType !== "LIMIT" || data.slippageToleranceBps === undefined, {
     message: "slippageToleranceBps is only allowed for MARKET parent TP/SL",
     path: ["slippageToleranceBps"],
+})
+    // Same sizing contract the position-attached rail enforces: omit both to
+    // track the live position, or name a deliberate partial that never resizes.
+    .refine((data) => data.closePosition !== true || data.quantity === undefined, {
+    message: "quantity must be omitted when closePosition is true",
+    path: ["quantity"],
+})
+    .refine((data) => data.quantity !== undefined || data.closePosition !== false, {
+    message: "quantity is required when closePosition is false",
+    path: ["closePosition"],
 });
 const hasParentTpSl = (options) => options?.takeProfit !== undefined || options?.stopLoss !== undefined;
 const legacyPositionSideMatchesOrderSide = (side, positionSide) => positionSide === undefined || (positionSide !== "NONE" && ((side === "BUY" && positionSide === "LONG") || (side === "SELL" && positionSide === "SHORT")));
@@ -429,13 +441,22 @@ export const BatchCreateOrderItemSchema = z
     message: "leverage is required for normal MARGIN orders",
     path: ["leverage"],
 });
+/**
+ * Maximum items per batch create/replace/cancel request. Mirrors the server's
+ * cap (Zenith #11): a batch is one matching-engine sequencer command, so its
+ * item count is bounded independent of the transport message-size limit.
+ */
+export const MAX_BATCH_ORDER_ITEMS = 100;
 /**
  * Batch Create Orders validation schema
  *
  * Validates the full array of orders for a batch create request.
  */
 export const BatchCreateOrdersSchema = z.object({
-    orders: z.array(BatchCreateOrderItemSchema).min(1, "At least one order is required"),
+    orders: z
+        .array(BatchCreateOrderItemSchema)
+        .min(1, "At least one order is required")
+        .max(MAX_BATCH_ORDER_ITEMS, `At most ${MAX_BATCH_ORDER_ITEMS} orders per batch request`),
 });
 /**
  * Single batch replace order item validation schema
@@ -463,5 +484,8 @@ export const BatchReplaceOrderItemSchema = z
  * Validates the full array of orders for a batch replace request.
  */
 export const BatchReplaceOrdersSchema = z.object({
-    orders: z.array(BatchReplaceOrderItemSchema).min(1, "At least one order is required"),
+    orders: z
+        .array(BatchReplaceOrderItemSchema)
+        .min(1, "At least one order is required")
+        .max(MAX_BATCH_ORDER_ITEMS, `At most ${MAX_BATCH_ORDER_ITEMS} orders per batch request`),
 });

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

@@ -0,0 +1,45 @@
+/**
+ * Account WebSocket Event Types
+ *
+ * Types for real-time account-level margin updates: equity, collateral, free
+ * collateral, margin ratio, and maintenance requirement for a margin account.
+ *
+ * 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. Each
+ * frame carries the account's full current health, so consume it as a
+ * terminal-state snapshot per margin account, never as an additive delta.
+ */
+/**
+ * Account event data carrying the current margin health of a single account.
+ */
+export interface AccountEventData {
+    /** Margin account this update describes (UUID) */
+    marginAccountId: string;
+    /** Mark-inclusive account equity: collateral + unrealized PnL + funding (decimal string) */
+    equity: string;
+    /** Raw deposited collateral in USD (decimal string) */
+    collateral: string;
+    /** Collateral available for new margin allocation (decimal string) */
+    freeCollateral: string;
+    /**
+     * Maintenance margin required divided by equity; `0` when equity is zero
+     * (decimal string).
+     */
+    marginRatio: string;
+    /** Maintenance margin required to keep the account solvent (decimal string) */
+    maintenanceRequirement: string;
+    /** Timestamp when the account state was updated (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * Account event emitted when a user's account-level margin health changes.
+ */
+export interface AccountEvent {
+    /** Event type identifier */
+    eventType: "account_update";
+    /** User ID (UUID) */
+    userId: string;
+    /** Account data */
+    data: AccountEventData;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Account WebSocket Event Types
+ *
+ * Types for real-time account-level margin updates: equity, collateral, free
+ * collateral, margin ratio, and maintenance requirement for a margin account.
+ *
+ * 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. Each
+ * frame carries the account's full current health, so consume it as a
+ * terminal-state snapshot per margin account, never as an additive delta.
+ */

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

@@ -6,9 +6,24 @@
  */
 import type { Address } from "viem";
 /**
- * Reason for the balance update
+ * Reason for the balance update.
+ *
+ * `fee` and `rebate` accompany a fill: `fee` when a taker/application fee is
+ * charged, `rebate` when a maker rebate is credited (including perp/margin
+ * makers). `funding` accompanies a funding settlement against margin collateral
+ * (also surfaced on the movements channel with `transactionType: "funding"`).
+ * `liquidation` and `adl` accompany a forced-close on the liquidation-worker
+ * path: `liquidation` on the liquidated victim's collateral, `adl` on an
+ * account impacted by auto-deleveraging.
+ *
+ * A single fill can emit more than one `balance_update` for the same account
+ * (e.g. a `trade` frame plus a `rebate` frame). Each frame carries the
+ * account's RESULTING balance for its token — it is a terminal-state snapshot,
+ * not an additive delta — so consume it by applying the latest balance per
+ * (account, token). That makes reconnect/replay naturally idempotent: never sum
+ * the `reason` frames as if they were separate credits.
  */
-export type BalanceUpdateReason = "lock" | "unlock" | "deposit" | "withdrawal" | "trade" | "margin_transfer_in" | "margin_transfer_out";
+export type BalanceUpdateReason = "lock" | "unlock" | "deposit" | "margin_deposit" | "withdrawal" | "trade" | "fee" | "rebate" | "funding" | "liquidation" | "adl" | "margin_transfer_in" | "margin_transfer_out";
 /**
  * User balance event data containing current balance state
  */

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

@@ -1,6 +1,8 @@
+export * from "./account-events";
 export * from "./balance-events";
 export * from "./conditional-order-events";
 export * from "./liquidation-events";
+export * from "./market-stats-events";
 export * from "./movement-events";
 export * from "./ohlcv-events";
 export * from "./orderbook-events";

package/dist/websocket/events/index.js

@@ -1,6 +1,8 @@
+export * from "./account-events";
 export * from "./balance-events";
 export * from "./conditional-order-events";
 export * from "./liquidation-events";
+export * from "./market-stats-events";
 export * from "./movement-events";
 export * from "./ohlcv-events";
 export * from "./orderbook-events";