Legend documentation

Orders

Request parameters and responses for orders.

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.

If the user turned on fat-finger protection in Legend, an order with a value above the limit returns 400 with code fat_finger_limit. The value is size × price. A market trigger uses the trigger price.

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:

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:

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:

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:

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.

"gtc"