Tracking Hyperliquid Perps in Your Portfolio

A perpetual futures position does not exist as a token in your wallet. It is state inside a protocol: margin posted, size, entry price, funding accrued, unrealised PnL. Nothing about it shows up in a balance query.

That is why perp traders routinely see their net worth read low. In our benchmark, a Hyperliquid trading wallet read ~$27k through token-only APIs against $56k when the positions were actually decoded.

What a decoded perp position contains

Reporting only the collateral — which is the common failure — tells you what you deposited, not what you have. A profitable position reads low; a losing one reads high. Both are wrong, and neither is flagged as incomplete.

Why exposure matters more than value here

For spot holdings, value and exposure are the same number. For perps they are not, and a portfolio system that reports only value is not enough for risk.

A wallet with $50k of margin might carry $500k of notional exposure. The portfolio line says $50k. The risk question — what happens if ETH moves 10% — depends on the notional, the side and the liquidation price.

If you are producing NAV, both matter: value flows into the NAV calculation, while exposure feeds position limits and risk reporting.

Hyperliquid and Lighter

Hyperliquid is a chain as well as an exchange, which is part of why coverage is patchy — a provider needs Hyperliquid support as a distinct integration, not as another EVM RPC endpoint. Lighter has the same problem for the same reason.

Octav decodes both, in the same call as EVM and Solana positions:

curl -s https://api.octav.fi/v1/portfolio \
  -H "Authorization: Bearer $OCTAV_API_KEY" \
  -G --data-urlencode "addresses=0xYourAddress"

Perp positions come back inside the same response shape as lending and LP positions, categorised by protocol, rather than requiring a separate endpoint or a separate provider.

Checking whether your provider covers perps

The test takes five minutes:

1. Open a small perp position on Hyperliquid.
2. Query your portfolio API for that address.
3. Compare against the Hyperliquid UI.

If the API returns only your deposited collateral — or nothing at all — perps are not covered. Note that the API will not error. It will return a portfolio that looks complete.

For the general shape of this problem across sectors, see Why Portfolio APIs Disagree About Net Worth. For the other derivatives sector almost nobody covers, see Decoding Derive Options in a Crypto Portfolio.