Account data shapes - @lifi/perps-sdk

Account-level reads — account summary, positions, orders, fills, activity, and single-order lookup — are served by the SDK directly from each provider via @lifi/perps-sdk (getAccount, getPositions, getOrders, getFills, getActivity, getOrder). They are not LI.FI HTTP endpoints. This page documents the data shapes those calls return.

getAccount

Returns the account summary including balances, margin, and fee tier.

const account = await getAccount(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
});

Parameters

Name	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address

Shape

{
  "provider": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "balances": [
    {
      "categoryId": "perps",
      "asset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" },
      "units": "10000.00",
      "valueUsd": "10000.00"
    }
  ],
  "collateralBalances": [
    {
      "categoryId": "spot",
      "asset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" },
      "units": "2500.00",
      "valueUsd": "2500.00"
    }
  ],
  "marginUsed": "2500.00",
  "unrealizedPnl": "150.00",
  "feeTier": {
    "maker": "0.0002",
    "taker": "0.0005"
  },
  "config": {
    "provider": "hyperliquid",
    "abstractionMode": "unifiedAccount",
    "agents": [],
    "builderFeeApproval": {
      "builderAddress": "0x5678901234abcdef5678901234abcdef56789012",
      "maxFeeRate": "0.001",
      "approved": true
    }
  }
}

AccountResponse fields

Field	Type	Description
`provider`	`string`	Provider identifier
`address`	`string`	User’s wallet address
`balances`	`Balance[]`	Flat, non-collateral holdings. Each `Balance` is `{ categoryId, asset, units, valueUsd }`.
`collateralBalances`	`Balance[]`	SDK-determined collateral subset (spot balances in a category’s quote asset).
`marginUsed`	`string`	Total margin used across all positions
`unrealizedPnl`	`string`	Total unrealized PnL across all positions
`feeTier`	`FeeTier`	Maker and taker fee rates
`config`	`AccountConfig`	Provider-specific account state — see AccountConfig

AccountConfig

Discriminated union of per-provider account configuration state. Narrow with config.provider === '<key>' to access provider-specific fields. Hyperliquid (provider: "hyperliquid"):

Field	Type	Description
`provider`	`"hyperliquid"`	Discriminator
`abstractionMode`	`string \| null`	Active abstraction variant (e.g. `"unifiedAccount"`, `"dexAbstraction"`, `"disabled"`). `null` when abstraction has never been set — the widget falls back to the descriptor’s `default` `ParamOption`.
`agents`	`HyperliquidAgent[]`	Currently-authorised agent wallets. The `approveAgent` setup descriptor consults this to detect expiry.
`builderFeeApproval`	`HyperliquidBuilderFeeApproval?`	Builder fee approval state. Absent when no builder is configured.

Lighter (provider: "lighter"):

Field	Type	Description
`provider`	`"lighter"`	Discriminator
`accountIndex`	`number`	L2 integer account identifier — used by the SDK for WASM signing and by the widget when rendering transfer counterparties
`apiKeyIndex`	`number`	Slot the SDK has registered (or will register) the session API key in
`apiKeyRegistered`	`boolean`	Whether a key is currently live in `apiKeyIndex`. The `registerApiKey` setup descriptor consults this to gate trading.
`accountType`	`number`	Raw integer fee/latency tier from Lighter’s `/api/v1/account.account_type`. Decoded to a human label by the widget once Lighter publishes the numeric→string mapping.

Positions and orders are fetched separately: getPositions and getOrders.

SDK: getAccount()

getPositions

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

const result = await getPositions(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
});

Parameters

Name	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`marketId`	`string`	No	Filter by the canonical `Market.id` (not display symbol)
`limit`	`integer`	No	Items per page (default 50, max 100)
`cursor`	`string`	No	Pagination cursor from previous response

Shape

