@0xmonaco/core 0.7.7 → 0.7.8

package/dist/api/trading/api.js

@@ -0,0 +1,481 @@
+/**
+ * Trading API Implementation
+ *
+ * Handles trading operations including order placement and management.
+ * All operations use JWT authentication and go through the API Gateway.
+ *
+ * This class provides a complete interface for trading operations on the Monaco protocol,
+ * including various order types, order management, and position operations.
+ *
+ * @example
+ * ```typescript
+ * const tradingAPI = new TradingAPIImpl(apiUrl);
+ * tradingAPI.setAccessToken(jwtToken);
+ *
+ * // Place a limit order
+ * const order = await tradingAPI.placeLimitOrder(
+ *   "123e4567-e89b-12d3-a456-426614174000", // trading pair UUID
+ *   "BUY",
+ *   "1.5",
+ *   "2000.50"
+ * );
+ * ```
+ */
+import { BatchCreateOrdersSchema, BatchReplaceOrdersSchema, CancelConditionalOrderSchema, CancelOrderSchema, CreateConditionalOrderSchema, GetPaginatedOrdersSchema, ListConditionalOrdersSchema, PlaceLimitOrderSchema, PlaceMarketOrderSchema, ReplaceOrderSchema, validate, } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+import { perpRoutes } from "../perp";
+export class TradingAPIImpl extends BaseAPI {
+    /**
+     * Places a limit order on the order book.
+     *
+     * Limit orders are executed only when the market price reaches or improves upon
+     * the specified price. They provide price protection but may not execute immediately.
+     *
+     * @param tradingPairId - The trading pair UUID
+     * @param side - The order side ("BUY" or "SELL")
+     * @param quantity - The order quantity as string
+     * @param price - The limit price as string
+     * @param options - Optional parameters for the limit order
+     * @param options.tradingMode - Trading mode (e.g., "SPOT")
+     * @param options.useMasterBalance - Whether to use master balance for sub-accounts
+     * @param options.expirationDate - Optional expiration date for GTC orders (ISO 8601 format)
+     * @param options.timeInForce - Time in force ("GTC", "IOC", or "FOK")
+     * @returns Promise resolving to CreateOrderResponse with order details
+     *
+     * @example
+     * ```typescript
+     * // Regular limit order
+     * const order = await tradingAPI.placeLimitOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "0.5",
+     *   "35000.00",
+     *   { tradingMode: "SPOT" }
+     * );
+     *
+     * // GTC order with custom expiration
+     * const gtcOrder = await tradingAPI.placeLimitOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "0.5",
+     *   "35000.00",
+     *   {
+     *     tradingMode: "SPOT",
+     *     expirationDate: "2024-12-31T23:59:59Z" // GTC until this date
+     *   }
+     * );
+     *
+     * // IOC order (execute immediately or cancel)
+     * const iocOrder = await tradingAPI.placeLimitOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "0.5",
+     *   "35000.00",
+     *   { timeInForce: "IOC" }
+     * );
+     * ```
+     */
+    async placeLimitOrder(tradingPairId, side, quantity, price, options) {
+        // Validate inputs before making API call
+        validate(PlaceLimitOrderSchema, {
+            tradingPairId,
+            side,
+            quantity,
+            price,
+            options,
+        });
+        const requestBody = {
+            trading_pair_id: tradingPairId,
+            order_type: "LIMIT",
+            side,
+            price,
+            quantity,
+            trading_mode: options?.tradingMode || "SPOT",
+            use_master_balance: options?.useMasterBalance,
+            expiration_date: options?.expirationDate,
+            time_in_force: options?.timeInForce,
+            margin_account_id: options?.marginAccountId,
+            position_side: options?.positionSide,
+            leverage: options?.leverage,
+            reduce_only: options?.reduceOnly,
+        };
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.create(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    /**
+     * Places a market order for immediate execution.
+     *
+     * Market orders execute immediately at the current market price. They provide
+     * immediate execution but may experience slippage.
+     *
+     * @param tradingPairId - The trading pair UUID
+     * @param side - The order side ("BUY" or "SELL")
+     * @param quantity - The order quantity as string
+     * @param options - Optional parameters for the market order
+     * @param options.tradingMode - Trading mode (e.g., "SPOT")
+     * @param options.slippageTolerance - Slippage tolerance as decimal (e.g., 0.01 for 1%, 0 for best price only, undefined for unlimited slippage)
+     * @returns Promise resolving to CreateOrderResponse with order details
+     *
+     * @example
+     * ```typescript
+     * // Market order with 1% slippage tolerance
+     * const order1 = await tradingAPI.placeMarketOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "SELL",
+     *   "0.5",
+     *   { tradingMode: "SPOT", slippageTolerance: 0.01 } // 1% slippage
+     * );
+     *
+     * // Market order with zero slippage (only execute at best price)
+     * const order2 = await tradingAPI.placeMarketOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "1.0",
+     *   { slippageTolerance: 0 } // Only execute at best ask price
+     * );
+     *
+     * // Market order with unlimited slippage
+     * const order3 = await tradingAPI.placeMarketOrder(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   "BUY",
+     *   "1.0"
+     *   // No slippageTolerance specified = unlimited slippage
+     * );
+     * ```
+     */
+    async placeMarketOrder(tradingPairId, side, quantity, options) {
+        // Validate inputs before making API call
+        validate(PlaceMarketOrderSchema, {
+            tradingPairId,
+            side,
+            quantity,
+            options,
+        });
+        const requestBody = {
+            trading_pair_id: tradingPairId,
+            order_type: "MARKET",
+            side,
+            slippage_tolerance_bps: options?.slippageTolerance !== undefined ? Math.round(options.slippageTolerance * 10000) : undefined,
+            price: null, // Market orders don't need price
+            quantity,
+            trading_mode: options?.tradingMode || "SPOT",
+            margin_account_id: options?.marginAccountId,
+            position_side: options?.positionSide,
+            leverage: options?.leverage,
+            reduce_only: options?.reduceOnly,
+        };
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.create(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    /**
+     * Cancels an existing order.
+     *
+     * Cancels an open order by its ID. The order must be in an open state to be canceled.
+     * Canceled orders cannot be recovered.
+     *
+     * @param orderId - The ID of the order to 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}`);
+     * ```
+     */
+    async cancelOrder(orderId) {
+        // Validate inputs before making API call
+        validate(CancelOrderSchema, { orderId });
+        const requestBody = {
+            order_id: orderId,
+        };
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.cancel(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    async createConditionalOrder(params) {
+        validate(CreateConditionalOrderSchema, params);
+        const requestBody = {
+            trading_pair_id: params.tradingPairId,
+            margin_account_id: params.marginAccountId,
+            condition_type: params.conditionType,
+            trigger_price: params.triggerPrice,
+            trigger_source: params.triggerSource ?? "MARK_PRICE",
+            side: params.side,
+            position_side: params.positionSide,
+            order_type: params.orderType,
+            limit_price: params.limitPrice,
+            quantity: params.quantity,
+            reduce_only: params.reduceOnly ?? true,
+            time_in_force: params.timeInForce,
+            slippage_tolerance_bps: params.slippageToleranceBps,
+            expires_at: params.expiresAt,
+        };
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.createConditional(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    async cancelConditionalOrder(conditionalOrderId) {
+        validate(CancelConditionalOrderSchema, { conditionalOrderId });
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.cancelConditional(conditionalOrderId), {
+            method: "DELETE",
+        });
+    }
+    async listConditionalOrders(params) {
+        if (params) {
+            validate(ListConditionalOrdersSchema, params);
+        }
+        const { page = 1, page_size = 20, margin_account_id, trading_pair_id, state } = params || {};
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.listConditional({
+            page,
+            page_size: Math.min(Math.max(page_size, 1), 100),
+            margin_account_id,
+            trading_pair_id,
+            state,
+        }), { method: "GET" });
+    }
+    /**
+     * Batch cancels specific orders by their IDs.
+     *
+     * @param orderIds - Array of order IDs to cancel
+     * @returns Promise resolving to BatchCancelOrdersResponse with cancellation details
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * const result = await tradingAPI.batchCancel(["order_123", "order_456"]);
+     * ```
+     */
+    async batchCancel(orderIds) {
+        if (!orderIds || orderIds.length === 0) {
+            throw new Error("orderIds is required and must not be empty");
+        }
+        return this.makeAuthenticatedRequest(perpRoutes.orders.batchCancel(), {
+            method: "POST",
+            body: JSON.stringify({ order_ids: orderIds }),
+        });
+    }
+    /**
+     * Cancels all active orders, optionally filtered by trading pair.
+     *
+     * @param tradingPairId - Optional trading pair ID to filter cancellation
+     * @returns Promise resolving to BatchCancelOrdersResponse with cancellation details
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * // Cancel all active orders globally
+     * await tradingAPI.batchCancelAll();
+     *
+     * // Cancel all orders for a specific trading pair
+     * await tradingAPI.batchCancelAll("123e4567-e89b-12d3-a456-426614174000");
+     * ```
+     */
+    async batchCancelAll(tradingPairId) {
+        const endpoint = tradingPairId ? perpRoutes.orders.batchCancelAllByPair(tradingPairId) : perpRoutes.orders.batchCancelAll();
+        return this.makeAuthenticatedRequest(endpoint, {
+            method: "POST",
+        });
+    }
+    async replaceOrder(orderId, newOrder) {
+        // Validate inputs before making API call
+        validate(ReplaceOrderSchema, { orderId, newOrder });
+        const requestBody = {
+            use_master_balance: newOrder.useMasterBalance ?? false,
+        };
+        if (newOrder.price !== undefined) {
+            requestBody.price = newOrder.price;
+        }
+        if (newOrder.quantity !== undefined) {
+            requestBody.quantity = newOrder.quantity;
+        }
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.replace(orderId), {
+            method: "PUT",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    /**
+     * Batch creates multiple orders in a single request.
+     *
+     * Each order is validated and processed through the matching engine.
+     * Failed orders do not prevent other orders from being created.
+     *
+     * @param orders - Array of order parameters to create
+     * @returns Promise resolving to BatchCreateOrdersResponse with individual results
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * const result = await tradingAPI.batchCreate([
+     *   {
+     *     tradingPairId: "123e4567-e89b-12d3-a456-426614174000",
+     *     orderType: "LIMIT",
+     *     side: "BUY",
+     *     price: "35000.00",
+     *     quantity: "0.5",
+     *   },
+     *   {
+     *     tradingPairId: "123e4567-e89b-12d3-a456-426614174000",
+     *     orderType: "LIMIT",
+     *     side: "SELL",
+     *     price: "36000.00",
+     *     quantity: "0.3",
+     *   },
+     * ]);
+     * ```
+     */
+    async batchCreate(orders) {
+        validate(BatchCreateOrdersSchema, { orders });
+        const requestBody = {
+            orders: orders.map((order) => ({
+                trading_pair_id: order.tradingPairId,
+                order_type: order.orderType,
+                side: order.side,
+                price: order.price,
+                quantity: order.quantity,
+                trading_mode: order.tradingMode || "SPOT",
+                slippage_tolerance_bps: order.slippageTolerance !== undefined ? Math.round(order.slippageTolerance * 10000) : undefined,
+                use_master_balance: order.useMasterBalance,
+                expiration_date: order.expirationDate,
+                time_in_force: order.timeInForce,
+                margin_account_id: order.marginAccountId,
+                position_side: order.positionSide,
+                leverage: order.leverage,
+                reduce_only: order.reduceOnly,
+            })),
+        };
+        return this.makeAuthenticatedRequest(perpRoutes.orders.batchCreate(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    /**
+     * Batch replaces multiple orders in a single request.
+     *
+     * Each order is canceled and re-created with new parameters.
+     * Failed replacements do not prevent other orders from being replaced.
+     *
+     * @param orders - Array of order replacement parameters
+     * @returns Promise resolving to BatchReplaceOrdersResponse with individual results
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * const result = await tradingAPI.batchReplace([
+     *   {
+     *     orderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+     *     price: "35500.00",
+     *     quantity: "0.7",
+     *   },
+     *   {
+     *     orderId: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+     *     price: "36500.00",
+     *   },
+     * ]);
+     * ```
+     */
+    async batchReplace(orders) {
+        validate(BatchReplaceOrdersSchema, { orders });
+        const requestBody = {
+            orders: orders.map((order) => ({
+                order_id: order.orderId,
+                price: order.price,
+                quantity: order.quantity,
+                use_master_balance: order.useMasterBalance,
+            })),
+        };
+        return this.makeAuthenticatedRequest(perpRoutes.orders.batchReplace(), {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    /**
+     * Gets paginated orders based on query parameters with automatic pagination.
+     *
+     * Retrieves orders with optional filtering by status, trading pair, and pagination.
+     * Pagination parameters are always included with sensible defaults for consistent API behavior.
+     *
+     * @param params - Query parameters for filtering orders
+     * @param params.status - Filter by order status (e.g., "SUBMITTED", "FILLED") (optional)
+     * @param params.trading_pair_id - Filter by trading pair UUID (optional)
+     * @param params.page - Page number for pagination (defaults to 1, must be > 0)
+     * @param params.page_size - Number of orders per page (defaults to 10, max 100, must be > 0)
+     * @returns Promise resolving to GetPaginatedOrdersResponse with orders and pagination info
+     * @throws {APIError} When API communication fails
+     *
+     * @example
+     * ```typescript
+     * // Get submitted orders for a specific trading pair with custom pagination
+     * const orders = await tradingAPI.getPaginatedOrders({
+     *   status: "SUBMITTED",
+     *   trading_pair_id: "456e7890-e12b-12d3-a456-426614174000",
+     *   page: 1,
+     *   page_size: 20
+     * });
+     * console.log(`Found ${orders.total} orders, showing page ${orders.page}`);
+     *
+     * // Get all orders with default pagination (page=1, page_size=10)
+     * const allOrders = await tradingAPI.getPaginatedOrders();
+     * ```
+     */
+    async getPaginatedOrders(params) {
+        // Validate inputs before making API call
+        if (params) {
+            validate(GetPaginatedOrdersSchema, params);
+        }
+        // Set pagination defaults with destructuring and validation
+        const { page = 1, page_size = 10, status, trading_pair_id, trading_mode, margin_account_id } = params || {};
+        const validPage = page > 0 ? page : 1;
+        const validPageSize = page_size > 0 ? page_size : 10;
+        const pageSize = Math.min(validPageSize, 100);
+        const searchParams = new URLSearchParams();
+        // Always include pagination parameters for consistent API behavior
+        searchParams.append("page", validPage.toString());
+        searchParams.append("page_size", pageSize.toString());
+        if (status) {
+            searchParams.append("status", status);
+        }
+        if (trading_pair_id) {
+            searchParams.append("trading_pair_id", trading_pair_id);
+        }
+        if (trading_mode) {
+            searchParams.append("trading_mode", trading_mode);
+        }
+        if (margin_account_id) {
+            searchParams.append("margin_account_id", margin_account_id);
+        }
+        const endpoint = `/api/v1/orders?${searchParams.toString()}`;
+        return await this.makeAuthenticatedRequest(endpoint, {
+            method: "GET",
+        });
+    }
+    /**
+     * Gets a single order by its ID.
+     *
+     * Retrieves detailed information about a specific order using its unique identifier.
+     * This endpoint provides complete order details including status, quantities, and timestamps.
+     *
+     * @param orderId - The unique identifier of the order to retrieve
+     * @returns Promise resolving to GetOrderResponse with order details
+     * @throws {APIError} When API communication fails or order is not found
+     *
+     * @example
+     * ```typescript
+     * // Get order details by ID
+     * const orderDetails = await tradingAPI.getOrder("order_123");
+     * console.log(`Order status: ${orderDetails.order.status}`);
+     * console.log(`Remaining quantity: ${orderDetails.order.remaining_quantity}`);
+     * ```
+     */
+    async getOrder(orderId) {
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.get(orderId), {
+            method: "GET",
+        });
+    }
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Trading API Module
+ */
+export { TradingAPIImpl } from "./api";

package/dist/api/trading/index.js

@@ -0,0 +1,4 @@
+/**
+ * Trading API Module
+ */
+export { TradingAPIImpl } from "./api";