Account API

Endpoints for fetching account information, positions, orders, fills, and activity.

GET /account

Get account summary including balances, margin, and fee tier.

GET /v1/perps/account?provider=hyperliquid&address=0x1234...

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`address`	query	`string`	Yes	User’s wallet address
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

{
  "provider": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "balances": {
    "perps": [
      { "currency": "USDC", "amount": "10000.00" }
    ],
    "spot": [
      { "currency": "USDC", "amount": "2500.00" },
      { "currency": "ETH", "amount": "2.5" }
    ]
  },
  "marginUsed": "2500.00",
  "unrealizedPnl": "150.00",
  "feeTier": {
    "maker": "0.0002",
    "taker": "0.0005"
  },
  "config": {
    "abstractionStatus": "unifiedAccount",
    "agents": [],
    "builderFeeApproval": {
      "builderAddress": "0x5678901234abcdef5678901234abcdef56789012",
      "maxFeeRate": "0.001",
      "approved": true
    }
  }
}

Positions and orders are fetched via separate endpoints: GET /positions and GET /orders.

SDK: getAccount()

GET /positions

Get the user’s open positions. Results are paginated.

GET /v1/perps/positions?provider=hyperliquid&address=0x1234...

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`address`	query	`string`	Yes	User’s wallet address
`symbol`	query	`string`	No	Filter by asset identifier
`limit`	query	`integer`	No	Items per page (default 50, max 100)
`cursor`	query	`string`	No	Pagination cursor from previous response
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

