> ## Documentation Index > Fetch the complete documentation index at: https://docs.tide.ag/llms.txt > Use this file to discover all available pages before exploring further. # Execute Smart Order > Executes a trade by automatically routing it to the exchange with the best price, or to a preferred exchange if specified. Executes a trade by automatically routing it to the exchange with the best price, or to a preferred exchange if specified. ## Features * **Unified order primitive**: Access market and limit orders through one endpoint * **Routing flexibility**: Auto-route or pin to a preferred exchange per request * **Advanced controls**: Configure reduce-only behaviour and custom quantities * **Rich telemetry**: Responses include routing decisions, pricing, and execution latency ## Use Cases * Power algorithmic trading systems needing granular order flags * Build discretionary trading interfaces that display execution venue rationale * Prototype new strategies without managing venue-specific adapters ## Request * **Method**: `POST` * **Endpoint**: `/api/trade/execute` * **Headers**: * `Content-Type`: `application/json` * `Authorization`: `Bearer ` This endpoint requires authentication. You must provide a valid JWT token in the `Authorization` header. ## Request Fields | Field | Type | Required | Description | | ------------------- | ------- | -------- | --------------------------------------------------------------------------------------- | | `symbol` | string | ✅ | Trading pair symbol (e.g., "BTC", "ETH") | | `side` | string | ✅ | Order side: `BUY` or `SELL` | | `type` | string | ✅ | Order type: `MARKET` or `LIMIT` | | `quantity` | string | ✅ | Amount of base asset to trade | | `price` | string | ❌ | Limit price. Required if `type` is `LIMIT` | | `reduceOnly` | boolean | ❌ | If `true`, the order will only reduce an existing position (default: `false`) | | `preferredExchange` | string | ❌ | Force execution on a specific exchange: `hyperliquid`, `aster`, `lighter`, or `avantis` | ## Example Request ```bash theme={null} curl -X POST https://api.tide.ag/api/trade/execute \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "symbol": "BTC", "side": "BUY", "type": "MARKET", "quantity": "0.1", "reduceOnly": false }' ``` ## Success Response ```json theme={null} { "success": true, "data": { "executedOn": "hyperliquid", "order": { "orderId": "123456789", "symbol": "BTC", "status": "FILLED", "price": 97500.50, "quantity": 0.1, "side": "BUY", "timestamp": 1678900000000 }, "routing": { "recommended": "hyperliquid", "price": 97500.50, "reason": "Best price", "savings": 15.20, "savingsPercent": 0.015, "alternatives": { "hyperliquid": { "price": 97500.50, "available": true }, "aster": { "price": 97515.70, "available": true }, "lighter": { "price": 97520.00, "available": true }, "avantis": { "price": 97510.25, "available": true } } }, "execution": { "timestamp": 1678900000100, "latencyMs": 45 } }, "timestamp": 1678900000100 } ``` ## Response Fields | Field | Type | Description | | ----------------------------- | ------ | ------------------------------------- | | `data.executedOn` | string | Exchange where the order was executed | | `data.order.orderId` | string | Unique order identifier | | `data.order.symbol` | string | Trading pair symbol | | `data.order.status` | string | Order status (e.g., "FILLED") | | `data.order.price` | number | Execution price | | `data.order.quantity` | number | Order quantity | | `data.order.side` | string | Order side ("BUY" or "SELL") | | `data.routing.recommended` | string | Recommended exchange | | `data.routing.price` | number | Best execution price | | `data.routing.reason` | string | Reason for exchange selection | | `data.routing.savings` | number | Estimated savings vs next-best venue | | `data.routing.savingsPercent` | number | Savings as percentage | | `data.routing.alternatives` | object | Pricing from all available exchanges | | `data.execution.latencyMs` | number | Execution latency in milliseconds | ## Error Responses ### 400 Bad Request - Missing Required Fields ```json theme={null} { "success": false, "error": "Missing required field: symbol", "timestamp": 1678900000000 } ``` ### 401 Unauthorized - Invalid Token ```json theme={null} { "success": false, "error": "Unauthorized: No valid wallet address found in token", "timestamp": 1678900000000 } ``` ### 500 Internal Server Error ```json theme={null} { "success": false, "error": "Execution failed or upstream error", "timestamp": 1678900000000 } ``` ## When to Use * Implement custom order flows while still benefiting from smart routing * Execute trades with automatic best-price venue selection * Run discretionary trades while preserving reduce-only protections Use `preferredExchange` to force execution on a specific venue when you need deterministic routing, otherwise let the system automatically select the best price. **Avantis**: When Avantis is selected as the execution venue, trades are executed client-side on the Base network via wallet signing, not through the Tide backend. The routing recommendation may include Avantis pricing for comparison. ## OpenAPI ````yaml POST /api/trade/execute openapi: 3.1.0 info: title: Tide API description: >- Decentralized Perpetual Aggregator API for multi-exchange trading across Hyperliquid, Aster, Lighter, and Pacifica version: 1.0.0 contact: name: Tide Support email: support@tide.ag url: https://tide.ag license: name: MIT servers: - url: https://api.tide.ag description: Production server security: - ApiKeyAuth: [] tags: - name: Market Data description: Public market data endpoints - name: Trading description: Order placement and management - name: Positions description: Position management and history - name: Account description: Account and balance management - name: System description: System status and health paths: /api/trade/execute: post: tags: - Trading summary: Execute Smart Order description: >- Executes a trade by automatically routing it to the exchange with the best price, or to a preferred exchange if specified. requestBody: required: true content: application/json: schema: type: object required: - symbol - side - type - quantity properties: symbol: type: string description: Trading pair symbol (e.g., 'BTC', 'ETH') example: BTC side: type: string enum: - BUY - SELL description: Order side type: type: string enum: - MARKET - LIMIT description: Order type quantity: type: string description: Amount of base asset to trade example: '0.1' price: type: string description: Limit price. Required if type is LIMIT reduceOnly: type: boolean description: If true, the order will only reduce an existing position default: false preferredExchange: type: string enum: - hyperliquid - aster - lighter description: Force execution on a specific exchange responses: '200': description: Order executed successfully content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: executedOn: type: string enum: - hyperliquid - aster - lighter description: Exchange where the order was executed order: type: object properties: orderId: type: string description: Unique order identifier symbol: type: string description: Trading pair symbol status: type: string enum: - FILLED - PARTIALLY_FILLED - NEW - CANCELED price: type: number description: Execution price quantity: type: number description: Order quantity side: type: string enum: - BUY - SELL timestamp: type: integer description: Order timestamp in milliseconds routing: type: object properties: recommended: type: string description: Recommended exchange price: type: number description: Best execution price reason: type: string description: Reason for exchange selection savings: type: number description: Estimated savings vs next-best venue savingsPercent: type: number description: Savings as percentage alternatives: type: object description: Pricing from all available exchanges execution: type: object properties: timestamp: type: integer description: Execution timestamp latencyMs: type: number description: Execution latency in milliseconds timestamp: type: integer '400': description: Bad request - Missing required fields or invalid parameters content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: 'Missing required field: symbol' timestamp: type: integer '401': description: Unauthorized - Missing or invalid authentication token content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: 'Unauthorized: No valid wallet address found in token' timestamp: type: integer '500': description: Internal server error - Execution failed or upstream error content: application/json: schema: $ref: '#/components/schemas/Error' security: - BearerAuth: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: integer description: HTTP status code type: type: string description: Error type identifier message: type: string description: Human-readable error message details: type: string description: Additional error details securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: >- API key for authentication. Also requires X-API-SECRET, X-API-TIMESTAMP, and X-API-SIGNATURE headers for private endpoints. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token for authentication. Required for smart order execution. ````