@0xmonaco/core 0.7.7 → 0.7.9

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

@@ -0,0 +1,301 @@
+/**
+ * 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 type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, CreateConditionalOrderParams, CreateConditionalOrderResponse, CreateOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, OrderSide, ParentTpSlLegParams, PositionSide, ReplaceOrderResponse, TimeInForce, TradingAPI, TradingMode } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
+    /**
+     * 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" }
+     * );
+     * ```
+     */
+    placeLimitOrder(tradingPairId: string, side: OrderSide, quantity: string, price: string, options?: {
+        tradingMode?: TradingMode;
+        useMasterBalance?: boolean;
+        expirationDate?: string;
+        timeInForce?: TimeInForce;
+        marginAccountId?: string;
+        positionSide?: PositionSide;
+        leverage?: string;
+        reduceOnly?: boolean;
+        takeProfit?: ParentTpSlLegParams;
+        stopLoss?: ParentTpSlLegParams;
+    }): Promise<CreateOrderResponse>;
+    /**
+     * 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
+     * );
+     * ```
+     */
+    placeMarketOrder(tradingPairId: string, side: OrderSide, quantity: string, options?: {
+        tradingMode?: TradingMode;
+        slippageTolerance?: number;
+        marginAccountId?: string;
+        positionSide?: PositionSide;
+        leverage?: string;
+        reduceOnly?: boolean;
+        takeProfit?: ParentTpSlLegParams;
+        stopLoss?: ParentTpSlLegParams;
+    }): Promise<CreateOrderResponse>;
+    /**
+     * 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}`);
+     * ```
+     */
+    cancelOrder(orderId: string): Promise<CancelOrderResponse>;
+    createConditionalOrder(params: CreateConditionalOrderParams): Promise<CreateConditionalOrderResponse>;
+    cancelConditionalOrder(conditionalOrderId: string): Promise<CancelConditionalOrderResponse>;
+    listConditionalOrders(params?: ListConditionalOrdersParams): Promise<ListConditionalOrdersResponse>;
+    /**
+     * 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"]);
+     * ```
+     */
+    batchCancel(orderIds: string[]): Promise<BatchCancelOrdersResponse>;
+    /**
+     * 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");
+     * ```
+     */
+    batchCancelAll(tradingPairId?: string): Promise<BatchCancelOrdersResponse>;
+    replaceOrder(orderId: string, newOrder: {
+        price?: string;
+        quantity?: string;
+        useMasterBalance?: boolean;
+    }): Promise<ReplaceOrderResponse>;
+    /**
+     * 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",
+     *   },
+     * ]);
+     * ```
+     */
+    batchCreate(orders: BatchCreateOrderParams[]): Promise<BatchCreateOrdersResponse>;
+    /**
+     * 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",
+     *   },
+     * ]);
+     * ```
+     */
+    batchReplace(orders: BatchReplaceOrderParams[]): Promise<BatchReplaceOrdersResponse>;
+    /**
+     * 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();
+     * ```
+     */
+    getPaginatedOrders(params?: GetPaginatedOrdersParams): Promise<GetPaginatedOrdersResponse>;
+    /**
+     * 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}`);
+     * ```
+     */
+    getOrder(orderId: string): Promise<GetOrderResponse>;
+}