> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legend.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

> Request parameters and responses for orders.

All paths are relative to the [base URL](/api-reference/trading/overview). See [authentication](/api-reference/trading/authentication) and [errors and idempotency](/api-reference/trading/errors).

Use `status=open` to list current exchange orders, including orders placed through the UI. Omitting it lists stored API order history. Open-order cursors are native order IDs; history cursors are Legend UUIDs. Read-only listing does not reconcile every historical order. Retrieve an individual order for reconciliation.

For a price-only modification, the API preserves the order’s current remaining size. Account, market, and side cannot be changed by modification.

## Place an order

`POST /v1/orders`

Requires `trading:write` and `Idempotency-Key`.

### Parameters

| Name              | Location | Required | Type   |
| ----------------- | -------- | -------- | ------ |
| `Idempotency-Key` | header   | Yes      | string |

### Request body

| Field            | Type    | Required | Details                               |
| ---------------- | ------- | -------- | ------------------------------------- |
| `account`        | string  | Yes      | Format: `uuid`                        |
| `market`         | string  | Yes      | Max length: `100`                     |
| `side`           | string  | Yes      | `buy`, `sell`                         |
| `size`           | string  | Yes      | Max length: `40`                      |
| `price`          | string  | Yes      | Max length: `40`                      |
| `time_in_force`  | string  | No       | `gtc`, `ioc`, `alo`; Default: `"gtc"` |
| `reduce_only`    | boolean | No       | Default: `false`                      |
| `trigger`        | object  | No       |                                       |
| `trigger.price`  | string  | Yes      | Max length: `40`                      |
| `trigger.kind`   | string  | Yes      | `take_profit`, `stop_loss`            |
| `trigger.market` | boolean | Yes      |                                       |

```json theme={null}
{
  "account": "00000000-0000-4000-8000-000000000001",
  "market": "BTC",
  "side": "buy",
  "price": "60000",
  "size": "0.001",
  "time_in_force": "gtc",
  "reduce_only": false
}
```

### Example request

```bash theme={null}
curl -X POST "$LEGEND_API_BASE/v1/orders" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"account":"00000000-0000-4000-8000-000000000001","market":"BTC","side":"buy","price":"60000","size":"0.001","time_in_force":"gtc","reduce_only":false}'
```

### Response

| Field               | Type           | Required | Details                                                                                  |
| ------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `id`                | string         | Yes      | Format: `uuid`                                                                           |
| `object`            | string         | Yes      | `order`                                                                                  |
| `account`           | string         | Yes      | Format: `uuid`                                                                           |
| `market`            | string         | Yes      | Max length: `100`                                                                        |
| `side`              | string         | Yes      | `buy`, `sell`                                                                            |
| `size`              | string         | Yes      | Max length: `40`                                                                         |
| `price`             | string         | Yes      | Max length: `40`                                                                         |
| `time_in_force`     | string         | No       | `gtc`, `ioc`, `alo`; Default: `"gtc"`                                                    |
| `reduce_only`       | boolean        | No       | Default: `false`                                                                         |
| `trigger`           | object         | No       |                                                                                          |
| `trigger.price`     | string         | Yes      | Max length: `40`                                                                         |
| `trigger.kind`      | string         | Yes      | `take_profit`, `stop_loss`                                                               |
| `trigger.market`    | boolean        | Yes      |                                                                                          |
| `network`           | string         | Yes      | `hyperliquid_mainnet`                                                                    |
| `status`            | string         | Yes      | `processing`, `open`, `filled`, `canceled`, `rejected`, `unknown`, `waiting_for_trigger` |
| `exchange_order_id` | string or null | Yes      |                                                                                          |
| `filled_size`       | string or null | Yes      |                                                                                          |
| `average_price`     | string or null | Yes      |                                                                                          |
| `error`             | string or null | Yes      |                                                                                          |
| `created_at`        | string         | Yes      |                                                                                          |

