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

# Get Order Status

> Retrieve the latest status for any order placed through the aggregator. Normalizes venue-specific payloads from Lighter, Aster, Hyperliquid, and Avantis.

Retrieve the latest status for any order placed through the aggregator. The service normalizes venue-specific payloads from **Lighter**, **Aster**, **Hyperliquid**, and **Avantis** so you can reconcile execution states with a single integration.

## Request

* **Method**: `GET`
* **Endpoint**: `/api/trading/{exchange}/orders/{orderId}/status`
* **Authentication**: Required

## Path Parameters

| Name       | Type   | Required | Description                                                    |
| ---------- | ------ | -------- | -------------------------------------------------------------- |
| `exchange` | string | ✅        | Target venue (`lighter`, `aster`, `hyperliquid`, or `avantis`) |
| `orderId`  | string | ✅        | Identifier of the order to inspect                             |

## Query Parameters

| Name     | Type   | Required | Description                                                    |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| `symbol` | string | ❌        | Optional trading pair hint (e.g. `BTC`) to speed up the lookup |

## Example

```bash theme={null}
curl -X GET "https://api.tide.ag/api/trading/lighter/orders/12345/status?symbol=BTC"
```

## Response

The API returns a normalized order record including identifiers, execution side, order type, fill progress, and the latest venue timestamp.

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "12345",
    "symbol": "BTC",
    "side": "BUY",
    "type": "LIMIT",
    "status": "PARTIALLY_FILLED",
    "price": "49850.00",
    "quantity": "1.0",
    "filledQuantity": "0.6",
    "timestamp": 1730869356000
  }
}
```

## Status Values

| Status             | Description                                       |
| ------------------ | ------------------------------------------------- |
| `OPEN`             | Order is active and waiting to fill               |
| `PARTIALLY_FILLED` | Order has partial fills                           |
| `FILLED`           | Order fully executed                              |
| `CANCELED`         | Order was canceled before completion              |
| `REJECTED`         | Exchange rejected the order                       |
| `UNKNOWN`          | The adapter could not determine the current state |

## Errors

* **404** – `{ "success": false, "error": "Order 12345 not found in any market" }`
* **401** – `{ "success": false, "error": "Missing or invalid credentials for Aster" }`
* **500** – `{ "success": false, "error": "Failed to fetch order status: timeout" }`

<Tip>
  Provide per-request credentials for the venues you want to query. Adapters read the payload, fetch live data, and immediately discard the supplied keys.
</Tip>

***

## Hyperliquid - Get Historical Orders

Retrieve all previously placed orders for a wallet on Hyperliquid.

### Endpoint

`GET /api/hyperliquid/:walletId/orders/historical`

### Path Parameters

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

### Headers

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| `x-wallet-id` | Wallet ID (UUID) | Yes      |

### Example Request

```bash theme={null}
curl -X GET https://api.tide.ag/api/hyperliquid/a1e82339-29f8-41a6-a468-ce8d268a3261/orders/historical \
  -H "x-wallet-id: a1e82339-29f8-41a6-a468-ce8d268a3261"
```

### Success Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "orderId": "255641266600",
      "symbol": "BTC",
      "side": "BUY",
      "type": "Limit",
      "price": "88287.0",
      "quantity": "0.0",
      "timestamp": 1764682699221
    },
    {
      "orderId": "255638423999",
      "symbol": "BTC",
      "side": "SELL",
      "type": "Limit",
      "price": "87131.0",
      "quantity": "0.00831",
      "timestamp": 1764682498119
    },
    {
      "orderId": "255608992308",
      "symbol": "HYPE",
      "side": "BUY",
      "type": "Limit",
      "price": "31.9",
      "quantity": "1.0",
      "timestamp": 1764680449095
    }
  ],
  "count": 46
}
```

### Response Fields

| Field              | Type    | Description                        |
| ------------------ | ------- | ---------------------------------- |
| `success`          | boolean | Operation status                   |
| `data`             | array   | Array of historical orders         |
| `data[].orderId`   | string  | Unique order identifier            |
| `data[].symbol`    | string  | Asset symbol (e.g., "BTC", "HYPE") |
| `data[].side`      | string  | Order side ("BUY" or "SELL")       |
| `data[].type`      | string  | Order type ("Limit" or "Market")   |
| `data[].price`     | string  | Order price                        |
| `data[].quantity`  | string  | Order quantity                     |
| `data[].timestamp` | number  | Unix timestamp in milliseconds     |
| `count`            | number  | Total number of historical orders  |

***

## Avantis - Get Open Limit Orders

Retrieve all open limit orders for a wallet on Avantis.

### Endpoint

`GET /api/trading/avantis/orders`

### Headers

| Header        | Value          | Required |
| ------------- | -------------- | -------- |
| `x-wallet-id` | Wallet address | Yes      |

### Example Request

