> ## 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.

# Leverage, margin, and TWAPs

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

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).

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`         |

```json theme={null}
{
  "market": "BTC",
  "leverage": 3,
  "margin_type": "cross"
}
```

### Example request

```bash theme={null}
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](/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": "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](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/margining).

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

```json theme={null}
{
  "market": "BTC",
  "amount": "10"
}
```

### Example request

```bash theme={null}
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](/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": "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`               |

```json theme={null}
{
  "market": "BTC",
  "side": "buy",
  "size": "0.001",
  "duration_minutes": 5,
  "randomize": false,
  "reduce_only": false
}
```

### Example request

```bash theme={null}
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](/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": "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` |

```json theme={null}
{
  "market": "BTC",
  "twap_id": 123
}
```

### Example request

```bash theme={null}
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](/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": "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

```bash theme={null}
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](/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": "operation",
  "account": "00000000-0000-4000-8000-000000000001",
  "action": "leverage",
  "status": "succeeded",
  "exchange_id": null,
  "error": null
}
```