6.3 PnL Reporter

1. Bot Identity

2. Purpose

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.

3. Why This Bot Matters

• 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.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "report_window": "daily" }

assert p.report_window in ('daily', 'weekly')

{ "group_by": "bot" }

assert p.group_by in ('bot', 'market', 'builder')

{ "include_paper": false }

if (p.include_paper && report.is_regulatory) log.warn('PNL_REPORTER_PAPER_IN_REGULATORY')

{ "reconcile_tolerance_pusd": 0.01 }

if (drift > p.hard) alerting.emit("PNL_REPORTER_ONCHAIN_RECONCILE_FAIL", { drift })

8. Default Configuration

{
  "bot_id": "gov.pnl_reporter",
  "version": "2.0.0",
  "mode": "general_live",
  "defaults": {
    "report_window": "daily",
    "group_by": "bot",
    "include_paper": false,
    "reconcile_tolerance_pusd": 0.01
  }
}

9. Implementation Flow

1. On every fill event from CTFExchangeV2: extract fill_id, order_id, market_id, side, size_pusd, price, and fee_bps from the MATCH EVENT (not from the signed order).
2. Compute gross_fee_pusd = size_pusd * fee_bps / 10_000. Distinguish maker vs taker side; apply maker rebate (20–25% of fee, per market, paid in pUSD).
3. Compute net_fee_pusd = gross_fee_pusd - maker_rebate_pusd. Validate taker fee_bps <= 100, maker fee_bps <= 50.
4. Determine position delta: BUY increases long position; SELL decreases or creates short position.
5. Compute realised_pnl_pusd on position close using FIFO cost basis. Mark open positions at current mid-price for unrealised_pnl_pusd.
6. For negative-risk markets (negRisk=true), use NegRiskAdapter payoff function instead of binary payoff.
7. Append fill record to the P&L ledger (Postgres) with all fields including net_fee_pusd, maker_rebate_pusd, realised_pnl_pusd, unrealised_pnl_pusd.
8. Emit SettlementReport per fill event (emit-every) to satisfy regulatory retention requirement.
9. At report_window boundary, compute aggregate SettlementReport grouped by group_by dimension. Cross-check totals against on-chain pUSD balance.
10. Retain all SettlementReport records for 7 years (regulatory requirement). Use WAL-backed store with retry on bus failure.

10. Reference Implementation

Consumes fill events from CTFExchangeV2, reads fee from match event, accrues maker rebates, computes realised and unrealised pUSD P&L with negRisk awareness, emits SettlementReport per fill and on window cadence.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

// ---- PER-FILL HANDLER ----
FUNCTION onFill(matchEvent):
  // V2: fee is operator-set at match time — read from matchEvent, NOT from order
  IF matchEvent.fee_bps IS NULL:
    alerting.emit('PNL_REPORTER_FEE_MISSING', { fill_id: matchEvent.fill_id })
    quarantine(matchEvent)
    RETURN

  side = matchEvent.side  // 'maker' | 'taker'
  IF side == 'taker' AND matchEvent.fee_bps > 100:
    alerting.emit('PNL_REPORTER_FEE_CAP_EXCEEDED', { fill_id: matchEvent.fill_id, fee_bps: matchEvent.fee_bps })
    quarantine(matchEvent)
    RETURN
  IF side == 'maker' AND matchEvent.fee_bps > 50:
    alerting.emit('PNL_REPORTER_FEE_CAP_EXCEEDED', { fill_id: matchEvent.fill_id, fee_bps: matchEvent.fee_bps })
    quarantine(matchEvent)
    RETURN

  size_pusd = toPusdUnits(matchEvent.size_usd)
  gross_fee_pusd = size_pusd * matchEvent.fee_bps / 10_000

  // Maker rebate: 20–25% of fee, paid in pUSD, per market
  rebate_rate = FETCH clob_public.GET('/market-rebate-rate?market_id=' + matchEvent.market_id)
  maker_rebate_pusd = 0
  IF side == 'maker':
    maker_rebate_pusd = gross_fee_pusd * rebate_rate  // rebate_rate in [0.20, 0.25]
  net_fee_pusd = gross_fee_pusd - maker_rebate_pusd

  // Market metadata — check negRisk
  market = FETCH clob_public.getMarketByConditionId(matchEvent.condition_id)

  // Position delta and realised P&L (FIFO cost basis)
  position = portfolio_sync.getPosition(matchEvent.market_id, matchEvent.token_id)
  realised_pnl_pusd = computeRealisedPnL(position, matchEvent, costBasis='FIFO')

  // Unrealised P&L: mark open positions at current mid-price
  IF market.negRisk:
    unrealised_pnl_pusd = negRiskPayoff(position, market)
  ELSE:
    mid_price = FETCH clob_public.GET('/midprice?token_id=' + matchEvent.token_id)
    unrealised_pnl_pusd = (mid_price - position.avg_cost) * position.remaining_size

  record = {
    fill_id:             matchEvent.fill_id,
    market_id:           matchEvent.market_id,
    side:                side,
    size_pusd:           size_pusd,
    price:               matchEvent.price,
    fee_bps_match_event: matchEvent.fee_bps,
    gross_fee_pusd:      gross_fee_pusd,
    maker_rebate_pusd:   maker_rebate_pusd,
    net_fee_pusd:        net_fee_pusd,
    realised_pnl_pusd:   realised_pnl_pusd,
    unrealised_pnl_pusd: unrealised_pnl_pusd,
    negRisk:             market.negRisk,
    fill_confirmed_at_ms: matchEvent.timestamp
  }
  postgres.INSERT('pnl_ledger', record)

  EMIT SettlementReport(event_type='FILL_PNL_COMPUTED', fill_id=matchEvent.fill_id, ...record)

