Skip to main content
POST
/
api
/
trade
/
execute
Execute Smart Order
curl --request POST \
  --url https://api.tide.ag/api/trade/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "symbol": "BTC",
  "quantity": "0.1",
  "price": "<string>",
  "reduceOnly": false
}
'
{
  "success": true,
  "data": {
    "order": {
      "orderId": "<string>",
      "symbol": "<string>",
      "price": 123,
      "quantity": 123,
      "timestamp": 123
    },
    "routing": {
      "recommended": "<string>",
      "price": 123,
      "reason": "<string>",
      "savings": 123,
      "savingsPercent": 123,
      "alternatives": {}
    },
    "execution": {
      "timestamp": 123,
      "latencyMs": 123
    }
  },
  "timestamp": 123
}
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 <token>
This endpoint requires authentication. You must provide a valid JWT token in the Authorization header.

​
Request Fields

FieldTypeRequiredDescription
symbolstring✅Trading pair symbol (e.g., “BTC”, “ETH”)
sidestring✅Order side: BUY or SELL
typestring✅Order type: MARKET or LIMIT
quantitystring✅Amount of base asset to trade
pricestring❌Limit price. Required if type is LIMIT
reduceOnlyboolean❌If true, the order will only reduce an existing position (default: false)
preferredExchangestring❌Force execution on a specific exchange: hyperliquid, aster, lighter, or avantis

​
Example Request

curl -X POST https://api.tide.ag/api/trade/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "symbol": "BTC",
    "side": "BUY",
    "type": "MARKET",
    "quantity": "0.1",
    "reduceOnly": false
  }'

​
Success Response

{
  "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

FieldTypeDescription
data.executedOnstringExchange where the order was executed
data.order.orderIdstringUnique order identifier
data.order.symbolstringTrading pair symbol
data.order.statusstringOrder status (e.g., “FILLED”)
data.order.pricenumberExecution price
data.order.quantitynumberOrder quantity
data.order.sidestringOrder side (“BUY” or “SELL”)
data.routing.recommendedstringRecommended exchange
data.routing.pricenumberBest execution price
data.routing.reasonstringReason for exchange selection
data.routing.savingsnumberEstimated savings vs next-best venue
data.routing.savingsPercentnumberSavings as percentage
data.routing.alternativesobjectPricing from all available exchanges
data.execution.latencyMsnumberExecution latency in milliseconds

​
Error Responses

​
400 Bad Request - Missing Required Fields

{
  "success": false,
  "error": "Missing required field: symbol",
  "timestamp": 1678900000000
}

​
401 Unauthorized - Invalid Token

{
  "success": false,
  "error": "Unauthorized: No valid wallet address found in token",
  "timestamp": 1678900000000
}

​
500 Internal Server Error

{
  "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.

Authorizations

​
Authorization
string
header
required

JWT token for authentication. Required for smart order execution.

Body

application/json
​
symbol
string
required

Trading pair symbol (e.g., 'BTC', 'ETH')

Example:

"BTC"

​
side
enum<string>
required

Order side

Available options:
BUY,
SELL
​
type
enum<string>
required

Order type

Available options:
MARKET,
LIMIT
​
quantity
string
required

Amount of base asset to trade

Example:

"0.1"

​
price
string

Limit price. Required if type is LIMIT

​
reduceOnly
boolean
default:false

If true, the order will only reduce an existing position

​
preferredExchange
enum<string>

Force execution on a specific exchange

Available options:
hyperliquid,
aster,
lighter

Response

Order executed successfully

​
success
boolean
​
data
object
​
timestamp
integer