Legend documentation

Leverage, margin, and TWAPs

Request parameters and responses for leverage, margin, and twaps.

All paths are relative to the base URL. See authentication and errors and idempotency.

Native Hyperliquid TWAPs do not support a builder-fee parameter and do not charge Legend’s builder fee. Hyperliquid trading fees still apply.

These actions require perpetual markets. Positive isolated-margin amounts add margin; negative amounts remove it. Margin amounts use USDC decimal strings with at most six decimal places. TWAP duration follows the exchange’s 5–10,080 minute range. A command returns an operation UUID; TWAP creation also returns its native ID in exchange_id.

Set leverage and margin type

POST /v1/leverage

Requires trading:write and Idempotency-Key.

Parameters

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

Request body

Field	Type	Required	Details
`market`	string	Yes	Max length: `100`
`leverage`	integer	Yes	Maximum: `9007199254740991`
`margin_type`	string	Yes	`cross`, `isolated`

{
  "market": "BTC",
  "leverage": 3,
  "margin_type": "cross"
}

Example request

curl -X POST "$LEGEND_API_BASE/v1/leverage" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"market":"BTC","leverage":3,"margin_type":"cross"}'

Response

Field	Type	Required	Details
`id`	string	Yes	Format: `uuid`
`object`	string	Yes	`operation`
`account`	string	Yes	Format: `uuid`
`action`	string	Yes
`status`	string	Yes	`processing`, `succeeded`, `rejected`, `unknown`
`exchange_id`	string or null	Yes
`error`	string or null	Yes

See the OpenAPI schema for nested response objects and validation patterns.

Illustrative successful response:

{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "operation",
  "account": "00000000-0000-4000-8000-000000000001",
  "action": "leverage",
  "status": "succeeded",
  "exchange_id": null,
  "error": null
}

Add or remove isolated margin

POST /v1/margin

Requires trading:write and Idempotency-Key.

Hyperliquid checks the remaining margin before accepting a negative amount. Remaining margin must satisfy the initial-margin requirement and be at least 10% of the position’s notional value. Adding margin does not necessarily make that same amount immediately removable. Strict-isolated markets do not allow margin removal. See Hyperliquid’s margining rules.

Check the returned operation’s status and error: a venue rejection returns status: "rejected", even when the HTTP request succeeds.

Parameters

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

Request body

Field	Type	Required	Details
`market`	string	Yes	Max length: `100`
`amount`	string	Yes

{
  "market": "BTC",
  "amount": "10"
}

Example request

curl -X POST "$LEGEND_API_BASE/v1/margin" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"market":"BTC","amount":"10"}'

Response

Field	Type	Required	Details
`id`	string	Yes	Format: `uuid`
`object`	string	Yes	`operation`
`account`	string	Yes	Format: `uuid`
`action`	string	Yes
`status`	string	Yes	`processing`, `succeeded`, `rejected`, `unknown`
`exchange_id`	string or null	Yes
`error`	string or null	Yes

See the OpenAPI schema for nested response objects and validation patterns.

Illustrative successful response:

{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "operation",
  "account": "00000000-0000-4000-8000-000000000001",
  "action": "isolated_margin",
  "status": "succeeded",
  "exchange_id": null,
  "error": null
}

Create a native Hyperliquid TWAP

POST /v1/twaps

Requires trading:write and Idempotency-Key.

Parameters

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

Request body

Field	Type	Required	Details
`market`	string	Yes	Max length: `100`
`side`	string	Yes	`buy`, `sell`
`size`	string	Yes	Max length: `40`
`duration_minutes`	integer	Yes	Minimum: `5`; Maximum: `10080`
`randomize`	boolean	No	Default: `false`
`reduce_only`	boolean	No	Default: `false`

{
  "market": "BTC",
  "side": "buy",
  "size": "0.001",
  "duration_minutes": 5,
  "randomize": false,
  "reduce_only": false
}

Example request

curl -X POST "$LEGEND_API_BASE/v1/twaps" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"market":"BTC","side":"buy","size":"0.001","duration_minutes":5,"randomize":false,"reduce_only":false}'

Response

Field	Type	Required	Details
`id`	string	Yes	Format: `uuid`
`object`	string	Yes	`operation`
`account`	string	Yes	Format: `uuid`
`action`	string	Yes
`status`	string	Yes	`processing`, `succeeded`, `rejected`, `unknown`
`exchange_id`	string or null	Yes
`error`	string or null	Yes

See the OpenAPI schema for nested response objects and validation patterns.

Illustrative successful response:

{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "operation",
  "account": "00000000-0000-4000-8000-000000000001",
  "action": "twap",
  "status": "succeeded",
  "exchange_id": "123",
  "error": null
}

Cancel a native Hyperliquid TWAP

POST /v1/twaps/cancel

Requires trading:write and Idempotency-Key.

Parameters

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

Request body

Field	Type	Required	Details
`market`	string	Yes	Max length: `100`
`twap_id`	integer	Yes	Minimum: `0`; Maximum: `9007199254740991`

{
  "market": "BTC",
  "twap_id": 123
}

Example request

curl -X POST "$LEGEND_API_BASE/v1/twaps/cancel" \
  -H "Authorization: Bearer $LEGEND_API_KEY" \
  -H "Idempotency-Key: UNIQUE_ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"market":"BTC","twap_id":123}'

Response

Field	Type	Required	Details
`id`	string	Yes	Format: `uuid`
`object`	string	Yes	`operation`
`account`	string	Yes	Format: `uuid`
`action`	string	Yes
`status`	string	Yes	`processing`, `succeeded`, `rejected`, `unknown`
`exchange_id`	string or null	Yes
`error`	string or null	Yes

See the OpenAPI schema for nested response objects and validation patterns.

Illustrative successful response:

{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "operation",
  "account": "00000000-0000-4000-8000-000000000001",
  "action": "twap_cancel",
  "status": "succeeded",
  "exchange_id": null,
  "error": null
}

Retrieve an action result

GET /v1/operations/{id}

Requires trading:read.

Parameters

Name	Location	Required	Type
`id`	path	Yes	string

Example request

curl "$LEGEND_API_BASE/v1/operations/ORDER_OR_OPERATION_ID" \
  -H "Authorization: Bearer $LEGEND_API_KEY"

Response

Field	Type	Required	Details
`id`	string	Yes	Format: `uuid`
`object`	string	Yes	`operation`
`account`	string	Yes	Format: `uuid`
`action`	string	Yes
`status`	string	Yes	`processing`, `succeeded`, `rejected`, `unknown`
`exchange_id`	string or null	Yes
`error`	string or null	Yes

See the OpenAPI schema for nested response objects and validation patterns.

Illustrative successful response:

{
  "id": "00000000-0000-4000-8000-000000000002",
  "object": "operation",
  "account": "00000000-0000-4000-8000-000000000001",
  "action": "leverage",
  "status": "succeeded",
  "exchange_id": null,
  "error": null
}