See the [OpenAPI schema](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "order",
  "account": "00000000-0000-4000-8000-000000000001",
  "network": "hyperliquid_mainnet",
  "market": "BTC",
  "side": "buy",
  "size": "0.001",
  "price": "60000",
  "time_in_force": "gtc",
  "reduce_only": false,
  "status": "open",
  "exchange_order_id": "123",
  "filled_size": "0",
  "average_price": null,
  "error": null,
  "created_at": "2026-09-19T12:00:00.000Z"
}
```

## List API order history, or current account orders with status=open

`GET /v1/orders`

Requires `trading:read`.

### Parameters

| Name     | Location | Required | Type                                                                          |
| -------- | -------- | -------- | ----------------------------------------------------------------------------- |
| `status` | query    | No       | string                                                                        |
| `dex`    | query    | No       | string; omit for all supported DEXes, `xyz` for XYZ, or empty for native only |
| `cursor` | query    | No       | string                                                                        |
| `limit`  | query    | No       | integer                                                                       |

### Example request

```bash theme={null}
curl "$LEGEND_API_BASE/v1/orders" \
  -H "Authorization: Bearer $LEGEND_API_KEY"
```

### Response

| Field         | Type           | Required | Details |
| ------------- | -------------- | -------- | ------- |
| `object`      | string         | Yes      | `list`  |
| `data`        | array          | Yes      |         |
| `has_more`    | boolean        | Yes      |         |
| `next_cursor` | string or null | Yes      |         |

See the [OpenAPI schema](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "object": "order",
      "account": "00000000-0000-4000-8000-000000000001",
      "network": "hyperliquid_mainnet",
      "market": "BTC",
      "side": "buy",
      "size": "0.001",
      "price": "60000",
      "time_in_force": "gtc",
      "reduce_only": false,
      "status": "open",
      "exchange_order_id": "123",
      "filled_size": "0",
      "average_price": null,
      "error": null,
      "created_at": "2026-09-19T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Retrieve and reconcile an order

`GET /v1/orders/{id}`

Requires `trading:read`.

### Parameters

| Name | Location | Required | Type             |
| ---- | -------- | -------- | ---------------- |
| `id` | path     | Yes      | string or string |

### Example request

```bash theme={null}
curl "$LEGEND_API_BASE/v1/orders/ORDER_OR_OPERATION_ID" \
  -H "Authorization: Bearer $LEGEND_API_KEY"
```

### Response

| Field               | Type           | Required | Details                                                                                  |
| ------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `id`                | string         | Yes      | Format: `uuid`                                                                           |
| `object`            | string         | Yes      | `order`                                                                                  |
| `account`           | string         | Yes      | Format: `uuid`                                                                           |
| `market`            | string         | Yes      | Max length: `100`                                                                        |
| `side`              | string         | Yes      | `buy`, `sell`                                                                            |
| `size`              | string         | Yes      | Max length: `40`                                                                         |
| `price`             | string         | Yes      | Max length: `40`                                                                         |
| `time_in_force`     | string         | No       | `gtc`, `ioc`, `alo`; Default: `"gtc"`                                                    |
| `reduce_only`       | boolean        | No       | Default: `false`                                                                         |
| `trigger`           | object         | No       |                                                                                          |
| `trigger.price`     | string         | Yes      | Max length: `40`                                                                         |
| `trigger.kind`      | string         | Yes      | `take_profit`, `stop_loss`                                                               |
| `trigger.market`    | boolean        | Yes      |                                                                                          |
| `network`           | string         | Yes      | `hyperliquid_mainnet`                                                                    |
| `status`            | string         | Yes      | `processing`, `open`, `filled`, `canceled`, `rejected`, `unknown`, `waiting_for_trigger` |
| `exchange_order_id` | string or null | Yes      |                                                                                          |
| `filled_size`       | string or null | Yes      |                                                                                          |
| `average_price`     | string or null | Yes      |                                                                                          |
| `error`             | string or null | Yes      |                                                                                          |
| `created_at`        | string         | Yes      |                                                                                          |

See the [OpenAPI schema](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "order",
  "account": "00000000-0000-4000-8000-000000000001",
  "network": "hyperliquid_mainnet",
  "market": "BTC",
  "side": "buy",
  "size": "0.001",
  "price": "60000",
  "time_in_force": "gtc",
  "reduce_only": false,
  "status": "open",
  "exchange_order_id": "123",
  "filled_size": "0",
  "average_price": null,
  "error": null,
  "created_at": "2026-09-19T12:00:00.000Z"
}
```

