getPortfolioHistory

Fetch the account’s portfolio value and cumulative PnL over a lookback window

Returns the account’s portfolio value and cumulative PnL over a lookback window. Points appear oldest first. The read goes direct to the provider.

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

getPortfolioHistory is a method on PerpsClient (not on the low-level PerpsSDKClient), not a standalone imported function. It throws an SDKError when the provider does not implement the read.

const history = await perps.getPortfolioHistory({
  provider: 'hyperliquid',
  address: userAddress,
  range: '30d',
});

for (const point of history.points) {
  console.log(point.timestamp, point.accountValue, point.pnl);
}

console.log('Total PnL for the window:', history.totalPnl);

Parameters

Parameter	Type	Required	Description
params.provider	string	Yes	Provider identifier
params.address	Address	Yes	User’s wallet address (viem 0x${string})
params.range	PortfolioHistoryRange	Yes	Lookback window — see PortfolioHistoryRange
options	SDKRequestOptions	No	Request options

PortfolioHistoryRange

PortfolioHistoryRange is a string union imported from @lifi/perps-sdk.

Value	Description
'24h'	Last 24 hours
'7d'	Last 7 days
'30d'	Last 30 days
'all'	Provider-defined coverage — not guaranteed to be the full account history

Returns

PortfolioHistoryResponse:

Field	Type	Description
range	PortfolioHistoryRange	The window the response covers
points	PortfolioHistoryPoint[]	Samples over the window, oldest first
volume	string?	Window trading volume in USD. Absent when the provider does not report it.
totalPnl	string?	Cumulative PnL for the full window in USD. Absent when the provider does not report it.

PortfolioHistoryPoint fields

Field	Type	Description
timestamp	number	Unix milliseconds
accountValue	string	Portfolio value in USD at this point
pnl	string	Cumulative PnL in USD from the start of the requested window

Point spacing and all coverage are provider-defined. totalPnl is the last pnl sample.

• Hyperliquid: non-unified accounts read the perps-only window; unified and portfolio-margin accounts read the combined window, so the scope of accountValue depends on the account mode.
• Lighter: bucket resolution is 24h → 1h, 7d → 1h, 30d → 1d, and all → up to 1000 daily buckets.

Auth requirements

Each provider reads portfolio history with its own credential. The requirement is per provider.

Hyperliquid

Hyperliquid needs no auth. The SDK reads portfolio history from a public Hyperliquid info endpoint using only the account address.

Ondo

Ondo needs an active session. The user signs in with siweLogin before this call. A call with no stored session throws SetupRequired. A call with a session that Ondo rejects throws Unauthorized.

Lighter

Lighter needs the account auth token or the read-only token. The SDK resolves a token from its stored key automatically. A call with no resolvable token throws SetupRequired, a token that Lighter rejects throws Unauthorized, and a wallet with no Lighter account throws AccountNotFound.

Throws

PerpsError with one code for the account’s access state. See Account access.

• SetupRequired — the venue needs a credential (a Lighter auth token or an Ondo session) and none is stored.
• Unauthorized — the venue rejects the credential.
• AccountNotFound — the wallet has no venue account.