Terms, statements, and settlement

Polyflight has a dedicated native-IDR subledger. It does not use the Opinion monthly settlement formula, post Polyflight tickets into the Finance USD trade-fee ledger, or convert ticket money to Credits.

Where to work

In Operator Dashboard, open:

1. Polyflight → Commercial terms for current, scheduled, and historical allocation rates.
2. Polyflight → Tickets for the terms version captured by each admitted ticket.
3. Polyflight → Settlement reports for finalized monthly statements, payments, corrections, liabilities, and downloads.
4. Polyflight → Wallet operations when a statement liability does not agree with wallet delivery evidence.

The same read-only resources are available through:

• Terms API
• Tickets API
• Settlement reports API
• Balance operations API

Read commercial terms

Two independent percentages apply to an admitted ticket:

Both values are basis points on a 100-BPS grid. Polynion receives the residual of each base. Account-manager allocation does not apply.

curl -sS \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/terms"

Read the response as follows:

• current applies to tickets admitted now;
• scheduled is the latest non-superseded future revision, or null;
• history retains every revision, including a future schedule that was replaced;
• settlementTimezone is fixed at enablement and defines monthly statement boundaries;
• status distinguishes enabled, purchases_suspended, and disabled.

Only authorized Polynion administrators enable or suspend Polyflight and schedule terms. Operator staff and API keys are read-only. Each ticket keeps its admission-time termsVersionId, fee share, and position share for its later result or cancellation; a current-rate change never reprices it.

Separate fee from signed position

For each admitted ticket:

fee base = feeMinor
position base on loss = netStakeMinor
position base on win = netStakeMinor - potentialPayoutMinor

The position base is signed. It has no zero clamp or discretionary loss carry-forward. The ticket fee is allocated independently. The winning payout is already included in the negative position base and must not be subtracted again.

For a 10,000 IDR ticket, the fee is 500, net stake is 9,500, and a winning payout is 38,000. At the default 100% fee share and 80% position share:

Loss: positive position

With no prior balance, payment, or adjustment, settlementNetMinor is 1900: transferDirection is operator_owes_polynion and transferAmountMinor is 1900.

Win: negative position

With no prior balance, payment, or adjustment, settlementNetMinor is -5700: transferDirection is polynion_owes_operator and transferAmountMinor is 5700. The separate 38,000 IDR user payout remains a wallet liability until delivered; it is not deducted again from settlement.

Aggregate zero position

One 10,000 IDR win contributes a −28,500 position base. Three 10,000 IDR losses contribute +28,500, so their aggregate position base is zero. Fees remain a separate +2,000 base. At 100% fee share, the operator receives the 2,000 fee allocation while position allocation is zero for both parties.

Statements calculate the full operator month, not one ticket at a time. These examples omit fractional carry, earlier balances, payments, adjustments, and other tickets so the sign is visible.

Recognition and wallet delivery

The economic result and wallet delivery are separate:

Planned, sent, failed, unknown, or manual-review wallet effects remain visible but do not pretend cash moved. A confirmed debit that misses admission has no ticket terms, fee, or position; it remains compensation payable until its exact reversal is confirmed.

Therefore:

• a won ticket can have paymentStatus: "owed" or "manual_review";
• a refunded ticket can still have a refund delivery liability;
• a statement may finalize with a known unpaid win, refund, or compensation shown explicitly;
• unknown monetary cash state blocks statement finalization, but does not change a public result; unresolved zero-amount loss delivery does not block flight financial settlement or represent unknown cash.

Use Operations, reconciliation, and rollback before acting on any unresolved delivery.

Newly settled losses use the existing durable payment-obligation lifecycle with effect loss and amount 0; owed / in_flight / paid / manual_review describe result-acknowledgement delivery only. Do not include these as winnings/refund/compensation liabilities or cash-clearing outflows. The loss's signed position recognition still occurs at the authoritative result exactly as above, independently of wallet acknowledgement. Historical losses are not backfilled.

Understand the monthly statement

Statement months use the fixed settlement timezone and half-open UTC bounds [periodStartAt, periodEndAt). Finalization is chronological and only occurs after:

• the local month has completed;
• earlier eligible months are finalized;
• relevant landed/void flight results are processed;
• ambiguous wallet cash state before period end is reconciled.

The reporting API exposes finalized statements only. No rows is a valid state before the first month is finalized. A finalized statement is immutable and never regenerated from current terms. A late event economically belonging to a closed month is an additive correction linked to the original and applied in a later open statement.

The settlement balance is:

operator entitlement = operator fee allocation + operator position allocation
polynion entitlement = polynion fee allocation + polynion position allocation

settlement net =
  prior balance due
  + current Polynion entitlement
  - payments applied
  + adjustments applied

Payment sign follows its direction: an operator-to-Polynion payment reduces a positive amount due; a Polynion-to-operator payment reduces the magnitude of a negative amount due. transferAmountMinor is always the unsigned amount corresponding to the signed settlementNetMinor.

The statement deliberately separates:

• fee and position base/allocation;
• prior balance, payments, and audited adjustments;
• confirmed wallet-clearing receipts and outflows;
• opening and closing unadmitted suspense and open stake;
• compensation, winnings, and refund liabilities.

cashClearing proves confirmed wallet movement. It is not another entitlement and must never be added to fee or position income.

Fractional rounding carry

Shares are calculated in numerator units of $1/10{,}000$ IDR and summed by operator, month, section, and terms version before conversion:

fee operator numerator = sum(feeMinor × ticketFeeShareBps)
position operator numerator = sum(positionMinor × positionShareBps)
T = opening fractional remainder + period operator numerator
operator allocation = truncTowardZero(T / 10000)
closing fractional remainder = T - operator allocation × 10000
polynion allocation = section base - operator allocation

Fee and position carry are separate signed values, each strictly between −10,000 and +10,000 numerator units. This is fractional rounding carry, not an economic loss carry-forward.

Reconcile and download a statement

1. Open Polyflight → Settlement reports and select Details.
2. Confirm month, timezone, periodStartAt, and periodEndAt.
3. Compare fee and position sections with the ticket terms breakdown.
4. Check opening/closing liabilities against Tickets and Wallet operations.
5. Review priorBalanceDueMinor, paymentsAppliedMinor, adjustmentsAppliedMinor, and the signed settlement direction.
6. Review payment history and corrections. A pending correction has appliedStatementId: null; an applied correction names the later statement.
7. Choose Download canonical statement, or request the JSON export:

curl -sS \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/settlement-reports/{statementId}/export?format=json" \
  --output polyflight-statement.json

The detail JSON export contains { "statement": {...}, "payments": [...] }. Reconcile decimal-string amounts with integer/decimal arithmetic, never floating point.

Verify the signed record

A final statement includes revisionIdentity, canonical statementDigest, signatureVersion, signerKeyVersion, signature, input event IDs/digest, result-processing watermark, finalizer, reason, and time. Retain them together with the export.

The shipped signature version is hmac-sha256-v1; the reporting API intentionally exposes no signing secret or signer-key endpoint. Use the signer key version and secure verification procedure provided during onboarding. A TLS connection or webhook signature is not a statement signature.

Interparty settlement is manual; these operator routes do not initiate a bank transfer. Authorized Polynion administrators can record a partial/full payment or an additive correction with evidence. Operators inspect and reconcile those immutable records and provide missing bank or wallet evidence; they cannot rewrite the statement or mark it settled themselves.