@0xmonaco/core 1.0.42 → 1.0.43

package/dist/api/perp/routes.d.ts

@@ -26,6 +26,15 @@ export declare const perpRoutes: {
         }) => string;
         readonly cancelConditional: (conditionalOrderId: string) => string;
         readonly getConditional: (conditionalOrderId: string) => string;
+        readonly createTwap: () => string;
+        readonly listTwap: (params?: {
+            state?: string;
+            tradingPairId?: string;
+            page?: number;
+            pageSize?: number;
+        }) => string;
+        readonly getTwap: (twapOrderId: string) => string;
+        readonly cancelTwap: (twapOrderId: string) => string;
     };
     readonly delegatedAgents: {
         readonly list: () => string;

package/dist/api/perp/routes.js

@@ -29,6 +29,10 @@ export const perpRoutes = {
         listConditional: (params) => withQuery(`${API_V1}/orders/conditional`, params),
         cancelConditional: (conditionalOrderId) => `${API_V1}/orders/conditional/${encodeSegment(conditionalOrderId)}`,
         getConditional: (conditionalOrderId) => `${API_V1}/orders/conditional/${encodeSegment(conditionalOrderId)}`,
+        createTwap: () => `${API_V1}/orders/twap`,
+        listTwap: (params) => withQuery(`${API_V1}/orders/twap`, params),
+        getTwap: (twapOrderId) => `${API_V1}/orders/twap/${encodeSegment(twapOrderId)}`,
+        cancelTwap: (twapOrderId) => `${API_V1}/orders/twap/${encodeSegment(twapOrderId)}/cancel`,
     },
     delegatedAgents: {
         list: () => `${API_V1}/delegated-agents`,

package/dist/api/trading/api.d.ts

@@ -21,7 +21,7 @@
  * );
  * ```
  */
-import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, ConditionalOrder, CreateOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, MarginMode, OrderSide, ParentTpSlLegParams, PositionSide, ReplaceOrderResponse, TimeInForce, TradingAPI, TradingMode } from "@0xmonaco/types";
+import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, MarginMode, OrderSide, ParentTpSlLegParams, PositionSide, ReplaceOrderResponse, TimeInForce, TradingAPI, TradingMode, TwapOrder } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     /**
@@ -157,16 +157,25 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      * Canceled orders cannot be recovered.
      *
      * @param orderId - The ID of the order to cancel
+     * @param options - Optional partial-cancel: `remainingQuantityTarget` reduces
+     *   the resting order in place to that 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 current remaining
+     *   quantity. Omit for a full cancel.
      * @returns Promise resolving to CancelOrderResponse with cancellation details
      * @throws {APIError} When API communication fails
      *
      * @example
      * ```typescript
      * const result = await tradingAPI.cancelOrder("order_123");
-     * console.log(`Order canceled: ${result.status}`);
+     * // Partial: keep 0.5 resting at the same queue position
+     * await tradingAPI.cancelOrder("order_123", { remainingQuantityTarget: "0.5" });
      * ```
      */
-    cancelOrder(orderId: string): Promise<CancelOrderResponse>;
+    cancelOrder(orderId: string, options?: {
+        remainingQuantityTarget?: string;
+    }): Promise<CancelOrderResponse>;
     cancelConditionalOrder(conditionalOrderId: string): Promise<CancelConditionalOrderResponse>;
     getConditionalOrder(conditionalOrderId: string): Promise<ConditionalOrder>;
     listConditionalOrders(params?: ListConditionalOrdersParams): Promise<ListConditionalOrdersResponse>;
@@ -344,4 +353,109 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      * ```
      */
     getOrder(orderId: string): Promise<GetOrderResponse>;
+    /**
+     * Creates a server-side TWAP (time-weighted average price) parent order.
+     *
+     * The matching engine executes the parent as a schedule of MARKET child
+     * orders across the window, with seeded size (±30%) and timing (±30%)
+     * randomization when `randomize` is enabled (the default). Execution stops
+     * hard at the window end — any unfilled remainder is reported as shortfall,
+     * never traded past the end.
+     *
+     * @param tradingPairId - The trading pair UUID
+     * @param side - The order side ("BUY" or "SELL")
+     * @param quantity - Total quantity to execute across the window as string
+     *   (must be at least 2x the pair's minimum order size so it can be sliced)
+     * @param options - Window and execution parameters
+     * @param options.durationSeconds - Window length in seconds from launch;
+     *   exactly one of `durationSeconds` or `endTime` must be set
+     * @param options.endTime - Window end (ISO 8601); exactly one of
+     *   `durationSeconds` or `endTime` must be set
+     * @param options.startTime - Window start (ISO 8601); only valid together
+     *   with `endTime`, defaults to now
+     * @param options.limitPrice - Optional parent-level limit price; BUY child
+     *   orders never execute above it, SELL children never below it
+     * @param options.slippageToleranceBps - Per-slice protective price band in
+     *   basis points (default 100 = 1%)
+     * @param options.clientTwapId - Idempotency key (max 36 chars), unique per
+     *   user and application; a duplicate is rejected with 409
+     * @returns Promise resolving to CreateTwapOrderResponse with the parent id,
+     *   initial state, and the planned schedule summary
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * // Buy 10 units spread across one hour
+     * const twap = await tradingAPI.createTwapOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "10",
+     *   { durationSeconds: 3600 }
+     * );
+     *
+     * // Margin TWAP with an explicit window and a parent limit price
+     * const marginTwap = await tradingAPI.createTwapOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "SELL",
+     *   "5",
+     *   {
+     *     startTime: "2026-08-01T10:00:00Z",
+     *     endTime: "2026-08-01T11:00:00Z",
+     *     limitPrice: "35000.00",
+     *     tradingMode: "MARGIN",
+     *     leverage: "5",
+     *   }
+     * );
+     * ```
+     */
+    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 - The TWAP parent order UUID to cancel
+     * @returns Promise resolving to CancelTwapOrderResponse with cancellation details
+     * @throws {APIError} When API communication fails or the parent is already terminal
+     *
+     * @example
+     * ```typescript
+     * const result = await tradingAPI.cancelTwapOrder("123e4567-e89b-12d3-a456-426614174000");
+     * console.log(`TWAP cancelled: ${result.status}`);
+     * ```
+     */
+    cancelTwapOrder(twapOrderId: string): Promise<CancelTwapOrderResponse>;
+    /**
+     * Gets a single TWAP parent order by its UUID.
+     *
+     * Users can only access their own TWAP orders. The read model carries the
+     * live execution progress (executed quantity/notional, VWAP, slice
+     * counters) alongside the immutable schedule configuration.
+     *
+     * @param twapOrderId - The TWAP parent order UUID to retrieve
+     * @returns Promise resolving to the TwapOrder read model
+     * @throws {APIError} When API communication fails or the order is not found
+     *
+     * @example
+     * ```typescript
+     * const twap = await tradingAPI.getTwapOrder("123e4567-e89b-12d3-a456-426614174000");
+     * console.log(`State: ${twap.state}, progress: ${twap.progress}`);
+     * ```
+     */
+    getTwapOrder(twapOrderId: string): Promise<TwapOrder>;
+    /**
+     * Lists TWAP parent orders for the authenticated user.
+     *
+     * @param params - Optional pagination and state / trading-pair filters
+     * @returns Promise resolving to ListTwapOrdersResponse with orders and pagination info
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * const active = await tradingAPI.listTwapOrders({ state: "ACTIVE", pageSize: 50 });
+     * console.log(`Found ${active.total} active TWAP orders`);
+     * ```
+     */
+    listTwapOrders(params?: ListTwapOrdersParams): Promise<ListTwapOrdersResponse>;
 }

