@0xmonaco/types 1.0.42 → 1.0.43

package/dist/portfolio/index.d.ts

@@ -122,6 +122,28 @@ export interface PortfolioAssetRow {
     allocationPct?: string;
     priceAsOf?: string;
     pricingStatus: "priced" | "unpriced";
+    /**
+     * Weighted-average cost per unit of the holding, quote-denominated, from the
+     * spot cost-basis engine. Present only when a cost-basis checkpoint exists.
+     */
+    avgCost?: string;
+    /**
+     * Unrealized PnL for the holding: costBasisQuantity x (markPrice - avgCost),
+     * quote-denominated. Uses the cost-basis engine's folded quantity so it agrees
+     * with the portfolio summary headline. Present only when both a cost-basis
+     * checkpoint and a mark price exist.
+     */
+    unrealizedPnl?: string;
+    /**
+     * Unrealized return on the holding's cost basis, as a percentage. Present only
+     * when unrealizedPnl is present and the cost basis is non-zero.
+     */
+    unrealizedRoe?: string;
+    /**
+     * Cumulative realized PnL booked against this holding over its lifetime, gross
+     * of fees, quote-denominated. Present only when a cost-basis checkpoint exists.
+     */
+    cumRealized?: string;
 }
 export interface PortfolioAssets {
     window: PortfolioSeriesWindow;

package/dist/positions/index.d.ts

@@ -151,6 +151,15 @@ export interface PositionRisk {
      * as unavailable, never as zero.
      */
     liquidationPrice: string;
+    /**
+     * Account distress ratio: maintenance margin required divided by equity
+     * (higher is closer to liquidation, decimal string). Equity that is zero or
+     * negative has no meaningful quotient, so an account that still owes a
+     * maintenance requirement reports the max-decimal sentinel
+     * (`79228162514264337593543950335`, maximal distress) rather than zero or a
+     * negative value, and an account with no open maintenance requirement reports
+     * `0`. Clamp the sentinel before display.
+     */
     marginRatio: string;
     /**
      * Position-scoped requirement at markPrice using the market
@@ -169,7 +178,16 @@ export interface TpSlLeg {
     orderType: OrderType;
     limitPrice?: string;
     quantity?: string;
-    /** Resolve the full live position size when triggered. */
+    /**
+     * Resolve the full live position size when triggered.
+     *
+     * A full-close leg supersedes the position's previously active full-close
+     * legs of the same condition type — they are cancelled in the same engine
+     * step that creates this one, so moving a take-profit or stop-loss is a
+     * single call. Fixed-`quantity` legs never participate (laddered partial
+     * exits stack), a superseded leg's OCO sibling stays active, and legs
+     * attached to an entry order are excluded on both sides.
+     */
     closePosition?: boolean;
     timeInForce?: Extract<TimeInForce, "GTC" | "IOC">;
     slippageToleranceBps?: number;

package/dist/profile/index.d.ts

@@ -199,6 +199,12 @@ export interface AccountBalance {
     lockedBalanceRaw: string;
     /** Total balance (available + locked) in raw format (wei) */
     totalBalanceRaw: string;
+    /**
+     * True when this asset is the chain's wrapped-native token (e.g. WSEI):
+     * vault deposits can be made in native coin via depositNative (the vault
+     * wraps on entry) and withdrawals pay out native.
+     */
+    wrappedNative?: boolean;
 }
 /**
  * A single user trade execution.

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, MonacoWebSocketConfig, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, TradeEvent, UserBalanceEvent, UserMovementEvent } from "../websocket";
+import type { ConditionalOrderEvent, MonacoWebSocketConfig, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, TradeEvent, TwapOrderEvent, UserBalanceEvent, UserMovementEvent } from "../websocket";
 import type { WhitelistAPI } from "../whitelist";
 import type { WithdrawalsAPI } from "../withdrawals";
 import type { Network } from "./network";
@@ -154,6 +154,7 @@ export interface MonacoSDK {
         userOrders: (handler: (event: OrderEvent) => void) => () => void;
         balances: (handler: (event: UserBalanceEvent) => void) => () => void;
         conditionalOrders: (handler: (event: ConditionalOrderEvent) => void, tradingPairId?: string) => () => void;
+        twapOrders: (handler: (event: TwapOrderEvent) => void, tradingPairId?: string) => () => void;
     };
     /** Wallet client for all blockchain operations (undefined until set) */
     walletClient: WalletClient | undefined;

package/dist/trading/index.d.ts

@@ -6,7 +6,7 @@
 import type { BaseAPI } from "../api/index";
 import type { MarginMode } from "../margin-accounts";
 import type { Order, OrderSide, PositionSide, TimeInForce, TradingMode } from "./orders";
-import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, ConditionalOrder, CreateOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ParentTpSlLegParams, ReplaceOrderResponse } from "./responses";
+import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, ParentTpSlLegParams, ReplaceOrderResponse, TwapOrder } from "./responses";
 /**
  * Trading API interface.
  * Provides methods for placing and managing orders.
@@ -92,7 +92,9 @@ export interface TradingAPI extends BaseAPI {
      * @param orderId - ID of the order to cancel
      * @returns Promise resolving to the cancellation result
      */
