Balance operations

Inspect wallet mutation records against operator adapter.

Path

GET /api/operator/balance-operations

Required scope: balance_operations:read

Query params

All query parameters are optional.

Direction values:

• debit
• credit
• debit_reversal
• credit_reversal

Status values:

• planned
• sent
• succeeded
• failed
• unknown
• retrying
• manual_review

Filtered summary

Every response includes a summary computed across all rows matching the same authenticated-operator and query-filter predicates as items and pagination.total. Summary values are not limited to the current page and are not implicitly restricted to succeeded; use status when a status-specific report is required.

The response also returns product_scope and includes_multiple_products. Summary amounts follow the explicit product filter; the default remains Opinion-only so Polyflight money is never silently mixed into existing Opinion views.

For product=opinion, the three summary totals are JSON numbers. For product=polyflight or product=all, they are exact decimal integer strings. Preserve the returned type and do not parse integer strings through floating-point arithmetic.

created_from and created_to remain inclusive for the summary, count, and rows. Dashboard date-only filters expand to 00:00:00.000Z and 23:59:59.999Z UTC before calling this endpoint.

Response highlights

The envelope is { product_scope, includes_multiple_products, summary, items, pagination }. Pagination contains page, page_size, total, and total_pages (at least 1).

• external_amount_minor
• currency_code
• idempotency_key
• remote_reference
• request_json
• response_json
• balance_after_minor
• product
• operation_type
• polyflight_purchase_request_id and polyflight_ticket_id, when applicable
• original_operation_id, when applicable
• failure_reason
• attempt_count
• next_retry_at
• nested operator_user
• nested market, nullable for Polyflight

balance_after_minor is nullable and is extracted from wallet response balanceMinor or balance_minor when present.

operation_type is derived from source links: order_id means trade; redemption_item_id means resolution; Polyflight purchase/ticket links mean polyflight_purchase / polyflight_ticket; an unlinked historical/internal row returns unknown.

Each item also includes numeric id, nullable order_id / redemption_item_id, direction, status, created_at, and updated_at. operator_user contains id, external_user_id, and nullable display_name; a non-null market contains id, slug, and title. Optional source links, remote reference, payloads, failure reason, balance-after, and retry timestamp may be null. The legacy generic list returns external_amount_minor as a JSON number; it is not the integer-string contract of the dedicated Polyflight operations endpoint.

Amounts are nonnegative operation magnitudes, not signed cash flow. A debit or credit reversal reduces the user's balance; a credit or debit reversal increases it. Only succeeded confirms an applied operation. With no status filter, summary totals include planned, failed, and unknown work and must not be described as cash received/paid. Distinct successful operation IDs are distinct wallet movements, even when their source order is the same.

For resolved-market warnings and redacted evidence, use Cash-flow triage, which additionally requires trades:read and redemptions:read. Neither this list nor triage permits operator-side financial confirmation or replay. Preserve the original operation and idempotency key when reconciling an unknown result; do not create a new-key payment.

Invalid enums return INVALID_STATUS, INVALID_DIRECTION, INVALID_TYPE, INVALID_PRODUCT, or INVALID_SORT. Invalid ID/date filters return the corresponding INVALID_* code. A market ID and market slug supplied together are combined, not alternatives.