> ## 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.

# Place Order

# Place Trading Orders

Execute trading orders on supported exchanges. Each exchange has its own endpoint with specific requirements.

## Supported Exchanges

| Exchange    | Endpoint                               | Symbol Format | Notes                                      |
| ----------- | -------------------------------------- | ------------- | ------------------------------------------ |
| Aster       | `POST /api/trading/aster/orders`       | BTCUSDT       | Requires x-wallet-id header                |
| Hyperliquid | `POST /api/trading/hyperliquid/orders` | BTC           | Requires x-wallet-id header                |
| Lighter     | `POST /api/trading/lighter/orders`     | USDC          | Requires API credentials as query params   |
| Avantis     | Client-side execution                  | ETH, BTC, SOL | On-chain via wallet signing (Base network) |

<Warning>
  **Lighter DEX Requirement**: Before using Lighter, you must:

  1. Create an account on [Lighter DEX](https://app.lighter.xyz)
  2. Deposit funds on Lighter
  3. Generate API keys from Lighter dashboard
  4. Provide credentials as query parameters
</Warning>

***

## Aster - Place Order

Execute orders on Aster exchange for perpetual futures trading.

### Endpoint

`POST /api/aster/perp/:walletId/order`

### Path Parameters

| Parameter  | Type   | Required | Description      |
| ---------- | ------ | -------- | ---------------- |
| `walletId` | string | Yes      | Wallet ID (UUID) |

### Request Body

```json theme={null}
{
  "symbol": "BTCUSDT",
  "side": "BUY",
  "type": "MARKET",
  "quantity": "0.001",
  "positionSide": "BOTH"
}
```

### Request Parameters

| Field          | Type    | Required | Description                                                           |
| -------------- | ------- | -------- | --------------------------------------------------------------------- |
| `symbol`       | string  | Yes      | Trading pair (e.g., "BTCUSDT")                                        |
| `side`         | string  | Yes      | "BUY" (open LONG/close SHORT) or "SELL" (open SHORT/close LONG)       |
| `type`         | string  | Yes      | Order type: "MARKET", "LIMIT", "STOP\_MARKET", "TAKE\_PROFIT\_MARKET" |
| `quantity`     | string  | Yes      | Base asset quantity                                                   |
| `price`        | string  | No       | Required for LIMIT orders                                             |
| `positionSide` | string  | No       | "BOTH" (one-way mode, default), "LONG", or "SHORT" (hedge mode)       |
| `reduceOnly`   | boolean | No       | Prevent increasing exposure                                           |
| `timeInForce`  | string  | No       | "GTC" (default), "IOC", or "FOK"                                      |

### Order Types

* `MARKET` - Execute immediately at best price
* `LIMIT` - Execute only at specified price
* `STOP_MARKET` - Stop loss (market execution)
* `TAKE_PROFIT_MARKET` - Take profit (market execution)

### Position Sides

* `BOTH` - One-way mode (default) - single position per symbol
* `LONG` - Long position (hedge mode)
* `SHORT` - Short position (hedge mode)

### Time in Force

* `GTC` - Good Till Cancel (default)
* `IOC` - Immediate or Cancel
* `FOK` - Fill or Kill

### Example Request

```bash theme={null}
curl -X POST https://api.tide.ag/api/aster/perp/ee337309-3e77-4278-b21a-4681468168ba/order \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "MARKET",
    "quantity": "0.001",
    "positionSide": "BOTH"
  }'
```

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": 9884649221,
    "symbol": "BTCUSDT",
    "status": "NEW",
    "clientOrderId": "6D52PQwRlg0PcdHz5ttkgN",
    "price": "0",
    "avgPrice": "0.0000",
    "origQty": "0.001",
    "executedQty": "0",
    "cumQty": "0",
    "cumQuote": "0",
    "timeInForce": "GTC",
    "type": "MARKET",
    "reduceOnly": false,
    "closePosition": false,
    "side": "BUY",
    "positionSide": "BOTH",
    "stopPrice": "0",
    "workingType": "CONTRACT_PRICE",
    "priceProtect": false,
    "origType": "MARKET",
    "updateTime": 1764640797006
  }
}
```

***

## Hyperliquid - Place Order

Execute orders on Hyperliquid exchange for perpetual futures trading.

### Endpoint

`POST /api/trading/hyperliquid/orders`

### Headers

| Header         | Value            | Required |
| -------------- | ---------------- | -------- |
| `x-wallet-id`  | Wallet ID (UUID) | Yes      |
| `Content-Type` | application/json | Yes      |

### Request Body

```json theme={null}
{
  "userId": "a1e82339-29f8-41a6-a468-ce8d268a3261",
  "symbol": "BTC",
  "side": "SELL",
  "type": "MARKET",
  "quantity": "0.01",
  "price": "87131.0",
  "reduceOnly": false
}
```

### Request Parameters

| Field        | Type    | Required | Description                                  |
| ------------ | ------- | -------- | -------------------------------------------- |
| `userId`     | string  | Yes      | User's wallet ID or address                  |
| `symbol`     | string  | Yes      | Asset symbol (e.g., "BTC", "ETH", "HYPE")    |
| `side`       | string  | Yes      | "BUY" or "SELL"                              |
| `type`       | string  | Yes      | "MARKET" or "LIMIT"                          |
| `quantity`   | string  | Yes      | Base asset quantity                          |
| `price`      | string  | Yes      | Price for the order                          |
| `reduceOnly` | boolean | No       | Prevent increasing exposure (default: false) |

<Note>
  Hyperliquid uses simple asset symbols like `BTC`, `ETH`, `HYPE`. The `price` field should be provided for both MARKET and LIMIT orders.
</Note>

### Example Request

```bash theme={null}
curl -X POST https://api.tide.ag/api/trading/hyperliquid/orders \
  -H "x-wallet-id: a1e82339-29f8-41a6-a468-ce8d268a3261" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "a1e82339-29f8-41a6-a468-ce8d268a3261",
    "symbol": "BTC",
    "side": "SELL",
    "type": "MARKET",
    "quantity": "0.01",
    "price": "87131.0",
    "reduceOnly": false
  }'
