How to Build a Hyperliquid Portfolio Tracker
Build a portfolio tracker for Hyperliquid: perps on every DEX, spot balances, vaults and staking, and the account modes that change what a balance means.
Almost half of Hyperliquid's most active traders keep their money in spot. Of the 500 most active accounts we checked for the delta-neutral guide, 224 used a unified or portfolio-margin account, and for those the perps request most trackers rely on shows only the margin in open positions. A portfolio tracker that adds up perp account value alone shows those users a near-empty balance, which to them looks like lost money.
That is why a Hyperliquid portfolio tracker is harder than the usual wallet front page of positions, balances and yesterday's value. One address can hold value in seven places: the main perp DEX, each of the 10 HIP-3 DEXs run by other teams, spot, vaults, staking, lending and sub-accounts. This guide reads all of them for 20 wallets, on the official API and on Hydromancer, and checks the two outputs match line for line.
Why build it on Hyperliquid
• All you need is an address. Every balance and position is public, so there's no login or exchange key to ask users for.
• It's the screen users open first, and the one they open every day if it's right. The trade button sits right next to it.
• Wallets prove it. Phantom, MetaMask, Trust Wallet and Rabby have collected $43.21M in builder fees between them, Flowscan's 2 October 2026 snapshot shows (top builders by revenue), and a wallet's perps tab starts with the user's own positions and balances.
This is different from a whale tracker, which watches other people. A portfolio tracker reads your users' own wallets, so it has to be complete: a missing balance looks like lost money.
Where a Hyperliquid account keeps things
One address can hold value in several places, and each has its own request on the official API:
| Where | Official request |
|---|---|
| Perp positions on the main DEX | clearinghouseState |
| Perp positions on each HIP-3 DEX | clearinghouseState with dex, once per DEX |
| Spot balances | spotClearinghouseState |
| Vault deposits | userVaultEquities |
| Staked HYPE | delegatorSummary |
| Lending and borrowing | borrowLendUserState |
| Sub-accounts | subAccounts, then all of the above per sub-account |
The HIP-3 row is the easy one to miss. Hyperliquid had 10 HIP-3 DEXs alongside the main one when we tested, and a position on any of them only shows when you ask that DEX.
Read the account mode first
Hyperliquid accounts work in different modes, and the mode changes what the numbers mean. In a unified or portfolio-margin account, the balance sits in spot, and clearinghouseState alone shows only the margin in open positions. That is the 45% of active traders from the top of this post: add up perps account value without spot and they look almost empty.
userAbstraction returns the mode on the official API ({"type": "userAbstraction", "user": "0x…"}). Hydromancer's batchPortfolioStates includes it for every wallet, in the userAbstraction field: default, unifiedAccount, portfolioMargin or disabled (and dexAbstraction, a legacy mode).
Twenty wallets, every DEX, two ways
Twelve requests per wallet
One clearinghouseState request per DEX per wallet, plus one for spot:
import requests
URL = "https://api.hyperliquid.xyz/info"
dexs = [""] + [d["name"] for d in requests.post(
URL, json={"type": "perpDexs"}).json() if d]
for u in open("wallets.txt").read().split()[:20]:
n = 0
for dex in dexs: # one request per DEX
st = requests.post(URL, json={"type": "clearinghouseState",
"user": u, "dex": dex}).json()
n += len(st["assetPositions"])
spot = requests.post(URL, json={"type": "spotClearinghouseState",
"user": u}).json()
print(u[:10], n, "positions,", len(spot["balances"]), "spot balances")One request for all twenty
batchPortfolioStates with "dex": "ALL_DEXES" returns perps on every DEX, spot balances and the account mode for up to 100 wallets in one request (500 for the main DEX only). Here it is:
import os, requests
H = {"Authorization": "Bearer " + os.environ["HYDROMANCER_API_KEY"]}
users = open("wallets.txt").read().split()[:20]
r = requests.post("https://api.hydromancer.xyz/info", headers=H, json={
"type": "batchPortfolioStates", "users": users, "dex": "ALL_DEXES"})
for u, st in r.json()["successful_states"]:
n = sum(len(s["assetPositions"])
for s in st["clearinghouseState"].values())
print(u[:10], n, "positions,",
len(st["spotClearinghouseState"]["balances"]), "spot balances")Both printed the same 20 lines, wallet for wallet. The first few:
0x46921f69 22 positions, 1 spot balances
0xf5d81a13 28 positions, 2 spot balances
0xecb63caa 132 positions, 40 spot balances
0xcf3f419d 1 positions, 0 spot balances
0x25773676 180 positions, 165 spot balances
... (15 more lines)How we tested. The job: every perp position and spot balance for 20 wallets, across every DEX. We ran it on both APIs on 31 October 2026 and checked the two outputs matched line for line. The examples that read a .txt file expect one full wallet address per line. To try them, take addresses (each row's ethAddress) from Hyperliquid's public leaderboard file, https://stats-data.hyperliquid.xyz/Mainnet/leaderboard. The snippets are prototypes that prove each step works, not an app to copy as is; the request bodies and URLs are exact.
batchPortfolioStates is a Hydromancer endpoint, not part of Hyperliquid's own API. Orders still go to Hyperliquid.
Side by side
| Hyperliquid API | Hydromancer batchPortfolioStates | |
|---|---|---|
| Result | 20 wallets, every DEX | The same 20 lines |
| Requests | 241 | 1 |
| Time | 42 s | 0.2 s |
| Rate-limit cost | 500 weight of 1,200/min per IP | 200 points of 20,000/min (Growth plan) |
Identical output, so the choice is about scale. For one user's live screen, the official API has a faster route than the loop: the allDexsClearinghouseState subscription streams one user's state on every DEX at once (Hyperliquid stopped at 15 users per IP in our tests). For a tracker with many users, the loop's request count is the limit: at 25 weight per wallet, one IP can refresh about 48 wallets a minute. A Hyperliquid node you run yourself with --serve-info answers these requests locally without that limit; Hyperliquid recommends 16 CPU cores, 128 GB of memory and 500 GB of disk for one.
What to show for each position
Each perp position in clearinghouseState already carries what a trader looks at first: size, entry price, unrealized PnL, return on equity, leverage, liquidation price, margin used and funding paid since it opened. Show the distance to the liquidation price as a percentage; it's the number users act on. Divide the gap between the current price and liquidationPx by the current price, where the current price is positionValue divided by the absolute size (abs(szi), since shorts are negative). liquidationPx is empty for positions with no liquidation price, so skip those. Add alerts on top: a position within 10% of liquidation, a large unrealized loss, or a new position on a wallet they follow.
Value over time
Users want to see yesterday and last month, not just now. For the chart, Hyperliquid's portfolio request gives you account value and PnL over four windows, from a day to all time. For your own daily snapshots, store the totals once a day. For history from before a user joined, Reservoir has daily account value snapshots for every wallet from August 2025 (Reservoir is free; you pay only AWS download charges).
Put a "trade" or "close" button beside each position and attach your builder code to those orders, the same model the wallets above use.
FAQ
How do I get every position a Hyperliquid wallet holds?
Ask each perp DEX with clearinghouseState and dex, plus spotClearinghouseState for spot: 12 requests per wallet in our test. Or stream allDexsClearinghouseState for one user, or use Hydromancer's batchPortfolioStates with ALL_DEXES for up to 100 wallets in one request. Vaults, staking and lending are separate requests on both APIs.
Why does a wallet show almost no balance on Hyperliquid's API?
Check whether it's a unified or portfolio-margin account, where the balance sits in spot. Read spotClearinghouseState too, and check the mode with userAbstraction.
Do I need the user's keys to track their portfolio?
No. A wallet address is enough; everything is public.
Related reading
• Hyperliquid whale tracker
• Hyperliquid vaults API
• HyperCore vs HyperEVM
• How to query Reservoir's Hyperliquid data
Sources
- Hyperliquid docs: Info endpoint, Subscriptions
- Hydromancer docs: portfolioState, batchPortfolioStates
Read next

How to Build a Hyperliquid TWAP Execution Tool
Build a TWAP execution tool on Hyperliquid: native TWAP orders vs your own slicing, tracking slice fills, and seeing every active TWAP in a market.

How to Build a Trading Terminal on Hyperliquid
Build a Hyperliquid trading terminal: charts, order book, trades and order entry, plus 1-second candles and older chart history. Tested on both APIs.

How to Build a Trading Journal for Hyperliquid
Build a Hyperliquid trading journal: turn fills into closed trades with entry, exit, fees, funding and hold time, and keep history past 10,000 fills.