Pick the right source
1
Read the account at one revision
The snapshot returns the summary, positions, and working orders at a single consistent
revision.Prefer it over stitching the one-shot reads together. Three reads taken separately are three
moments, and nothing in them says whether they agree — the snapshot is one moment that names
itself. It serves the same body the stream frames carry, so a client with no stream open, or
one coming back after a disconnect, reads exactly what it would have received.Apply it by the revision and nothing else: keep the newest frame you hold for that
accountId,
drop anything at or behind it, replace your whole picture with anything ahead of it. A frame
that skips revisions is still complete, so there is nothing to recover. Never compute a
revision of your own.One thing to know before you compare revisions: clock says whether the revision is the
account’s own history (engine) or trdrs reading a venue (observation). On an observation
clock every read is a new reading and carries a new revision, so two reads of an account that
nothing happened to still differ. Compare revisions, never count them.If a venue read fails part-way the answer is 502. Nothing partial is ever served — re-read.2
Read the fills
Fills come from the engine’s own ledger — backfill plus capture-forward — not from the live
broker, because execution marks want history that outlives a broker session.
instrument is
required.limit is 1–500 and defaults to 200. Each row is an id, the instrument, the side, the
quantity, the price, and executedAt in epoch seconds.3
Page the order history
List order history is the durable order ledger,
newest first. Pass the previous response’s
limit is 1–200 and defaults to 100.nextCursor back verbatim to get the next page; a null
nextCursor is the last page. The cursor is opaque — a malformed one is rejected with 400
rather than silently resetting you to page one, so a bug in your pager shows up as an error
instead of duplicate rows. The raw broker payload is stripped from every row.The live sibling is List orders. Omit filter and you
get the working orders — the same set the account stream snapshots, so the two agree. Supply
filter (all, open, filled, cancelled) to read the other buckets.4
Draw the equity curve
from and to are optional and must be exactly YYYY-MM-DD. A present-but-malformed bound is
a 400 rather than a silently widened range.Each row carries two disjoint sets of columns: the matched ones the engine computed
(matchedRealizedPnl, matchedCommission, matchedFees) and the ones the broker reported
(brokerRealizedPnl, brokerUnrealizedPnl, brokerNetLiq, brokerBalance,
brokerCommission). They are not alternatives to average — pick the series you mean and stay
on it. Nulls here are true nulls.5
List the closed trades
A round trip is one FIFO-matched closed trade: direction, quantity, entry and exit average
price, when it opened and closed, its trade day, and the realized P&L with commission and fees.Cursor-paged, newest first,
limit 1–500 and defaults to 100. This cursor has three components
because rows can share a close time and close execution id, and are only made unique by the
entry execution id — a two-part cursor would skip or duplicate those siblings. Treat it as
opaque and pass nextCursor back verbatim.List closed positions is the simpler,
broker-supplied view. A broker that cannot supply position history answers an empty list, never
an error — which is exactly why the next step matters.6
Know whether the ledger is complete
An empty ledger and a ledger that is still filling look identical. This is the route that tells
them apart.It reports backfill and tail progress for the fills and orders ledgers. Each stream is
null
until its first sync row exists, so:Snapshot or ledgers
Use the snapshot — or the stream, which carries the same body — whenever the question is about the present: what is open, what is resting, what the account is worth. It is one revision, it is internally consistent, and it costs one call. Use the ledgers whenever the question is about the past: an execution mark on a chart, a trade journal, a monthly statement, a reconciliation. They are durable, they page, and they are not bounded by the broker session that produced them. The one thing not to do is stitch several one-shot reads into a picture and treat it as consistent. That is what the snapshot exists to replace.Where to go deeper
- Paging — the three-line cursor loop, once, for both paged routes.
- Conventions — epoch seconds, true nulls, signed quantities.
- Stream live market data — the account stream, and why a reconnect needs no bookkeeping.
- Close a position — what produced the rows you are reading.