```

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "255730787458",
    "status": "FILLED",
    "symbol": "BTC",
    "side": "SELL",
    "type": "MARKET",
    "price": "87131.0",
    "quantity": "0.01",
    "filledQuantity": "0.00157",
    "timestamp": 1764688069312
  },
  "timestamp": 1764688069314
}
```

***

## Lighter - Place Order

Execute orders on Lighter DEX using API credentials from your Lighter account.

### Endpoint

`POST /api/trading/lighter/orders`

### Query Parameters (Required)

<Warning>
  These credentials must be obtained from your Lighter DEX account dashboard.
</Warning>

| Parameter          | Type   | Required | Description                                   |
| ------------------ | ------ | -------- | --------------------------------------------- |
| `apiKeyPrivateKey` | string | Yes      | Your Lighter API key private key (hex format) |
| `apiKeyIndex`      | number | Yes      | API key index from Lighter                    |
| `accountIndex`     | number | Yes      | Your Lighter account index                    |

### Full Example URL

```
POST /api/trading/lighter/orders?apiKeyPrivateKey=539ef81cacb...&apiKeyIndex=5&accountIndex=316225
```

### Request Body

```json theme={null}
{
  "userId": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "symbol": "USDC",
  "side": "BUY",
  "type": "MARKET",
  "quantity": "1.1",
  "price": "1",
  "reduceOnly": true
}
```

### Request Parameters

| Field        | Type    | Required | Description                 |
| ------------ | ------- | -------- | --------------------------- |
| `userId`     | string  | Yes      | User's wallet address       |
| `symbol`     | string  | Yes      | Token symbol (e.g., "USDC") |
| `side`       | string  | Yes      | "BUY" or "SELL"             |
| `type`       | string  | Yes      | "MARKET" or "LIMIT"         |
| `quantity`   | string  | Yes      | Base asset quantity         |
| `price`      | string  | No       | Required for LIMIT orders   |
| `reduceOnly` | boolean | No       | Prevent increasing exposure |

