How often should broker reconciliation run?
Choose frequency based on the operating workflow, broker limits, stream reliability, and consequence of drift. Use faster checks for uncertain requests and broader scheduled reviews for completeness.
Trading Systems
Building a Reconciliation Ledger for Broker Integrations
Compare local order and execution records with broker snapshots using durable observations, discrepancy types, ownership, and controlled resolution.
How the workflow connects
- 1Capture a broker account snapshot
- 2Match orders and executions by durable identity
- 3Compare state, quantity, and timestamps
- 4Create an owned discrepancy record
- 5Resolve and retain both source observations
Streams and request responses can be delayed, missed, or interpreted incorrectly. A reconciliation ledger provides a separate record of what the application expected, what the broker reported at a known time, and how any discrepancy was resolved. It supports software operations and does not imply a trading outcome.
Store observations instead of overwriting state
Record the reconciliation run, connection, environment, query window, source time, received time, and broker response reference. Match broker records to local requests using client and broker identifiers. Keep both local and observed fields when they differ.
Classify discrepancies by required action
Examples include local order missing broker ID, broker order missing locally, state mismatch, filled-quantity mismatch, duplicate local mapping, unrecognized execution, or stale local update. Each type should define severity, automatic checks, owner, and permitted resolution.
- Affected account, order, execution, or position
- Local value and update time
- Broker-observed value and source time
- Discrepancy type and confidence
- Owner, status, and resolution note
Limit automatic repair to safe facts
The system may attach a broker identifier when the match is unambiguous or apply a later confirmed state. It should not submit, cancel, or alter an order merely to make records agree unless that action is part of an explicit, authorized recovery policy.
Use checkpoints without hiding late events
Reconcile a recent overlap window and maintain a separate schedule for older open or uncertain records. Advance checkpoints after observations are stored, not after every discrepancy is resolved. Later broker events can update the discrepancy while preserving the earlier evidence.
Compare observations without erasing history
Suppose the local system records an order as open while the broker snapshot reports it filled. Add the broker observation with source time, retrieval time, broker order ID, quantities, prices, and raw status. Create a discrepancy that links both facts and classifies the required response. Do not overwrite the local event history to make the records appear consistent.
The resolution may apply a missing fill event, mark a stale local projection for rebuild, or require review because identifiers do not match. If an automated repair is allowed, record the rule and resulting events exactly as a manual resolution would. Financial calculations and positions should be recomputed from confirmed facts according to the system design.
| Difference | Likely class | Response |
|---|---|---|
| Broker order missing locally | Unmatched venue record | Investigate identity before import |
| Local open; broker filled | Missing lifecycle event | Retrieve source detail and apply confirmed event |
| Quantity differs | Partial fill or mapping issue | Compare source fills and units |
| Local request absent at broker | Unknown submission result | Check attempts and broker history before retry |
| Same facts; stale projection | Read-model lag | Rebuild projection without changing source events |
Make reconciliation a routine operating process
Run comparison at startup, after reconnect, on a schedule appropriate to the workflow, and before clearing uncertain incidents. Checkpoints can limit the time range, but include overlap and open records so late events are not skipped. Monitor unmatched identities, discrepancy age, automatic repair volume, repeated categories, and ledger runs that did not complete.
Give operators search, evidence, ownership, resolution options, and a way to reopen an incorrect resolution. Restrict repair actions by role and require reasons for consequential changes. Reconciliation verifies software records against broker-reported facts; it does not validate a strategy or provide investment advice.
Visual guide
The reconciliation operating loop
The process observes both sides, classifies differences, resolves them through controlled events, and verifies the result.
- 1
Collect
Load local durable state and broker-reported orders, fills, and positions.
- 2
Match
Use stable local and venue identifiers with connection context.
- 3
Compare
Check lifecycle, quantities, and relevant source versions.
- 4
Resolve
Apply a safe event, rebuild a projection, or assign review.
- 5
Verify
Run comparison again and retain the resolution evidence.
Practical questions
Questions that often come up
Does reconciliation replace streaming order updates?
No. Streams provide timely events. Reconciliation provides an independent comparison that can recover missed updates and detect disagreement.
Continue exploring
Related projects and tutorials
Work with Sun Cluster
Planning a similar system for your organization?
Sun Cluster develops broker integrations with durable order records, reconciliation, monitoring, and controlled recovery paths.