3.10 Resolution Fair-Value

1. Bot Identity

2. Purpose

Resolution Fair-Value detects Polymarket binary markets that are close to resolution and priced away from their fair value (e.g. trading at ¢96 when the outcome is virtually certain). It emits an IOC OrderIntent to trade toward fair value on unambiguous markets whose oracle signal is clean and within resolution window.

3. Why This Bot Matters

• Ambiguous resolution rule

  A market that appears certain may resolve 'N/A' or be disputed. Trading on assumed certainty creates a position that resolves against expectations.

• Oracle data stale near resolution

  Oracle snapshots have a freshness window; a stale snapshot near resolution may show apparent certainty when the underlying data has moved.

• UMA dispute window not respected

  A winning position can be disputed and reversed within the 2-hour challenge window. Ignoring open disputes creates timing risk.

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

{ "min_edge_bps": 100 }

if edge_bps < params.hard: return skip('RFV_NO_EDGE')

{ "max_size_per_market_usd": 500 }

if params.max_size_per_market_usd > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "require_unambiguous_source": true }

if not oracle_clean: return skip('RFV_AMBIGUOUS_SOURCE')

{ "require_oracle_clean": true }

if oracle_stale or dispute_open: return skip('RFV_ORACLE_NOT_CLEAN')

8. Default Configuration

{
  "bot_id": "strat.resolution_fair_value",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_edge_bps": 100,
    "max_size_per_market_usd": 500,
    "require_unambiguous_source": true,
    "require_oracle_clean": true
  },
  "locked": {
    "require_unambiguous_source": {
      "value": true
    },
    "require_oracle_clean": {
      "value": true
    },
    "min_edge_bps": {
      "min": 20
    }
  }
}

9. Implementation Flow

1. Check KillSwitch; if active, emit no OrderIntents.
2. FETCH clob_public market status; skip if closed or resolved.
3. Check oracle signal from resolution tracker; if stale or source ambiguous, emit RFV_ORACLE_NOT_CLEAN / RFV_AMBIGUOUS_SOURCE and skip.
4. Check onchain UMA dispute status; if dispute open, skip.
5. Compute fair_value from oracle signal; edge_bps = |fair_value - clob_mid| * 10000.
6. IF edge_bps < hard (20 bps): emit sampled DecisionReport RFV_NO_EDGE; skip.
7. IF edge_bps < warning (50 bps): WARN RFV_EDGE_MARGINAL; reduce size 50%.
8. Compute order size = min(max_size_per_market_usd, available_depth).
9. EMIT IOC OrderIntent toward fair value; EMIT DecisionReport reason=RFV_EDGE_TRADE.

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.

FUNCTION onOracleUpdate(market_id, oracleSignal):
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  mkt = FETCH clob_public.GET('/markets/' + market_id)
  IF mkt.closed OR mkt.resolved: RETURN

  // Oracle freshness and dispute checks
  IF oracleSignal.stale OR NOT oracleSignal.source_unambiguous:
    EMIT DecisionReport(intent_emitted=false, reason='RFV_ORACLE_NOT_CLEAN')
    RETURN

  disputeStatus = FETCH onchain.UMADisputeStatus(market_id)
  IF disputeStatus.open:
    EMIT DecisionReport(intent_emitted=false, reason='RFV_ORACLE_NOT_CLEAN')
    RETURN

  // Edge computation
  book = FETCH ws_market.book(market_id)
  clobMid = (book.best_bid + book.best_ask) / 2
  fairValue = oracleSignal.fair_value
  edgeBps = abs(fairValue - clobMid) * 10000

  IF edgeBps < params.min_edge_bps_hard:  // 20 bps
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='RFV_NO_EDGE')
    RETURN

  sizeMultiplier = 0.5 IF edgeBps < params.min_edge_bps_warn ELSE 1.0
  IF sizeMultiplier < 1.0: WARN('RFV_EDGE_MARGINAL')

  depth = FETCH clob_public.depth(market_id)
  orderSize = toPusdUnits(min(params.max_size_per_market_usd * sizeMultiplier, depth.available))
  direction = 'YES' IF fairValue > clobMid ELSE 'NO'

  EMIT OrderIntent(market=market_id, outcome=direction, side='buy', price=clobMid,
                   size_pUSD=orderSize, tif='IOC', builder=internalBuilderCode)
  EMIT DecisionReport(intent_emitted=true, edge_bps=edgeBps, reason='RFV_EDGE_TRADE')

SDK calls used

• ws_market.subscribe('book', [market_id])
• fetchClobPublic('/markets/' + market_id)
• onchain.UMADisputeStatus(market_id)
• internal.resolutionTracker.signal(market_id)
• buildOrderTypedData(orderParams, {name:'CTFExchange', version:'2', chainId:137})

Complexity: O(1) per oracle signal per market

11. Wire Examples

Input — what arrives on the wire

Oracle signal — market at ¢96 with fair value 1.0 — internal (resolution tracker)

{
  "market_id": "0xrfv0000000000000000000000000000000000000000000000000000000000001",
  "fair_value": "1.0",
  "clob_mid": "0.960",
  "oracle_fresh": true,
  "dispute_open": false,
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — RFV IOC buy YES

{
  "intent_id": "oi_01HRFV0000001A",
  "market_id": "0xrfv0000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.960",
  "size_pUSD": "300.00",
  "tif": "IOC",
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "decision": {
    "edge_bps": 400.0,
    "reasons": [
      "RFV_EDGE_TRADE"
    ]
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HRFV0000001A",
  "trace_id": "tr_01HRFV000TR001",
  "market_id": "0xrfv0000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.960",
  "size_pUSD": "300.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "edge_bps": 400.0,
    "fair_value": 1.0,
    "clob_mid": 0.96,
    "reasons": [
      "RFV_EDGE_TRADE"
    ]
  },
  "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "strat.resolution_fair_value",
  "market_id": "0xrfv0000000000000000000000000000000000000000000000000000000000001",
  "fair_value": 1.0,
  "clob_mid": 0.96,
  "edge_bps": 400.0,
  "oracle_fresh": true,
  "dispute_open": false,
  "intent_emitted": true,
  "reason": "RFV_EDGE_TRADE",
  "emitted_at_ms": 1746790800000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, oracle signals rebuilt from next resolution-tracker poll; dispute state re-fetched from onchain.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Oracle signal spoofing to induce trades on incorrect fair values
• Dispute-status delay causing bot to trade during open dispute window

Mitigations

• Oracle signals sourced from internal resolution tracker using authenticated feeds
• UMA dispute status fetched directly from onchain; staleness treated as dispute_open=true

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

RFV incidents are typically oracle staleness or open UMA disputes blocking trades. Escalate if oracle staleness persists > 5 min on active markets near resolution.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/resolution-fair-value -> 200 if Oracle snapshots < 60s old; no markets blocked by open disputes for > 30s; KillSwitch inactive.. Red: Resolution tracker down or KillSwitch active..

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%