Opinion Settlement Reports

Required scope: settlements:read or * for both routes. redemptions:read, trades:read, and polyflight_settlements:read do not authorize these endpoints. Grant only settlements:read to a reporting key or staff member that needs this report but no other resources.

All report data is derived from the authenticated operator. No operator-ID parameter is accepted; an API key or staff session cannot select another operator. The report uses the same calculation, camelCase data shape, and CSV/PDF exports as Admin, without duplicating accounting rules.

Read a report

GET /api/operator/settlement-report?month=2026-09

For the current operator-local month, request a read-only preview:

GET /api/operator/settlement-report?month=2026-11&preview=true

The preview example applies only while November 2026 is the current month in the operator's timezone; use the actual current month for later requests.

The server uses the operator's actual configured timezone for calendar boundaries and daily grouping, not a client-supplied timezone, browser timezone, or fixed UTC offset. period.startAt is the inclusive local-month start and period.endAt the exclusive next-month start, expressed as timestamps. Preview does not finalize the period or enable exports.

Response

The success envelope is { ok: true, report: MiniAppMonthlySettlementReport }, identical to Admin's report shape. Fields are camelCase, not the snake_case resolution API fields.

Summary and daily amount/count fields:

• tradeCount, tradeVolumeExternalMinor;
• grossFeeCredits, grossFeeExternalMinor;
• operatorShareCredits, operatorShareExternalMinor;
• accountManagerShareCredits, accountManagerShareExternalMinor;
• polynionShareCredits, polynionShareExternalMinor;
• redemptionCount, redemptionPayoutExternalMinor;
• principalSettlementCount, settledBuyPrincipalExternalMinor, settledSellPrincipalExternalMinor, settledGrossFeeExternalMinor, settledPrincipalNetExternalMinor, settledTradingPnlExternalMinor;
• operatorUnderwrittenPrincipalNetExternalMinor, operatorUnderwrittenTradingPnlExternalMinor, operatorUnderwrittenRedemptionPayoutExternalMinor;
• netOperatorPaysPolynionExternalMinor.

External monetary amounts are safe-integer JSON numbers in operator.currencyCode minor units (zero-decimal IDR), not integer strings like the Market PnL response. Credit amounts are integer credits-equivalent (10000 = 1 USDT) and must not be added to external-currency amounts. settlementDirection is operator_pays_polynion, polynion_pays_operator, or settled; settlementAmountExternalMinor is the absolute amount due. Positive signed net due means the operator owes Polynion; negative means Polynion owes the operator.

The three operator-underwritten fields are required integer monetary amounts in every v3 summary and daily row:

Private-market requests and underwriting attribution are described here as the current repository contract, not confirmation of environment rollout. Confirm availability with Polynion Support before relying on this workflow; see Private market requests. The required-field rules below apply to v3 responses.

The existing principal, trading P&L, and redemption payout fields remain total public plus private amounts. Do not treat them as Polynion-only economics. A missing underwriting field is invalid in v3, not an implied zero. Only immutable historical v2 exports interpret missing underwriting fields as zero; historical attribution and recorded net due are not reclassified.

Export a completed month

GET /api/operator/settlement-report/export?month=2026-09&format=csv
GET /api/operator/settlement-report/export?month=2026-09&format=daily-csv
GET /api/operator/settlement-report/export?month=2026-09&format=pdf

Exports return file content, not the JSON { ok, report } envelope. CSV, daily-breakdown CSV, and PDF are the same exports offered by Admin. Preview cannot bypass export checks. Incomplete/future months, missing historical fee evidence, unreconciled payouts, and missing v3 underwriting attribution block export. Pending principal alone does not: an otherwise eligible export describes captured closures with that exclusion disclosed, not final fully reconciled all-time performance.

All current CSV and PDF exports distinguish operator-underwritten principal, trading P&L, and payout cash from the totals. Polyfinance's immutable monthly CSV, XLSX, and PDF exports retain the same distinction and support legacy v2 snapshots without rewriting them.

Errors and response handling

Read and export use Cache-Control: private, no-store and X-Content-Type-Options: nosniff. Exports add attachment Content-Disposition and return text/csv; charset=utf-8 or application/pdf; do not parse success file bytes as the JSON report envelope.

dailyBreakdown is ordered by local activity date and includes dates with report activity, not necessarily every calendar day. Amounts/counts span the whole month; there are no page controls. redemptionCount can include processed items whose unreconciled payout contributes zero cash and increments unreconciledPayoutCount.

Accounting and recognition

Use actual successful reconciled operator-wallet movements in the original operator currency:

B = full successful buy debits
S = net successful sell credits
G = all gross external trade fees
R = lifetime successful reconciled redemption credits for the closed market

closed-market principal = B - S - G
realized trading P&L = closed-market principal - R
monthly net due = monthly Polynion trade-fee share
                + total principal recognized in the month
                - operator-underwritten principal recognized in the month
                - total successful reconciled payout cash processed in the month
                + operator-underwritten reconciled payout cash processed in the month

For platform-underwritten public markets, Polynion owns the Opinion principal profit or loss and its allocated fees. For operator-underwritten private markets, the owning operator retains 100% of principal gains or losses and winning-share payout obligations; those principal and payout amounts are excluded from net due to Polynion. The operator, account manager, and Polynion trade-fee allocation percentages are unchanged for both market types. Gross fees are removed from principal so they are not counted twice. Total and operator-underwritten realized P&L are informational and already subtract lifetime payouts; do not add either P&L field to net due or deduct lifetime payouts again.

Trade-fee allocations remain on the trade's processing date. Payout cash remains on its successful processing date. Each immutable operator/market principal closure has its own recognition date and covers full reconciled history across months. A historical closure first recognized in a later month is catch-up recognition, not new stakes or new cash received in that month, and does not rewrite prior/frozen Finance history. Open stakes are not earned income; pending winning-share payouts or unreconciled wallet operations prevent principal closure, with recognition deferred until reconciliation.

Actual wallet-credit cash is authoritative for settlement. Do not equate resolution exposure or stored projected/fallback payout amounts with reconciled cash. Reconcile unknown wallet results using the original operation and idempotency key, never a fresh-key payment retry.

See the accounting formulas and timing policy and dashboard guide. A report, completed month, or export is not proof of a paid bank transfer, does not initiate payment or post accounting entries, and is not necessarily a fully reconciled final result. Polyflight has separate native-IDR statement endpoints, terms, accounting, and polyflight_settlements:read permission.