package/dist/api/trading/api.js

@@ -21,7 +21,7 @@
  * );
  * ```
  */
-import { BatchCreateOrdersSchema, BatchReplaceOrdersSchema, CancelConditionalOrderSchema, CancelOrderSchema, GetPaginatedOrdersSchema, ListConditionalOrdersSchema, PlaceLimitOrderSchema, PlaceMarketOrderSchema, ReplaceOrderSchema, validate, } from "@0xmonaco/types";
+import { BatchCreateOrdersSchema, BatchReplaceOrdersSchema, CancelConditionalOrderSchema, CancelOrderSchema, CancelTwapOrderSchema, CreateTwapOrderSchema, GetPaginatedOrdersSchema, ListConditionalOrdersSchema, ListTwapOrdersSchema, PlaceLimitOrderSchema, PlaceMarketOrderSchema, ReplaceOrderSchema, validate, } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 import { perpRoutes } from "../perp";
 function parentTpSlLegToRequest(leg) {
@@ -212,20 +212,30 @@ export class TradingAPIImpl extends BaseAPI {
      * Canceled orders cannot be recovered.
      *
      * @param orderId - The ID of the order to cancel
+     * @param options - Optional partial-cancel: `remainingQuantityTarget` reduces
+     *   the resting order in place to that 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 current remaining
+     *   quantity. Omit for a full cancel.
      * @returns Promise resolving to CancelOrderResponse with cancellation details
      * @throws {APIError} When API communication fails
      *
      * @example
      * ```typescript
      * const result = await tradingAPI.cancelOrder("order_123");
