Account, positions, and fills

All paths are relative to the base URL. See authentication and errors and idempotency. 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

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 for nested response objects and validation patterns. Illustrative successful response:

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

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 for nested response objects and validation patterns. Illustrative successful response:

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

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 for nested response objects and validation patterns. Illustrative successful response:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

​Read account balances

​Example request

​Response

​Read positions across supported DEXes or filter by DEX

​Parameters

​Example request

​Response

​List account fills indexed by Legend

​Parameters

​Example request

​Response

Read account balances

Example request

Response

Read positions across supported DEXes or filter by DEX

Parameters

Example request

Response

List account fills indexed by Legend

Parameters

Example request

Response