Orders - Legend Docs

All paths are relative to the base URL. See authentication and errors and idempotency. 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

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

Example request

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 for nested response objects and validation patterns. Illustrative successful response:

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

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 for nested response objects and validation patterns. Illustrative successful response:

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

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 for nested response objects and validation patterns. Illustrative successful response:

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

{
  "price": "59000"
}

Example request

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 for nested response objects and validation patterns. Illustrative successful response:

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

{}

Example request

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 for nested response objects and validation patterns. Illustrative successful response:

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

​Place an order

​Parameters

​Request body

​Example request

​Response

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

​Parameters

​Example request

​Response

​Retrieve and reconcile an order

​Parameters

​Example request

​Response

​Modify order price, size, or trigger

​Parameters

​Request body

​Example request

​Response

​Cancel an open order

​Parameters

​Request body

​Example request

​Response

​Modification behavior

​Builder fees

Place an order

Parameters

Request body

Example request

Response

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

Parameters

Example request

Response

Retrieve and reconcile an order

Parameters

Example request

Response

Modify order price, size, or trigger

Parameters

Request body

Example request

Response

Cancel an open order

Parameters

Request body

Example request

Response

Modification behavior

Builder fees