```bash theme={null}
curl -X GET https://api.tide.ag/api/trading/avantis/orders \
  -H "x-wallet-id: 0xabc123..."
```

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "exchange": "avantis",
    "orders": [
      {
        "orderId": "avantis-0-3",
        "symbol": "ETH",
        "side": "Long",
        "type": "Limit",
        "status": "OPEN",
        "price": "3200.00",
        "quantity": "0.05",
        "filledQuantity": "0",
        "timestamp": 12345678,
        "exchange": "avantis"
      }
    ],
    "count": 1
  }
}
```

### Response Fields

| Field            | Type   | Description                            |
| ---------------- | ------ | -------------------------------------- |
| `orderId`        | string | Format: `avantis-<pairIndex>-<index>`  |
| `symbol`         | string | Asset symbol (e.g., "ETH", "BTC")      |
| `side`           | string | `"Long"` or `"Short"`                  |
| `type`           | string | Always `"Limit"` for open orders       |
| `status`         | string | Always `"OPEN"`                        |
| `price`          | string | Limit price in USD                     |
| `quantity`       | string | Token amount                           |
| `filledQuantity` | string | Always `"0"` for open orders           |
| `timestamp`      | number | Block number when the order was placed |
| `exchange`       | string | Always `"avantis"`                     |

***

## Avantis - Trade History (Closed Trades)

Retrieve closed trade history for a wallet on Avantis.

### Endpoint

`GET /api/trading/avantis/history/trades`

### Headers

| Header        | Value          | Required |
| ------------- | -------------- | -------- |
| `x-wallet-id` | Wallet address | Yes      |

### Example Request

```bash theme={null}
curl -X GET https://api.tide.ag/api/trading/avantis/history/trades \
  -H "x-wallet-id: 0xabc123..."
```

### Success Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "trade_001",
      "symbol": "ETH",
      "exchange": "avantis",
      "price": "3500.00",
      "size": "0.032416",
      "side": "Long",
      "timestamp": 1698840000000
    }
  ]
}
```

### Response Fields

| Field       | Type   | Description                         |
| ----------- | ------ | ----------------------------------- |
| `id`        | string | Unique trade identifier             |
| `symbol`    | string | Asset symbol                        |
| `exchange`  | string | Always `"avantis"`                  |
| `price`     | string | Close price in USD                  |
| `size`      | string | Token amount                        |
| `side`      | string | `"Long"` or `"Short"`               |
| `timestamp` | number | Closed-at timestamp in milliseconds |

***

## Avantis - Historical Orders (Limit Order History)

Retrieve historical limit orders for a wallet on Avantis.

### Endpoint

`GET /api/trading/avantis/history/orders`

### Headers

| Header        | Value          | Required |
| ------------- | -------------- | -------- |
| `x-wallet-id` | Wallet address | Yes      |

### Example Request

```bash theme={null}
curl -X GET https://api.tide.ag/api/trading/avantis/history/orders \
  -H "x-wallet-id: 0xabc123..."
```

### Success Response

Same shape as the open limit orders response above, but includes orders in all statuses (filled, cancelled, expired).


## OpenAPI

````yaml GET /api/trading/{exchange}/orders/{orderId}/status
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/trading/{exchange}/orders/{orderId}/status:
    get:
      tags:
        - Trading
      summary: Get Order Status
      description: >-
        Retrieve the latest status for any order placed through the aggregator.
        Normalizes venue-specific payloads from Lighter, Aster, Hyperliquid, and
        Avantis.
      parameters:
        - name: exchange
          in: path
          required: true
          schema:
            type: string
            enum:
              - lighter
              - aster
              - hyperliquid
              - avantis
          description: Target venue (lighter, aster, hyperliquid, or avantis)
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: Identifier of the order to inspect
        - name: symbol
          in: query
          schema:
            type: string
            example: BTC
          description: Optional trading pair hint (e.g. BTC) to speed up the lookup
      responses:
        '200':
          description: Order status payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      orderId:
                        type: string
                      symbol:
                        type: string
                      side:
                        $ref: '#/components/schemas/OrderSide'
                      type:
                        $ref: '#/components/schemas/OrderType'
                      status:
                        $ref: '#/components/schemas/OrderStatus'
                      price:
                        type: string
                      quantity:
                        type: string
                      filledQuantity:
                        type: string
                      timestamp:
                        type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Missing or invalid credentials for Aster
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Order 12345 not found in any market
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Failed to fetch order status: timeout'
components:
  schemas:
    OrderSide:
      type: string
      enum:
        - BUY
        - SELL
    OrderType:
      type: string
      enum:
        - LIMIT
        - MARKET
        - STOP_MARKET
        - STOP_LIMIT
    OrderStatus:
      type: string
      enum:
        - OPEN
        - FILLED
        - PARTIALLY_FILLED
        - CANCELED
        - REJECTED
        - UNKNOWN
  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.

````