{
  "provider": "hyperliquid",
  "positions": [
    {
      "market": {
        "providerId": "hyperliquid",
        "id": "BTC",
        "categoryId": "hyperliquid",
        "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" },
        "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
      },
      "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
`market`	`MarketDisplay`	Market reference (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

MarketDisplay

The MarketDisplay object is used across positions, orders, fills, and activity to identify the market and its underlying assets:

Field	Type	Description
`providerId`	`string`	Provider that owns the market (e.g., `"hyperliquid"`)
`id`	`string`	Provider’s canonical, stringified market id that uniquely identifies the trading instrument (e.g., `"BTC"`, `"xyz:PURR"`, `"@142"`; numeric on Lighter)
`categoryId`	`string`	Provider category id (e.g., `"hyperliquid"`, `"xyz"`, `"spot"`)
`baseAsset`	`Asset`	Base leg of the market
`quoteAsset`	`Asset`	Quote leg of the market

SDK: getPositions()

getOrders

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

const result = await getOrders(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
});

Parameters

Name	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`marketId`	`string`	No	Filter by the canonical `Market.id` (not display symbol)
`limit`	`integer`	No	Items per page (default 50, max 100)
`cursor`	`string`	No	Pagination cursor from previous response

Shape

{
  "provider": "hyperliquid",
  "openOrders": [
    {
      "orderId": "12345678",
      "market": {
        "providerId": "hyperliquid",
        "id": "ETH",
        "categoryId": "hyperliquid",
        "baseAsset": { "providerId": "hyperliquid", "id": "ETH", "displaySymbol": "ETH", "logoURI": "https://assets.li.fi/tokens/eth.png" },
        "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
      },
      "side": "BUY",
      "type": "LIMIT",
      "size": "1.0",
      "price": "3150.00",
      "filledSize": "0",
      "reduceOnly": false,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "triggerOrders": [
    {
      "orderId": "87654321",
      "market": {
        "providerId": "hyperliquid",
        "id": "BTC",
        "categoryId": "hyperliquid",
        "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" },
        "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
      },
      "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
`orderId`	`string`	Order ID
`market`	`MarketDisplay`	Market reference
`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
`orderId`	`string`	Order ID
`market`	`MarketDisplay`	Market reference
`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()

getFills

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

const fills = await getFills(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
  limit: 50,
});

Parameters

Name	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`startTime`	`integer`	No	Filter: fills after this timestamp (ms)
`endTime`	`integer`	No	Filter: fills before this timestamp (ms)
`cursor`	`string`	No	Pagination cursor from previous response
`limit`	`integer`	No	Items per page (default 50, max 100)

Shape

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",
      "orderId": "12340001",
      "market": {
        "providerId": "hyperliquid",
        "id": "BTC",
        "categoryId": "hyperliquid",
        "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" },
        "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
      },
      "side": "BUY",
      "type": "MARKET",
      "size": "0.5",
      "price": "94000.00",
      "status": "FILLED",
      "liquidity": "taker",
      "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"
  }
}

Fill fields

Field	Type	Description
`id`	`string`	Fill ID
`orderId`	`string`	ID of the parent order
`market`	`MarketDisplay`	Market reference
`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`
`liquidity`	`LiquidityRole`	`'maker'` or `'taker'` — whether the fill provided or removed liquidity
`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
`explorerLink`	`string?`	Block-explorer URL for the settling on-chain tx. Absent when the fill has no on-chain tx (every Hyperliquid fill is off-chain).

FillClassification

Describes how the fill affected the user’s position. Wire values are Title Case strings:

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:

const nextPage = await getFills(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
  cursor: 'abc123',
});

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

getActivity

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

const activity = await getActivity(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
});

Parameters

Name	Type	Required	Description
`provider`	`string`	Yes	Provider identifier
`address`	`string`	Yes	User’s wallet address
`startTime`	`integer`	No	Filter: activity after this timestamp (ms)
`endTime`	`integer`	No	Filter: activity before this timestamp (ms)
`cursor`	`string`	No	Pagination cursor from previous response
`limit`	`integer`	No	Items per page (default 50, max 200)
`type`	`ActivityType[]`	No	Filter by activity type(s): `DEPOSIT`, `WITHDRAWAL`, `FUNDING`, `LIQUIDATION`, `TRANSFER`

Shape

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",
      "market": {
        "providerId": "hyperliquid",
        "id": "BTC",
        "categoryId": "hyperliquid",
        "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" },
        "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
      },
      "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": [
        {
          "market": {
            "providerId": "hyperliquid",
            "id": "ETH",
            "categoryId": "hyperliquid",
            "baseAsset": { "providerId": "hyperliquid", "id": "ETH", "displaySymbol": "ETH", "logoURI": "https://assets.li.fi/tokens/eth.png" },
            "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
          },
          "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
`explorerLink`	`string?`	Block-explorer URL for the on-chain deposit tx

WITHDRAWAL — Funds withdrawn from the DEX account:

Field	Type	Description
`amount`	`string`	Withdrawal amount
`fee`	`string`	Withdrawal fee
`explorerLink`	`string?`	Block-explorer URL for the on-chain withdrawal tx

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

Field	Type	Description
`market`	`MarketDisplay`	Market reference
`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
`market`	`MarketDisplay`	Market reference
`size`	`string`	Position size liquidated

TRANSFER — Internal transfer between two accounts on the same provider (currently emitted by Lighter only; the type definition supports Hyperliquid as well). Direction is relative to the queried account. The counterparty is identified by either an account index (integer L2 account identifier — Lighter) or a wallet address (Hyperliquid, where accounts ARE addresses). The shape is a discriminated union: at least one of counterpartyAccountIndex / counterpartyAddress MUST be present, and either may appear alone or alongside the other. Consumers that render counterparties should prefer counterpartyAccountIndex when present (canonical handle on index-based providers) and fall back to a truncated counterpartyAddress otherwise.

Field	Type	Description
`direction`	`'IN' \| 'OUT'`	Direction relative to the queried account
`counterpartyAccountIndex`	`number?`	The other side’s account index (required when `counterpartyAddress` is absent)
`counterpartyAddress`	`string?`	The other side’s wallet address (required when `counterpartyAccountIndex` is absent)
`asset`	`string`	Asset symbol (e.g., `"USDC"`)
`amount`	`string`	Transfer amount
`meta`	`object?`	Provider-specific metadata
`explorerLink`	`string?`	Block-explorer URL for the on-chain transfer tx

Pagination

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

const nextPage = await getActivity(client, {
  provider: 'hyperliquid',
  address: '0x1234...',
  cursor: 'abc123',
});

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

​getAccount

​Parameters

​Shape

​AccountResponse fields

​AccountConfig

​getPositions

​Parameters

​Shape

​Position fields

​MarketDisplay

​getOrders

​Parameters

​Shape

​OpenOrder fields

​TriggerOrder fields

​getFills

​Parameters

​Shape

​Fill fields

​FillClassification

​Pagination

​getActivity

​Parameters

​Shape

​Activity Types

​Pagination

getAccount

Parameters

Shape

AccountResponse fields

AccountConfig

getPositions

Parameters

Shape

Position fields

MarketDisplay

getOrders

Parameters

Shape

OpenOrder fields

TriggerOrder fields

getFills

Parameters

Shape

Fill fields

FillClassification

Pagination

getActivity

Parameters

Shape

Activity Types

Pagination