## Modify order price, size, or trigger

`POST /v1/orders/{id}/modify`

Requires `trading:write` and `Idempotency-Key`.

### Parameters

| Name              | Location | Required | Type             |
| ----------------- | -------- | -------- | ---------------- |
| `id`              | path     | Yes      | string or string |
| `Idempotency-Key` | header   | Yes      | string           |

### Request body

| Field            | Type    | Required | Details                    |
| ---------------- | ------- | -------- | -------------------------- |
| `price`          | string  | No       | Max length: `40`           |
| `size`           | string  | No       | Max length: `40`           |
| `trigger`        | object  | No       |                            |
| `trigger.price`  | string  | Yes      | Max length: `40`           |
| `trigger.kind`   | string  | Yes      | `take_profit`, `stop_loss` |
| `trigger.market` | boolean | Yes      |                            |

```json theme={null}
{
  "price": "59000"
}
```

### Example request

```bash theme={null}
curl -X POST "$LEGEND_API_BASE/v1/orders/ORDER_OR_OPERATION_ID/modify" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"price":"59000"}'
```

### Response

| Field               | Type           | Required | Details                                                                                  |
| ------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `id`                | string         | Yes      | Format: `uuid`                                                                           |
| `object`            | string         | Yes      | `order`                                                                                  |
| `account`           | string         | Yes      | Format: `uuid`                                                                           |
| `market`            | string         | Yes      | Max length: `100`                                                                        |
| `side`              | string         | Yes      | `buy`, `sell`                                                                            |
| `size`              | string         | Yes      | Max length: `40`                                                                         |
| `price`             | string         | Yes      | Max length: `40`                                                                         |
| `time_in_force`     | string         | No       | `gtc`, `ioc`, `alo`; Default: `"gtc"`                                                    |
| `reduce_only`       | boolean        | No       | Default: `false`                                                                         |
| `trigger`           | object         | No       |                                                                                          |
| `trigger.price`     | string         | Yes      | Max length: `40`                                                                         |
| `trigger.kind`      | string         | Yes      | `take_profit`, `stop_loss`                                                               |
| `trigger.market`    | boolean        | Yes      |                                                                                          |
| `network`           | string         | Yes      | `hyperliquid_mainnet`                                                                    |
| `status`            | string         | Yes      | `processing`, `open`, `filled`, `canceled`, `rejected`, `unknown`, `waiting_for_trigger` |
| `exchange_order_id` | string or null | Yes      |                                                                                          |
| `filled_size`       | string or null | Yes      |                                                                                          |
| `average_price`     | string or null | Yes      |                                                                                          |
| `error`             | string or null | Yes      |                                                                                          |
| `created_at`        | string         | Yes      |                                                                                          |

