Account analytics

Read how an account your venue holds is doing in its current cycle: its profit and loss, its trading days, its equity samples and how complete the evidence is. Use this page when you build reports, payouts or advancement on top of an account’s results. By the end you know what each field measures and when a figure is safe to act on. The read reaches only accounts your venue holds. An account the venue doesn’t hold answers 404, the same as one that doesn’t exist.

Read performance

Required scope: account:read.

export TRDRS_API_BASE_URL="https://sandbox.trdrs.co"

curl "$TRDRS_API_BASE_URL/api/venues/$VENUE/accounts/$ACCOUNT/analytics" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY"

The response is { accountId, analytics }. analytics is one consistent snapshot, identified by asOf, snapshotId and cycle.id. Reading it places no order, moves no balance, resets nothing and advances no stage. Money is in the account’s currency, stated once at the precision trdrs posts it in (cents for US dollars) and rounded half to even, so an equity of 50,070.625 reads 50,070.62. Quantities can be fractional, timestamps are UTC ISO 8601, and a fill is dated by the instant trdrs recorded it.

Field	Meaning
`pnl.grossRealized`	Realized profit and corrections in the current cycle.
`pnl.fees`	Commission, fees, financing and funding charged in the cycle, including fees paid to open positions that are still open.
`pnl.netTrading`	Gross realized profit minus all fees, plus `pnl.imported`. This is the stage target’s basis.
`pnl.balanceAdjustments`	Signed credits, debits and adjustments since the current cycle began, such as top-ups and payouts. The cycle’s opening balance isn’t one.
`pnl.balance`	The account’s balance, including those adjustments.
`pnl.unrealized`, `pnl.equity`	The account’s risk valuation of what it holds, or `null` while that valuation doesn’t cover the account. A flat account’s equity equals its balance.
`pnl.imported`, `tradingDays.imported`	A result and trading days the cycle opened with from the account’s earlier records, kept apart from everything the cycle did since, or `null`. An account you issue opens with neither.
`closedTrades`	Each fill’s closing portion: a stable id, the instrument, the `positionId` it closed (on `independent_tickets`, the ticket), direction, quantity, entry and exit prices, opening and closing times, gross profit, allocated fees and net profit. Partial closes are separate rows, and a reversing fill closes the old position and opens its remainder.
`positionModel`	The account’s position mode: `net`, one position per instrument, or `independent_tickets`, where each entry order opens its own ticket.
`openPositions`	Signed quantities, average prices, when each opened, and unrealized profit where valued. Each row names its position by `positionId`, a new id each time a position opens. On `independent_tickets` each open ticket is its own row, so a long and a short ticket on one instrument are two rows.
`openOrders`	Every working order, including protective stops and targets. An empty position list alone doesn’t make the account safe to advance.
`risk.breaches`	The risk rules that fired in the current cycle, and each liquidation it opened, recorded as `stop_out`. Your own halt, the profit targets and the end-of-day close aren’t breaches, and a lock that lifts doesn’t erase one.
`risk.halted`, `risk.lockReason`	Whether the account is locked now, and why.

Example: $3,010 of realized profit, $10 of fees and a $500 promotional credit produce `netTrading: 3000` and `balanceAdjustments: 500`. The credit can't satisfy a $3,500 trading target. A closed trade’s net profit can differ from the account’s net trading profit while positions are open, because the entry fees on those positions are already charged to the account. An account held at a provider answers from the provider’s own records instead, marked book: "provider". It has no equity history (equityHistory is null) and no breaches, because your rules don’t apply there. trdrs judges your risk rules on the account’s present state, at present prices. If an account’s risk decisions fall more than a minute behind its prices, for example after an outage, they catch up on those older prices for the record and act only at the present. A rule the older prices broke that the account no longer breaks once its decisions catch up isn’t reported in risk.breaches: it locks nothing, closes nothing and doesn’t disqualify the account. A rule the account still breaks fires at once. completeness.risk reads false until the decisions catch up.

Count trading days