<Note>
  Lighter uses spot token symbols like "USDC". Quantity is in base asset units.
</Note>

### Example Request

```bash theme={null}
curl -X POST "https://api.tide.ag/api/trading/lighter/orders?apiKeyPrivateKey=539ef81cacb...&apiKeyIndex=5&accountIndex=316225" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "0x07943f0f79097572451601e768c329a2765f2ea2",
    "symbol": "USDC",
    "side": "BUY",
    "type": "MARKET",
    "quantity": "1.1",
    "price": "1",
    "reduceOnly": true
  }'
```

### Success Response

```json theme={null}
{
  "success": true,
  "orderId": "948233341",
  "status": "submitted",
  "adapter": "lighter",
  "timestamp": 1698840000000
}
```

***

## Avantis - Place Order (Client-Side Execution)

Avantis trades are executed **client-side** via on-chain transactions on the Base network. Unlike other exchanges, orders are not routed through the Tide backend — the frontend signs and submits transactions directly to Avantis smart contracts.

<Warning>
  Avantis execution uses client-side wallet signing via the `useAvantisTrade` React hook. The Tide backend provides **data only** (positions, orders, history, balances). Trade execution happens on-chain.
</Warning>

### Open Position

```typescript theme={null}
useAvantisTrade().openPosition({
  symbol: "ETH",                    // Pair from PAIR_INDEX_MAP
  direction: "LONG",                // "LONG" or "SHORT"
  positionSizeUsd: "100.00",        // Collateral in USDC
  leverage: 10,                     // See leverage rules below
  openPrice: "3420.50",             // Required for all order types
  orderType: "MARKET",              // MARKET, LIMIT, STOP_LIMIT, or MARKET_ZERO_FEE
  slippagePercent: 0.3,             // Default: 0.3
  tp: "4000",                       // Take-profit price (optional)
  sl: "3000"                        // Stop-loss price (optional)
})
// Returns: { txHash, symbol, direction, size, leverage }
```

### Request Parameters

| Field             | Type   | Required | Description                                                      |
| ----------------- | ------ | -------- | ---------------------------------------------------------------- |
| `symbol`          | string | Yes      | Asset symbol (e.g., "ETH", "BTC", "SOL") from the pair index map |
| `direction`       | string | Yes      | `"LONG"` or `"SHORT"`                                            |
| `positionSizeUsd` | string | Yes      | Collateral amount in USDC                                        |
| `leverage`        | number | Yes      | Leverage multiplier (see limits below)                           |
| `openPrice`       | string | Yes      | Price for the order (required for all types)                     |
| `orderType`       | string | Yes      | `"MARKET"`, `"LIMIT"`, `"STOP_LIMIT"`, or `"MARKET_ZERO_FEE"`    |
| `slippagePercent` | number | No       | Slippage tolerance (default: 0.3%)                               |
| `tp`              | string | No       | Take-profit price                                                |
| `sl`              | string | No       | Stop-loss price                                                  |

### Order Types

| On-chain Value | Type              | Description                                                  |
| -------------- | ----------------- | ------------------------------------------------------------ |
| 0              | `MARKET`          | Execute at current price with slippage tolerance             |
| 1              | `STOP_LIMIT`      | Trigger at stop price, execute as limit                      |
| 2              | `LIMIT`           | Execute only at specified price or better                    |
| 3              | `MARKET_ZERO_FEE` | Zero-fee market order (ETH, BTC, SOL only, 75-250x leverage) |

### Leverage Limits

| Order Type        | Pairs              | Min | Max                |
| ----------------- | ------------------ | --- | ------------------ |
| MARKET            | All                | 1x  | 50x (ETH/BTC: 75x) |
| LIMIT             | All                | 1x  | 50x (ETH/BTC: 75x) |
| STOP\_LIMIT       | All                | 1x  | 50x (ETH/BTC: 75x) |
| MARKET\_ZERO\_FEE | ETH, BTC, SOL only | 75x | 250x               |

