Skip to content

feat(importers): import Hyperliquid trade history exports - #55

Merged
ChristopherDownie merged 1 commit into
mainfrom
feat/hyperliquid-csv-import
Oct 26, 2026
Merged

ChristopherDownie merged 1 commit into
mainfrom
feat/hyperliquid-csv-import

Conversation

@ChristopherDownie

Copy link
Copy Markdown
Contributor

Adds an importer for Hyperliquid's trade history CSV export (#53).

Cause

The export (time, coin, dir, px, sz, ntl, fee, closedPnl) was not detected, and mapping its columns by hand rejected all 100 rows of the sample in #53. 11/8/2025 - 19:31:18 did not parse, Close Long (Price Improved) did not match the Open/Close labels, and the hedged Open/Close path refuses identical fills and closes whose opening is not in the file, both of which Hyperliquid exports contain.

Fix

  • A hyperliquid format, detected by its headers. Hyperliquid perps are one-way (one net position per coin), so every direction, including flips such as Long > Short and annotated labels, is a buy or a sell, and the fills net exactly like broker sync's. Unknown directions and unreadable perpetual rows stop the import. Spot Buy/Sell rows are skipped and counted, because the export does not say which token paid their fee.
  • Symbols match broker sync: HIP-3 markets use the API name (ANTH (io) becomes io:ANTH, checked against Hyperliquid's meta endpoint), and case is kept (kPEPE).
  • Identical fills are numbered as in the NinjaTrader importer, so the same or a later export imports once. Fills carry no import group, so they net with synced fills of the same coin.
  • The shared date parser accepts M/D/YYYY - HH:MM:SS.
  • Importing into a synced account adds only fills older than its first synced fill (reconcileHyperliquidSync, called from the import route like the XTB reconciliation). The export rounds times to the second, so its fills cannot share content hashes with synced fills, which keep milliseconds; sync owns the account's history from its first synced fill on. If none of the file's fills inside the synced period match a synced fill within a second, the statement timezone or the wallet is wrong, and the import is refused. Other brokers' sync accounts, and Hyperliquid accounts that have not synced yet, are refused too. The preview counts only the fills that will be saved.

Decisions worth a look:

  • Netting instead of the hedged Open/Close path, since Hyperliquid has no hedge mode.
  • A fill in the same second as the first synced fill, but before it, cannot be told apart from synced fills and is left out.
  • Fees use the absolute value, as every other importer and broker sync do, so maker rebates count as costs.

Test

  • packages/importers/tests/hyperliquid.test.ts uses the reporter's anonymized 100-row export as the fixture: all 100 fills import with the right sides, symbols, fees and statement timezones, identical fills stay separate, and a reversed export has the same identities. Synthetic cases cover flips, netting with a synced fill, spot rows, and unknown or unreadable rows.
  • apps/web/tests/hyperliquid-import.test.ts goes through the import route. Importing again adds nothing. In a synced account the file adds only the older fill, and the short that sync alone showed becomes the long that actually closed. A wrong timezone, another broker's account and an unsynced account are refused with nothing saved.
  • dates.test.ts covers the new separator.

The sample's prices, sizes and times are scaled, so its fills do not pair into real positions; it validates parsing, not trade history. I have not run the import in the browser.

Checks run locally

pnpm format:check, pnpm typecheck, pnpm test (67 files, 635 tests), node scripts/check-licenses.mjs, pnpm -r --filter "./packages/*" build and pnpm build all pass. Merged together with #54, the suite also passes (68 files, 642 tests); apart from the changelog, the two touch different files.

Fixes #53

Hyperliquid's trade history CSV (time, coin, dir, px, sz, ntl, fee,
closedPnl) was not detected, and mapping its columns by hand rejected
every row: its "11/8/2025 - 19:31:18" timestamps did not parse,
"(Price Improved)" directions did not match the Open/Close labels, and
the hedged Open/Close path refuses identical fills and closes whose
opening is outside the file.

- Detect the export by its headers and read it as perpetual fills.
  Hyperliquid perps are one-way, so each direction (including flips such
  as "Long > Short" and annotated labels) is a buy or a sell, and the
  fills net exactly like broker sync's. Unknown directions and
  unreadable perpetual rows stop the import; spot Buy/Sell rows are
  skipped and counted because the export omits their fee token.
- Store HIP-3 markets under the API name broker sync uses ("ANTH (io)"
  becomes "io:ANTH") and keep symbol case (kPEPE).
- Number identical fills, as the NinjaTrader importer does, so the same
  or a later export imports once. Fills carry no import group, so they
  net with synced fills of the same coin.
- Accept "M/D/YYYY - HH:MM:SS" timestamps in the shared date parser.
- Importing into a synced account adds only fills older than its first
  synced fill. The export rounds times to the second, so its fills can't
  share content hashes with synced fills; sync owns everything from its
  first fill onward. If none of the file's fills in the synced period
  match a synced fill, the statement timezone or wallet is wrong and the
  import is refused. Other brokers' sync accounts, and Hyperliquid
  accounts that have not synced yet, are refused too.

The reporter's anonymized 100-row export is the fixture.

Fixes #53
@ChristopherDownie
ChristopherDownie merged commit 05e4c19 into main Oct 26, 2026
1 check passed
@ChristopherDownie
ChristopherDownie deleted the feat/hyperliquid-csv-import branch October 28, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hyperliquid trade history CSV import (anonymized sample attached)

1 participant