getAccount

Fetch account balances, margin, and fee tier

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

The examples on this page use Hyperliquid (provider: 'hyperliquid'). Replace the provider value with any supported DEX from getProviders().

import { getAccount } from '@lifi/perps-sdk';

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

console.log('Balances:', account.balances); // Balance[]
console.log('Collateral:', account.collateralBalances); // Balance[]
console.log('Margin used:', account.marginUsed);
console.log('Unrealized PnL:', account.unrealizedPnl);

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client from createPerpsClient()
params.provider	string	Yes	DEX identifier
params.address	string	Yes	User’s wallet address
options	SDKRequestOptions	No	Request options

Returns

AccountResponse:

Field	Type	Description
provider	string	Provider identifier
address	string	User’s wallet address
balances	Balance[]	Flat, non-collateral holdings
collateralBalances	Balance[]	SDK-determined collateral subset (spot balances in a category’s quote asset)
positions	Position[]	Open positions the snapshot already computed; equals the unfiltered getPositions() output
marginUsed	string	Margin currently in use
unrealizedPnl	string	Total unrealized PnL
feeTier	FeeTier	Maker and taker fee rates
config	AccountConfig	Provider-specific account state — a discriminated union over provider. Narrow with config.provider === 'hyperliquid' / 'lighter' to access provider-specific fields. See AccountConfig.

Each Balance:

Field	Type	Description
categoryId	string	Which category/venue this balance sits in — references a ProviderCategory
asset	Asset	The held asset
units	string	Amount held, in asset units
valueUsd	string	USD value of the holding

The positions array mirrors the unfiltered getPositions() output. Orders are fetched separately via getOrders().

PerpsClient.getAccount

The PerpsClient method wraps the standalone getAccount and additionally resolves the account’s setting descriptors. It returns a GetAccountResult — every AccountResponse field plus a settings array.

const result = await perps.getAccount({
  provider: 'hyperliquid',
  address: userAddress,
});

console.log(result.balances); // AccountResponse fields, as above
console.log(result.settings); // AccountConfigSetting[]

Field	Type	Description
(AccountResponse)		All fields from the standalone getAccount return above
settings	AccountConfigSetting[]	Resolved per-account setting descriptors (e.g. leverage, margin mode)

PerpsClient.getAccountSummary

Derives portfolio-level totals from an already-fetched account snapshot and its positions. Pure computation — makes no network request.

const summary = perps.getAccountSummary(account, account.positions);

Parameter	Type	Required	Description
account	AccountResponse	Yes	Snapshot from getAccount
positions	Position[]	Yes	Positions to summarize

Returns: AccountSummary:

Field	Type	Description
portfolioValue	string	Total account value in USD
availableMargin	string	Margin available for new positions
marginUsed	string	Margin currently in use
unrealizedPnl	string	Total unrealized PnL across positions

accountExists

Thin existence check for a provider account at address — useful for gating signing-mode or onboarding flows on whether the user has any account state with the provider yet.

const exists = await perps.accountExists('hyperliquid', userAddress);

Parameter	Type	Required	Description
provider	string	Yes	DEX identifier
address	string	Yes	User’s wallet address

Returns: Promise<boolean> — true when getAccount resolves, false when the backend reports PerpsErrorCode.AccountNotFound. Any other error (transport, validation, server) is re-thrown.

API Reference: GET /account