When your engine and your broker disagree
There are always two books. One of them is authoritative and it is not yours — and an empty answer from it can mean three completely different things.
Your strategy believes it holds a position. The broker's book does not show it. Or the reverse: there is a position in your account that no strategy claims.
Both happen, and the first thing to be clear about is which book wins.
The broker's book is authoritative. It is the record held by the entity that actually faces the exchange. Your engine's view is a derived belief — it is what the engine concluded from the fills it knows about. If the two disagree, the engine's belief is what needs correcting, not the broker's record.
That ordering sounds obvious and is routinely violated in practice, usually by someone who trusts their own screen because it is more convenient to read. The practical form of the rule is sharper: when reconciling, the broker's quantity is the truth. Not the engine's expectation, not the sum of what you think you ordered. The quantity the broker reports is what you own.
Why the engine's view drifts
Partial fills. You ordered 300 units and 180 filled. If the engine records intent rather than execution, it believes 300. Everything downstream — the stop quantity, the exit, the risk calculation — is then sized for a position you do not have. This is the most common source of drift and the most quietly damaging, because a stop for 300 units against a 180-unit position is itself a new position once it triggers.
Manual intervention. You closed something by hand, or adjusted a leg from the mobile app, and the engine was not told. From its point of view nothing changed.
An order whose outcome was never recorded. It was sent and the response was lost, or it was rejected and the rejection was not stored. The engine does not know which, and "I do not know" tends to get stored as "it did not happen".
Something the engine never opened. A position exists that no strategy claims — a manual trade, another strategy's leg, or a residue from an earlier session. The engine is not wrong about its own positions; it is simply not the only thing trading this account.
The principle that avoids most of this: a position should be derived from fills, never from intentions. If the engine's holding is computed from the orders that actually executed, drift from partial fills is impossible by construction, because there is no second number to disagree with.
"Empty" is three different answers
Here is the trap that turns a reconciliation into an incident.
You ask the broker for the position book and get back nothing. That looks unambiguous. It is not.
The defence is to make every read say why it is empty. A system that distinguishes "the broker said you hold nothing" from "the broker did not answer" can reconcile safely; one that collapses both into an empty list cannot, and no amount of care further down will recover the distinction once it is lost.
If you are evaluating a tool rather than building one, this is a sharp question to ask it: when a position read fails, does it tell me, or does it show me an empty book? The second behaviour is common and it is the one that produces incidents.
Paper trading has no broker book at all
A specific case of the same confusion, and it bites during setup.
Simulated positions exist only in the platform. There is no broker holding them, so asking the broker about them returns — correctly — nothing. If a reconciliation routine compares simulated positions against a real broker book, every single one appears to be missing, and a routine that "corrects" discrepancies will try to reconcile away positions that were never supposed to be there.
The fix is conceptual rather than technical: simulated and live positions need one predicate that decides which book a position belongs to, applied everywhere, rather than each screen deciding for itself. The same applies to square-off: the word means one thing to a user and selects between two entirely different paths underneath, and a path that sends a simulated position to a broker — or a live position to a simulator — is a bug with real money attached.
Phantom rows
One last category, and it surprises people because the position is real.
A position can exist in your account on a contract that your local instrument list does not contain. Perhaps it is an expired series, or a contract from a segment whose master was not loaded, or an instrument added after your reference data was last refreshed. The broker reports a holding keyed by an identifier, and nothing locally knows what that identifier is.
The result is a row that cannot be named, cannot be priced, and often cannot be squared off through the normal path, because every one of those operations needs the contract's specification. It is a real position with no identity.
Two things to do about it. Show it anyway, labelled as unidentified, rather than filtering it out — a position you cannot name is precisely the one you most need to see. And treat it as a signal that your instrument data is stale for that segment, because that is almost always the actual cause.
A reconciliation worth running
Not complicated, and worth doing at the start and end of every session:
- Read the broker's book, and confirm the read succeeded — not that it returned zero rows, but that it actually answered.
- Compare quantities, instrument by instrument. The broker's number is the truth.
- Investigate every difference before correcting anything. A difference is information about what went wrong; silently overwriting it destroys the only evidence you had.
- Check for positions nothing claims — including unidentified rows.
- Correct the engine's belief, never the broker's record.
The habit matters more than the procedure. A mismatch found at 09:20 is a question. The same mismatch found at 15:25 is an emergency, and it will be the same mismatch.
What to take from this chapter
- There are always two books, and the broker's is authoritative. When reconciling, its quantity is the truth.
- The engine's view drifts from partial fills, manual intervention, unrecorded order outcomes, and positions it never opened.
- Derive holdings from fills, not from intentions — then a partial fill cannot create a disagreement.
- A stop sized for the quantity you ordered, against the quantity that filled, becomes a new position when it triggers.
- "Empty" means flat, refused, or wrong account. Only one of those is safe to act on, and some brokers return an error inside a success response.
- Ask of any tool: when a position read fails, does it tell me or show me an empty book?
- Simulated positions have no broker book. One predicate must decide which book a position belongs to, everywhere.
- Show unidentified positions rather than hiding them, and treat them as a sign your instrument data is stale.
- Reconcile at the start and end of every session. The same mismatch is a question at 09:20 and an emergency at 15:25.