Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 17 additions & 1 deletion apps/web/src/app/api/import/route.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import {
FORMATS,
HYPERLIQUID_FORMAT_ID,
parseAuto,
parseWithMapping,
readHeaders,
Expand All @@ -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,
Expand Down Expand Up @@ -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") {
Expand Down Expand Up @@ -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,
Expand Down
84 changes: 84 additions & 0 deletions apps/web/src/server/hyperliquid-import.ts
Original file line number Diff line number Diff line change
@@ -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<ImportedExecution, "symbol" | "side" | "quantity" | "price">) =>
[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<string, number[]>();
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 };
};
145 changes: 145 additions & 0 deletions apps/web/tests/hyperliquid-import.test.ts
Original file line number Diff line number Diff line change
@@ -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<typeof accounts.$inferInsert> = {}) =>
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);
});
});
30 changes: 30 additions & 0 deletions docs/importers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions packages/importers/src/dates.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
2 changes: 2 additions & 0 deletions packages/importers/src/detect.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -35,6 +36,7 @@ const LEGACY_FORMATS: ImportFormat[] = [
webull,
dastrader,
xtb,
hyperliquid,
];

export const FORMATS: ImportFormat[] = [...LEGACY_FORMATS, historyFormat];
Expand Down
Loading
Loading