-     * console.log(`Order canceled: ${result.status}`);
+     * // Partial: keep 0.5 resting at the same queue position
+     * await tradingAPI.cancelOrder("order_123", { remainingQuantityTarget: "0.5" });
      * ```
      */
-    async cancelOrder(orderId) {
+    async cancelOrder(orderId, options) {
         // Validate inputs before making API call
-        validate(CancelOrderSchema, { orderId });
+        validate(CancelOrderSchema, { orderId, remainingQuantityTarget: options?.remainingQuantityTarget });
         const requestBody = {
             orderId: orderId,
+            ...(options?.remainingQuantityTarget !== undefined && {
+                remainingQuantityTarget: options.remainingQuantityTarget,
+            }),
         };
         return await this.makeAuthenticatedRequest(perpRoutes.orders.cancel(), {
             method: "POST",
@@ -573,4 +583,166 @@ export class TradingAPIImpl extends BaseAPI {
         const order = await this.makeAuthenticatedRequest(perpRoutes.orders.get(orderId), { method: "GET" });
         return { order, status: "SUCCESS" };
     }
+    /**
+     * Creates a server-side TWAP (time-weighted average price) parent order.
+     *
+     * The matching engine executes the parent as a schedule of MARKET child
+     * orders across the window, with seeded size (±30%) and timing (±30%)
+     * randomization when `randomize` is enabled (the default). Execution stops
+     * hard at the window end — any unfilled remainder is reported as shortfall,
+     * never traded past the end.
+     *
+     * @param tradingPairId - The trading pair UUID
+     * @param side - The order side ("BUY" or "SELL")
+     * @param quantity - Total quantity to execute across the window as string
+     *   (must be at least 2x the pair's minimum order size so it can be sliced)
+     * @param options - Window and execution parameters
+     * @param options.durationSeconds - Window length in seconds from launch;
+     *   exactly one of `durationSeconds` or `endTime` must be set
+     * @param options.endTime - Window end (ISO 8601); exactly one of
+     *   `durationSeconds` or `endTime` must be set
+     * @param options.startTime - Window start (ISO 8601); only valid together
+     *   with `endTime`, defaults to now
+     * @param options.limitPrice - Optional parent-level limit price; BUY child
+     *   orders never execute above it, SELL children never below it
+     * @param options.slippageToleranceBps - Per-slice protective price band in
+     *   basis points (default 100 = 1%)
+     * @param options.clientTwapId - Idempotency key (max 36 chars), unique per
+     *   user and application; a duplicate is rejected with 409
+     * @returns Promise resolving to CreateTwapOrderResponse with the parent id,
+     *   initial state, and the planned schedule summary
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * // Buy 10 units spread across one hour
+     * const twap = await tradingAPI.createTwapOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "10",
+     *   { durationSeconds: 3600 }
+     * );
+     *
+     * // Margin TWAP with an explicit window and a parent limit price
+     * const marginTwap = await tradingAPI.createTwapOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "SELL",
+     *   "5",
+     *   {
+     *     startTime: "2026-08-01T10:00:00Z",
+     *     endTime: "2026-08-01T11:00:00Z",
+     *     limitPrice: "35000.00",
+     *     tradingMode: "MARGIN",
+     *     leverage: "5",
+     *   }
+     * );
+     * ```
+     */
+    async createTwapOrder(tradingPairId, side, quantity, options) {
+        // Validate inputs before making API call
+        validate(CreateTwapOrderSchema, {
+            tradingPairId,
+            side,
+            quantity,
+            options,
+        });
+        const requestBody = {
+            tradingPairId: tradingPairId,
+            side,
+            quantity,
+            // The server deserializes durationSeconds into an int64 with plain
+            // serde, which rejects strings — send a JSON number (durations are
+            // bounded at 30 days = 2,592,000, far inside the safe-integer range).
+            durationSeconds: options.durationSeconds !== undefined ? Number(options.durationSeconds) : undefined,
+            startTime: options.startTime,
+            endTime: options.endTime,
+            limitPrice: options.limitPrice,
+            slippageToleranceBps: options.slippageToleranceBps,
+            randomize: options.randomize,
+            reduceOnly: options.reduceOnly,
+            tradingMode: options.tradingMode || "SPOT",
+            marginAccountId: options.marginAccountId,
+            riskBucketId: options.riskBucketId,
+            marginMode: options.marginMode,
+            leverage: options.leverage,
+            strategyKey: options.strategyKey,
+            useMasterBalance: options.useMasterBalance,
+            clientTwapId: options.clientTwapId,
+        };
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.createTwap(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    /**
+     * Cancels a TWAP parent order.
+     *
+     * Child orders are IOC and never rest, so the cancel is atomic and
+     * immediate; executed quantity stands.
+     *
+     * @param twapOrderId - The TWAP parent order UUID to cancel
+     * @returns Promise resolving to CancelTwapOrderResponse with cancellation details
+     * @throws {APIError} When API communication fails or the parent is already terminal
+     *
+     * @example
+     * ```typescript
+     * const result = await tradingAPI.cancelTwapOrder("123e4567-e89b-12d3-a456-426614174000");
+     * console.log(`TWAP cancelled: ${result.status}`);
+     * ```
+     */
+    async cancelTwapOrder(twapOrderId) {
+        // Validate inputs before making API call
+        validate(CancelTwapOrderSchema, { twapOrderId });
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.cancelTwap(twapOrderId), {
+            method: "POST",
+        });
+    }
+    /**
+     * Gets a single TWAP parent order by its UUID.
+     *
+     * Users can only access their own TWAP orders. The read model carries the
+     * live execution progress (executed quantity/notional, VWAP, slice
+     * counters) alongside the immutable schedule configuration.
+     *
+     * @param twapOrderId - The TWAP parent order UUID to retrieve
+     * @returns Promise resolving to the TwapOrder read model
+     * @throws {APIError} When API communication fails or the order is not found
+     *
+     * @example
+     * ```typescript
+     * const twap = await tradingAPI.getTwapOrder("123e4567-e89b-12d3-a456-426614174000");
+     * console.log(`State: ${twap.state}, progress: ${twap.progress}`);
+     * ```
+     */
+    async getTwapOrder(twapOrderId) {
+        validate(CancelTwapOrderSchema, { twapOrderId });
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.getTwap(twapOrderId), {
+            method: "GET",
+        });
+    }
+    /**
+     * Lists TWAP parent orders for the authenticated user.
+     *
+     * @param params - Optional pagination and state / trading-pair filters
+     * @returns Promise resolving to ListTwapOrdersResponse with orders and pagination info
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * const active = await tradingAPI.listTwapOrders({ state: "ACTIVE", pageSize: 50 });
+     * console.log(`Found ${active.total} active TWAP orders`);
+     * ```
+     */
+    async listTwapOrders(params) {
+        if (params) {
+            validate(ListTwapOrdersSchema, params);
+        }
+        const { page = 1, pageSize = 20, state, tradingPairId } = params || {};
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.listTwap({
+            page,
+            pageSize: Math.min(Math.max(pageSize, 1), 100),
+            state,
+            tradingPairId,
+        }), { method: "GET" });
+    }
 }

