IBKR import

What a Flex query is

A Flex query is a saved report definition inside Interactive Brokers. You choose which sections it contains — positions, trades, cash transactions — and IBKR generates that report on demand when something asks for it with your Flex Web Service token.

That is the entire connection. The token fetches statements and nothing else: it cannot place a trade, move cash, or change a single setting in your account. You generate it yourself in Client Portal and you can revoke it there at any time, without telling us. Bitnora stores it encrypted at rest and never displays it again after you save it.

Setting it up

About three minutes in IBKR Client Portal, once. The connect screen in Bitnora carries this same recipe next to the fields, with a live checklist that tells you which sections IBKR actually returned — so if you miss one, you find out immediately rather than a month later.

1. Step 01

   Generate the token

   Performance & Reports → Flex Queries → Flex Web Service Configuration → turn it on → set expiry to 1 year → copy the token.

2. Step 02

   Create an Activity Flex Query

   Performance & Reports → Flex Queries → next to “Activity Flex Query”, click + Create. Name it Bitnora History. Set yours up before the rename? A query still called WealthMap History keeps working — the importer goes by Query ID, never the name, so leave it alone.

3. Step 03

   Tick five sections

   Inside each one, selecting all fields is fine. Two of them need a setting changed — see the table below.

4. Step 04

   Set the delivery configuration

   Format XML, Period Last 365 Calendar Days. Any date format works.

5. Step 05

   Save and copy the Query ID

   The Query ID is the number next to your query in the list, not its name. Paste it and the token into Bitnora, then choose Test and import.

Open Positions

What you hold right now; this is your net worth.

Trades

Set Options to Executions — every buy and sell, so your cost basis and history are real.

Cash Transactions

Set Level of Detail to Detail — your dividends, deposits, and withdrawals; without these your returns are wrong.

Cash Report

Your cash balance; it is part of your net worth.

Corporate Actions

Splits and mergers, so share counts stay correct over time. Leave it out and the import still works, but splits will not be tracked.

IBKR builds the report when asked, which usually takes under a minute. If it is still generating, Bitnora retries on its own and tells you which attempt it is on. A query that returns positions but no trades or cash rows is caught before anything is imported, with the exact edit needed to fix it — that combination produces a correct net worth and a wrong performance chart, which is worse than an obvious failure.

What gets imported

Everything the query contains, classified into a single ledger that manual and paper portfolios also write into:

• Open positions, with quantity, cost basis, and currency.
• Trades, with price, proceeds, commission, and tax, down to the individual execution.
• Cash transactions: dividends, interest, deposits, withdrawals, fees, withholding tax, and FX conversions.
• Cash balances per currency.
• Corporate actions, when that section is in the query.

The import receipt counts what landed — trades, dividends, deposits, positions, cash balances — and says plainly when a row could not be parsed, rather than reporting a clean import over a partial one. A cash row whose description matches nothing known is filed as unclassified instead of being guessed at.

Rebuilding a year of history

An import gives you today. The backfill gives you the year behind it: Bitnora replays the imported ledger day by day, fetching the historical prices and exchange rates each day needs, and stores a daily snapshot of what the book was worth. Your performance chart is therefore measured, not reconstructed from today’s balance and an assumption.

Window

Up to 365 days, ending yesterday. It starts wherever your Flex report starts, floored at a year back.

Young accounts

The window is clamped to the earliest date the ledger can actually reconstruct. Reaching further back would fabricate history, so it does not.

While it runs

It runs in the background and you can close the tab. The dashboard shows its progress in the chart slot rather than an empty chart.

Syncing, and importing the same statement twice

A scheduled sync runs on weekday evenings and pulls the same query again, so positions, new trades, and new cash activity arrive without you doing anything. You can also sync on demand from settings, or upload a Flex report file directly if you would rather not store a token at all.

Every import is replay-safe. Each event is fingerprinted from what it is — the instrument, the timestamp, the size, the price — and matched on the broker’s own event id where IBKR provides one, so re-importing a statement you already imported changes nothing. Two genuine partial fills that share every field down to the second are still counted as two, because the deduplication is ordered rather than set-based.

0 new rows — all 412 trades were already recorded.

That message is a success, not a warning, and the receipt says so. The one thing worth watching for is the opposite case: a sync that keeps succeeding while importing nothing at all usually means the saved query stopped covering Trades and Cash Transactions, and Bitnora says exactly that on the income page rather than letting the figures quietly go stale.

Reconciliation

After a rebuild, Bitnora compares the state its own ledger replays to against the latest statement the broker sent, position by position and currency by currency. It reports what disagrees instead of averaging the difference away.

• Position mismatches, named by ticker.
• Cash gaps, named by currency.
• Unclassified broker rows that may leave the reconstructed state incomplete.
• A stale broker statement, when the newest one on file is more than a few days old.

The result is a trust state you can see rather than a silent assertion of correctness: a clean run says no differences were found; a run with warnings names them and leaves the numbers on screen so you can judge them. Reconciliation never blocks anything — it is a report about your data, not a gate in front of it.

You can see all of this working on the public demo book, which was built exactly this way and reconciles cleanly.