-    cancelOrder(orderId: string): Promise<CancelOrderResponse>;
+    cancelOrder(orderId: string, options?: {
+        remainingQuantityTarget?: string;
+    }): Promise<CancelOrderResponse>;
     /**
      * Cancels an active conditional TP/SL order.
      */
@@ -179,7 +181,35 @@ export interface TradingAPI extends BaseAPI {
      * @returns Promise resolving to the order details
      */
     getOrder(orderId: string): Promise<GetOrderResponse>;
+    /**
+     * Creates a server-side TWAP (time-weighted average price) parent order.
+     * The matching engine executes it as a schedule of market child orders
+     * across the window, hard-stopping at the window end.
+     * @param tradingPairId - Trading pair UUID
+     * @param side - Order side ("BUY" or "SELL")
+     * @param quantity - Total quantity to execute across the window (at least 2x the pair's minimum order size)
+     * @param options - Window (exactly one of durationSeconds or endTime) plus optional execution parameters
+     * @returns Promise resolving to the TWAP creation result
+     */
+    createTwapOrder(tradingPairId: string, side: OrderSide, quantity: string, options: CreateTwapOrderOptions): Promise<CreateTwapOrderResponse>;
+    /**
+     * Cancels a TWAP parent order. Child orders are IOC and never rest, so the
+     * cancel is atomic and immediate; executed quantity stands.
+     * @param twapOrderId - TWAP parent order UUID
+     * @returns Promise resolving to the cancellation result
+     */
+    cancelTwapOrder(twapOrderId: string): Promise<CancelTwapOrderResponse>;
+    /**
+     * Gets a single TWAP parent order by its UUID. Users can only access their
+     * own TWAP orders.
+     */
+    getTwapOrder(twapOrderId: string): Promise<TwapOrder>;
+    /**
+     * Lists TWAP parent orders for the authenticated user with pagination and
+     * optional state / trading pair filters.
+     */
+    listTwapOrders(params?: ListTwapOrdersParams): Promise<ListTwapOrdersResponse>;
 }
-export type { ConditionalOrderConditionType, ConditionalOrderState, ConditionalOrderTriggerSource, Order, OrderRole, OrderSide, OrderStatus, OrderStatusFilter, OrderTerminalReason, OrderType, PositionSide, TimeInForce, TradingMode, } from "./orders";
+export type { ConditionalOrderConditionType, ConditionalOrderState, ConditionalOrderTriggerSource, Order, OrderRole, OrderSide, OrderStatus, OrderStatusFilter, OrderTerminalReason, OrderType, PositionSide, TimeInForce, TradingMode, TwapOrderState, } from "./orders";
 export { ORDER_STATUS_VALUES } from "./orders";
-export type { BatchCancelError, BatchCancelOrdersResponse, BatchCancelResult, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchCreateResult, BatchError, BatchReplaceOrderParams, BatchReplaceOrdersResponse, BatchReplaceResult, CancelConditionalOrderResponse, CancelOrderResponse, ConditionalOrder, CreateOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, MatchResult, ParentTpSlLegParams, ReplaceOrderResponse, UpdatedFields, } from "./responses";
+export type { BatchCancelError, BatchCancelOrdersResponse, BatchCancelResult, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchCreateResult, BatchError, BatchReplaceOrderParams, BatchReplaceOrdersResponse, BatchReplaceResult, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, MatchResult, ParentTpSlLegParams, ReplaceOrderResponse, TwapOrder, UpdatedFields, } from "./responses";