package/dist/api/vault/api.d.ts

@@ -78,10 +78,17 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      */
     private getClientId;
     /**
-     * Resolves an asset ID to its token address and determines if it's a native token.
+     * Resolves an asset ID to its token address and determines whether it is the
+     * chain's wrapped-native asset (e.g. WSEI).
+     *
+     * The wrapped-native asset is a real ERC20 — its token address is never the
+     * zero address — so native handling keys on the balance response's
+     * `wrappedNative` flag, not on the address. Deposits of that asset are made
+     * in native coin via the payable `depositNative` (the vault wraps on entry);
+     * withdrawals of it pay out native coin (the vault unwraps).
      *
      * @param assetId - The asset identifier (UUID) to resolve
-     * @returns Promise resolving to object with tokenAddress and isNativeToken flag
+     * @returns Promise resolving to object with tokenAddress and isWrappedNative flag
      * @throws {ContractError} When asset ID cannot be resolved
      * @private
      */
@@ -128,7 +135,12 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * first checks if sufficient approval exists, then obtains a signature from the
      * API Gateway, and finally executes the deposit transaction on-chain.
      *
-     * Note: This method requires prior approval via the `approve()` method.
+     * Note: This method requires prior approval via the `approve()` method for
+     * standard ERC20 assets. The wrapped-native asset (e.g. WSEI, flagged
+     * `wrappedNative` in the balances API) is deposited in native coin via the
+     * payable `depositNative` — the vault wraps it into the ERC20 on entry — so
+     * no approval is needed and `amount` is sent as msg.value. Withdrawals of the
+     * wrapped-native asset pay out native coin (the vault unwraps).
      *
      * @param assetId - The asset identifier (UUID) to deposit
      * @param amount - The amount of tokens to deposit (as bigint)
@@ -209,6 +221,10 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * the index would strand the funds; the caller keeps it and finishes the
      * withdrawal later with `retryWithdrawal(withdrawalIndex)`.
      *
