A broker's position endpoint is not a complete source of truth. It is one observation of account state, often arriving after fills, cancellations or manual changes have already occurred.
An unattended agent needs to know what it believes it holds, what the broker reports, and whether those records refer to the same point in time. If they disagree, the agent must contain risk before it decides which record to trust.
A position mismatch is not merely a dashboard warning. It can make the next order double exposure, reverse a hedge or close a position that is no longer open.
Use the first 30 days to build that process as a small, testable subsystem. Keep position accounting separate from strategy logic. Do not let the strategy submit an order while its account state is marked uncertain.
Treat broker state as evidence, not a ledger
Maintain an internal position ledger from execution events, then compare it with broker snapshots. For each instrument, calculate expected quantity from the starting position, signed executions and explicit adjustments.
A buy fill adds quantity and a sell fill subtracts it for a netted position. In a hedging account, long and short quantities are separate. The account's position mode changes the meaning of a quantity, so record it as part of the account configuration.
Do not add an order's cumulative filled quantity to every update. Broker streams may send repeated updates containing the new cumulative total.
Store execution identifiers and apply each execution once. If the API exposes only cumulative fills, track the last accepted total per order and apply only the positive difference. Treat corrections, busts and trade cancellations as signed ledger entries, not as edits that erase history.
Position identity needs more than a ticker string. Include broker account, canonical instrument identifier, contract expiry where relevant, currency and position mode. Include the venue's contract multiplier for futures and the correct quantity scale for fractional shares or lots.
For FX, define whether the position is represented in base units, quote units or lots. An apparently small mismatch can be a unit conversion bug.
Set explicit states such as known, reconciling, drifted and halted. Strategy code may trade only when the account is known and the latest reconciliation is within policy. A broker snapshot should update that state, but should not silently overwrite the execution ledger.
Days 1-10: define identity and build the event ledger
Days 1-4: write down the rules
Document the account's position model, supported instrument types and all events that can change quantity. Include fills, execution corrections, transfers, corporate actions, expiry or exercise, broker liquidation and manual trades. If a broker allows manual orders, assume someone will eventually use them. Record the operational response instead of pretending those trades cannot happen.
Define a reconciliation key and a comparison policy before writing the polling loop. Quantity is usually the primary comparison. Notional is a useful secondary check, but prices move and valuations may use different marks. Set tolerances per instrument, not with one account-wide percentage. A fractional-share account may tolerate a different absolute residual from a futures account where one contract is indivisible.
- Persist raw broker events and snapshots with receipt time, broker event time and a local sequence number.
- Deduplicate executions using broker execution IDs where available, scoped to the account and order.
- Store order state separately from position state. An open order is potential exposure, not a filled position.
- Define how to handle missing IDs, unknown instruments, stale snapshots and events received out of order.
Days 5-10: implement a replayable ledger
Keep an append-only record of events and derive current positions from it. Each record should carry its source and an idempotency key. Make the calculation deterministic: replaying the same accepted events must produce the same positions. Store the broker's raw payload alongside parsed fields so an adapter change can be investigated without relying on logs that may have been discarded.
Build tests for partial fills, duplicate events, a cancel arriving before a delayed fill, and reconnects that replay old executions. Test long and short positions, netting and hedging modes, and at least one instrument with a multiplier.
Keep strategy decisions out of these tests. At this stage the question is whether the ledger accounts for broker events correctly, not whether a trading signal is profitable.
Days 11-17: reconcile snapshots without racing fills
A snapshot and an execution stream rarely form one atomic view. A fill can happen while a positions request is in flight. Comparing a snapshot from before that fill with a ledger that already includes it creates false drift. Conversely, accepting a snapshot first and then applying a replayed fill can count the same exposure twice.
Use a watermark when the broker provides event sequence numbers or timestamps with documented ordering. Request a snapshot, record the request and response times, then reconcile against ledger events through a defensible boundary.
If the API gives no consistent watermark, treat a mismatch shortly after an event as provisional. Fetch again after a short delay and check whether the stream and snapshot converge. Do not claim strong consistency where the API does not provide it.
The ranges below are typical operating ranges across broker APIs, not guarantees. Measure the actual venue and account in use, then tune polling and alert thresholds against its rate limits and event behaviour.
| Measurement | Typical range | Design use | Operational caveat |
|---|---|---|---|
| Position snapshot response | 100 ms to 2 s | Estimate request latency and timeout budget | Slow responses can already be stale when received |
| Execution event delivery delay | 50 ms to 5 s | Set provisional mismatch windows | Reconnects can deliver duplicates or older events |
| Post-fill snapshot convergence | 1 to 30 s | Choose a second-check delay | Some APIs document no convergence bound |
| Position polling interval | 1 to 5 s | Balance detection speed against API limits | Use backoff and respect account-level quotas |
| Initial quantity tolerance | 1 smallest tradable unit, or a policy-defined residual | Separate rounding noise from actionable drift | Never use the same rule for every product |
For every comparison, retain both values, their timestamps and the calculation of the difference. A useful record says which account and instrument differed, the expected and reported quantities, the latest accepted execution, the snapshot age and the reason the agent chose to continue or halt. That gives an operator something actionable and makes automated tests repeatable.
Days 18-24: contain drift and recover safely
Not every mismatch should trigger the same response. A one-unit residual within a documented rounding tolerance may be a warning. An unexplained position that changes gross exposure, or a stale account snapshot during an open order, may require a trading halt.
Make the policy explicit and deterministic. A default safe response is to stop new risk-increasing orders, keep polling and alert an operator. Automatically flattening on every discrepancy can turn a temporary data race into a real loss.
On reconnect, do not immediately resume from a cached position. Mark the account uncertain, restore the event stream, fetch open orders and positions, and reconcile them against the durable ledger. If an event gap cannot be repaired from broker history, identify the affected instruments and require a fresh baseline or human review.
Preserve the old ledger and record the baseline adjustment with its source. Never disguise a reset as an ordinary fill.
- Halt new orders when position state is uncertain, while keeping risk-reducing actions available only under a separate rule.
- Check open orders as well as filled positions. Pending quantity can change exposure before the next position snapshot.
- Alert on repeated drift, stale snapshots, unknown instruments and event gaps, with account and instrument identifiers.
- Require an explicit operator action for unexplained manual trades or broker-side adjustments.
Use a bounded recovery loop: retry the snapshot with backoff, compare again after pending events have had time to arrive, then escalate. Bound the number of retries and the total time spent in an uncertain state. If the account remains unresolved, leave it halted rather than allowing the strategy to infer a position from an old cache.
Days 25-30: prove behaviour under faults
Test the subsystem with controlled faults before it can place unattended orders. Disconnect the stream during a partial fill. Duplicate an execution. Delay a snapshot. Change a position manually at the broker. Return an incomplete response or an unknown contract identifier.
Verify that the ledger, reconciliation state and order gate move through the expected states. A test passes only if the agent's order behaviour is safe, not merely if its logs contain an error.
Rehearse reconnect and drift scenarios in a realistic paper environment such as agentic paper trading. Paper fills cannot prove live broker consistency, but they can test the agent's response to delayed events, retries and state resets without placing live orders. Agentic Trading Index paper trading starts at $9.99 per month.
Run the reconciler in shadow mode against the intended broker account before enabling its order gate. Compare its decisions with broker records and investigate every mismatch. Then enable a small, tightly limited deployment: cap order size and gross exposure, restrict the instrument set, and keep an operator alert channel active. Do not increase limits just because a few clean sessions passed.
By day 30, the deliverable is not a green status light. It is a replayable ledger, a measured view of the broker's timing, defined mismatch policies, tested recovery paths and a hard block on trading from uncertain state. Put the policy version and last successful reconciliation time in the order decision log, so each submitted order can be traced to the state that authorised it.
This week, implement the durable execution ledger and a test that proves duplicate fills cannot change the derived position twice.
Frequently Asked Questions
How often should a trading agent reconcile positions?
A common starting range is polling every 1 to 5 seconds, subject to the broker's API limits and event-stream quality. Reconcile after reconnects, event gaps and relevant order changes as well as on a timer. Measure the broker's actual delays before choosing a production interval.
Should the broker position or the agent ledger win when they disagree?
Neither should be accepted blindly. Compare timestamps, execution history, open orders and snapshot freshness, then mark the account uncertain if the mismatch cannot be explained. Block new risk-increasing orders until the difference is resolved or explicitly reviewed.
Can an agent use a broker position snapshot as its only position record?
That is risky because snapshots may be delayed, incomplete or inconsistent with fills received during the request. Maintain a durable execution ledger and use snapshots as an independent reconciliation check. Record broker-side adjustments as explicit events or baselines with their source.
