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

# Account, positions, and fills

> Request parameters and responses for account, positions, and fills.

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

Balances include native perpetual, supported HIP-3, and spot balances. Top-level `equity`, `withdrawable`, and `margin_used` describe the native perpetual account. The `perpetuals` array exposes these metrics per DEX (`""` for native, `"xyz"` for XYZ). Do not sum these balances blindly: collateral may be shared across account modes. Positions include all supported DEXes by default; pass `?dex=xyz` to select XYZ or `?dex=` for native markets only. Fills come from Legend’s indexed history and can lag the venue; they are isolated by user, wallet, and network. Pagination cursors are opaque and must not be edited.

## Read account balances

`GET /v1/account`

Requires `trading:read`.

### Example request

```bash theme={null}
curl "$LEGEND_API_BASE/v1/account" \
  -H "Authorization: Bearer $LEGEND_API_KEY"
```

### Response

| Field          | Type   | Required | Details                                                                                   |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `object`       | string | Yes      | `account`                                                                                 |
| `account`      | string | Yes      | Format: `uuid`                                                                            |
| `network`      | string | Yes      | `hyperliquid_mainnet`                                                                     |
| `equity`       | string | Yes      |                                                                                           |
| `withdrawable` | string | Yes      |                                                                                           |
| `margin_used`  | string | Yes      |                                                                                           |
| `perpetuals`   | array  | Yes      | Per-DEX balances; each entry includes `dex`, `equity`, `withdrawable`, and `margin_used`. |
| `spot`         | array  | Yes      | Spot token balances.                                                                      |

See the [OpenAPI schema](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "object": "account",
  "account": "00000000-0000-4000-8000-000000000001",
  "network": "hyperliquid_mainnet",
  "equity": "100",
  "withdrawable": "100",
  "margin_used": "0",
  "perpetuals": [
    { "dex": "", "equity": "100", "withdrawable": "100", "margin_used": "0" },
    { "dex": "xyz", "equity": "0", "withdrawable": "0", "margin_used": "0" }
  ],
  "spot": []
}
```

## Read positions across supported DEXes or filter by DEX

`GET /v1/positions`

Requires `trading:read`.

### Parameters

| Name     | Location | Required | Type    |
| -------- | -------- | -------- | ------- |
| `dex`    | query    | No       | string  |
| `cursor` | query    | No       | string  |
| `limit`  | query    | No       | integer |

### Example request

```bash theme={null}
curl "$LEGEND_API_BASE/v1/positions" \
  -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](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

## List account fills indexed by Legend

`GET /v1/fills`

Requires `trading:read`.

### Parameters

| Name     | Location | Required | Type    |
| -------- | -------- | -------- | ------- |
| `limit`  | query    | No       | integer |
| `cursor` | query    | No       | string  |

### Example request

```bash theme={null}
curl "$LEGEND_API_BASE/v1/fills" \
  -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](/api-reference/trading/openapi.json) for nested response objects and validation patterns.

Illustrative successful response:

```json theme={null}
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```