+     * Withdrawals of the wrapped-native asset (e.g. WSEI) pay out native coin —
+     * the vault unwraps on exit. This is decided server-side; no request change
+     * is needed.
+     *
      * @param assetId - The asset identifier (UUID) to withdraw
      * @param amount - The raw token amount to withdraw (as bigint)
      * @param autoWait - When `true` (default) polls for the merkle-proof calldata
@@ -309,6 +325,11 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * Compares the current allowance with the requested amount to determine if
      * the user needs to approve more tokens before performing operations.
      *
+     * The wrapped-native asset (e.g. WSEI) never needs approval: its deposits
+     * are made in native coin via the payable `depositNative` (the vault wraps
+     * on entry), so no ERC20 allowance is consumed and this method returns
+     * `false` without reading the chain.
+     *
      * @param assetId - The asset identifier (UUID) to check for
      * @param amount - The amount to check approval for (as bigint)
      * @returns Promise resolving to true if approval is needed, false otherwise

package/dist/api/vault/api.js

@@ -25,7 +25,7 @@
  */
 import { CONTRACT_ABIS } from "@0xmonaco/contracts";
 import { ApproveTokenSchema, DepositSchema, validate, WithdrawSchema } from "@0xmonaco/types";
-import { erc20Abi, zeroAddress } from "viem";
+import { erc20Abi } from "viem";
 import { APIError, ContractError, InvalidConfigError } from "../../errors";
 import { BaseAPI } from "../base";
 /** Default delay between polls while waiting for a withdrawal's proof. */
@@ -108,18 +108,27 @@ export class VaultAPIImpl extends BaseAPI {
         return config.clientId;
     }
     /**
-     * Resolves an asset ID to its token address and determines if it's a native token.
+     * Resolves an asset ID to its token address and determines whether it is the
+     * chain's wrapped-native asset (e.g. WSEI).
+     *
+     * The wrapped-native asset is a real ERC20 — its token address is never the
+     * zero address — so native handling keys on the balance response's
+     * `wrappedNative` flag, not on the address. Deposits of that asset are made
+     * in native coin via the payable `depositNative` (the vault wraps on entry);
+     * withdrawals of it pay out native coin (the vault unwraps).
      *
      * @param assetId - The asset identifier (UUID) to resolve
-     * @returns Promise resolving to object with tokenAddress and isNativeToken flag
+     * @returns Promise resolving to object with tokenAddress and isWrappedNative flag
      * @throws {ContractError} When asset ID cannot be resolved
      * @private
      */
     async resolveAsset(assetId) {
         let tokenAddress;
+        let isWrappedNative;
         try {
             const assetBalance = await this.profileAPI.getUserBalanceByAssetId(assetId);
             tokenAddress = assetBalance.token;
+            isWrappedNative = assetBalance.wrappedNative === true;
         }
         catch (error) {
             // Differentiate between network errors and asset not found
@@ -142,8 +151,7 @@ export class VaultAPIImpl extends BaseAPI {
                 cause: error instanceof Error ? error : undefined,
             });
         }
