# Tracking Hyperliquid Perps in Your Portfolio

> Perp positions are protocol state, not tokens, so most trackers miss them. What Hyperliquid and Lighter positions look like when decoded properly.

- **URL:** https://octav.fi/blog/hyperliquid-perps-portfolio-tracking
- **Published:** 2026-05-02
- **Author:** Octav Team — Portfolio Intelligence for Digital Assets
- **Topic:** DeFi Tracking
- **Tags:** hyperliquid, perps, portfolio-tracking
- **Source:** Octav, Practical guides on crypto NAV reporting, multi-chain portfolio management and digital asset APIs, from the team behind Octav.

---
<LogoRow items="hyperliquid,ethereum" caption="Venues covered" />

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](/crypto-portfolio-api-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

| Component | Why it matters |
| --- | --- |
| Margin / collateral | The capital actually at risk |
| Position size and side | Direction and magnitude of exposure |
| Entry price | Basis for unrealised PnL |
| Unrealised PnL | Moves net worth continuously |
| Funding accrued | Ongoing cost or income of holding |
| Liquidation price | The number risk teams care about |

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](/what-is-crypto-nav-reporting), 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:

```bash
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](/why-portfolio-apis-disagree). For
the other derivatives sector almost nobody covers, see
[Decoding Derive Options in a Crypto Portfolio](/derive-options-portfolio-tracking).