getAccount

Fetch account balances, margin, and fee tier

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

The examples on this page use Hyperliquid (provider: 'hyperliquid'). Replace the provider value with any supported provider 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	Provider identifier
params.address	Address	Yes	User’s wallet address (viem 0x${string})
options	SDKRequestOptions	No	Request options

Returns

AccountResponse:

Field	Type	Description
provider	string	Provider identifier
address	Address	User’s wallet address
balances	Balance[]	Flat, non-collateral holdings, non-zero units only
collateralBalances	Balance[]	SDK-determined collateral subset, non-zero units only. An entry is a held collateral balance: it can be a non-quote asset and can be unpriced (price absent, valueUsd '0'). It is not buying power — read AccountSummary.availableMargin for that.
positions	Position[]	Open positions the snapshot already computed; equals the unfiltered getPositions() output
marginUsed	string?	Margin currently in use. Absent when the venue reports none.
unrealizedPnl	string?	Total unrealized PnL. Absent when the venue reports none.
feeTier	FeeTier	Maker and taker fee rates
config	AccountConfig	Provider-specific account state — a discriminated union over provider. Narrow with config.provider === 'hyperliquid' / 'lighter' / 'ondo' 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
price	string?	USD price of one unit. Absent when the provider holds no price for the asset.
transferable	string	Part of units the venue releases from this category in a category transfer, from 0 to units. Every collateral row and every spot row carries it.

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

Throws

Hyperliquid getAccount throws AccountNotFound when preTransferCheck.userExists is false, before reading account data. Lighter getAccount throws the same code when the wallet has no Lighter account and Unauthorized when Lighter rejects the resolved token used for its fee-tier read. Ondo getAccount remains a status read and returns its logged-out account value without a session.

See Account access for the provider-specific status-read and data-read contract.

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[]	One entry per setup descriptor (e.g. accountMode), with its current values and satisfied. For per-market leverage and margin mode use getMarketSettings.

PerpsClient.getAccountSummary

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

const account = await perps.getAccount({ provider: 'hyperliquid', address: userAddress });
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, as the venue reports or the SDK computes it
availableMargin	string	The account-scoped margin figure the venue publishes for new orders
marginUsed	string	The venue’s own total margin used across open positions
unrealizedPnl	string	The venue’s own total unrealized PnL across open positions

Each provider reads these figures from its own venue fields. See Hyperliquid, Ondo, and Lighter for the exact source of each value on that venue.

To size an order on one market, read getAvailableToTrade() instead. availableMargin stays account-scoped. getAvailableToTrade() returns the per-market amount an order panel needs.

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	Provider identifier
address	Address	Yes	User’s wallet address

Returns: Promise<boolean> — the SDK delegates the check to the registered provider plugin’s own accountExists probe. Each provider defines the probe differently: Hyperliquid checks preTransferCheck.userExists; Ondo sends an authenticated /v1/account request and returns false when there is no session. The method throws when no plugin is registered for provider, or when the plugin’s probe itself fails.

Venue reads can lag a write (order placement, updateLeverage, sendAsset, margin updates) by a couple of seconds. After a write, apply the change optimistically and re-read once after a short delay instead of immediately. See Streaming.

Data shapes: getAccount — a direct-to-provider read, not a LI.FI HTTP endpoint.