package/dist/trading/orders.d.ts

@@ -160,3 +160,11 @@ export type ConditionalOrderTriggerSource = "MARK_PRICE";
  * Conditional TP/SL lifecycle state.
  */
 export type ConditionalOrderState = "PENDING_PARENT" | "ACTIVE" | "TRIGGERING" | "TRIGGERED" | "CANCELLED" | "EXPIRED" | "FAILED";
+/**
+ * TWAP parent-order lifecycle state.
+ * - PENDING: window start is in the future; no child orders yet
+ * - ACTIVE: inside the execution window; child slices are firing
+ * - COMPLETED: window ended (fully filled or hard-stopped with a shortfall)
+ * - CANCELLED: cancelled by the user before the window ended
+ */
+export type TwapOrderState = "PENDING" | "ACTIVE" | "COMPLETED" | "CANCELLED";

package/dist/trading/responses.d.ts

@@ -4,7 +4,7 @@
  * Response types for trading operations.
  */
 import type { MarginMode } from "../margin-accounts";
-import type { ConditionalOrderConditionType, ConditionalOrderState, ConditionalOrderTriggerSource, Order, OrderSide, OrderStatus, OrderStatusFilter, OrderType, PositionSide, TimeInForce, TradingMode } from "./orders";
+import type { ConditionalOrderConditionType, ConditionalOrderState, ConditionalOrderTriggerSource, Order, OrderSide, OrderStatus, OrderStatusFilter, OrderType, PositionSide, TimeInForce, TradingMode, TwapOrderState } from "./orders";
 /**
  * Match result information for order execution.
  * Contains detailed information about trades, fills, and execution quality.
@@ -455,3 +455,193 @@ export interface ListConditionalOrdersResponse {
     page: number;
     pageSize: number;
 }
+/**
+ * Options for creating a server-side TWAP parent order.
+ *
+ * The execution window is mandatory: exactly one of `durationSeconds` or
+ * `endTime` must be set. `startTime` is only valid together with `endTime`
+ * and defaults to now.
+ */
+export interface CreateTwapOrderOptions {
+    /**
+     * Execution window length in seconds from launch. Exactly one of
+     * `durationSeconds` or `endTime` must be set. Bounds (env-tunable server
+     * defaults): 300 to 86400 (5 minutes to 24 hours).
+     */
+    durationSeconds?: number | string;
+    /** Window start (ISO 8601). Only valid together with `endTime`; defaults to now. */
+    startTime?: string;
+    /**
+     * Window end (ISO 8601). Exactly one of `durationSeconds` or `endTime` must
+     * be set. Execution stops hard at this time; any unfilled remainder is
+     * reported as shortfall.
+     */
+    endTime?: string;
+    /**
+     * Optional parent-level limit price as decimal string. BUY child orders
+     * never execute above it, SELL children never below it. Omitted: slippage
+     * band protection only.
+     */
+    limitPrice?: string;
+    /** Per-slice protective price band in basis points around the reference price (default 100 = 1%). */
+    slippageToleranceBps?: number;
+    /**
+     * Apply seeded randomization to slice sizes (±30%) and timing (±30%);
+     * default true. The seed is recorded for audit, so the schedule is
+     * reproducible to compliance but unpredictable to the market.
+     */
+    randomize?: boolean;
+    /** Whether the TWAP parent is reduce-only (margin only). Child orders inherit it and clamp to the live position. */
+    reduceOnly?: boolean;
+    /** Trading mode: "SPOT" or "MARGIN" (default: "SPOT"). */
+    tradingMode?: TradingMode;
+    /** Margin account UUID for margin TWAP orders. Resolved once at creation and reused by every child order. */
+    marginAccountId?: string;
+    /** Existing isolated risk bucket UUID for risk-bucket-scoped margin TWAP orders. Snapshot at creation. */
+    riskBucketId?: string;
+    /** Risk bucket mode for margin TWAP orders. Defaults to ISOLATED. */
+    marginMode?: MarginMode;
+    /** Leverage multiplier as a decimal string. Required for normal margin TWAP orders; optional and ignored for reduce-only. */
+    leverage?: string;
+    /** Strategy key used to group risk buckets for margin orders. */
+    strategyKey?: string;
+    /** Use master account balance for sub-account orders. */
+    useMasterBalance?: boolean;
+    /** Client-assigned idempotency key (max 36 chars), unique per user and application. A duplicate is rejected with 409. */
+    clientTwapId?: string;
+}
+/**
+ * Response from creating a TWAP parent order.
+ */
+export interface CreateTwapOrderResponse {
+    /** Created TWAP parent order UUID */
+    twapOrderId: string;
+    /**
+     * Result status: SUCCESS or FAILED. SUCCESS means the parent is durably
+     * recorded; execution itself is best-effort within the window.
+     */
+    status: "SUCCESS" | "FAILED";
+    /** Human-readable status message */
+    message: string;
+    /** Initial parent state: always PENDING at create; the parent activates on its first attempted slice */
+    state: TwapOrderState;
+    /** Resolved margin account UUID for margin TWAP orders */
+    marginAccountId?: string;
+    /** Resolved isolated risk bucket UUID for risk-bucket-scoped margin TWAP orders */
+    riskBucketId?: string;
+    /** Number of slices in the planned schedule */
+    plannedSlices: number;
+    /** Planned time of the first slice (ISO 8601) */
+    firstSliceAt?: string;
+    /** Resolved window end (ISO 8601). Execution never continues past it. */
+    endTime: string;
+}
+/**
+ * Response from cancelling a TWAP parent order.
+ */
+export interface CancelTwapOrderResponse {
+    /** Cancelled TWAP parent order UUID */
+    twapOrderId: string;
+    /** Result status: SUCCESS or FAILED */
+    status: "SUCCESS" | "FAILED";
+    /** Human-readable status message */
+    message: string;
+}
+/**
+ * A TWAP parent order read model.
+ */
+export interface TwapOrder {
+    /** TWAP parent order UUID */
+    twapOrderId: string;
+    /** Trading pair UUID */
+    tradingPairId: string;
+    /** Order side: "BUY" or "SELL" */
+    side: OrderSide;
+    /** Trading mode: "SPOT" or "MARGIN" */
+    tradingMode: TradingMode;
+    /** Total quantity requested */
+    totalQuantity: string;
+    /** Quantity executed so far across all child orders */
+    executedQuantity: string;
+    /** Notional (quote) value executed so far */
+    executedNotional: string;
+    /** Volume-weighted average fill price (executedNotional / executedQuantity); absent until the first fill */
+    averageFillPrice?: string;
+    /** Execution progress as a decimal fraction (executedQuantity / totalQuantity, 0 to 1) */
+    progress: string;
+    /** Parent-level limit price; absent when only the slippage band protects child orders */
+    limitPrice?: string;
+    /** Per-slice protective price band in basis points */
+    slippageToleranceBps: number;
+    /** Whether the parent is reduce-only */
+    reduceOnly: boolean;
+    /** Margin account UUID for margin TWAP orders */
+    marginAccountId?: string;
+    /** Isolated risk bucket UUID for risk-bucket-scoped margin TWAP orders */
+    riskBucketId?: string;
+    /** Leverage for margin TWAP orders */
+    leverage?: string;
+    /** Whether child orders use the master account balance */
+    useMasterBalance?: boolean;
+    /** Strategy key used to group risk buckets */
+    strategyKey?: string;
+    /** Client-assigned idempotency key */
+    clientTwapId?: string;
+    /** Whether seeded size/timing randomization is applied to the schedule */
+    randomize: boolean;
+    /** Window start (ISO 8601) */
+    startTime: string;
+    /** Window end (ISO 8601). Execution stops hard at this time. */
+    endTime: string;
+    /** Derived base slice interval in milliseconds (int64 serialized as a JSON number; stored for audit) */
+    intervalMs: number;
+    /** Number of slices in the planned schedule */
+    plannedSlices: number;
+    /** Number of child orders placed so far */
+    slicesPlaced: number;
+    /**
+     * Number of slices skipped or failed so far (limit price through the
+     * market, self-trade prevention, halted market, failed admission). Skips
+     * never terminate the parent; the deficit flows into catch-up.
+     */
+    slicesSkipped: number;
+    /** Planned time of the next slice (ISO 8601); absent once the parent is terminal */
+    nextSliceAt?: string;
+    /** Parent state: PENDING, ACTIVE, COMPLETED, or CANCELLED */
+    state: TwapOrderState;
+    /** Terminal cause detail, e.g. an end-of-window shortfall ('ended with shortfall <qty>'); absent for non-terminal parents */
+    terminalReason?: string;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last update timestamp (ISO 8601) */
+    updatedAt: string;
+    /** Cancellation timestamp (ISO 8601) */
+    cancelledAt?: string;
+    /** Completion timestamp (ISO 8601) */
+    completedAt?: string;
+}
+/**
+ * Query parameters for listing TWAP parent orders.
+ */
+export interface ListTwapOrdersParams {
+    /** Filter by parent state */
+    state?: TwapOrderState;
+    /** Filter by trading pair UUID */
+    tradingPairId?: string;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page (max 100) */
+    pageSize?: number;
+}
+/**
+ * Response from listing TWAP parent orders.
+ */
+export interface ListTwapOrdersResponse {
+    orders: TwapOrder[];
+    /** Total number of TWAP orders matching the filter */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    pageSize: number;
+}