{
  "provider": "hyperliquid",
  "positions": [
    {
      "asset": {
        "assetId": "BTC",
        "market": "hyperliquid",
        "displaySymbol": "BTC",
        "displayQuote": "USDC"
      },
      "side": "LONG",
      "size": "0.5",
      "entryPrice": "94000.00",
      "markPrice": "95000.50",
      "liquidationPrice": "85000.00",
      "unrealizedPnl": "500.25",
      "leverage": 10,
      "marginUsed": "4700.00",
      "marginMode": "ISOLATED"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false
  }
}

Position fields

Field	Type	Description
`asset`	`AssetDisplay`	Asset identity (see below)
`side`	`'LONG' \| 'SHORT'`	Position direction
`size`	`string`	Position size
`entryPrice`	`string`	Average entry price
`markPrice`	`string`	Current mark price
`liquidationPrice`	`string`	Estimated liquidation price
`unrealizedPnl`	`string`	Unrealized profit/loss
`leverage`	`number`	Current leverage
`marginUsed`	`string`	Margin allocated
`marginMode`	`'ISOLATED' \| 'CROSS'`	Margin mode

AssetDisplay

The AssetDisplay object is used across positions, orders, fills, and activity to identify assets:

Field	Type	Description
`assetId`	`string`	Provider’s canonical identity (e.g., `"BTC"`, `"xyz:PURR"`, `"@142"`)
`market`	`string`	Market category (e.g., `"hyperliquid"`, `"xyz"`, `"spot"`)
`displaySymbol`	`string`	UI-friendly symbol (e.g., `"BTC"`, `"PURR"`)
`displayQuote`	`string \| null`	Quote asset (e.g., `"USDC"`)

SDK: getPositions()

GET /orders

Get the user’s open orders and trigger orders. Results are paginated.

GET /v1/perps/orders?provider=hyperliquid&address=0x1234...

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`address`	query	`string`	Yes	User’s wallet address
`symbol`	query	`string`	No	Filter by asset identifier
`limit`	query	`integer`	No	Items per page (default 50, max 100)
`cursor`	query	`string`	No	Pagination cursor from previous response
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

{
  "provider": "hyperliquid",
  "openOrders": [
    {
      "id": "12345678",
      "asset": {
        "assetId": "ETH",
        "market": "hyperliquid",
        "displaySymbol": "ETH",
        "displayQuote": "USDC"
      },
      "side": "BUY",
      "type": "LIMIT",
      "size": "1.0",
      "price": "3150.00",
      "filledSize": "0",
      "reduceOnly": false,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "triggerOrders": [
    {
      "id": "87654321",
      "asset": {
        "assetId": "BTC",
        "market": "hyperliquid",
        "displaySymbol": "BTC",
        "displayQuote": "USDC"
      },
      "type": "TAKE_PROFIT_MARKET",
      "size": "0.1",
      "triggerPrice": "100000.00",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false
  }
}

OpenOrder fields

Field	Type	Description
`id`	`string`	Order ID
`asset`	`AssetDisplay`	Asset identity
`side`	`'BUY' \| 'SELL'`	Order direction
`type`	`OrderType`	Order type: `MARKET`, `LIMIT`, `STOP_MARKET`, `STOP_LIMIT`, `TAKE_PROFIT_MARKET`, `TAKE_PROFIT_LIMIT`, `TRIGGER_ONLY`
`size`	`string`	Order size
`price`	`string`	Limit price
`filledSize`	`string`	Amount filled
`reduceOnly`	`boolean`	Whether reduce-only
`label`	`string?`	Optional order label
`createdAt`	`string`	ISO 8601 timestamp

TriggerOrder fields

Field	Type	Description
`id`	`string`	Order ID
`asset`	`AssetDisplay`	Asset identity
`type`	`OrderType`	Trigger order type (e.g., `TAKE_PROFIT_MARKET`, `STOP_LIMIT`)
`size`	`string`	Order size
`triggerPrice`	`string`	Price at which the order activates
`limitPrice`	`string?`	Execution limit price (market order if omitted)
`label`	`string?`	Optional order label
`createdAt`	`string`	ISO 8601 timestamp

SDK: getOrders()

GET /fills

Get paginated order fills. Results are sorted by creation time, newest first.

GET /v1/perps/fills?provider=hyperliquid&address=0x1234...&limit=50

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`address`	query	`string`	Yes	User’s wallet address
`startTime`	query	`integer`	No	Filter: orders after this timestamp (ms)
`endTime`	query	`integer`	No	Filter: orders before this timestamp (ms)
`cursor`	query	`string`	No	Pagination cursor from previous response
`limit`	query	`integer`	No	Items per page (default 50, max 100)
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

The filledSize, fee, and realizedPnl fields are optional — they may be absent on cancelled or rejected orders, and realizedPnl is null when the order did not close a position.

{
  "provider": "hyperliquid",
  "items": [
    {
      "id": "12345678",
      "asset": {
        "assetId": "BTC",
        "market": "hyperliquid",
        "displaySymbol": "BTC",
        "displayQuote": "USDC"
      },
      "side": "BUY",
      "type": "MARKET",
      "size": "0.5",
      "price": "94000.00",
      "status": "FILLED",
      "filledSize": "0.5",
      "fee": "4.70",
      "realizedPnl": "125.50",
      "startPosition": "0",
      "classification": "OPENED_LONG",
      "createdAt": "2025-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "cursor": "abc123",
    "nextUrl": "/v1/perps/fills?address=0x1234...&cursor=abc123&limit=50"
  }
}

Fill fields

Field	Type	Description
`id`	`string`	Fill ID
`asset`	`AssetDisplay`	Asset identity
`side`	`'BUY' \| 'SELL'`	Order direction
`type`	`OrderType`	Order type
`size`	`string`	Original order size
`price`	`string`	Fill price
`status`	`FillStatus`	`FILLED`, `PARTIALLY_FILLED`, `CANCELLED`, `REJECTED`
`filledSize`	`string?`	Amount filled (absent if no fills yet)
`fee`	`string?`	Total fees paid (absent if no fills yet)
`realizedPnl`	`string \| null?`	Realized PnL (present only when closing a position, `null` otherwise)
`startPosition`	`string?`	Position size before this fill
`classification`	`FillClassification`	How this fill affected the position (see below)
`createdAt`	`string`	ISO 8601 timestamp

FillClassification

Describes how the fill affected the user’s position:

Value	Description
`OPENED_LONG`	Opened a new long position from zero
`OPENED_SHORT`	Opened a new short position from zero
`INCREASED_LONG`	Added to an existing long position
`INCREASED_SHORT`	Added to an existing short position
`REDUCED_LONG`	Partially closed a long position
`REDUCED_SHORT`	Partially closed a short position
`CLOSED_LONG`	Fully closed a long position
`CLOSED_SHORT`	Fully closed a short position
`SWITCHED_LONG`	Closed a short and opened a long (crossed zero)
`SWITCHED_SHORT`	Closed a long and opened a short (crossed zero)
`SPOT_BUY`	Spot market buy
`SPOT_SELL`	Spot market sell

Pagination

Use the cursor from the response to fetch the next page:

GET /v1/perps/fills?provider=hyperliquid&address=0x1234...&cursor=abc123

When hasMore is false, there are no more pages. SDK: getFills()

GET /activity

Get paginated account activity: deposits, withdrawals, liquidations, and funding payments.

GET /v1/perps/activity?provider=hyperliquid&address=0x1234...

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`address`	query	`string`	Yes	User’s wallet address
`startTime`	query	`integer`	No	Filter: activity after this timestamp (ms)
`endTime`	query	`integer`	No	Filter: activity before this timestamp (ms)
`cursor`	query	`string`	No	Pagination cursor from previous response
`limit`	query	`integer`	No	Items per page (default 50, max 200)
`type`	query	`string[]`	No	Filter by activity type(s): `DEPOSIT`, `WITHDRAWAL`, `FUNDING`, `LIQUIDATION`
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

The response contains a discriminated union of activity items — the type field determines which fields are present.

{
  "provider": "hyperliquid",
  "items": [
    {
      "id": "dep-001",
      "provider": "hyperliquid",
      "type": "DEPOSIT",
      "timestamp": "2025-01-15T10:00:00Z",
      "amount": "5000.00"
    },
    {
      "id": "wd-002",
      "provider": "hyperliquid",
      "type": "WITHDRAWAL",
      "timestamp": "2025-01-14T09:00:00Z",
      "amount": "1000.00",
      "fee": "1.00"
    },
    {
      "id": "fund-003",
      "provider": "hyperliquid",
      "type": "FUNDING",
      "timestamp": "2025-01-14T08:00:00Z",
      "asset": {
        "assetId": "BTC",
        "market": "hyperliquid",
        "displaySymbol": "BTC",
        "displayQuote": "USDC"
      },
      "amount": "-2.50",
      "positionSize": "0.5",
      "fundingRate": "0.0001"
    },
    {
      "id": "liq-004",
      "provider": "hyperliquid",
      "type": "LIQUIDATION",
      "timestamp": "2025-01-13T12:00:00Z",
      "liquidatedNotionalPosition": "50000.00",
      "accountValue": "100.00",
      "leverageType": "Cross",
      "liquidatedPositions": [
        {
          "asset": {
            "assetId": "ETH",
            "market": "hyperliquid",
            "displaySymbol": "ETH",
            "displayQuote": "USDC"
          },
          "size": "10.0"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "cursor": "abc123"
  }
}

Activity Types

All activity items share these base fields:

Field	Type	Description
`id`	`string`	Activity ID
`provider`	`string`	Provider identifier
`type`	`string`	Activity type (discriminator)
`timestamp`	`string`	ISO 8601 timestamp

DEPOSIT — Funds deposited into the DEX account:

Field	Type	Description
`amount`	`string`	Deposit amount

WITHDRAWAL — Funds withdrawn from the DEX account:

Field	Type	Description
`amount`	`string`	Withdrawal amount
`fee`	`string`	Withdrawal fee

FUNDING — Funding payment received or paid on an open position:

Field	Type	Description
`asset`	`AssetDisplay`	Asset identity
`amount`	`string`	Funding amount (negative = paid)
`positionSize`	`string`	Position size at time of funding
`fundingRate`	`string`	Funding rate applied

LIQUIDATION — Position(s) liquidated:

Field	Type	Description
`liquidatedNotionalPosition`	`string`	Total notional value liquidated
`accountValue`	`string`	Account value at time of liquidation
`leverageType`	`string`	Leverage type (e.g., `"Cross"`)
`liquidatedPositions`	`LiquidatedPosition[]`	Positions that were liquidated

Each LiquidatedPosition:

Field	Type	Description
`asset`	`AssetDisplay`	Asset identity
`size`	`string`	Position size liquidated

Pagination

Use the cursor from the response to fetch the next page:

GET /v1/perps/activity?provider=hyperliquid&address=0x1234...&cursor=abc123

When hasMore is false, there are no more pages. SDK: getActivity()

Getting Started

Concepts

Providers

SDK

API Reference

Reference

GET /account

Parameters

Response `200`

GET /positions

Parameters

Response `200`

Position fields

AssetDisplay

GET /orders

Parameters

Response `200`

OpenOrder fields

TriggerOrder fields

GET /fills

Parameters

Response `200`

Fill fields

FillClassification

GET /activity

Parameters

Response `200`

Activity Types

Getting Started

Concepts

Providers

SDK

API Reference

Reference

​GET /account

​Parameters

​Response 200

​GET /positions

​Parameters

​Response 200

​Position fields

​AssetDisplay

​GET /orders

​Parameters

​Response 200

​OpenOrder fields

​TriggerOrder fields

​GET /fills

​Parameters

​Response 200

​Fill fields

​FillClassification

​Pagination

​GET /activity

​Parameters

​Response 200

​Activity Types

​Pagination

GET /account

Parameters

Response `200`

GET /positions

Parameters

Response `200`

Position fields

AssetDisplay

GET /orders

Parameters

Response `200`

OpenOrder fields

TriggerOrder fields

GET /fills

Parameters

Response `200`

Fill fields

FillClassification

Pagination

GET /activity

Parameters

Response `200`

Activity Types

Pagination