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 balances describe the unified account: equity is spot USDC plus the mark value of other spot tokens and already includes perpetual PnL. cash is spot USDC, withdrawable is unheld USDC, and margin_used sums margin across supported perpetual DEXes. Do not add perpetual equity or PnL again. available_to_trade_estimate matches the app header estimate; it is not market-specific buying power. 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

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",
  "user": {
    "id": "00000000-0000-4000-8000-000000000002",
    "username": "trader",
    "display_name": "Trader"
  },
  "balance_mode": "unified",
  "equity": "100",
  "cash": "100",
  "available_to_trade_estimate": "100",
  "display": {
    "equity": "$100.00",
    "cash": "$100.00",
    "margin_used": "$0.00",
    "available_to_trade_estimate": "$100.00",
    "withdrawable": "$100.00"
  },
  "withdrawable": "100",
  "margin_used": "0",
  "perpetuals": [
    { "dex": "", "equity": "100", "withdrawable": "100", "margin_used": "0" },
    { "dex": "xyz", "equity": "0", "withdrawable": "0", "margin_used": "0" }
  ],
  "spot": [{ "token": "USDC", "total": "100", "held": "0" }]
}

Read positions across supported DEXes or filter by DEX

GET /v1/positions

Requires trading:read.

Parameters

Example request

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

Response

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

Example request

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

Response

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

Illustrative successful response:

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