A qualifying day is a distinct session with at least one fill. Opening fills, closing fills and losing trades count. Placing or cancelling an order that doesn’t fill, signing in, receiving a credit, or holding a position overnight doesn’t. Weekends count too: a crypto fill on Saturday counts if it falls in a distinct session. Sessions come from the stage version the account’s running cycle is judged by, the session your venue published with that stage, and tradingDays.session states which one a response counted in. A cycle no stage judges is counted in the 17:00 America/Chicago roll: at 17:00 local time the next session starts, its label is the next calendar date, and the time zone observes daylight-saving changes. No request can choose another session, so no caller can move an account’s days. trdrs doesn’t evaluate minimum profitable days, minimum volume per day or exchange-holiday exclusions. If your stage rule needs them, check them in your backend before you advance.

Page through equity history

equityHistory.points holds the latest samples, up to 1,000, newest first, at most one a minute. trdrs samples each account’s balance, and its equity from the account’s risk valuation, with a null equity while that valuation doesn’t cover the account. It’s a sampled curve, not tick-by-tick history or proof of the exact intraday high and low, and it can have gaps. continuous is always false. mayHaveOlderSamples says another page exists. Request the same analytics URL with equityBefore set to equityHistory.nextBefore to get the next older page, and continue until nextBefore is null. Check that cycle.id hasn’t changed on each page, and start again if it has. Every other field describes the latest snapshot, not the page’s time. A missing or stale mark gives a null equity point, never an invented zero, and a mark values a position for at most 10 seconds.

Check completeness before you use a total

trading is false when the cycle’s fills and balance don’t reconcile (balance_does_not_reconcile), a fill’s terms are unknown (execution_terms_unknown), a charge is owed that nobody could price (charge_unpriced), or a source passes 50,000 rows (source_limit_exceeded). reasons names each one. A capped response holds partial data, so don’t use its totals as final performance.
risk is true while the account’s risk decisions cover its whole current cycle, and riskReasons says why when they don’t. An account whose cycle isn’t fully covered reads false, even if no breach can be found.
currentEquity is false while the risk valuation doesn’t cover the account. equityHistory reads sampled_not_continuous.
unresolvedCommands counts orders and commands whose outcome isn’t known. Any of them blocks advancement, even when the account looks flat.

These reads report the risk evidence trdrs recorded. They don’t test your own rules after the fact or rebuild an intraday drawdown nobody recorded. Configure your risk controls before trading, and evaluate any other business rule in your own backend. Never read an incomplete answer or an HTTP error as permission to advance.

Read reset boundaries

cycle.startedAt is when the account opened or was last reset. A reset starts a new cycle.id and restarts the trading-day count and the profit figures. cycle.resetBoundaries lists the reset boundaries, and cycle.resetAt is the latest reset. The read covers the current cycle alone, so priorTradingHistoryAvailable is always false. Export analytics before a reset if you need that history. When completeness.risk is false, don’t reset the account just to make it pass: review its history separately. A new cycle is covered from its start, and trdrs never declares an earlier cycle’s missing evidence complete.

Check a stage and advance

Stage eligibility and the advance are separate venue operations. GET /api/venues/{venueId}/accounts/{accountId}/stages/{stageId}/eligibility measures the account against the rules its current cycle opened under and states every failing reason, and POST .../stages/{stageId}/advance issues the one next account a passed stage allows. Run a venue walks through both.

Handle errors

Status	What to do
`400 invalid_equity_before`	`equityBefore` isn’t an ISO timestamp. Send the `nextBefore` the previous page gave you.
`401`, `403`	Fix the key or its scope.
`404`	Check that your venue holds the account.
`429`, `5xx` or a network failure	Retry with backoff.

Never read an error or a missing figure as a pass.

Start here

Set up your venue

Run accounts

Connect pre-registration

Check your integration

Read performance

Count trading days

Page through equity history

Check completeness before you use a total

Read reset boundaries

Check a stage and advance

Handle errors

​Read performance

​Count trading days

​Page through equity history

​Check completeness before you use a total

​Read reset boundaries

​Check a stage and advance

​Handle errors

Read performance

Count trading days

Page through equity history

Check completeness before you use a total

Read reset boundaries

Check a stage and advance

Handle errors