Aggregate volumes

Name of the ledger

A filter, accepted in EITHER of two interchangeable representations that parse to the same filter and are validated against the same per-target rules:

• Textual — the human-readable filter grammar, e.g. metadata[status] == "active", address ^= "users:", metadata[a] == "x" and metadata[b] == "y". Passed verbatim as the query-parameter value (URL-encoded).
• Structured — the JSON QueryFilter DSL (see the QueryFilter schema: $and/$or/$not + $match/$gt/$exists/…). Passed by URL-encoding the JSON object as the query-parameter value.

A condition that is not valid on the endpoint's target (e.g. a transaction-only condition on the accounts list) is rejected with 400. This generic filter is AND-combined with any convenience parameters the endpoint also exposes (e.g. the transactions startDate/endDate timestamp range). Selections that used to have dedicated aliases are expressed through this filter: an account address prefix via filter=address ^= "users:", a transaction reference via filter=reference == "..." or filter={"$match":{"reference":"..."}} (URL-encoded).

Both representations cover the same fields under the same names: metadata[<key>], address, source, destination, reference, reverted, ledger, id, timestamp, insertedAt, revertedAt, logId, date (e.g. textual id > 100 and reverted == false or structured {"$and":[{"$gt":{"id":100}},{"$match":{"reverted":false}}]}).

Date fields accept either an RFC3339 timestamp or raw Unix microseconds, in both representations: on transactions timestamp / insertedAt / revertedAt (e.g. textual filter=timestamp >= "2023-11-14T22:13:20Z" or structured filter={"$gte":{"timestamp":"2023-11-14T22:13:20Z"}}), and on logs date (e.g. filter=date >= "2023-11-14T22:13:20Z"). An RFC3339 value before the Unix epoch (1970-01-01) is rejected with 400.

Note: the bare audit fields (outcome, ledger, seq, proposal_id, timestamp, log_seq, caller_subject, order_type, idempotency_key) are valid only on the audit-entries endpoint, where both representations resolve them against the audit target.

Merge assets with the same base at the highest observed precision

Comma-separated list of account prefixes to group volumes by

When true, every colored bucket of the same (asset, precision) is summed and the resulting AggregatedVolume entry carries color = "". By default the response is segregated per (asset, color).

Read consistency. linearizable (the default) runs a Raft ReadIndex barrier and waits for the receiving node to apply up to it. stale serves the read from the receiving node's own store, with no barrier and no forwarding to the leader, so the answer may lag the leader. Matching ignores case and surrounding whitespace. An unknown value, or a repeated or comma-joined header, returns 400 INVALID_REQUEST on every /v3 route, writes included; a valid value has no effect on writes. The gRPC equivalent is the x-consistency request metadata.

Render all response Uint256, BigUint and SignedBigInt values as canonical decimal strings, regardless of business meaning, including posting amounts, volume input/output and balances. Ordinary integer IDs/counts, metadata and explicitly string-encoded counters keep their existing representation. Case-insensitive true, yes, y and 1 enable this option, matching Ledger v2. Whitespace is not trimmed. Omission and every other value retain JSON number tokens. This affects only this response, including nested objects, maps, arrays, transaction/log/cursor and bulk results. Request decoding is unchanged.

Set to any non-empty value to receive the query profile in the X-Query-Profile-Result response header.

The profile reports server-side request timing (how long the server spent handling the request, broken down into prepare / execute / read-barrier / deliver phases) plus the query execution plan. Use it to tell a slow network from a slow server: serverDurationUs is the consumer-independent server cost, and it excludes both the caller-requested read barrier and response delivery.

Supported on the transactions list, accounts list, aggregated volumes and prepared-query execution endpoints. The equivalent gRPC opt-in is the x-query-profile request metadata, answered in the x-query-profile-result-bin trailer; serverDurationUs has the same definition on both surfaces, so the two are directly comparable.