PnL Reporter
PnLReporter reconciles all fill events into realised and unrealised P&L, denominated in pUSD.
What it does
PnLReporter reconciles all fill events into realised and unrealised P&L, denominated in pUSD. It reads fee from the fill's match event (not from the signed order — fees are operator-set at match time in V2). It accrues maker rebates (20–25% of fees, paid in pUSD, per market) and credits them against gross fees. It groups P&L by bot, market, and builder as configured. It emits a SettlementReport after every fill and on the configured window cadence for regulatory retention. PnLReporter is the authoritative post-trade ledger for all pUSD flows.
Pipeline placement
Applies to: Every filled or partially filled order; daily and weekly P&L windows across all bots, markets, and builders
Why it matters
| If this fails | Consequence |
|---|---|
| Fee read from signed order instead of match event | In V2, operator fees are set at match time — not on the signed order. Reading fees from the order produces systematically wrong P&L. Maker rebates accrued against wrong fee basis will cause discrepancies in regulatory reports. |
| Maker rebate not accrued | Gross fees overstate true cost. P&L appears worse than actual. Fee dispute evidence is incomplete. |
| P&L not denominated in pUSD | Mixed USDC.e and pUSD figures corrupt the ledger. Post-trade reports cannot be reconciled against on-chain settlement. |
| Realised P&L not separated from unrealised | Open positions inflate reported returns. Regulatory settlement reports misrepresent actual cash flows. |
| Negative-risk positions mis-valued | Multi-outcome market positions (NegRiskAdapter) have non-linear payoffs. Treating them as independent binary positions overstates or understates exposure. |
Inputs
Polymarket inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Fill confirmation from CTFExchangeV2 match event (includes operator-set fee_bps at match time) | clob_auth | required | Primary fill record. Fee is extracted from match event field — not from the signed order. |
| Mark-to-market prices for open positions | clob_public | required | Compute unrealised P&L by marking open positions at current mid-price. |
| On-chain balance query (pUSD wallet balance) | onchain | required | Cross-check realised P&L against actual on-chain pUSD balance for regulatory reconciliation. |
| Market metadata (negRisk flag, condition_id, market_type) | clob_public | required | Identify negative-risk markets for correct payoff valuation. |
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Position store snapshot | gov.portfolio_sync | required | Current open position sizes per token per market, used for unrealised P&L computation. |
| BuilderAttribution fill log | gov.builder_attribution | required | Join fills with builder code and builder_fee_pusd for per-builder P&L breakdown. |
| KillSwitch active flag | KillSwitch | optional | When KillSwitch is active, continue recording fills but flag the reporting window as impacted. |
Authority
What this bot is permitted to do
State
Readiness
General live
Status
live
Class
Governance Service
Default mode
general_live
Developer owner
Polytraders core — Governance pod
Capital impact
Indirect
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| PNL_REPORTER_FILL_PNL_COMPUTED | INFO | Fill event successfully processed; realised and unrealised P&L computed; SettlementReport emitted. | No action — routine. |
| PNL_REPORTER_FEE_MISSING | HARD_REJECT | Fill event arrived without fee_bps in the match event. Cannot compute net P&L without match-event fee. | Quarantine fill; emit alert; require manual review before inclusion in ledger. |
| PNL_REPORTER_FEE_CAP_EXCEEDED | WARN | Observed fee_bps in match event exceeds V2 cap (taker > 100 bps or maker > 50 bps). | Quarantine fill; emit alert for manual review. |
| PNL_REPORTER_PAPER_IN_REGULATORY | WARN | include_paper=true is set on a report that is flagged as regulatory. Paper fills must not appear in regulatory reports. | Flag report as mixed; emit WARN; do not include in 7-year retention tier. |
| PNL_REPORTER_ONCHAIN_RECONCILE_FAIL | WARN | Aggregate P&L total diverges from on-chain pUSD balance beyond the reconciliation tolerance. | Flag report as unreconciled; emit alert; retry reconciliation after RPC cooldown. |
| STALE_DATA | WARN | Mark-to-market price for an open position is stale (last fetch > 60s ago). Unrealised P&L uses last known price. | Emit WARN; use stale price for unrealised calculation; retry fetch on next cycle. |
| PNL_REPORTER_NEGRISK_DETECTED | INFO | A negative-risk market position was detected; NegRiskAdapter payoff function applied. | No action — informational. |
| MARKET_CLOSED | INFO | A market has resolved; open positions closed; realised P&L finalised at settlement price. | Compute final realised P&L; emit SettlementReport with event_type=MARKET_SETTLED. |
Related bots in Governance & Ops
Used by
Reverse index — strategies that currently reference gov.pnl-reporter. If you change this bot's authority or reason codes, these strategies must re-pass shadow.
| Strategy | State | Activity |
|---|---|---|
| BTC weekly — close-aware quotes | demo-wired | last triggered 37m ago |
| Fed Rates — surprise drift | frozen | last triggered 44m ago |
Showing 2 of 2 · demo-wired ≠ production-live
Why this matters
Governance & Ops bots does NOT propose, approve, or block trades; only observes and reports. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →