Cash-flow triage
Cash-flow triage
The Operator API exposes read-only Opinion cash reconciliation evidence:
| Method and path | Response |
|---|---|
GET /api/operator/market-pnl/issues | { items, pagination } |
GET /api/operator/market-pnl/issues/{kind}/{sourceId} | { issue } |
Both require trades:read, redemptions:read, and balance_operations:read, or *. Either an operator API key or staff session may read. Identity is always derived from authentication; operatorId or operator_id query parameters return 400 OPERATOR_SELECTOR_NOT_ALLOWED. Other operators' private markets are excluded.
There is no operator financial-resolution mutation endpoint. * does not turn an operator session/key into a Polynion Admin credential. Confirmation decisions belong to the separate Admin authorization and audit boundary.
List filters
All parameters are optional. Only resolved markets are included; there is no default date cutoff.
| Parameter | Values/default |
|---|---|
market_id | Exact positive market ID, maximum 2147483647. |
external_user_id | Exact operator external user ID; surrounding query whitespace is trimmed. |
search | Case-insensitive literal market title/slug substring. |
resolved_from_date, resolved_to_date | Inclusive YYYY-MM-DD dates in the operator timezone. Bounds select markets, not operation timestamps. |
issue_state | unresolved (default), failed, resolved, all; semantics below. |
kind | order or redemption. |
source_id | Exact positive source ID, maximum 2147483647. Use kind with this filter because IDs from the two source tables can overlap. |
page | Default 1, maximum 10000. |
page_size | Default 25, maximum 100. |
Ordering is source updated_at descending, kind, then source ID descending; no sort control is provided. pagination contains numeric page, page_size, total, and total_pages (minimum 1). One item represents one source, not one operation. A source blocker with no wallet-operation row remains visible with operations: [].
unresolved: positive pending count.failed: remaining failed payout or source statusfailed.resolved: no pending work and at least one recorded wallet-resolution decision. A remaining failed/unpaid obligation can still exist.all: unresolved work, remaining failed payouts, or recorded resolution history. This is not every normal historical order/redemption.
As in Market PnL, resolved_at currently uses markets.updated_at. Metadata edits can move its date. Reversed date bounds return INVALID_RESOLVED_DATE_RANGE.
Source and operation fields
Each issue contains:
| Field | Contents |
|---|---|
kind, source_id | order or redemption and its numeric source ID. |
operator | id, name, slug, timezone. |
operator_user | id, external_user_id, nullable display_name. |
market | id, slug, title. |
resolved_at | Approximate market resolution timestamp, nullable. |
source_status, failure_reason | Source state and nullable redacted failure context. |
created_at, updated_at | Source timestamps. |
pending_operation_count | Count of unresolved operations, or at least one source-level blocker where applicable. |
failed_payout_count, failed_payout_minor | Outstanding failed payout count and exact integer-string amount, not confirmed cash. |
operations | Linked Opinion wallet operations, ordered by operation ID. |
Operation fields are numeric id, state_version, attempt_count; strings direction, status, amount_minor, currency_code, idempotency_key; nullable remote_reference, failure_reason, next_retry_at, dispatched_at, completed_at; and created_at, updated_at timestamps. amount_minor is a nonnegative exact integer string; derive balance effect from direction (debit/credit_reversal subtract, credit/debit_reversal add) and check status before counting confirmed cash.
The projection also returns can_confirm_applied, can_confirm_not_applied, and nullable resolution_block_reason. These describe reconciliation eligibility, not operator permission to perform a confirmation.
Detail and evidence
kind must be order or redemption; sourceId must be a positive safe integer no larger than 2147483647. Detail can return an owned source even when it does not match the default unresolved list state.
Detail adds these fields to each operation:
request_evidenceandresponse_evidence: redacted, bounded JSON projections, not raw adapter payloads;resolutions: ordered history with stringid,decision, numericactor_admin_id, redactedreason, redactedevidence_reference, andrecorded_at.
Evidence withholds unknown adapter fields, headers, transport URLs, credentials, and unstructured response bodies. It may be truncated. Missing/withheld evidence is not proof that a wallet mutation was absent. The list does not include these detail-only evidence/history fields.
Correlate the original operation ID, user, direction, currency, amount, idempotency key, and remote ledger reference with your wallet ledger before escalating. Never issue a fresh-key credit/refund to resolve an ambiguous response: the original request may already have applied. Preserve redaction when sharing evidence through operator support.
Errors and caching
400 INVALID_TRIAGE_SOURCE: invalid detail kind/source ID.400 INVALID_SOURCE_ID: invalid/oversized source selector (including oversized list market ID).400 INVALID_MARKET_ID,INVALID_KIND,INVALID_ISSUE_STATE,INVALID_RESOLVED_FROM_DATE,INVALID_RESOLVED_TO_DATE,INVALID_RESOLVED_DATE_RANGE: correct list filters.404 CASH_ISSUE_NOT_FOUND: source is missing or outside the authenticated operator's readable scope.403 INSUFFICIENT_SCOPE: one or more required read scopes are missing.
Both responses use Cache-Control: private, no-store and X-Content-Type-Options: nosniff. Do not cache operator financial evidence in shared caches.