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.

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
}

​Set leverage and margin type

​Parameters

​Request body

​Example request

​Response

​Add or remove isolated margin

​Parameters

​Request body

​Example request

​Response

​Create a native Hyperliquid TWAP

​Parameters

​Request body

​Example request

​Response

​Cancel a native Hyperliquid TWAP

​Parameters

​Request body

​Example request

​Response

​Retrieve an action result

​Parameters

​Example request

​Response

Set leverage and margin type

Parameters

Request body

Example request

Response

Add or remove isolated margin

Parameters

Request body

Example request

Response

Create a native Hyperliquid TWAP

Parameters

Request body

Example request

Response

Cancel a native Hyperliquid TWAP

Parameters

Request body

Example request

Response

Retrieve an action result

Parameters

Example request

Response