6.12 PostTradeExplainer

1. Bot Identity

2. Purpose

PostTradeExplainer turns every fill into a plain-English SettlementReport: which strategy, which signal, which guard checks passed, why this size, why this price. Retained 7 years for regulatory compliance.

3. Why This Bot Matters

• No post-trade explanation

  Users and regulators cannot understand why a trade was made; compliance audit fails.

• Explanation not linked to fill

  Fill records and strategy intent cannot be reconciled; audit trail is broken.

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

{ "retain_explanation_days": 2555 }

if p.retain_explanation_days < 2555: emit('RETENTION_BELOW_REGULATORY_MINIMUM')

{ "min_detail_level": "standard" }

if p.min_detail_level == 'advanced': explanation.include(raw_params=True)

8. Default Configuration

{
  "bot_id": "gov.posttradeexplainer",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "retain_explanation_days": 2555,
    "min_detail_level": "standard",
    "publish_to_user": true,
    "require_for_advanced": false
  }
}

9. Implementation Flow

1. Subscribe to ExecutionReport events on the internal report bus.
2. For each ExecutionReport, fetch the linked DecisionReport and RiskVote from the report archive.
3. Compose the explanation: strategy name, signal summary, guard vote outcomes, size rationale, fill price, builder_fee_pusd.
4. Generate a plain-English summary sentence for user display.
5. Emit SettlementReport(event_type=TRADE_EXPLAINED) with full explanation and plain-English summary.
6. Store SettlementReport in the post-trade archive with retain_explanation_days retention.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

// ---- SUBSCRIBE TO EXECUTION REPORTS ----
FUNCTION onExecutionReport(execReport):
  // Fetch supporting records from archive
  decisionReport = FETCH internal.reportArchive.GET({
    trace_id: execReport.trace_id, kind: 'DecisionReport'
  })
  riskVotes = FETCH internal.reportArchive.GET({
    trace_id: execReport.trace_id, kind: 'RiskVote'
  })

  complete = decisionReport IS NOT NULL AND riskVotes IS NOT NULL

  // Compose explanation
  explanation = {
    fill_id:         execReport.fill_id,
    strategy:        decisionReport?.strategy_slug ?? 'unknown',
    signal_summary:  decisionReport?.signal_summary ?? '',
    guard_votes:     riskVotes ?? [],
    size_rationale:  buildSizeRationale(decisionReport, riskVotes),
    fill_price:      execReport.fill_price,
    fill_size_pusd:  execReport.fill_size_pusd,
    builder_fee_pusd: execReport.builder_fee_pusd,
    plain_english:   composePlainEnglish(explanation),
    explanation_complete: complete
  }

  // Emit SettlementReport
  EMIT SettlementReport(event_type='TRADE_EXPLAINED',
    ...explanation,
    report_kind='SettlementReport',
    topic='polytraders.reports.settlement',
    retained_until=now() + days(config.retain_explanation_days))

FUNCTION composePlainEnglish(exp):
  side = 'Bought' IF exp.fill_side == 'BUY' ELSE 'Sold'
  return f"{side} {exp.fill_size_pusd} pUSD at {exp.fill_price} — {exp.signal_summary}; all risk checks passed."

SDK calls used

• internal.reportArchive.GET({trace_id, kind})
• alerting.emit('EXPLANATION_ARCHIVE_UNAVAILABLE', metadata)

Complexity: O(1) per fill; O(R) for archive fetch where R = linked report count

11. Wire Examples

Input — what arrives on the wire

{
  "label": "ExecutionReport from fill",
  "source": "internal.report_bus",
  "payload": {
    "fill_id": "fill_00a1b2c3d4e5f6a7",
    "trace_id": "trc_01HX9Z",
    "fill_price": 0.621,
    "fill_size_pusd": 430.0,
    "builder_fee_pusd": 1.075,
    "fill_confirmed_at_ms": 1746792060000
  }
}

Output — what the bot emits

{
  "label": "SettlementReport — TRADE_EXPLAINED",
  "payload": {
    "report_id": "stl_01HX9Z",
    "event_type": "TRADE_EXPLAINED",
    "fill_id": "fill_00a1b2c3d4e5f6a7",
    "plain_english": "Bought 430 pUSD of YES at 0.621 — sports model edge 4.2 bps; all risk checks passed.",
    "report_kind": "SettlementReport",
    "topic": "polytraders.reports.settlement",
    "retained_until": "2033-05-09"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a SettlementReport object. See SettlementReport schema.

{
  "report_id": "stl_posttradeexplainer_01HX9Z",
  "bot_id": "gov.posttradeexplainer",
  "event_type": "TRADE_EXPLAINED",
  "fill_id": "fill_00a1b2c3d4e5f6a7",
  "strategy": "sports-model",
  "signal_summary": "Model edge 4.2 bps on YES leg of market 0x9b0c",
  "guard_votes": [
    {
      "bot": "liquidityguard",
      "vote": "pass"
    },
    {
      "bot": "portfolioguard",
      "vote": "pass"
    }
  ],
  "size_rationale": "Position sized at 80% of max_size_pusd due to LiquidityGuard spread signal",
  "fill_price": 0.621,
  "fill_size_pusd": 430.0,
  "builder_fee_pusd": 1.075,
  "plain_english": "Bought 430 pUSD of YES on market 0x9b0c at 0.621 \u2014 sports model detected 4.2 bps edge; all risk checks passed.",
  "report_kind": "SettlementReport",
  "topic": "polytraders.reports.settlement",
  "retained_until": "2033-05-09"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "gov.posttradeexplainer",
  "event_type": "EXPLANATION_COMPOSED",
  "fill_id": "fill_00a1b2c3d4e5f6a7",
  "archive_fetch_ms": 12,
  "explanation_length": 280
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, resume consuming ExecutionReport events from the last processed offset.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Requesting explanations for fills not belonging to the requesting user

Mitigations

• SettlementReport records are scoped to wallet_address; read access requires authenticated user context

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

PostTradeExplainer incidents are usually archive unavailability producing partial explanations. These are low-urgency unless retention is also breached.

On-call actions

Manual overrides

• —

Healthcheck

/internal/health/posttradeexplainer → green if Consuming ExecutionReport events; retention_days >= 2555; partial_explanations rate == 0; red if retention_days < 2555 or archive unreachable

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%