-        const isNativeToken = tokenAddress === zeroAddress;
-        return { tokenAddress, isNativeToken };
+        return { tokenAddress, isWrappedNative };
     }
     /**
      * Approves the vault contract to spend tokens on behalf of the user.
@@ -216,7 +224,12 @@ export class VaultAPIImpl extends BaseAPI {
      * first checks if sufficient approval exists, then obtains a signature from the
      * API Gateway, and finally executes the deposit transaction on-chain.
      *
-     * Note: This method requires prior approval via the `approve()` method.
+     * Note: This method requires prior approval via the `approve()` method for
+     * standard ERC20 assets. The wrapped-native asset (e.g. WSEI, flagged
+     * `wrappedNative` in the balances API) is deposited in native coin via the
+     * payable `depositNative` — the vault wraps it into the ERC20 on entry — so
+     * no approval is needed and `amount` is sent as msg.value. Withdrawals of the
+     * wrapped-native asset pay out native coin (the vault unwraps).
      *
      * @param assetId - The asset identifier (UUID) to deposit
      * @param amount - The amount of tokens to deposit (as bigint)
@@ -269,8 +282,8 @@ export class VaultAPIImpl extends BaseAPI {
         // The on-chain applicationData carries the client id plus, for margin
         // deposits, the routing hint the indexer decodes.
         const applicationData = encodeDepositApplicationData(clientId, target);
-        const { tokenAddress, isNativeToken } = await this.resolveAsset(assetId);
-        if (!isNativeToken) {
+        const { tokenAddress, isWrappedNative } = await this.resolveAsset(assetId);
+        if (!isWrappedNative) {
             // Check if approval is needed before proceeding
             const needsApproval = await this.needsApproval(assetId, amount);
             if (needsApproval) {
@@ -283,9 +296,11 @@ export class VaultAPIImpl extends BaseAPI {
         if (!walletAccount) {
             throw new InvalidConfigError("No account available in wallet client", "account");
         }
-        // For native SEI (zero address), use depositNative (payable); for ERC20 tokens, use depositERC20
+        // For the wrapped-native asset (e.g. WSEI), use depositNative (payable) — the
+        // vault wraps the native coin into the ERC20 on entry, so no allowance is
+        // involved. All other ERC20 tokens go through approve + depositERC20.
         let hash;
-        if (isNativeToken) {
+        if (isWrappedNative) {
             hash = await this.walletClient.writeContract({
                 address: vaultAddress,
                 abi: CONTRACT_ABIS.vault,
@@ -380,6 +395,10 @@ export class VaultAPIImpl extends BaseAPI {
      * the index would strand the funds; the caller keeps it and finishes the
      * withdrawal later with `retryWithdrawal(withdrawalIndex)`.
      *
+     * Withdrawals of the wrapped-native asset (e.g. WSEI) pay out native coin —
+     * the vault unwraps on exit. This is decided server-side; no request change
+     * is needed.
+     *
      * @param assetId - The asset identifier (UUID) to withdraw
      * @param amount - The raw token amount to withdraw (as bigint)
      * @param autoWait - When `true` (default) polls for the merkle-proof calldata
@@ -597,6 +616,11 @@ export class VaultAPIImpl extends BaseAPI {
      * Compares the current allowance with the requested amount to determine if
      * the user needs to approve more tokens before performing operations.
      *
+     * The wrapped-native asset (e.g. WSEI) never needs approval: its deposits
+     * are made in native coin via the payable `depositNative` (the vault wraps
+     * on entry), so no ERC20 allowance is consumed and this method returns
+     * `false` without reading the chain.
+     *
      * @param assetId - The asset identifier (UUID) to check for
      * @param amount - The amount to check approval for (as bigint)
      * @returns Promise resolving to true if approval is needed, false otherwise
@@ -616,6 +640,12 @@ export class VaultAPIImpl extends BaseAPI {
      * ```
      */
     async needsApproval(assetId, amount) {
+        const { isWrappedNative } = await this.resolveAsset(assetId);
+        if (isWrappedNative) {
+            // Wrapped-native deposits route to the payable depositNative — no ERC20
+            // allowance is consumed, so approval is never needed.
+            return false;
+        }
         const allowance = await this.getAllowance(assetId);
         return allowance < amount;
     }

package/dist/api/websocket/types.d.ts

