How to Get a Hyperliquid Wallet's Trade History (API + Bulk)
Learn how to get a Hyperliquid wallet's trade history by API: userFills, paging with userFillsByTime, reaching older fills, and turning fills into PnL by market.
A trading journal, a tax export or a PnL dashboard all start with the same thing: a wallet's complete trade history. On Hyperliquid, that history is the wallet's fills, one record each time an order executes, and getting every one of them takes more than one request.
Hyperliquid trade history: any wallet, not just yours
On a centralized exchange (CEX), the trade API usually covers only your own account. Hyperliquid runs its order books on-chain, so every wallet's trades are public:
| Trade history on Hyperliquid | Trade history on a CEX | |
|---|---|---|
| Whose trades you can read | Any wallet's, through the free API | Usually only your own account's |
| How you get it | Public API requests, no key needed | Typically an API key for your own account |
| What each trade includes | Price, size, side, fee and realized PnL per fill | Depends on the exchange |
That makes it possible to study any trader, audit a vault, or build analytics across many wallets.
Below, we get a wallet's latest fills, page further back, and turn fills into realized PnL by market. Then we look at how to reach history older than Hyperliquid keeps. Outputs are from our test runs.
Which request gets a wallet's fills
| You want | Use | Reach |
|---|---|---|
| The latest fills | userFills | Up to the 2,000 most recent |
| A time range | userFillsByTime | 2,000 per call, the 10,000 most recent in total |
| TWAP slice fills | userTwapSliceFills | Up to the 2,000 most recent |
| Older history | Hydromancer's API | From 28 July 2025 |
| A one-off bulk export | Reservoir daily files | From 28 July 2025 |
The limits come from Hyperliquid's info endpoint docs. If you want an alert the moment a wallet trades, rather than its history, see our whale tracker guide.
The snippets need requests, and HYDROMANCER_API_KEY for the Hydromancer one. Names in capitals, like USER, are placeholders for your own values.
Step 1: Get a wallet's latest fills with userFills
The quickest way to see what a wallet traded is userFills. One request returns its most recent fills, newest first, for any public address:
import requests
fills = requests.post(
"https://api.hyperliquid.xyz/info",
json={"type": "userFills", "user": USER},
).json()
f = fills[0]
print(len(fills), "fills, newest first. Latest:", f["coin"], f["dir"],
f["sz"], "@", f["px"], "| fee", f["fee"], f["feeToken"])2000 fills, newest first. Latest: BTC Open Long 0.14883 @ 80294.0 | fee 4.302056 USDCUSER is any wallet address; we used an active public one. If you get 2,000 back, you've hit the cap, and older fills aren't in this response. For an active wallet, that can be only a few days.
The fields you'll use:
| Field | Meaning |
|---|---|
coin | The market: BTC , xyz:SP500 for HIP-3, @107 for a spot pair |
px, sz | Fill price and size, as strings |
dir | Open Long , Close Short , Buy , Sell and so on |
closedPnl | Realized PnL from this fill, before fees |
fee, feeToken | The fee, usually in USDC. Negative means a rebate |
crossed | true for a taker fill, false for a maker fill |
time, oid, tid | Fill time (ms), order ID, trade ID |
Two things trip people up. closedPnl doesn't include fees, so subtract fee yourself, converting first if feeToken isn't USDC. And funding isn't in fills at all; it comes from userFunding. Our Hyperliquid fees guide explains how fees are set.
Step 2: Page further back with userFillsByTime
For more than the latest 2,000, userFillsByTime takes a startTime and an optional endTime, in milliseconds. It returns fills oldest first, 2,000 per call, so you page forward from where the last page stopped:
- Restart on the last timestamp, not one millisecond after. Many fills can share a timestamp, so skipping ahead can skip fills.
- Drop repeats by time, coin and trade ID after each restart. Trade ID alone can repeat.
- Fix
endTimebefore you start, so new fills don't shift the pages. - Stay within the rate limit. A full page costs 120 of the 1,200 request weight each IP gets per minute. See Hyperliquid rate limits.
Both fill requests also take aggregateByTime: true, which merges an order's partial fills into fewer rows. Use it for a cleaner journal. Leave it off when you need every trade ID, for example to match fills against your own order log.
Hyperliquid's docs say only a wallet's 10,000 most recent fills are available this way. For a busy wallet, that can be just a few days.
Step 3: Turn fills into realized PnL by market
Sum closedPnl minus fee for each coin, and you have a wallet's realized result per market. Keep fills with non-USDC fees separate, or convert them first. Here it is for the wallet from Step 1, over its latest 2,000 fills:
Most of this wallet's result came from HIP-3 markets such as xyz:SP500. BTC ended slightly negative once fees were counted.
Before you show a number like this to users:
- It's a window, not a lifetime. It covers only the fills you fetched.
- Add funding from
userFunding. - Fills record trades, not open positions. Current positions and unrealized PnL come from
clearinghouseState.
Hyperliquid trade history older than 10,000 fills
Steps 1 to 3 use Hyperliquid's own API, and they're enough for a wallet whose history fits in its 10,000 most recent fills. For anything older, or for many wallets, here's what changes:
| What you need | Without Hydromancer (Hyperliquid's API only) | With Hydromancer's API |
|---|---|---|
| Fills older than the latest 10,000 | Not available | userFillsByTimefrom 28 July 2025, with the same request body |
| Paging through long histories | Restart on timestamps and drop repeats | A cursor of thelast fill's time and txIndex |
| Whole days of every wallet's trades | Not available | Reservoir : free daily Parquet files of every fill (requester-pays S3) |
| Win rate and per-trade stats | Compute them from fills ( portfoliogives PnL history) | userPnlSummary :realized PnL, win rate, fees and funding from fully closed positions, since 1 August 2025 |
| Live fills from many wallets | One subscription per wallet; the docs allow 10 users per IP | One userFillssubscribe request for up to 1,000 addresses; each counts toward your plan's subscription total (500 on Starter) |
Example: the same request, sent to both
Take a wallet that trades thousands of times a day, and ask for its fills since 28 July 2025. body is {"type": "userFillsByTime", "user": USER, "startTime": 1753660800000}.
Without Hydromancer: Hyperliquid returns only the most recent fills it still keeps.
import requests
native = requests.post("https://api.hyperliquid.xyz/info", json=body).json()
print("Hyperliquid, oldest fill still available:", when(native[0]["time"]))Hyperliquid, oldest fill still available: 22 Oct 2026With Hydromancer: the same body, plus your API key, reaches back to 28 July 2025.
import os
import requests
hydro = requests.post(
"https://api.hydromancer.xyz/info",
json=body,
headers={"Authorization": f"Bearer {os.environ['HYDROMANCER_API_KEY']}"},
).json()
print("Hydromancer, first fill returned:", when(hydro[0]["time"]))Hydromancer, first fill returned: 28 Jul 2025when turns a millisecond timestamp into a date. Only the URL and the Authorization header changed. TWAP fills are merged in from 2 August 2025, and you can filter by builder or dex.
If the wallet's history fits in 10,000 fills, stick with Hyperliquid's free API. For older fills, use Hydromancer; for whole days of every wallet's trades, use Reservoir.
FAQ
Can I see anyone's trade history on Hyperliquid?
Yes. Every wallet's fills are public on Hyperliquid. Send userFills with any address to https://api.hyperliquid.xyz/info; no API key is needed.
Can I download a wallet's full trade history?
Hyperliquid's API keeps a wallet's 10,000 most recent fills. For older fills, use Hydromancer's API from 28 July 2025, or Reservoir's daily files for bulk exports.
How far back does the Hyperliquid API keep a wallet's trade history?
Hyperliquid's docs say the 10,000 most recent fills are available through userFillsByTime. For an active wallet, that can be only a few days.
How many fills does userFills return?
At most 2,000, newest first. If you get exactly 2,000, page further back with userFillsByTime.
Does closedPnl include fees?
No. Subtract fee yourself, and get funding separately from userFunding.
Are TWAP fills included?
Hyperliquid has a separate request for them, userTwapSliceFills. Hydromancer's userFills and userFillsByTime merge TWAP and normal fills, from 2 August 2025.
Next steps
- Pull a wallet's fills: run the Step 1 snippet with any address.
- Learn the API basics: our Hyperliquid API guide.
- Need history before the last 10,000 fills? See Hydromancer's REST API.
- Exporting whole days of trades? Start with Reservoir.
Read next
How to Build a Hyperliquid Copy Trading Bot
Learn how to build a Hyperliquid copy trading bot on Hyperliquid with the Hyperliquid API.
Read ↗
Hyperliquid Leaderboard: How to Track Top Addresses' PnL
Learn how to get Hyperliquid leaderboard data using the Hyperliquid API.
Read ↗
How to Build a Hyperliquid Trading Bot
Learn how to build a Hyperliquid trading bot: a signal from market data, signed orders through Hyperliquid's API, risk limits and a kill switch, with examples.
Read ↗