// ---- WINDOW REPORT ----
FUNCTION emitWindowReport(windowStart, windowEnd):
  rows = postgres.SELECT('pnl_ledger', WHERE fill_confirmed_at_ms BETWEEN windowStart AND windowEnd)
  agg = aggregatePnL(rows, group_by=config.group_by)
  onchain_balance = FETCH onchain.getBalance(wallet_address, token='pUSD')
  onchain_reconciled = abs(agg.net_pnl_pusd - onchain_balance) < RECONCILE_TOLERANCE
  EMIT SettlementReport(event_type='SETTLEMENT_REPORT', retention='7y', ...agg, onchain_reconciled=onchain_reconciled)

SDK calls used

• clob_public.GET('/market-rebate-rate?market_id=...')
• clob_public.getMarketByConditionId(condition_id)
• clob_public.GET('/midprice?token_id=...')
• clob_auth.GET('/fills?order_id=...')
• onchain.getBalance(wallet_address, token='pUSD')
• toPusdUnits(raw_usd)
• postgres.INSERT('pnl_ledger', record)
• alerting.emit('PNL_REPORTER_FEE_MISSING', metadata)

Complexity: O(F) per window where F = fill count; O(1) per fill event

11. Wire Examples

Input — what arrives on the wire

{
  "label": "CTFExchangeV2 match event (fill with operator-set fee)",
  "source": "clob_auth",
  "payload": {
    "fill_id": "fill_00a1b2c3d4e5f6a7",
    "order_id": "ord_00123",
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "condition_id": "0x3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
    "side": "maker",
    "size_usd": 500.0,
    "price": 0.58,
    "fee_bps": 25,
    "negRisk": false,
    "timestamp": 1746792060000
  }
}

Output — what the bot emits

{
  "label": "SettlementReport — FILL_PNL_COMPUTED",
  "payload": {
    "report_id": "settlement_fill_fill_00a1b2c3d4e5f6a7",
    "bot_id": "gov.pnl_reporter",
    "event_type": "FILL_PNL_COMPUTED",
    "fill_id": "fill_00a1b2c3d4e5f6a7",
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "side": "maker",
    "size_pusd": 500.0,
    "price": 0.58,
    "fee_bps_match_event": 25,
    "gross_fee_pusd": 12.5,
    "maker_rebate_pusd": 3.12,
    "net_fee_pusd": 9.38,
    "realised_pnl_pusd": 0,
    "unrealised_pnl_pusd": 11.0,
    "negRisk": false,
    "fill_confirmed_at_ms": 1746792060000,
    "report_kind": "SettlementReport",
    "retained_until": "2033-05-09"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a SettlementReport object. See SettlementReport schema.

{
  "report_id": "settlement_pnl_20260509T000000Z",
  "bot_id": "gov.pnl_reporter",
  "event_type": "SETTLEMENT_REPORT",
  "window_start": "2026-05-08T00:00:00Z",
  "window_end": "2026-05-09T00:00:00Z",
  "group_by": "bot",
  "total_fills": 143,
  "gross_volume_pusd": 87450.0,
  "realised_pnl_pusd": 1240.5,
  "unrealised_pnl_pusd": 312.0,
  "gross_fees_pusd": 218.6,
  "maker_rebates_pusd": 49.7,
  "net_fees_pusd": 168.9,
  "net_pnl_pusd": 1071.6,
  "onchain_balance_pusd": 52341.0,
  "onchain_reconciled": true,
  "negRisk_positions": 2,
  "report_kind": "SettlementReport",
  "retained_until": "2033-05-09"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Governance / PnL Reporter daily P&L and fee breakdown
• Grafana — Fee accounting / maker rebates vs gross fees (pUSD)

16. Developer Reporting

{
  "bot_id": "gov.pnl_reporter",
  "event_type": "FILL_PNL_COMPUTED",
  "fill_id": "fill_00a1b2c3d4e5f6a7",
  "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "side": "BUY",
  "size_pusd": 500.0,
  "price": 0.58,
  "fee_bps_from_match_event": 25,
  "gross_fee_pusd": 12.5,
  "maker_rebate_pusd": 2.5,
  "net_fee_pusd": 10.0,
  "realised_pnl_pusd": 0,
  "unrealised_pnl_pusd": 10.0,
  "negRisk": false,
  "fill_confirmed_at_ms": 1746792060000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Postgres ledger is durable. On restart, in-flight fill events may be reprocessed — idempotency enforced by fill_id uniqueness constraint.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Injecting a fill event with artificially low fee_bps to inflate net P&L
• Setting include_paper=true to mix paper and live fills in regulatory reports
• Manipulating the mark-to-market price feed to inflate unrealised P&L

Mitigations

• Fee is always read from the match event — order-level fee manipulation is ignored
• Fee cap validation (taker <=100 bps, maker <=50 bps) rejects anomalous fills
• Regulatory reports are flagged if include_paper=true; paper fills are segregated
• On-chain balance reconciliation detects any P&L inflation that does not match actual pUSD flows
• Postgres unique constraint on fill_id prevents duplicate processing

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

PnLReporter incidents involve missing fees in match events (critical — halts ledger for affected fills), on-chain reconciliation drift (regulatory flag), or stale price feeds (unrealised P&L degraded). Missing fee is always P1.

On-call actions

Manual overrides

• polytraders gov pnl reprocess --fill-id <id> --reviewed-by <operator> — After manually verifying a quarantined fill, re-ingest it with corrected fields.

Healthcheck

Endpoint: /internal/health/pnl-reporter | Green: Last fill processed < 300s ago (during active trading); Postgres pnl_ledger writable; quarantine_count not growing. | Red: No fills processed in > 1h during trading hours; Postgres write failure; quarantine_count growing at > 1/min.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%