@@ -1,4 +1,4 @@
-import type { AccountEvent, ConditionalOrderEvent, Interval, LiquidationEvent, MarketStatsAllEvent, MarketStatsEvent, MonacoWebSocketConfig, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, PositionEvent, SessionCredentials, TradeEvent, TradingMode, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
+import type { AccountEvent, ConditionalOrderEvent, Interval, LiquidationEvent, MarketStatsAllEvent, MarketStatsEvent, MonacoWebSocketConfig, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderbookQuotationMode, OrderEvent, PositionEvent, SessionCredentials, TradeEvent, TradingMode, TwapOrderEvent, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
 export type { ResyncHandler, StatusHandler, WebSocketResyncInfo } from "@0xmonaco/types";
 export type MessageHandler<T> = (data: T) => void;
 /**
@@ -27,7 +27,7 @@ export interface MonacoWebSocket {
     /** Subscribe to orderbook events (public) */
     orderbook: (tradingPairId: string, tradingMode: TradingMode, magnitude: number, quotationMode: OrderbookQuotationMode, handler: MessageHandler<OrderbookEvent>) => () => void;
     /** Subscribe to OHLCV candlestick events (public) */
-    ohlcv: (tradingPairId: string, tradingMode: TradingMode, interval: Interval, handler: MessageHandler<OHLCVEvent>) => () => void;
+    ohlcv: (tradingPairId: string, tradingMode: TradingMode, interval: Interval, handler: MessageHandler<OHLCVEvent>, priceType?: OHLCVPriceType) => () => void;
     /** Subscribe to trade events (public) */
     trades: (tradingPairId: string, handler: MessageHandler<TradeEvent>) => () => void;
     /** Subscribe to user movement events (requires authentication) */
@@ -38,6 +38,8 @@ export interface MonacoWebSocket {
     balances: (handler: MessageHandler<UserBalanceEvent>) => () => void;
     /** Subscribe to conditional TP/SL lifecycle events (requires authentication) */
     conditionalOrders: (handler: MessageHandler<ConditionalOrderEvent>, tradingPairId?: string) => () => void;
+    /** Subscribe to TWAP parent-order lifecycle events (requires authentication) */
+    twapOrders: (handler: MessageHandler<TwapOrderEvent>, tradingPairId?: string) => () => void;
     /** Subscribe to position state updates (requires authentication); omit `tradingPairId` for all pairs */
     positions: (handler: MessageHandler<PositionEvent>, tradingPairId?: string) => () => void;
     /** Subscribe to liquidation alerts (requires authentication); omit `tradingPairId` for all pairs */

package/dist/api/websocket/websocket.js

@@ -12,6 +12,7 @@ const CONDITIONAL_ORDER_CONDITION_TYPES = ["STOP_LOSS", "TAKE_PROFIT"];
 const CONDITIONAL_ORDER_TRIGGER_SOURCES = ["MARK_PRICE"];
 const CONDITIONAL_ORDER_STATES = ["PENDING_PARENT", "ACTIVE", "TRIGGERING", "TRIGGERED", "CANCELLED", "EXPIRED", "FAILED"];
 const CONDITIONAL_ORDER_ASSOCIATION_TYPES = ["POSITION", "PARENT_ORDER"];
+const TWAP_ORDER_STATES = ["PENDING", "ACTIVE", "COMPLETED", "CANCELLED"];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -268,6 +269,49 @@ function parseMarketStatsAllEvent(rawData) {
         markets: rawData.markets.map(parseMarketStatsSummary),
     };
 }
+/**
+ * Parse a `twap_orders` channel frame into a typed event. Only the envelope
+ * and the snapshot's identity/state fields are validated strictly — the rest
+ * of the TwapOrder snapshot is passed through camelCased, so additive server
+ * fields never break older clients. The server serializes absent optional
+ * fields as explicit `null`; those are dropped so the parsed snapshot matches
+ * the optional (`?:`) fields of `TwapOrderEventData`.
+ */
+function parseTwapOrderEvent(rawData) {
+    if (!isRecord(rawData)) {
+        throw new Error("Invalid TWAP order event: payload must be an object");
+    }
+    if (!isRecord(rawData.data)) {
+        throw new Error("Invalid TWAP order event: data must be an object");
+    }
+    const eventType = rawData.event_type;
+    if (eventType !== "twap_order_update") {
+        throw new Error("Invalid TWAP order event: event_type must be twap_order_update");
+    }
+    const userId = rawData.user_id;
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new Error("Invalid TWAP order event: user_id must be a non-empty string");
+    }
+    const data = keysToCamelCase(rawData.data);
+    for (const key of Object.keys(data)) {
+        if (data[key] === null) {
+            delete data[key];
+        }
+    }
+    const twapOrderId = data.twapOrderId;
+    if (typeof twapOrderId !== "string" || twapOrderId.length === 0) {
+        throw new Error("Invalid TWAP order event: twapOrderId must be a non-empty string");
+    }
+    const state = data.state;
+    if (typeof state !== "string" || !TWAP_ORDER_STATES.includes(state)) {
+        throw new Error(`Invalid TWAP order event: state must be one of ${TWAP_ORDER_STATES.join(", ")}`);
+    }
+    return {
+        eventType: "twap_order_update",
+        userId,
+        data: data,
+    };
+}
 /**
  * Create a Monaco WebSocket client
  */
@@ -392,12 +436,35 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             send({ type: "Subscribe", channels });
         }
     };
+    // A subscription channel matches a frame when it is identical, is a prefix of
+    // the frame's dotted-by-colon path, or ends in a `:*` wildcard segment whose
+    // prefix the frame shares. The wildcard case exists because a `*` price-series
+    // subscription (`ohlcv:...:interval:*`) must receive the concrete series
+    // frames the server publishes (`ohlcv:...:interval:trade` / `:mark`), which are
+    // neither equal to nor prefixed by the literal `:*` channel.
+    // A legacy four-token OHLCV subscription (`ohlcv:pair:mode:interval`, no price
+    // series) is trade-only by contract. The server suffixes every OHLCV frame
+    // with a series, so it must match the bare four-token frame or the explicit
+    // `:trade` frame — never `:mark` — otherwise a connection that also holds a
+    // mark or wildcard subscription for the same pair would leak mark frames into
+    // the legacy handler via the generic prefix match.
+    const isLegacyOhlcvKey = (channel) => channel.startsWith("ohlcv:") && channel.split(":").length === 4;
+    const channelMatches = (subscriptionChannel, frameChannel) => {
+        if (subscriptionChannel.endsWith(":*")) {
+            // Keep the trailing colon so only frames with a further segment match.
+            return frameChannel.startsWith(subscriptionChannel.slice(0, -1));
+        }
+        if (isLegacyOhlcvKey(subscriptionChannel)) {
+            return frameChannel === subscriptionChannel || frameChannel === `${subscriptionChannel}:trade`;
+        }
+        return frameChannel === subscriptionChannel || frameChannel.startsWith(`${subscriptionChannel}:`);
+    };
     const routeMessage = (msg) => {
         if (msg.type !== "Event" || !msg.channel)
             return;
         // Find matching handlers and call all of them
         for (const [subscriptionChannel, channelHandlers] of handlers) {
-            if (msg.channel === subscriptionChannel || msg.channel.startsWith(`${subscriptionChannel}:`)) {
+            if (channelMatches(subscriptionChannel, msg.channel)) {
                 for (const handler of channelHandlers) {
                     handler(msg.data);
                 }
@@ -619,18 +686,26 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             }
         });
     };
