Account

Fetch account balances, positions, open orders, and trade history

Fetch account balances, positions, open orders, and trade history.

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

getAccount

Returns the full account summary for a DEX including balances, positions, open orders, and fee tier.

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

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

console.log('Balance:', account.balances);
console.log('Margin used:', account.marginUsed);
console.log('Unrealized PnL:', account.unrealizedPnl);
console.log('Positions:', account.positions.length);
console.log('Open orders:', account.openOrders.length);

Parameters

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

Returns

AccountResponse:

Field	Type	Description
dex	string	DEX identifier
address	string	User’s wallet address
balances	Balance[]	Account balances by currency
marginUsed	string	Margin currently in use
unrealizedPnl	string	Total unrealized PnL
feeTier	FeeTier	Maker and taker fee rates
positions	Position[]	Open positions
openOrders	OpenOrder[]	Resting orders
config	object	DEX-specific account configuration (agent status, builder fee, etc.)

Position fields

Field	Type	Description
symbol	string	Trading symbol
assetId	number	Asset ID
dex	string	DEX identifier
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

OpenOrder fields

Field	Type	Description
id	string	Order ID
symbol	string	Trading symbol
assetId	number	Asset ID
dex	string	DEX identifier
side	'BUY' | 'SELL'	Order direction
type	'LIMIT' | 'MARKET'	Order type
size	string	Order size
price	string	Limit price
filledSize	string	Amount filled
reduceOnly	boolean	Whether reduce-only
createdAt	string	ISO 8601 timestamp

API Reference: GET /account

---

getHistory

Returns paginated historical orders. Results are sorted by creation time, newest first.

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

const history = await getHistory(client, {
  dex: 'hyperliquid',
  address: userAddress,
  limit: 50,
});

for (const item of history.items) {
  console.log(item.symbol, item.side, item.status, item.realizedPnl);
}

// Pagination
if (history.pagination.hasMore) {
  const nextPage = await getHistory(client, {
    dex: 'hyperliquid',
    address: userAddress,
    cursor: history.pagination.cursor,
  });
}

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.dex	string	Yes	DEX identifier
params.address	string	Yes	User’s wallet address
params.cursor	string	No	Pagination cursor from previous response
params.limit	number	No	Items per page (default 50, max 100)
params.startTime	number	No	Filter: orders after this timestamp (ms)
params.endTime	number	No	Filter: orders before this timestamp (ms)
options	SDKRequestOptions	No	Request options

Returns

HistoryResponse:

Field	Type	Description
dex	string	DEX identifier
items	HistoryItem[]	Historical orders
pagination	Pagination	Pagination metadata

HistoryItem fields

Field	Type	Description
id	string	Order ID
symbol	string	Trading symbol
assetId	number	Asset ID
dex	string	DEX identifier
side	'BUY' | 'SELL'	Order direction
type	'MARKET' | 'LIMIT'	Order type
size	string	Original order size
price	string	Order price
status	HistoryItemStatus	FILLED, PARTIALLY_FILLED, CANCELLED, REJECTED (subset of OrderStatus — only terminal states appear in history)
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)
createdAt	string	ISO 8601 timestamp

Pagination fields

Field	Type	Description
limit	number	Items per page
hasMore	boolean	Whether more pages exist — use this as the authoritative check
cursor	string?	Cursor for next page (pass to getHistory for the next page)
nextUrl	string?	Full URL for next page (may be absent)

API Reference: GET /history