From 2016c4756e7c98c3aa3dca6c6790cbb1889eff26 Mon Sep 17 00:00:00 2001 From: Christopher Downie Date: Mon, 26 Oct 2026 13:30:28 -0500 Subject: [PATCH] feat(importers): import Hyperliquid trade history exports 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 --- CHANGELOG.md | 1 + apps/web/src/app/api/import/route.ts | 18 +- apps/web/src/server/hyperliquid-import.ts | 84 +++++++++ apps/web/tests/hyperliquid-import.test.ts | 145 ++++++++++++++++ docs/importers.md | 30 ++++ packages/importers/src/dates.ts | 4 +- packages/importers/src/detect.ts | 2 + packages/importers/src/formats/hyperliquid.ts | 118 +++++++++++++ packages/importers/src/index.ts | 1 + packages/importers/tests/dates.test.ts | 3 + .../fixtures/hyperliquid-trade-history.csv | 101 +++++++++++ packages/importers/tests/hyperliquid.test.ts | 160 ++++++++++++++++++ 12 files changed, 664 insertions(+), 3 deletions(-) create mode 100644 apps/web/src/server/hyperliquid-import.ts create mode 100644 apps/web/tests/hyperliquid-import.test.ts create mode 100644 packages/importers/src/formats/hyperliquid.ts create mode 100644 packages/importers/tests/fixtures/hyperliquid-trade-history.csv create mode 100644 packages/importers/tests/hyperliquid.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index bee46309..5792a511 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ All notable changes to this project are documented here. The format follows [Kee - Configurable breakeven tolerance, default fees, and default stop/target distances per account and symbol - Importers: MetaTrader 5 deal reports and TradingView strategy exports - Importers: XTB xStation `.xlsx` account workbooks, with closed positions, open holdings and later closes of those holdings (contributed by @zahei, [#42](https://github.com/LuxAlgo/trade-journal/issues/42)) +- Importers: Hyperliquid trade history CSV exports, with HIP-3 markets under the same symbols as broker sync. Imported into a synced Hyperliquid account, the file adds only the history older than broker sync reaches ([#53](https://github.com/LuxAlgo/trade-journal/issues/53)) - Realized R accounts for contract multipliers and scaled entries - Optional historical market data connections (London Strategic Edge, Alpaca, OANDA, Binance, Coinbase, or your own candle CSV) with estimated MAE/MFE and candle replay on closed trades - Prop firm tracker: evaluation and reset costs, refunds, payout requests, receipts, cash ROI, renewals, attachments, CSV import and export diff --git a/apps/web/src/app/api/import/route.ts b/apps/web/src/app/api/import/route.ts index ca554959..9dfdaa71 100644 --- a/apps/web/src/app/api/import/route.ts +++ b/apps/web/src/app/api/import/route.ts @@ -1,5 +1,6 @@ import { FORMATS, + HYPERLIQUID_FORMAT_ID, parseAuto, parseWithMapping, readHeaders, @@ -19,6 +20,7 @@ import { parseFlexXmlImport, } from "@/server/ibkr-flex-xml-import"; import { reconcileXtbHoldings, xlsxStatement } from "@/server/xtb-import"; +import { reconcileHyperliquidSync } from "@/server/hyperliquid-import"; import type { AiImportOptions } from "@/lib/ai-import"; import { createAiImportPreview, @@ -110,13 +112,26 @@ export const POST = handler(async (request: Request) => { parsed.format === "xtb" && body.accountId ? reconcileXtbHoldings(body.accountId, parsed.executions as ImportedExecution[]) : null; - const problems = [syncProblem, xtb?.problem].filter((problem): problem is string => !!problem); + const hyperliquid = + parsed.format === HYPERLIQUID_FORMAT_ID && body.accountId + ? reconcileHyperliquidSync(body.accountId, parsed.executions as ImportedExecution[]) + : null; + // The preview then counts only the fills that will be saved. + if (hyperliquid) parsed.executions = hyperliquid.executions; + const problems = [syncProblem, xtb?.problem, hyperliquid?.problem].filter( + (problem): problem is string => !!problem, + ); const errors = [...(parsed.errors ?? []), ...problems]; const warnings = [ ...(parsed.warnings ?? []), ...(xtb?.matched ? [`${xtb.matched} open holding(s) imported earlier are closed by this file.`] : []), + ...(hyperliquid?.covered + ? [ + `${hyperliquid.covered} fill(s) at or after this account's first synced fill (${hyperliquid.since}) are left to broker sync, which covers that period. Only older fills from this file are added.`, + ] + : []), ]; if (body.mode === "preview") { @@ -169,6 +184,7 @@ export const POST = handler(async (request: Request) => { { preserveFees: Boolean(body.ai) }, ); if (xtb?.matched) result.duplicates += xtb.matched; + if (hyperliquid?.covered) result.duplicates += hyperliquid.covered; // Invalid rows are skipped with a warning rather than failing the whole file. const commitWarnings = [ ...warnings, diff --git a/apps/web/src/server/hyperliquid-import.ts b/apps/web/src/server/hyperliquid-import.ts new file mode 100644 index 00000000..3081cc99 --- /dev/null +++ b/apps/web/src/server/hyperliquid-import.ts @@ -0,0 +1,84 @@ +import { and, eq } from "drizzle-orm"; +import type { ImportedExecution } from "@luxalgo/journal-importers"; +import { accounts, db, executions } from "@/db"; + +const fillKey = (fill: Pick) => + [fill.symbol, fill.side, fill.quantity.toPrecision(12), fill.price.toPrecision(12)].join("|"); + +/** + * Hyperliquid's export rounds fill times to the second, so a file's fills never + * share a content hash with the same fills from broker sync, which keeps + * milliseconds. Sync owns an account's history from its first synced fill + * onward: it refetches recent fills and deduplicates them itself. A file + * imported into a synced account therefore adds only the older fills sync + * cannot reach. A file time is the start of its second, so a fill is older only + * when that whole second ends by the first synced fill. + * + * If none of the file's fills inside the synced period match a synced fill, the + * statement timezone (or the wallet) is wrong, and the boundary would land in + * the wrong place. Nothing is saved in that case. + */ +export const reconcileHyperliquidSync = ( + accountId: string, + incoming: ImportedExecution[], +): { + executions: ImportedExecution[]; + covered: number; + since: string | null; + problem: string | null; +} => { + const unchanged = { executions: incoming, covered: 0, since: null, problem: null }; + const account = db.select().from(accounts).where(eq(accounts.id, accountId)).get(); + if (!account) return unchanged; + if (account.kind === "sync" && account.broker !== "hyperliquid") + return { + ...unchanged, + problem: + "This account syncs from another broker. Import Hyperliquid history into its Hyperliquid account or into a separate journal account. Nothing was saved.", + }; + const synced = db + .select() + .from(executions) + .where(and(eq(executions.accountId, accountId), eq(executions.source, "sync"))) + .all(); + if (!synced.length) + return account.kind === "sync" + ? { + ...unchanged, + problem: + "Sync this Hyperliquid account before importing its history from a file, so the file adds only the fills sync cannot reach. Nothing was saved.", + } + : unchanged; + + let first = Infinity; + let last = -Infinity; + const syncedTimes = new Map(); + for (const fill of synced) { + const time = Date.parse(fill.executedAt); + first = Math.min(first, time); + last = Math.max(last, time); + const key = fillKey(fill); + const keyTimes = syncedTimes.get(key); + if (keyTimes) keyTimes.push(time); + else syncedTimes.set(key, [time]); + } + const older = incoming.filter((fill) => Date.parse(fill.executedAt) + 1000 <= first); + const covered = incoming.length - older.length; + const since = new Date(first).toISOString(); + + const inSyncedPeriod = incoming.filter((fill) => { + const time = Date.parse(fill.executedAt); + return time + 1000 > first && time < last + 1000; + }); + const matches = inSyncedPeriod.some((fill) => + syncedTimes + .get(fillKey(fill)) + ?.some((time) => Math.abs(time - Date.parse(fill.executedAt)) < 1000), + ); + if (inSyncedPeriod.length && !matches) + return { + ...unchanged, + problem: `None of this file's ${inSyncedPeriod.length} fill(s) from ${since} onward match the fills broker sync stored in this account. Check that the file is from this account's wallet and that the statement timezone is the timezone of the browser it was exported from. Nothing was saved.`, + }; + return { executions: older, covered, since, problem: null }; +}; diff --git a/apps/web/tests/hyperliquid-import.test.ts b/apps/web/tests/hyperliquid-import.test.ts new file mode 100644 index 00000000..37002ecc --- /dev/null +++ b/apps/web/tests/hyperliquid-import.test.ts @@ -0,0 +1,145 @@ +import { afterAll, beforeEach, describe, expect, it, vi } from "vitest"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { eq } from "drizzle-orm"; + +const scratch = mkdtempSync(join(tmpdir(), "journal-hyperliquid-import-")); +vi.stubEnv("JOURNAL_DATA_DIR", scratch); +vi.stubEnv("JOURNAL_PASSWORD", ""); +const { db, accounts, executions, trades } = await import("../src/db"); +const { encryptJson } = await import("../src/server/crypto"); +const { insertExecutions } = await import("../src/server/executions"); +const { POST } = await import("../src/app/api/import/route"); + +// Reporter-provided, anonymized export from issue #53. +const sample = readFileSync( + new URL( + "../../../packages/importers/tests/fixtures/hyperliquid-trade-history.csv", + import.meta.url, + ), + "utf8", +); +const csv = (rows: string[]) => ["time,coin,dir,px,sz,ntl,fee,closedPnl", ...rows].join("\n"); +const post = async (body: object) => { + const response = await POST( + new Request("http://localhost/api/import", { method: "POST", body: JSON.stringify(body) }), + ); + return { status: response.status, body: await response.json() }; +}; +const preview = (accountId: string, content: string, timeZone = "UTC") => + post({ mode: "preview", accountId, content, timeZone }); +const commit = (accountId: string, content: string, timeZone = "UTC") => + post({ mode: "commit", accountId, content, timeZone }); +const stored = (accountId: string) => + db.select().from(executions).where(eq(executions.accountId, accountId)).all(); +const journal = (accountId: string) => + db + .select() + .from(trades) + .where(eq(trades.accountId, accountId)) + .all() + .sort((a, b) => a.openedAt.localeCompare(b.openedAt)); + +// Broker sync's history reaches back only to Oct 2, where it closed a long +// opened the day before, so sync alone shows a short that never existed. +const sync = () => + insertExecutions( + "hl", + [ + ["sell", 3100, "2026-10-02T09:00:00.123Z"], + ["buy", 3050, "2026-10-03T10:00:00.456Z"], + ].map(([side, price, executedAt]) => ({ + symbol: "ETH", + side: side as "buy" | "sell", + quantity: 1, + price: price as number, + fee: 0.5, + executedAt: executedAt as string, + })), + "sync", + ); +// The same wallet's export: one older fill, then the two fills sync already has. +const history = csv([ + "10/1/2026 - 09:00:00,ETH,Open Long,3000,1,3000,0.5,-0.5", + "10/2/2026 - 09:00:00,ETH,Close Long,3100,1,3100,0.5,99.5", + "10/3/2026 - 10:00:00,ETH,Open Long,3050,1,3050,0.5,-0.5", +]); + +beforeEach(() => { + db.delete(trades).run(); + db.delete(executions).run(); + db.delete(accounts).run(); + const account = (id: string, extra: Partial = {}) => + db + .insert(accounts) + .values({ id, name: id, kind: "import", createdAt: "2026-01-01", ...extra }) + .run(); + account("file"); + account("hl", { + kind: "sync", + broker: "hyperliquid", + credentialsEnc: encryptJson({ walletAddress: `0x${"1".repeat(40)}` }), + }); + account("ibkr", { + kind: "sync", + broker: "ibkr-flex", + credentialsEnc: encryptJson({ flexToken: "test-only", flexQueryId: "test-only" }), + }); +}); +afterAll(() => { + db.$client.close(); + vi.unstubAllEnvs(); + rmSync(scratch, { recursive: true, force: true }); +}); + +describe("Hyperliquid history files", () => { + it("import every perpetual fill into a journal account, and importing again adds nothing", async () => { + const { body } = await preview("file", sample); + expect(body).toMatchObject({ detected: "hyperliquid", totals: { executions: 100 } }); + expect((await commit("file", sample)).body).toMatchObject({ inserted: 100, duplicates: 0 }); + expect((await commit("file", sample)).body).toMatchObject({ inserted: 0, duplicates: 100 }); + expect(stored("file")).toHaveLength(100); + }); + + it("add only the history older than a synced account's first synced fill", async () => { + sync(); + expect(journal("hl")).toMatchObject([{ direction: "short", grossPnl: 50 }]); + + const { body } = await preview("hl", history); + expect(body.errors ?? []).toEqual([]); + expect(body.totals.executions).toBe(1); + expect(body.warnings.join(" ")).toMatch( + /2 fill\(s\) at or after this account's first synced fill \(2026-10-02T09:00:00\.123Z\) are left to broker sync/, + ); + expect((await commit("hl", history)).body).toMatchObject({ inserted: 1, duplicates: 2 }); + expect(stored("hl")).toHaveLength(3); + expect(journal("hl")).toMatchObject([ + { direction: "long", status: "win", grossPnl: 100 }, + { direction: "long", status: "open", openQuantity: 1 }, + ]); + expect((await commit("hl", history)).body).toMatchObject({ inserted: 0, duplicates: 3 }); + }); + + it("are refused when their times don't line up with synced fills, so nothing is stored twice", async () => { + sync(); + // The file was read in the wrong timezone: every fill lands four hours late. + const { body } = await preview("hl", history, "America/New_York"); + expect(body.errors.join(" ")).toMatch(/None of this file's 1 fill\(s\) from .* match/); + expect((await commit("hl", history, "America/New_York")).status).toBe(400); + expect(stored("hl")).toHaveLength(2); + }); + + it("are refused by an account that syncs from another broker", async () => { + expect((await preview("ibkr", history)).body.errors.join(" ")).toMatch(/another broker/); + expect((await commit("ibkr", history)).status).toBe(400); + }); + + it("wait for a Hyperliquid account's first sync, so sync and file can't overlap", async () => { + expect((await preview("hl", history)).body.errors.join(" ")).toMatch( + /Sync this Hyperliquid account before importing/, + ); + expect((await commit("hl", history)).status).toBe(400); + expect(stored("hl")).toHaveLength(0); + }); +}); diff --git a/docs/importers.md b/docs/importers.md index da7be80e..a66d1baa 100644 --- a/docs/importers.md +++ b/docs/importers.md @@ -39,6 +39,7 @@ Two validation tiers: | MetaTrader 5 (deals report) | fills | HTML/CSV deal table signature | ☐ (fixtures) | ☐ | | TradingView (strategy list) | trades → reconstructed fills | `List of trades` headers | ☐ (fixtures) | ☐ | | XTB xStation (account `.xlsx`) | closed trades + open lots | Closed Positions header | ☐ (fixtures) | ✅ (#42) | +| Hyperliquid (trade history) | perpetual fills | `coin`/`dir`/`px`/`closedPnl` headers | ☐ | ✅ (#53) | | Generic (column mapper) | fills | user-mapped | n/a | n/a | ¹ [TradeNote community broker parsers](https://github.com/Eleven-Trading/TradeNote/blob/main/src/utils/brokers.js): @@ -114,6 +115,35 @@ Limits: `.xlsx` only (not legacy `.xls` or password-protected workbooks), up to instrument currency, so for a position quoted in another currency the trade's result is in the account currency but its entry notional is not. +## Hyperliquid trade history + +Export the **Trade History** tab with **Export as CSV**. Each row is one fill, with +`time`, `coin`, `dir`, `px`, `sz`, `ntl`, `fee` and `closedPnl` columns. + +- Hyperliquid perpetuals are one-way: each coin has one net position. **Open/Close + Long/Short** and flips (**Long > Short**, **Short > Long**) are read as buys and + sells, so the fills form the same trades as broker sync's. Annotations such as + **(Price Improved)** are ignored. An unrecognized direction, or a perpetual fill + without a readable time, coin, size or price, stops the import. +- HIP-3 markets are stored under their API names (`ANTH (io)` becomes `io:ANTH`), and + symbol case is kept (`kPEPE`), so a coin has one symbol from file or sync. +- Times have no offset and are in the timezone of the browser the file was exported + from. Set **Statement timezone** to that timezone and check the preview. +- Rows carry no fill ID. Identical fills are kept as separate executions, and the + same or a later export imports once. +- Spot fills (**Buy**/**Sell**) are skipped and counted: the export does not say which + token paid a spot fee. `ntl` and `closedPnl` are not imported; P&L is computed from + the fills. + +**Adding older history to a synced account.** Broker sync reads only Hyperliquid's +latest 2,000 fills. Import the export into the Hyperliquid sync account after it has +synced at least once. The export rounds times to the second, so its fills cannot be +matched exactly to synced fills: the import adds only fills older than the account's +first synced fill and leaves everything from then on to sync. If none of the file's +fills in the synced period match a synced fill, the statement timezone or the wallet +is wrong, and nothing is saved. 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. + ## NinjaTrader execution exports Each source account gets a saved identity inside the selected journal account. diff --git a/packages/importers/src/dates.ts b/packages/importers/src/dates.ts index 47513f45..c2c10ff4 100644 --- a/packages/importers/src/dates.ts +++ b/packages/importers/src/dates.ts @@ -104,9 +104,9 @@ const toNaive = (value: string): NaiveParts | null => { }; } - // US: 01/05/2026 2:30:00 PM (also 1/5/26) + // US: 01/05/2026 2:30:00 PM (also 1/5/26, and Hyperliquid's 1/5/2026 - 14:30:00) match = text.match( - /^(\d{1,2})[-/](\d{1,2})[-/](\d{2}|\d{4})(?:[, ]+(\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?\s*(AM|PM|am|pm)?)?$/, + /^(\d{1,2})[-/](\d{1,2})[-/](\d{2}|\d{4})(?:(?:[, ]+|\s+-\s+)(\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?\s*(AM|PM|am|pm)?)?$/, ); if (match) { let hour = Number(match[4] ?? 0); diff --git a/packages/importers/src/detect.ts b/packages/importers/src/detect.ts index 8f86e8d9..097ea3f4 100644 --- a/packages/importers/src/detect.ts +++ b/packages/importers/src/detect.ts @@ -14,6 +14,7 @@ import { import { thinkorswim } from "./formats/thinkorswim"; import { tradezella } from "./formats/tradezella"; import { xtb } from "./formats/xtb"; +import { hyperliquid } from "./formats/hyperliquid"; import { historyFormat, parseHistory } from "./formats/history"; import type { ImportFormat, ImportOptions, ParsedImport } from "./types"; @@ -35,6 +36,7 @@ const LEGACY_FORMATS: ImportFormat[] = [ webull, dastrader, xtb, + hyperliquid, ]; export const FORMATS: ImportFormat[] = [...LEGACY_FORMATS, historyFormat]; diff --git a/packages/importers/src/formats/hyperliquid.ts b/packages/importers/src/formats/hyperliquid.ts new file mode 100644 index 00000000..5befe8c3 --- /dev/null +++ b/packages/importers/src/formats/hyperliquid.ts @@ -0,0 +1,118 @@ +import { hasHeaders, parseCsv, toRecords } from "../csv"; +import type { ImportFormat, ImportedExecution } from "../types"; +import { rowsToFills, type FillsColumnMap } from "./fills"; + +export const HYPERLIQUID_FORMAT_ID = "hyperliquid"; + +const columns: FillsColumnMap = { + symbol: ["coin"], + side: ["dir"], + quantity: ["sz"], + price: ["px"], + fees: [["fee"]], + timestamp: ["time"], +}; + +/** + * Perpetuals are one-way: each coin has a single net position, so every + * direction is a buy or a sell, and a flip ("Long > Short") is one fill + * through flat, which round-trip building already splits. + */ +const PERP_SIDES: Record = { + "open long": "buy", + "close short": "buy", + "short > long": "buy", + "open short": "sell", + "close long": "sell", + "long > short": "sell", +}; + +/** + * Broker sync reads the API's coin names, so symbols must match them exactly: + * HIP-3 markets read "ANTH (io)" here but "io:ANTH" there, and coins such as + * kPEPE are case-sensitive. + */ +const apiCoin = (coin: string): string => { + const hip3 = coin.trim().match(/^(\S+)\s+\(([^()\s]+)\)$/); + return hip3 ? `${hip3[2]}:${hip3[1]}` : coin.trim(); +}; + +/** + * Hyperliquid trade history export (Trade History → Export as CSV): time, coin, + * dir, px, sz, ntl, fee, closedPnl, one row per fill. Rows carry no fill ID, so + * identical fills are numbered like NinjaTrader's: the same or a later export + * imports once. Fills net with synced fills of the same coin (no import group). + */ +export const hyperliquid: ImportFormat = { + id: HYPERLIQUID_FORMAT_ID, + label: "Hyperliquid (trade history)", + detect: (headers) => + hasHeaders(headers, [["time"], ["coin"], ["dir"], ["px"], ["sz"], ["closedpnl"]]), + parse: (content, options) => { + const executions: ImportedExecution[] = []; + const copies = new Map(); + const unknown = new Set(); + let spot = 0; + let unknownRows = 0; + let unreadable = 0; + for (const row of toRecords(parseCsv(content))) { + // Annotations such as "(Price Improved)" don't change the direction. + const direction = (row.dir ?? "") + .replace(/\s*\([^()]*\)$/, "") + .trim() + .toLowerCase(); + const side = PERP_SIDES[direction]; + if (!side) { + if (direction === "buy" || direction === "sell") spot++; + else { + unknown.add(row.dir || "(blank)"); + unknownRows++; + } + continue; + } + const fill = rowsToFills([{ ...row, dir: side }], columns, options, { + normalizeSymbol: apiCoin, + }).executions[0]; + if (!fill) { + unreadable++; + continue; + } + const signature = JSON.stringify([ + fill.symbol, + fill.side, + fill.quantity, + fill.price, + fill.executedAt, + ]); + const occurrence = copies.get(signature) ?? 0; + copies.set(signature, occurrence + 1); + // Export row order is not execution order, so no tie-break is claimed. + fill.importMetadata = { id: `fill:${signature}:${occurrence}`, order: 0, preserveFee: true }; + executions.push(fill); + } + + const errors: string[] = []; + if (unknown.size) + errors.push( + `Unrecognized Hyperliquid direction: ${[...unknown].map((dir) => `"${dir}"`).join(", ")}. Nothing was imported, because skipping these fills would leave positions wrong. Please send an anonymized sample so they can be supported.`, + ); + if (unreadable) + errors.push( + `${unreadable} perpetual fill(s) are missing a readable time, coin, size or price. Nothing was imported, because skipping them would leave positions wrong.`, + ); + const warnings = [ + "Hyperliquid writes times in the timezone of the browser the file was exported from. Set the statement timezone to that timezone and check the preview times.", + ]; + if (spot) + warnings.push( + `${spot} spot fill(s) were skipped. The export does not say which token paid a spot fee, so only perpetual fills are imported.`, + ); + return { + format: HYPERLIQUID_FORMAT_ID, + executions, + skippedRows: spot + unknownRows + unreadable, + warnings, + ...(errors.length ? { errors } : {}), + }; + }, +}; diff --git a/packages/importers/src/index.ts b/packages/importers/src/index.ts index ab2e0db1..ad39a742 100644 --- a/packages/importers/src/index.ts +++ b/packages/importers/src/index.ts @@ -7,4 +7,5 @@ export { parseWithMapping, readHeaders, type GenericMapping } from "./formats/ge export { makeFillsFormat, parseSide, type FillsFormatSpec } from "./formats/fills"; export { parseHistory, type HistoryParseOptions } from "./formats/history"; export { xtbWorkbookToStatement } from "./formats/xtb"; +export { HYPERLIQUID_FORMAT_ID } from "./formats/hyperliquid"; export { positionFillProblem } from "./position-fills"; diff --git a/packages/importers/tests/dates.test.ts b/packages/importers/tests/dates.test.ts index e7e3572f..49c9e9f3 100644 --- a/packages/importers/tests/dates.test.ts +++ b/packages/importers/tests/dates.test.ts @@ -10,6 +10,7 @@ it.each([ ["20260105;093000", "2026-01-05T09:30:00.000Z"], ["2026.01.05", "2026-01-05T00:00:00.000Z"], ["2024-02-29 23:59:59.999", "2024-02-29T23:59:59.999Z"], + ["11/8/2025 - 19:31:18", "2025-11-08T19:31:18.000Z"], ])("preserves full timestamp %s", (input, expected) => { expect(parseTimestamp(input)).toBe(expected); }); @@ -33,6 +34,8 @@ it.each([ "2026-13-05", "1/5/2026 13:30 PM", "2026-01-05 09:30:00.1234", + "11/8/2025-19:31:18", + "11/8/2025 - - 19:31:18", ])("rejects invalid or unsupported precision rather than changing timestamp %s", (input) => { expect(parseTimestamp(input)).toBeNull(); }); diff --git a/packages/importers/tests/fixtures/hyperliquid-trade-history.csv b/packages/importers/tests/fixtures/hyperliquid-trade-history.csv new file mode 100644 index 00000000..54a94f28 --- /dev/null +++ b/packages/importers/tests/fixtures/hyperliquid-trade-history.csv @@ -0,0 +1,101 @@ +time,coin,dir,px,sz,ntl,fee,closedPnl +11/8/2025 - 19:31:18,BTC,Close Long,107376,0.000295163,31.693419,0.004564,0.152302 +11/9/2025 - 04:50:53,ETH,Close Long (Price Improved),3580.3,0.0127904,45.793541,0.006593,1.591611 +11/9/2025 - 04:51:07,SOL,Close Long,149.593,0.206614,30.908112,0.004450,1.015254 +11/9/2025 - 09:18:44,BTC,Close Long,108287,0.000295163,31.962376,0.004602,0.273765 +11/9/2025 - 11:55:07,BNB,Close Long,1028.03,0.0216453,22.251927,0.003203,0.329682 +11/9/2025 - 15:33:12,BNB,Close Long,1045.19,0.0216453,22.623396,0.003257,0.539830 +11/9/2025 - 18:17:47,BTC,Close Long (Price Improved),113736,0.000285325,32.451609,0.004672,1.616335 +11/10/2025 - 13:05:57,BTC,Close Long,113912,0.000137743,15.690628,0.002258,0.066353 +11/10/2025 - 13:05:57,BTC,Close Long,113912,0.000137743,15.690628,0.002258,0.066353 +11/11/2025 - 00:21:07,BNB,Open Long,1045.19,0.0216453,22.623396,0.003257,-0.003257 +11/11/2025 - 21:31:04,SOL,Close Long,152.104,0.206614,31.426815,0.004524,-0.365503 +11/12/2025 - 01:37:41,HYPE,Open Long,123.106,0.216453,26.646592,0.003837,-0.003837 +11/12/2025 - 06:49:06,SOL,Close Long,152.741,0.206614,31.558549,0.004544,-0.093849 +11/13/2025 - 00:00:53,ANTH (io),Open Long,2825.3,0.00688714,19.458223,0.000559,-0.000559 +11/13/2025 - 00:43:28,HYPE,Open Long,125.354,0.206614,25.900020,0.003729,-0.003729 +11/13/2025 - 02:01:51,BTC,Close Long,112163,0.000285325,32.002877,0.004608,0.057358 +11/13/2025 - 06:31:57,HYPE,Close Long,121.776,0.216453,26.358790,0.003795,-0.282828 +11/13/2025 - 06:47:05,HYPE,Close Long,122.218,0.216453,26.454532,0.003808,-0.187099 +11/13/2025 - 12:57:41,ETH,Close Long,3580.3,0.0127904,45.793541,0.006593,0.298878 +11/14/2025 - 01:20:27,HYPE,Open Long,121.776,0.216453,26.358790,0.003795,-0.003795 +11/14/2025 - 03:09:14,SOL,Close Long,162.597,0.196776,31.995179,0.004607,0.349063 +11/14/2025 - 15:20:39,HYPE,Close Long,122.218,0.216453,26.454532,0.003808,0.025691 +11/14/2025 - 21:35:13,HYPE,Open Long,122.661,0.216453,26.550275,0.003823,-0.003823 +11/16/2025 - 02:32:06,SOL,Open Long,161.933,0.196776,31.864491,0.004588,-0.004588 +11/16/2025 - 03:05:08,BTC,Open Long,111848,0.000285325,31.913054,0.004595,-0.004595 +11/16/2025 - 06:10:29,BNB,Open Long,1032.29,0.0216453,22.344219,0.003218,-0.003218 +11/16/2025 - 13:44:43,HYPE,Close Long,118.3,0.226292,26.770289,0.003854,-0.529876 +11/16/2025 - 14:05:43,BTC,Open Long,109821,0.000285325,31.334705,0.004511,-0.004511 +11/16/2025 - 15:52:02,HYPE,Close Long,119.592,0.216453,25.886115,0.003727,-0.197541 +11/16/2025 - 16:47:58,BNB,Close Long,1021.66,0.0216453,22.114207,0.003184,0.057511 +11/16/2025 - 19:12:23,BTC,Open Long,110285,0.000285325,31.466975,0.004531,-0.004531 +11/17/2025 - 05:49:32,BTC,Open Long,109975,0.000285325,31.378669,0.004518,-0.004518 +11/17/2025 - 20:00:06,BNB,Close Long,1002.8,0.0226292,22.692570,0.003267,-0.195611 +11/18/2025 - 16:59:49,BTC,Close Long,111533,0.000285325,31.823232,0.004582,0.212470 +11/18/2025 - 18:05:51,HYPE,Open Long,114.923,0.226292,26.006205,0.003744,-0.003744 +11/18/2025 - 18:14:55,HYPE,Close Long,114.923,0.226292,26.006205,0.003744,-0.093108 +11/18/2025 - 18:16:35,BTC,Close Long,112321,0.000275486,30.942875,0.004455,-0.069444 +11/19/2025 - 00:20:46,BTC,Open Long,111063,0.000285325,31.689067,0.004562,-0.004562 +11/19/2025 - 03:20:41,BTC,Open Long,111220,0.000285325,31.733789,0.004569,-0.004569 +11/19/2025 - 06:37:09,BNB,Open Long,1019.55,0.0216453,22.068493,0.003177,-0.003177 +11/19/2025 - 17:26:42,ETH,Open Long,3580.3,0.012692,45.441283,0.006542,-0.006542 +11/19/2025 - 18:07:39,BTC,Close Long,111377,0.000285325,31.778511,0.004575,0.057277 +11/20/2025 - 10:09:14,HYPE,Open Long,117.872,0.226292,26.673501,0.003841,-0.003841 +11/20/2025 - 23:09:17,ETH,Open Long,3526.24,0.0128888,45.449007,0.006544,-0.006544 +11/20/2025 - 23:46:17,HYPE,Open Long,114.923,0.226292,26.006205,0.003744,-0.003744 +11/23/2025 - 18:58:07,SPCX (xyz),Close Long,222.225,4.48648,997.007526,0.028714,104.707731 +11/24/2025 - 08:37:21,HYPE,Close Long,124.45,0.206614,25.713123,0.003702,0.241076 +11/24/2025 - 12:39:30,BTC,Open Long,114047,0.000275486,31.418215,0.004523,-0.004523 +11/25/2025 - 02:33:43,BNB,Close Long,1036.57,0.0216453,22.436799,0.003231,-0.081377 +11/25/2025 - 06:30:55,ETH,Open Long,3459.83,0.013184,45.614210,0.006568,-0.006568 +11/26/2025 - 11:44:03,SOL,Close Long,153.379,0.206614,31.690283,0.004562,-0.365459 +11/26/2025 - 19:52:46,SOL,Open Long (Price Improved),145.29,0.216453,31.448378,0.004528,-0.004528 +11/26/2025 - 19:52:59,HYPE,Open Long (Price Improved),111.24,0.236131,26.267151,0.003782,-0.003782 +11/26/2025 - 20:07:35,BTC,Open Long (Price Improved),107527,0.000295163,31.738115,0.004570,-0.004570 +11/26/2025 - 21:53:11,SOL,Open Long,141.69,0.216453,30.669213,0.004416,-0.004416 +11/27/2025 - 05:56:21,ETH,Close Long,3292.86,0.0138727,45.680757,0.006578,-0.743661 +11/28/2025 - 18:58:33,HYPE,Close Long,114.923,0.226292,26.006205,0.003744,0.401112 +11/29/2025 - 09:02:36,BNB,Close Long,992.48,0.0226292,22.459016,0.003233,0.143151 +11/29/2025 - 11:15:53,HYPE,Close Long,112.862,0.236131,26.650121,0.003837,-0.091566 +11/30/2025 - 06:44:08,ETH,Close Long,3381.72,0.0135775,45.915369,0.006612,0.625336 +11/30/2025 - 18:52:30,BTC,Close Long,110131,0.000285325,31.423011,0.004524,-0.133118 +12/1/2025 - 15:13:00,BTC,Open Long,110596,0.000285325,31.555660,0.004543,-0.004543 +12/1/2025 - 15:52:17,HYPE,Close Long,109.243,0.236131,25.795731,0.003714,-0.383422 +12/1/2025 - 16:03:57,HYPE,Open Long,109.243,0.236131,25.795731,0.003714,-0.003714 +12/1/2025 - 18:47:10,SOL,Close Long,144.081,0.216453,31.186740,0.004490,0.257809 +12/1/2025 - 19:05:39,SOL,Open Long,142.885,0.216453,30.927976,0.004453,-0.004453 +12/2/2025 - 14:34:08,BTC,Open Long,110440,0.000285325,31.511318,0.004538,-0.004538 +12/2/2025 - 20:29:49,ANTH (io),Open Long,2598.56,0.00787102,20.453286,0.000588,-0.000588 +12/3/2025 - 01:33:14,BTC,Open Long,108439,0.000285325,30.940169,0.004455,-0.004455 +12/3/2025 - 07:14:31,BTC,Close Long,107964,0.000295163,31.867104,0.004588,-0.197642 +12/3/2025 - 08:31:40,ANTH (io),Open Long,2555.52,0.00688714,17.600224,0.000506,-0.000506 +12/3/2025 - 09:24:11,ETH,Close Long,3169.86,0.014463,45.845660,0.006601,-1.045352 +12/3/2025 - 11:01:59,BTC,Close Long,107527,0.000295163,31.738115,0.004570,-0.243377 +12/3/2025 - 13:11:24,HYPE,Open Long,106.126,0.245969,26.103738,0.003759,-0.003759 +12/3/2025 - 19:09:11,BTC,Close Long,108134,0.000295163,31.917289,0.004595,0.160818 +12/3/2025 - 19:18:13,BNB,Close Long,968.132,0.0236131,22.860570,0.003291,0.077318 +12/4/2025 - 01:50:32,ANTH (io),Close Long,2560.43,0.00787102,20.153225,0.000580,-1.061688 +12/4/2025 - 02:19:50,BTC,Close Long,109358,0.000285325,31.202435,0.004493,0.230523 +12/4/2025 - 15:04:43,ETH,Close Long,3267.89,0.0139711,45.655848,0.006574,0.791411 +12/4/2025 - 20:30:17,BTC,Open Long (Price Improved),107983,0.000295163,31.872593,0.004588,-0.004588 +12/5/2025 - 16:48:33,BNB,Open Long,956.191,0.0236131,22.578596,0.003250,-0.003250 +12/7/2025 - 00:09:43,BTC,Open Long,107376,0.000295163,31.693419,0.004564,-0.004564 +12/7/2025 - 06:51:34,BNB,Open Long,964.134,0.000983878,0.948590,0.000136,-0.000136 +12/7/2025 - 07:16:53,BTC,Close Long,109666,0.000285325,31.290363,0.004505,0.386885 +12/7/2025 - 07:32:45,ETH,Open Long,3218.47,0.0141678,45.598815,0.006566,-0.006566 +12/7/2025 - 14:05:24,BTC,Close Long,110285,0.000285325,31.466975,0.004531,0.428966 +12/7/2025 - 14:57:58,HYPE,Open Long,105.36,0.245969,25.915220,0.003731,-0.003731 +12/7/2025 - 16:44:21,BTC,Close Long,109512,0.000285325,31.246399,0.004498,0.144978 +12/7/2025 - 20:40:11,HYPE,Close Long,104.6,0.255808,26.757468,0.003853,-0.104091 +12/8/2025 - 01:30:06,BNB,Close Long,968.132,0.0236131,22.860570,0.003291,0.216737 +12/8/2025 - 07:48:00,SOL,Open Long,139.352,0.226292,31.534241,0.004540,-0.004540 +12/8/2025 - 22:00:40,BTC,Open Long,109877,0.000285325,31.350623,0.004514,-0.004514 +12/9/2025 - 08:30:59,HYPE,Open Long,107.284,0.245969,26.388639,0.003799,-0.003799 +12/9/2025 - 14:32:50,BNB,Open Long,992.48,0.0226292,22.459016,0.003233,-0.003233 +12/9/2025 - 22:02:46,BNB,Close Long,996.598,0.0108227,10.785833,0.001553,0.257297 +12/10/2025 - 06:39:30,BTC,Close Long,110752,0.000285325,31.600382,0.004549,-0.241005 +12/10/2025 - 07:34:15,BTC,Open Long,110131,0.000285325,31.423011,0.004524,-0.004524 +12/10/2025 - 12:32:27,BTC,Open Long,109051,0.000285325,31.114887,0.004480,-0.004480 +12/10/2025 - 12:39:26,BNB,Open Long,976.182,0.0226292,22.090200,0.003181,-0.003181 +12/10/2025 - 22:32:26,HYPE,Open Long,101.983,0.255808,26.088081,0.003756,-0.003756 diff --git a/packages/importers/tests/hyperliquid.test.ts b/packages/importers/tests/hyperliquid.test.ts new file mode 100644 index 00000000..cddc3837 --- /dev/null +++ b/packages/importers/tests/hyperliquid.test.ts @@ -0,0 +1,160 @@ +import { describe, expect, it } from "vitest"; +import { readFileSync } from "node:fs"; +import { buildRoundTrips, type Execution } from "@luxalgo/journal-core"; +import { detectFormat, parseAuto } from "../src/detect"; + +// Reporter-provided, anonymized fixture from LuxAlgo/trade-journal issue #53: +// 100 random rows with prices, sizes and times scaled or shifted, so opening and +// closing fills don't pair up. It validates parsing, not position history. +const sample = readFileSync( + new URL("./fixtures/hyperliquid-trade-history.csv", import.meta.url), + "utf8", +); +const HEADER = "time,coin,dir,px,sz,ntl,fee,closedPnl"; +const csv = (rows: string[]) => [HEADER, ...rows].join("\n"); +const parse = (content: string, timeZone = "UTC") => parseAuto(content, { timeZone })!; +const ids = (content: string) => + parse(content) + .executions.map((e) => e.importMetadata!.id) + .sort(); +const trips = (executions: Omit[]) => + buildRoundTrips(executions.map((e, i) => ({ ...e, id: String(i), accountId: "hl" }))); + +describe("Hyperliquid trade history exports import as perpetual fills", () => { + it("the issue #53 export is detected and all 100 fills import", () => { + expect(detectFormat(sample)?.id).toBe("hyperliquid"); + const result = parse(sample); + expect(result.errors).toBeUndefined(); + expect(result.skippedRows).toBe(0); + expect(result.executions).toHaveLength(100); + expect(result.executions[0]).toMatchObject({ + symbol: "BTC", + side: "sell", + quantity: 0.000295163, + price: 107376, + fee: 0.004564, + executedAt: "2025-11-08T19:31:18.000Z", + importMetadata: { order: 0, preserveFee: true }, + }); + expect(result.executions.filter((e) => e.side === "buy")).toHaveLength(48); + expect(result.executions.filter((e) => e.side === "sell")).toHaveLength(52); + }); + + it("a Price Improved annotation keeps the fill's direction", () => { + const result = parse( + csv([ + "11/9/2025 - 04:50:53,ETH,Close Long (Price Improved),3580.3,0.0127904,45.793541,0.006593,1.591611", + "11/26/2025 - 19:52:46,SOL,Open Long (Price Improved),145.29,0.216453,31.448378,0.004528,-0.004528", + ]), + ); + expect(result.errors).toBeUndefined(); + expect(result.executions.map((e) => [e.symbol, e.side])).toEqual([ + ["ETH", "sell"], + ["SOL", "buy"], + ]); + }); + + it("symbols match broker sync's coin names: HIP-3 markets are dex:COIN and case is kept", () => { + const result = parse( + csv([ + "11/13/2025 - 00:00:53,ANTH (io),Open Long,2825.3,0.00688714,19.458223,0.000559,-0.000559", + "11/23/2025 - 18:58:07,SPCX (xyz),Close Long,222.225,4.48648,997.007526,0.028714,104.707731", + "11/24/2025 - 08:00:00,kPEPE,Open Short,0.0061,1000,6.1,0.001,-0.001", + ]), + ); + expect(result.executions.map((e) => e.symbol)).toEqual(["io:ANTH", "xyz:SPCX", "kPEPE"]); + expect(new Set(parse(sample).executions.map((e) => e.symbol))).toEqual( + new Set(["BTC", "ETH", "SOL", "BNB", "HYPE", "io:ANTH", "xyz:SPCX"]), + ); + }); + + it("times are read in the statement timezone", () => { + expect(parse(sample, "Europe/Paris").executions[0]!.executedAt).toBe( + "2025-11-08T18:31:18.000Z", + ); + expect(parse(sample, "America/New_York").executions[0]!.executedAt).toBe( + "2025-11-09T00:31:18.000Z", + ); + }); + + it("identical fills stay separate, and the same or a reordered export imports once", () => { + const identical = parse(sample).executions.filter( + (e) => e.symbol === "BTC" && e.executedAt === "2025-11-10T13:05:57.000Z", + ); + expect(identical).toHaveLength(2); + expect(new Set(identical.map((e) => e.importMetadata!.id)).size).toBe(2); + expect(new Set(ids(sample)).size).toBe(100); + const [header, ...rows] = sample.trim().split("\n"); + expect(ids([header, ...rows.reverse()].join("\n"))).toEqual(ids(sample)); + }); + + it("fills net with synced fills of the same coin: a file's open and a synced close make one trade", () => { + const [open] = parse( + csv(["10/1/2026 - 09:00:00,ETH,Open Long,3000,1,3000,0.5,-0.5"]), + ).executions; + expect(open!.importMetadata!.group).toBeUndefined(); + const synced = { + symbol: "ETH", + side: "sell" as const, + quantity: 1, + price: 3100, + fee: 0.5, + executedAt: "2026-10-02T09:00:00.123Z", + source: "sync" as const, + }; + expect(trips([{ ...open!, source: "import" }, synced])).toMatchObject([ + { direction: "long", status: "win", grossPnl: 100, netPnl: 99 }, + ]); + }); + + it("shorts and flips through flat become separate trades", () => { + const result = parse( + csv([ + "10/1/2026 - 09:00:00,ETH,Open Short,100,1,100,0.1,-0.1", + "10/1/2026 - 10:00:00,ETH,Short > Long,90,3,270,0.3,9.7", + "10/1/2026 - 11:00:00,ETH,Close Long,95,2,190,0.2,9.8", + ]), + ); + expect(result.errors).toBeUndefined(); + expect(result.executions.map((e) => e.side)).toEqual(["sell", "buy", "sell"]); + expect( + trips(result.executions.map((e) => ({ ...e, source: "import" as const }))), + ).toMatchObject([ + { direction: "short", grossPnl: 10, quantity: 1 }, + { direction: "long", grossPnl: 10, quantity: 2 }, + ]); + }); + + it("spot fills are skipped with a reason; the perpetual fills still import", () => { + const result = parse( + csv([ + "10/1/2026 - 09:00:00,HYPE/USDC,Buy,40,1,40,0.0004,0", + "10/1/2026 - 09:05:00,HYPE/USDC,Sell,41,1,41,0.04,0", + "10/1/2026 - 09:10:00,HYPE,Open Long,40,1,40,0.01,-0.01", + ]), + ); + expect(result.errors).toBeUndefined(); + expect(result.executions.map((e) => e.symbol)).toEqual(["HYPE"]); + expect(result.skippedRows).toBe(2); + expect(result.warnings.join(" ")).toMatch(/2 spot fill\(s\) were skipped/); + }); + + it("an unknown direction or an unreadable fill stops the import instead of being guessed", () => { + const unknown = parse( + csv([ + "10/1/2026 - 09:00:00,ETH,Open Long,3000,1,3000,0.5,-0.5", + "10/1/2026 - 09:30:00,ETH,Auto-Deleveraging,2500,1,2500,0,-500", + ]), + ); + expect(unknown.errors?.join(" ")).toMatch( + /Unrecognized Hyperliquid direction: "Auto-Deleveraging"/, + ); + const unreadable = parse( + csv([ + "10/1/2026 - 09:00:00,ETH,Open Long,3000,1,3000,0.5,-0.5", + "10/1/2026 - 09:30:00,ETH,Close Long,,1,2500,0,-500", + ]), + ); + expect(unreadable.errors?.join(" ")).toMatch(/1 perpetual fill\(s\) are missing/); + }); +});