-    const subscribeOHLCV = (tradingPairId, tradingMode, interval, handler) => {
-        const channel = `ohlcv:${tradingPairId}:${tradingMode}:${interval}`;
+    const subscribeOHLCV = (tradingPairId, tradingMode, interval, handler, priceType) => {
+        // Four-token channel selects the trade-derived candles (back-compat); the
+        // optional fifth token selects the price series (`mark` = close-only mark
+        // series, `*` = both).
+        const channel = priceType === undefined ? `ohlcv:${tradingPairId}:${tradingMode}:${interval}` : `ohlcv:${tradingPairId}:${tradingMode}:${interval}:${priceType}`;
         return subscribe(channel, (rawData) => {
             try {
                 const data = rawData;
                 const ohlcvData = data.data;
+                // Concrete price series of this candle (`trade`/`mark`). Present on
+                // every current frame; a wildcard (`*`) subscriber reads it to tell the
+                // two streams apart. Omitted when a legacy frame carries no `price_type`.
+                const priceType = data.price_type === "trade" || data.price_type === "mark" ? data.price_type : undefined;
                 const event = {
                     // `trading_pair_id` is the pair UUID; `symbol` is the display string.
                     // `tradingPairId` must carry the UUID (the symbol lives in `candlestick.s`).
                     tradingPairId: data.trading_pair_id,
                     tradingMode: data.trading_mode,
                     interval: data.interval,
+                    priceType,
                     candlestick: {
                         T: ohlcvData.period_start || 0,
                         t: ohlcvData.period_end || 0,
@@ -791,6 +866,23 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             }
         });
     };
+    const subscribeTwapOrders = (handler, tradingPairId) => {
+        if (!handler) {
+            throw new Error("twapOrders subscription requires a handler");
+        }
+        if (tradingPairId !== undefined && tradingPairId.length === 0) {
+            throw new Error("twapOrders tradingPairId cannot be empty");
+        }
+        const channel = tradingPairId ? `twap_orders:${tradingPairId}` : "twap_orders";
+        return subscribe(channel, (rawData) => {
+            try {
+                handler(parseTwapOrderEvent(rawData));
+            }
+            catch (err) {
+                console.error("WebSocket: Error processing TWAP order event", err);
+            }
+        });
+    };
     /**
      * Subscribe to authenticated user's position updates.
      * Requires authentication - user is identified from the signed session-key
@@ -933,6 +1025,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         userOrders: subscribeUserOrders,
         balances: subscribeBalances,
         conditionalOrders: subscribeConditionalOrders,
+        twapOrders: subscribeTwapOrders,
         positions: subscribePositions,
         liquidations: subscribeLiquidations,
         account: subscribeAccount,

package/dist/coverage.d.ts

@@ -10,6 +10,10 @@ export declare const COVERED: {
     cancel_conditional_order: string;
     get_conditional_order: string;
     cancel_order: string;
+    cancel_twap_order: string;
+    create_twap_order: string;
+    get_twap_order: string;
+    list_twap_orders: string;
     close_position: string;
     create_challenge: string;
     create_delegated_session: string;

package/dist/coverage.js

@@ -10,6 +10,10 @@ export const COVERED = {
     cancel_conditional_order: "cancelConditionalOrder",
     get_conditional_order: "getConditionalOrder",
     cancel_order: "cancelOrder",
+    cancel_twap_order: "cancelTwapOrder",
+    create_twap_order: "createTwapOrder",
+    get_twap_order: "getTwapOrder",
+    list_twap_orders: "listTwapOrders",
     close_position: "closePosition",
     create_challenge: "createChallenge",
     create_delegated_session: "createDelegatedSession",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.42",
+	"version": "1.0.43",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -23,8 +23,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.42",
-		"@0xmonaco/types": "1.0.42",
+		"@0xmonaco/contracts": "1.0.43",
+		"@0xmonaco/types": "1.0.43",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"