package/dist/validation/trading.d.ts

@@ -67,6 +67,8 @@ export declare const ISO8601DateSchema: z.ZodISODateTime;
  */
 export declare const SlippageToleranceSchema: z.ZodOptional<z.ZodNumber>;
 export declare const SlippageToleranceBpsSchema: z.ZodNumber;
+/** TWAP slices cap at 500 bps (5%) — tighter than standalone market orders. */
+export declare const TwapSlippageToleranceBpsSchema: z.ZodNumber;
 export declare const ParentTpSlLegSchema: z.ZodObject<{
     triggerPrice: z.ZodString;
     orderType: z.ZodEnum<{
@@ -226,6 +228,7 @@ export declare const PlaceMarketOrderSchema: z.ZodObject<{
  */
 export declare const CancelOrderSchema: z.ZodObject<{
     orderId: z.ZodUUID;
+    remainingQuantityTarget: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Replace Order validation schema
@@ -322,6 +325,63 @@ export declare const ListConditionalOrdersSchema: z.ZodObject<{
     page: z.ZodOptional<z.ZodNumber>;
     pageSize: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+export declare const TwapOrderStateSchema: z.ZodEnum<{
+    CANCELLED: "CANCELLED";
+    ACTIVE: "ACTIVE";
+    PENDING: "PENDING";
+    COMPLETED: "COMPLETED";
+}>;
+/**
+ * Create TWAP Order validation schema
+ *
+ * Validates parameters for creating a TWAP parent order. The execution
+ * window is mandatory: exactly one of durationSeconds or endTime.
+ */
+export declare const CreateTwapOrderSchema: z.ZodObject<{
+    tradingPairId: z.ZodUUID;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    quantity: z.ZodString;
+    options: z.ZodObject<{
+        durationSeconds: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        startTime: z.ZodOptional<z.ZodISODateTime>;
+        endTime: z.ZodOptional<z.ZodISODateTime>;
+        limitPrice: z.ZodOptional<z.ZodString>;
+        slippageToleranceBps: z.ZodOptional<z.ZodNumber>;
+        randomize: z.ZodOptional<z.ZodBoolean>;
+        reduceOnly: z.ZodOptional<z.ZodBoolean>;
+        tradingMode: z.ZodOptional<z.ZodEnum<{
+            SPOT: "SPOT";
+            MARGIN: "MARGIN";
+        }>>;
+        marginAccountId: z.ZodOptional<z.ZodUUID>;
+        riskBucketId: z.ZodOptional<z.ZodUUID>;
+        marginMode: z.ZodOptional<z.ZodEnum<{
+            ISOLATED: "ISOLATED";
+            CROSS: "CROSS";
+        }>>;
+        leverage: z.ZodOptional<z.ZodString>;
+        strategyKey: z.ZodOptional<z.ZodString>;
+        useMasterBalance: z.ZodOptional<z.ZodBoolean>;
+        clientTwapId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const CancelTwapOrderSchema: z.ZodObject<{
+    twapOrderId: z.ZodUUID;
+}, z.core.$strip>;
+export declare const ListTwapOrdersSchema: z.ZodObject<{
+    state: z.ZodOptional<z.ZodEnum<{
+        CANCELLED: "CANCELLED";
+        ACTIVE: "ACTIVE";
+        PENDING: "PENDING";
+        COMPLETED: "COMPLETED";
+    }>>;
+    tradingPairId: z.ZodOptional<z.ZodUUID>;
+    page: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * Single batch create order item validation schema
  *

package/dist/validation/trading.js

@@ -78,6 +78,12 @@ export const SlippageToleranceBpsSchema = z
     .int()
     .min(0, "Slippage tolerance must be at least 0 bps")
     .max(10000, "Slippage tolerance cannot exceed 10000 bps");
+/** TWAP slices cap at 500 bps (5%) — tighter than standalone market orders. */
+export const TwapSlippageToleranceBpsSchema = z
+    .number()
+    .int()
+    .min(0, "Slippage tolerance must be at least 0 bps")
+    .max(500, "TWAP slippage tolerance cannot exceed 500 bps (5%)");
 export const ParentTpSlLegSchema = z
     .object({
     triggerPrice: PositiveDecimalStringSchema,
@@ -276,6 +282,14 @@ export const PlaceMarketOrderSchema = z
  */
 export const CancelOrderSchema = z.object({
     orderId: UUIDSchema,
+    /**
+     * Partial cancel: reduce the resting order in place to this remaining
+     * quantity, keeping its queue position. A target ("leave this much
+     * resting"), not an amount to remove, so a retried request converges. Must
+     * be a positive multiple of the market's quantity step, strictly below the
+     * order's current remaining quantity. Omit for a full cancel.
+     */
+    remainingQuantityTarget: PositiveDecimalStringSchema.optional(),
 });
 /**
  * Replace Order validation schema
@@ -352,6 +366,86 @@ export const ListConditionalOrdersSchema = z.object({
     page: z.number().int().min(1, "Page must be at least 1").optional(),
     pageSize: z.number().int().min(1, "Page size must be at least 1").max(100, "Page size cannot exceed 100").optional(),
 });
+export const TwapOrderStateSchema = z.enum(["PENDING", "ACTIVE", "COMPLETED", "CANCELLED"], {
+    message: "Invalid TWAP order state",
+});
+/**
+ * TWAP window duration in whole seconds. Accepts a number or a numeric
+ * string for ergonomics; either way the client serializes it as a JSON
+ * number (the server deserializes an int64 and rejects strings). Only
+ * positivity and integrality are validated client-side — the min/max window
+ * bounds are env-tunable server configuration.
+ */
+const TwapDurationSecondsSchema = z.union([
+    z.number().int("durationSeconds must be a whole number of seconds").positive("durationSeconds must be greater than 0"),
+    z.string().regex(/^[1-9]\d*$/, "durationSeconds must be a positive integer string (e.g., '3600')"),
+]);
+/**
+ * Create TWAP Order validation schema
+ *
+ * Validates parameters for creating a TWAP parent order. The execution
+ * window is mandatory: exactly one of durationSeconds or endTime.
+ */
+export const CreateTwapOrderSchema = z
+    .object({
+    tradingPairId: UUIDSchema,
+    side: OrderSideSchema,
+    quantity: PositiveDecimalStringSchema,
+    options: z.object({
+        durationSeconds: TwapDurationSecondsSchema.optional(),
+        startTime: ISO8601DateSchema.optional(),
+        endTime: ISO8601DateSchema.optional(),
+        limitPrice: PositiveDecimalStringSchema.optional(),
+        slippageToleranceBps: TwapSlippageToleranceBpsSchema.optional(),
+        randomize: z.boolean().optional(),
+        reduceOnly: z.boolean().optional(),
+        tradingMode: TradingModeSchema.optional(),
+        marginAccountId: UUIDSchema.optional(),
+        riskBucketId: UUIDSchema.optional(),
+        marginMode: MarginModeSchema.optional(),
+        leverage: PositiveDecimalStringSchema.optional(),
+        strategyKey: z.string().min(1).max(128).optional(),
+        useMasterBalance: z.boolean().optional(),
+        clientTwapId: z.string().min(1).max(36, "clientTwapId cannot exceed 36 characters").optional(),
+    }),
+})
+    .refine((data) => (data.options.durationSeconds !== undefined) !== (data.options.endTime !== undefined), {
+    message: "Exactly one of durationSeconds or endTime must be set",
+    path: ["options", "durationSeconds"],
+})
+    .refine((data) => data.options.startTime === undefined || data.options.endTime !== undefined, {
+    message: "startTime is only valid together with endTime",
+    path: ["options", "startTime"],
+})
+    .refine((data) => data.options.marginMode === undefined || data.options.tradingMode === "MARGIN", {
+    message: "marginMode is only supported for MARGIN orders",
+    path: ["options", "tradingMode"],
+})
+    .refine((data) => data.options.riskBucketId === undefined || data.options.tradingMode === "MARGIN", {
+    message: "riskBucketId is only supported for MARGIN orders",
+    path: ["options", "tradingMode"],
+})
+    .refine((data) => data.options.marginMode !== "CROSS" || data.options.riskBucketId === undefined, {
+    message: "marginMode CROSS cannot be combined with riskBucketId",
+    path: ["options", "riskBucketId"],
+})
+    .refine((data) => data.options.marginMode !== "CROSS" || data.options.strategyKey === undefined, {
+    message: "marginMode CROSS cannot be combined with strategyKey",
+    path: ["options", "strategyKey"],
+})
+    .refine((data) => data.options.tradingMode !== "MARGIN" || data.options.reduceOnly === true || data.options.leverage !== undefined, {
+    message: "leverage is required for normal MARGIN TWAP orders",
+    path: ["options", "leverage"],
+});
+export const CancelTwapOrderSchema = z.object({
+    twapOrderId: UUIDSchema,
+});
+export const ListTwapOrdersSchema = z.object({
+    state: TwapOrderStateSchema.optional(),
+    tradingPairId: UUIDSchema.optional(),
+    page: z.number().int().min(1, "Page must be at least 1").optional(),
+    pageSize: z.number().int().min(1, "Page size must be at least 1").max(100, "Page size cannot exceed 100").optional(),
+});
 /**
  * Single batch create order item validation schema
  *

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

@@ -23,8 +23,12 @@ export interface AccountEventData {
     /** Collateral available for new margin allocation (decimal string) */
     freeCollateral: string;
     /**
-     * Maintenance margin required divided by equity; `0` when equity is zero
-     * (decimal string).
+     * Account distress ratio: maintenance margin required over equity (higher is
+     * closer to liquidation, decimal string). When equity is non-positive the
+     * quotient is undefined, so an account that still owes a maintenance
+     * requirement saturates to the max-decimal sentinel
+     * (`79228162514264337593543950335`, maximal distress) and an empty account
+     * with no requirement is `0`. Clamp the sentinel before display.
      */
     marginRatio: string;
     /** Maintenance margin required to keep the account solvent (decimal string) */

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

@@ -9,3 +9,4 @@ export * from "./orderbook-events";
 export * from "./orders-events";
 export * from "./position-events";
 export * from "./trade-events";
+export * from "./twap-order-events";

package/dist/websocket/events/index.js

@@ -9,3 +9,4 @@ export * from "./orderbook-events";
 export * from "./orders-events";
 export * from "./position-events";
 export * from "./trade-events";
+export * from "./twap-order-events";

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

@@ -5,6 +5,15 @@
  */
 import type { Candlestick, Interval } from "../../market";
 import type { TradingMode } from "../../trading";
+/**
+ * OHLCV price series selector for the optional fifth channel token.
+ *
+ * - `trade` — the trade-derived candles (the default when the token is omitted).
+ * - `mark` — the close-only mark-price series (open = high = low = close = mark,
+ *   zero volume), published on `1m` for margin pairs.
+ * - `*` — both series.
+ */
+export type OHLCVPriceType = "trade" | "mark" | "*";
 /**
  * OHLCV update event
  */
@@ -15,6 +24,12 @@ export interface OHLCVEvent {
     interval: Interval;
     /** Trading mode */
     tradingMode: TradingMode;
+    /**
+     * Price series this candle belongs to. Always a concrete series on the wire
+     * (`trade` or `mark`, never the `*` selector); lets a wildcard subscriber
+     * tell the two streams apart. Absent only on legacy frames that omit it.
+     */
+    priceType?: "trade" | "mark";
     /** OHLCV candlestick data */
     candlestick: Candlestick;
 }