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 @@ -17,6 +17,7 @@ All notable changes to this project are documented here. The format follows [Kee
- 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))
- Broker sync: Binance USDⓈ-M futures ([#30](https://github.com/LuxAlgo/trade-journal/issues/30)). A Binance connection now also reads futures balances, positions and the last three months of fills, as futures trades. Fees paid in BNB are converted at that hour's BNB/USDT price. In hedge mode, a long and a short held at once on one symbol stay separate trades. A fill that closes a position opened before Binance's history is skipped, or kept only for the part the history covers, and reported. Spot fills are not read yet, and a quarterly contract held to delivery stays open, because delivery leaves no fill.
- 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
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,10 +151,12 @@ Default import timezone** for Flex timestamps without an offset. Existing synced
timezone provenance require recovery into a separate account; see
[IBKR timezone recovery](docs/importers.md#ibkr-broker-sync-and-timezone-recovery).

Webull sync reads about a year of order history. A synced fill that closes a position opened before
that is skipped, or kept only for the part the history covers, and the sync reports it, rather than
showing a position that never existed. Options that expired while held close at 0 at the 4pm New
York expiry.
Webull sync reads about a year of order history, and Binance futures sync the last three months. A
synced fill that closes a position opened before that history is skipped, or kept only for the part
the history covers, and the sync reports it, rather than showing a position that never existed.
Webull options that expired while held close at 0 at the 4pm New York expiry. In Binance hedge mode,
a long and a short held at once on one symbol stay separate trades. A Binance quarterly contract held
to delivery stays open, because delivery leaves no fill.

## Screenshots

Expand Down
4 changes: 4 additions & 0 deletions apps/web/src/server/broker-trades.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ export const brokerTradesToExecutions = (
executedAt: trade.executedAt!,
// The SDK's "cash" has no journal equivalent.
...(trade.assetClass && trade.assetClass !== "cash" ? { assetClass: trade.assetClass } : {}),
// A hedge-mode side (Binance) is its own position, so it must not net with the other.
...(trade.positionSide
? { importMetadata: { id: "sync", group: `sync-hedge:${trade.positionSide}`, order: 0 } }
: {}),
})),
);
const positionEffects = new Map<ImportedExecution, "open" | "close">();
Expand Down
2 changes: 1 addition & 1 deletion apps/web/src/server/executions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ export const executionProblem = (row: unknown, source: ExecutionSource): string
const meta = r.importMetadata;
const metaOk =
!meta ||
(source === "import" &&
((source === "import" || source === "sync") &&
typeof meta.id === "string" &&
meta.id.length > 0 &&
meta.id.length <= 2000 &&
Expand Down
9 changes: 7 additions & 2 deletions apps/web/src/server/sync.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import { withoutSummaryRows } from "./ibkr-flex-xml-import";
export { listBrokers };

/** The asset class whose fills a broker's complete position list can vouch for. */
const CHECKED_ASSET_CLASS: Record<string, string> = { webull: "equity" };
const CHECKED_ASSET_CLASS: Record<string, string> = { webull: "equity", binance: "futures" };
/** Later syncs re-read this much before the last one, for orders that filled after placement. */
const HISTORY_OVERLAP_MS = 30 * 86_400_000;

Expand Down Expand Up @@ -101,13 +101,18 @@ export const syncAccount = async (accountId: string): Promise<SyncOutcome> => {
const checked = CHECKED_ASSET_CLASS[account.broker ?? ""];
const brokerQuantities = new Map<string, number>();
for (const position of snapshot.accounts.flatMap((a) => a.positions)) {
// Hedge-mode sides replay in their own groups, so they say nothing about one-way fills.
if (position.positionSide) continue;
brokerQuantities.set(
position.symbol,
(brokerQuantities.get(position.symbol) ?? 0) + position.quantity,
);
}
// A Binance quarterly contract (BTCUSDT_261225) settles at delivery without a
// fill, so its empty position doesn't show that its history is incomplete.
const delivered = (symbol: string) => account.broker === "binance" && /_\d{6}$/.test(symbol);
const brokerQuantity = (symbol: string) =>
checked ? (brokerQuantities.get(symbol) ?? 0) : undefined;
checked && !delivered(symbol) ? (brokerQuantities.get(symbol) ?? 0) : undefined;
let dropped = 0;
let trimmed = 0;
const withinHistory = (fills: ImportedExecution[]): ImportedExecution[] => {
Expand Down
227 changes: 227 additions & 0 deletions apps/web/tests/binance-sync.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,227 @@
import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const scratch = mkdtempSync(join(tmpdir(), "journal-binance-sync-"));
vi.stubEnv("JOURNAL_DATA_DIR", scratch);
const { db, accounts, executions, trades } = await import("../src/db");
const { encryptJson } = await import("../src/server/crypto");
const { syncAccount } = await import("../src/server/sync");

const HOUR_MS = 3_600_000;
const DAY_MS = 24 * HOUR_MS;
const hoursAgo = (hours: number) => Math.floor(Date.now() / HOUR_MS) * HOUR_MS - hours * HOUR_MS;

// USDⓈ-M userTrades rows, as broker-sdk's Binance adapter reads them.
let nextId = 1;
const fill = (
symbol: string,
side: "BUY" | "SELL",
qty: string,
price: string,
time: number,
extra: Record<string, unknown> = {},
) => ({
id: nextId++,
symbol,
side,
positionSide: "BOTH",
qty,
price,
commission: "0",
commissionAsset: "USDT",
time,
...extra,
});
let fills: ReturnType<typeof fill>[] = [];
let positions: Record<string, string>[] = [];
let bnbCloses: Record<number, string> = {};

beforeEach(() => {
db.delete(trades).run();
db.delete(executions).run();
db.delete(accounts).run();
db.insert(accounts)
.values({
id: "bn",
name: "Binance",
kind: "sync",
broker: "binance",
credentialsEnc: encryptJson({ apiKey: "k", apiSecret: "s" }),
createdAt: "2026-01-01",
})
.run();
fills = [];
positions = [];
bnbCloses = {};
vi.stubGlobal(
"fetch",
vi.fn<typeof fetch>(async (input) => {
const url = new URL(String(input));
const query = url.searchParams;
const inWindow = (time: number) =>
time >= Number(query.get("startTime")) && time <= Number(query.get("endTime"));
switch (url.pathname) {
case "/api/v3/account":
return Response.json({ balances: [{ asset: "USDT", free: "10", locked: "0" }] });
case "/api/v3/ticker/price":
return Response.json([]);
case "/api/v3/klines":
return Response.json(
Object.entries(bnbCloses)
.filter(([hour]) => inWindow(Number(hour)))
.map(([hour, close]) => [Number(hour), close, close, close, close, "1"]),
);
case "/fapi/v3/account":
return Response.json({ totalMarginBalance: "1000" });
case "/fapi/v3/positionRisk":
return Response.json(positions);
case "/fapi/v1/income":
return Response.json(
fills
.filter((f) => inWindow(f.time))
.map((f) => ({ symbol: f.symbol, incomeType: "COMMISSION" })),
);
case "/fapi/v1/userTrades":
return Response.json(
fills.filter((f) => f.symbol === query.get("symbol") && inWindow(f.time)),
);
}
throw new Error(`Unexpected Binance request: ${url.pathname}`);
}),
);
});
afterEach(() => vi.unstubAllGlobals());
afterAll(() => {
db.$client.close();
vi.unstubAllEnvs();
rmSync(scratch, { recursive: true, force: true });
});

const journal = () =>
db
.select()
.from(trades)
.all()
.sort((a, b) => a.openedAt.localeCompare(b.openedAt));

describe("Binance futures sync", () => {
it("futures fills become futures trades with their fees, and a re-sync adds nothing", async () => {
const closedAt = hoursAgo(20) + 600_000;
fills = [
fill("BTCUSDT", "BUY", "0.01", "60000", hoursAgo(30), { commission: "0.24" }),
fill("BTCUSDT", "SELL", "0.01", "61000", closedAt, {
commission: "0.0004",
commissionAsset: "BNB",
}),
];
bnbCloses = { [hoursAgo(20)]: "600" };

expect(await syncAccount("bn")).toMatchObject({ inserted: 2, skipped: 0, equity: 1010 });
const [trade] = journal();
expect(trade).toMatchObject({ symbol: "BTCUSDT", status: "win", direction: "long" });
expect(trade!.grossPnl).toBeCloseTo(10, 9);
expect(trade!.fees).toBeCloseTo(0.48, 9);
expect(
db
.select()
.from(executions)
.all()
.every((row) => row.assetClass === "futures"),
).toBe(true);

expect(await syncAccount("bn")).toMatchObject({ inserted: 0, duplicates: 2 });
});

it("in hedge mode, a long and a short held at once on one symbol stay two trades", async () => {
fills = [
fill("ETHUSDT", "BUY", "1", "3000", hoursAgo(10), { positionSide: "LONG" }),
fill("ETHUSDT", "SELL", "1", "3010", hoursAgo(9), { positionSide: "SHORT" }),
fill("ETHUSDT", "SELL", "1", "3050", hoursAgo(8), { positionSide: "LONG" }),
];
positions = [
{ symbol: "ETHUSDT", positionSide: "SHORT", positionAmt: "-1", notional: "-3000" },
];

expect(await syncAccount("bn")).toMatchObject({ inserted: 3, skipped: 0 });
const [long, short] = journal();
expect(long).toMatchObject({ direction: "long", status: "win" });
expect(long!.grossPnl).toBeCloseTo(50, 9);
expect(short).toMatchObject({ direction: "short", status: "open", openQuantity: 1 });
});

it("closes of positions opened before Binance's three months of history are skipped", async () => {
fills = [
// One-way mode: selling a long bought before the history starts.
fill("BTCUSDT", "SELL", "1", "60000", hoursAgo(5)),
// Hedge mode: closing a long with nothing open on that side.
fill("ETHUSDT", "SELL", "1", "3000", hoursAgo(4), { positionSide: "LONG" }),
];

const outcome = await syncAccount("bn");
expect(outcome).toMatchObject({ inserted: 0, skipped: 2 });
expect(outcome.skippedReasons.join(" ")).toContain("before the broker's available history");
expect(journal()).toEqual([]);
});

it("a close of a position partly opened before the history keeps the covered part, in both modes", async () => {
// A long of 2 opened before the history: buy 1 more, sell all 3, then trade 1 again.
const cycle = (symbol: string, positionSide: string) => [
fill(symbol, "BUY", "1", "100", hoursAgo(10), { positionSide }),
fill(symbol, "SELL", "3", "110", hoursAgo(9), { positionSide }),
fill(symbol, "BUY", "1", "120", hoursAgo(8), { positionSide }),
fill(symbol, "SELL", "1", "130", hoursAgo(7), { positionSide }),
];
fills = [...cycle("BTCUSDT", "BOTH"), ...cycle("ETHUSDT", "LONG")];

const outcome = await syncAccount("bn");
expect(outcome).toMatchObject({ inserted: 8, skipped: 2 });
const booked = journal();
expect(
booked.map((trade) => [trade.symbol, trade.direction, trade.status, trade.quantity]),
).toEqual([
["BTCUSDT", "long", "win", 1],
["ETHUSDT", "long", "win", 1],
["BTCUSDT", "long", "win", 1],
["ETHUSDT", "long", "win", 1],
]);
for (const trade of booked) expect(trade.grossPnl).toBeCloseTo(10, 9);
expect(await syncAccount("bn")).toMatchObject({ inserted: 0, duplicates: 8, skipped: 0 });
});

it("an open hedge-mode short doesn't hide a one-way close from before the history", async () => {
fills = [
fill("BTCUSDT", "SELL", "1", "60000", hoursAgo(6)),
fill("BTCUSDT", "SELL", "1", "61000", hoursAgo(2), { positionSide: "SHORT" }),
];
positions = [
{ symbol: "BTCUSDT", positionSide: "SHORT", positionAmt: "-1", notional: "-61000" },
];

expect(await syncAccount("bn")).toMatchObject({ inserted: 1, skipped: 1 });
expect(journal()).toMatchObject([{ direction: "short", status: "open", openQuantity: 1 }]);
});

it("a quarterly contract held to delivery keeps its opening fill", async () => {
// Settlement leaves no fill, so the flat position list can't prove the history is short.
fills = [fill("BTCUSDT_261225", "BUY", "1", "60000", hoursAgo(40))];

expect(await syncAccount("bn")).toMatchObject({ inserted: 1, skipped: 0 });
});

it("a later sync asks Binance only for recent fills", async () => {
fills = [fill("BTCUSDT", "BUY", "0.01", "60000", hoursAgo(30))];
positions = [{ symbol: "BTCUSDT", positionSide: "BOTH", positionAmt: "0.01", notional: "600" }];
await syncAccount("bn");
const fetchMock = vi.mocked(globalThis.fetch);
fetchMock.mockClear();

await syncAccount("bn");
const starts = fetchMock.mock.calls
.map(([input]) => new URL(String(input)))
.filter((url) => url.pathname === "/fapi/v1/userTrades")
.map((url) => Number(url.searchParams.get("startTime")));
expect(Math.min(...starts)).toBeGreaterThan(Date.now() - 31 * DAY_MS);
});
});
Loading