### Precision

| Value                                 | Decimals |
| ------------------------------------- | -------- |
| Price / Leverage / SL / TP / Slippage | 1e10     |
| USDC amounts                          | 6        |
| Min notional (after leverage)         | \$100    |

### Supported Pairs

| Symbol | Index | Symbol | Index | Symbol | Index |
| ------ | ----- | ------ | ----- | ------ | ----- |
| ETH    | 0     | BTC    | 1     | SOL    | 2     |
| ARB    | 3     | OP     | 4     | DOGE   | 5     |
| AVAX   | 6     | LINK   | 7     | AAVE   | 8     |
| MKR    | 9     | NEAR   | 10    | MATIC  | 11    |
| CRV    | 12    | UNI    | 13    | ATOM   | 14    |
| LTC    | 15    | FIL    | 16    | TRX    | 17    |
| XRP    | 18    | BNB    | 19    | WIF    | 20    |
| PEPE   | 21    | USDC   | 22    | STRK   | 23    |
| SUI    | 24    | SEI    | 25    | TIA    | 26    |
| INJ    | 27    | BONK   | 28    | JUP    | 29    |
| W      | 30    | ENA    | 31    | ETHFI  | 32    |
| PYTH   | 33    | JTO    | 34    | BLUR   | 35    |
| ZK     | 36    | BRETT  | 37    | TURBO  | 38    |
| FLOKI  | 39    | LQTY   | 40    | ONDO   | 41    |
| REZ    | 42    | ETHBTC | 43    | SHIB   | 44    |
| XLM    | 45    | HYPE   | 46    | APT    | 47    |
| TRUMP  | 48    | PENDLE | 49    | EIGEN  | 50    |

### Contract Addresses (Base Mainnet)

| Contract       | Address                                      |
| -------------- | -------------------------------------------- |
| Trading        | `0x44914408af82bC9983bbb330e3578E1105e11d4e` |
| TradingStorage | `0x8fE524Ca4AD62aF3E5b3808680e8b5c7822A134E` |
| USDC           | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |

***

## Error Responses

### 400 Bad Request - Missing Parameters

```json theme={null}
{
  "success": false,
  "error": "Missing required parameters",
  "timestamp": 1698840000000
}
```

### 400 Bad Request - Invalid Order Type

```json theme={null}
{
  "success": false,
  "error": "Invalid order type. Must be MARKET or LIMIT",
  "timestamp": 1698840000000
}
```

### 401 Unauthorized - Missing Wallet ID

```json theme={null}
{
  "success": false,
  "error": "Missing x-wallet-id header",
  "timestamp": 1698840000000
}
```

### 403 Forbidden - Invalid API Credentials (Lighter)

```json theme={null}
{
  "success": false,
  "error": "Invalid API credentials",
  "timestamp": 1698840000000
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": "Failed to place order",
  "timestamp": 1698840000000
}
```

***

## Order Types

### Market Orders

Execute immediately at the best available price.

```json theme={null}
{
  "type": "MARKET",
  "quantity": "0.1"
}
```

### Limit Orders

Execute only at the specified price or better.

```json theme={null}
{
  "type": "LIMIT",
  "quantity": "0.1",
  "price": "50000"
}
```

***

## Important Notes

<Warning>
  **Lighter API Credentials**: Never expose your Lighter API credentials in client-side code. Always make requests from your secure backend server.
</Warning>

<Note>
  **Wallet ID Header**: For Aster and Hyperliquid, you must include the `x-wallet-id` header with your server wallet ID.
</Note>

<Tip>
  **Reduce Only**: Set `reduceOnly: true` to ensure orders only close existing positions and don't open new ones.
</Tip>

<Info>
  **Symbol Formats**:

  * Aster: `BTCUSDT`, `ETHUSDT`
  * Hyperliquid: `BTC`, `ETH`, `HYPE` (simple asset symbols)
  * Lighter: `USDC`, `USDT`
  * Avantis: `ETH`, `BTC`, `SOL` (simple asset symbols, mapped to pair index)
</Info>