See the [OpenAPI schema](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "order",
  "account": "00000000-0000-4000-8000-000000000001",
  "network": "hyperliquid_mainnet",
  "market": "BTC",
  "side": "buy",
  "size": "0.001",
  "price": "60000",
  "time_in_force": "gtc",
  "reduce_only": false,
  "status": "open",
  "exchange_order_id": "123",
  "filled_size": "0",
  "average_price": null,
  "error": null,
  "created_at": "2026-09-19T12:00:00.000Z"
}
```

## Cancel an open order

`POST /v1/orders/{id}/cancel`

Requires `trading:write` and `Idempotency-Key`.

### Parameters

| Name              | Location | Required | Type             |
| ----------------- | -------- | -------- | ---------------- |
| `id`              | path     | Yes      | string or string |
| `Idempotency-Key` | header   | Yes      | string           |

### Request body

| Field | Type | Required | Details |
| ----- | ---- | -------- | ------- |

```json theme={null}
{}
```

### Example request

```bash theme={null}
curl -X POST "$LEGEND_API_BASE/v1/orders/ORDER_OR_OPERATION_ID/cancel" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
```

### Response

| Field               | Type           | Required | Details                                                                                  |
| ------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `id`                | string         | Yes      | Format: `uuid`                                                                           |
| `object`            | string         | Yes      | `order`                                                                                  |
| `account`           | string         | Yes      | Format: `uuid`                                                                           |
| `market`            | string         | Yes      | Max length: `100`                                                                        |
| `side`              | string         | Yes      | `buy`, `sell`                                                                            |
| `size`              | string         | Yes      | Max length: `40`                                                                         |
| `price`             | string         | Yes      | Max length: `40`                                                                         |
| `time_in_force`     | string         | No       | `gtc`, `ioc`, `alo`; Default: `"gtc"`                                                    |
| `reduce_only`       | boolean        | No       | Default: `false`                                                                         |
| `trigger`           | object         | No       |                                                                                          |
| `trigger.price`     | string         | Yes      | Max length: `40`                                                                         |
| `trigger.kind`      | string         | Yes      | `take_profit`, `stop_loss`                                                               |
| `trigger.market`    | boolean        | Yes      |                                                                                          |
| `network`           | string         | Yes      | `hyperliquid_mainnet`                                                                    |
| `status`            | string         | Yes      | `processing`, `open`, `filled`, `canceled`, `rejected`, `unknown`, `waiting_for_trigger` |
| `exchange_order_id` | string or null | Yes      |                                                                                          |
| `filled_size`       | string or null | Yes      |                                                                                          |
| `average_price`     | string or null | Yes      |                                                                                          |
| `error`             | string or null | Yes      |                                                                                          |
| `created_at`        | string         | Yes      |                                                                                          |

See the [OpenAPI schema](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "order",
  "account": "00000000-0000-4000-8000-000000000001",
  "network": "hyperliquid_mainnet",
  "market": "BTC",
  "side": "buy",
  "size": "0.001",
  "price": "60000",
  "time_in_force": "gtc",
  "reduce_only": false,
  "status": "canceled",
  "exchange_order_id": "123",
  "filled_size": "0",
  "average_price": null,
  "error": null,
  "created_at": "2026-09-19T12:00:00.000Z"
}
```

## Modification behavior

Hyperliquid’s default modify action requires a non-trigger replacement that does not immediately execute; a GTC replacement is treated as post-only. A rejected replacement can still cancel the original order. Always inspect the returned `status` and `error`; the API reconciles the original order rather than assuming it remains open. If that lookup fails, the result is `unknown` until retrieved and reconciled. Set `always_place: true` explicitly to permit a trigger or immediately executable replacement. This can place a new order even when cancellation fails; use it only when that behavior is intended. Trigger modifications without this opt-in fail before exchange submission. The default is `false`; successful default GTC modifications are reported as `alo` to match Hyperliquid’s effective order type.

## Builder fees

Regular perpetual order creation uses Legend’s shared builder-fee configuration (normally 5 bps, subject to existing account overrides). Clients cannot supply their own builder address or fee. Spot uses the same fee rules as the Legend UI; native TWAPs do not support builder fees. Exchange fees are separate from Legend’s builder fee.

The modification body also accepts `always_place` (boolean, optional, default `false`). It does not change account, market, side, reduce-only intent, or the server-selected fee configuration.