3.11 Late-Resolution Spread

1. Bot Identity

2. Purpose

Late-Resolution Spread captures the time-decay component of high-probability outcomes near market maturity. As a binary or multi-outcome market approaches its endDate (from Gamma API), a token priced at $0.95–$0.99 retains a positive expected settlement of $1.00 if the leading outcome holds. The spread between the current market price and $1.00 shrinks deterministically as resolution approaches. This bot monitors gamma.market.endDate to identify markets within max_minutes_to_resolution of close, checks that the price-to-$1.00 spread exceeds the configurable minimum, and emits a buy OrderIntent sized to max_clip_usd. It never averages down (never_average_down is locked true). This is a user-controlled execution tool exploiting time-value decay in near-resolution predictive markets; it is not a directional price forecast.

3. Why This Bot Matters

• endDate not fetched from Gamma API; using stale time-to-resolution

  Entering a late-resolution trade with incorrect time remaining may expose the position to a full overnight resolution cycle, dramatically extending holding time and risk.

• Oracle challenge window not respected

  UMA Optimistic Oracle: $750 pUSD bond, 2-hour challenge window, potential 24–48h DVM delay. Entering a late-resolution trade when a challenge is active means the position may not settle at $1.00 within the expected window.

• feeRateBps hardcoded on signed order (V1 pattern)

  CLOB V2 rejects orders containing feeRateBps. Fees are operator-set at match time. The signed order must not contain this field.

• never_average_down not enforced

  If price drops after entry on a late-resolution market, averaging down concentrates risk just before resolution — the opposite of the strategy intent.

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_spread_to_1_cents": 2 }

spread_cents = (1.00 - best_ask) * 100; if spread_cents < params.hard: return skip('LATE_RES_SPREAD_TOO_TIGHT')

{ "max_minutes_to_resolution": 120 }

minsLeft = (endDate - now_ms()) / 60000; if minsLeft > params.hard: return skip('LATE_RES_NOT_IN_WINDOW')

{ "max_clip_usd": 300 }

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

{ "never_average_down": true }

if position.exists and current_price < position.entry_price: return skip('LATE_RES_NO_AVERAGE_DOWN')

8. Default Configuration

{
  "bot_id": "strat.late_resolution_spread",
  "version": "2.1.0",
  "mode": "general_live",
  "defaults": {
    "min_spread_to_1_cents": 2,
    "max_minutes_to_resolution": 120,
    "max_clip_usd": 300,
    "never_average_down": true
  },
  "locked": {
    "never_average_down": true,
    "max_clip_usd": {
      "max": 750
    },
    "max_minutes_to_resolution": {
      "max": 360
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, emit no OrderIntents.
2. Poll Gamma API for markets with endDate within (now, now + max_minutes_to_resolution * 60).
3. For each candidate market: compute minutes_to_resolution = (endDate - now_ms()) / 60000.
4. If minutes_to_resolution > max_minutes_to_resolution hard (360 min), skip market.
5. Fetch best_ask for the leading YES outcome from clob_public.
6. Confirm best_ask ≥ 0.90 (minimum viable price — not a penny token). Skip if below.
7. Compute spread_cents = (1.00 - best_ask) * 100. If spread_cents < min_spread_to_1_cents hard floor (1), skip LATE_RES_SPREAD_TOO_TIGHT.
8. Check OracleRiskMonitor status for this market. If oracle challenge active or DVM escalation in progress, skip LATE_RES_ORACLE_CHALLENGE_ACTIVE.
9. Confirm negRisk flag from Gamma. For neg-risk markets, also check NegRiskAdapter availability for clean exit.
10. Check existing position: if position exists and current_price < position.entry_price, skip LATE_RES_NO_AVERAGE_DOWN (never_average_down locked true).
11. Compute clipSize = toPusdUnits(min(depth_available, max_clip_usd)).
12. If minutes_to_resolution < 30 (warning), reduce clipSize by 20% for thin-book safety.
13. Emit OrderIntent: market_id, outcome=YES, side=buy, price=best_ask, size_pUSD=clipSize, tif=GTC, post_only=false, builder={code, fee_bps: 25}.
14. Note: fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order.
15. Emit DecisionReport with intent_emitted=true, spread_cents, minutes_to_resolution, oracle_clear=true.

10. Reference Implementation

Polls Gamma API for near-resolution markets, validates oracle status and spread, and emits a buy OrderIntent when price-to-$1 spread is sufficient and oracle is clear.

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

FUNCTION scanLateResolutionMarkets():
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    RETURN

  // --- 1. Poll Gamma API for near-resolution markets ---
  now_ms = now_ms()
  windowEnd = now_ms + params.max_minutes_to_resolution * 60 * 1000
  markets = FETCH gamma.GET('/markets?endDateFrom=' + now_ms + '&endDateTo=' + windowEnd + '&active=true')
  IF isStale(markets, maxAgeS=60):
    EMIT DecisionReport(intent_emitted=false, reason='STALE_MARKET_DATA')
    RETURN

  FOR market IN markets:
    minutesLeft = (market.endDate - now_ms) / 60000
    IF minutesLeft > params.max_minutes_to_resolution_hard:  // 360
      CONTINUE

    // --- 2. Fetch best ask ---
    book = FETCH clob_public.GET('/book?market=' + market.conditionId)
    bestAsk = book.asks[0].price
    IF bestAsk < 0.90:  // minimum viable price
      CONTINUE

    // --- 3. Spread check ---
    spreadCents = (1.00 - bestAsk) * 100
    IF spreadCents < params.min_spread_to_1_cents_hard:  // 1 cent
      CONTINUE  // spread too tight

    // --- 4. Oracle check (UMA: $750 pUSD bond, 2h challenge, 24-48h DVM) ---
    oracleStatus = FETCH internal.oracleRiskMonitor.status(market.conditionId)
    IF oracleStatus.challenge_active OR oracleStatus.dvm_escalated:
      EMIT DecisionReport(intent_emitted=false, reason='LATE_RES_ORACLE_CHALLENGE_ACTIVE')
      CONTINUE

    // --- 5. NegRisk check ---
    IF market.negRisk:
      adapterAvailable = FETCH onchain.NegRiskAdapter.isConditionRegistered(market.conditionId)
      // negRisk_aware=true on intent; adapter path available for exit

    // --- 6. Never-average-down (locked true) ---
    position = FETCH clob_auth.GET('/positions?market=' + market.conditionId)
    IF position.exists AND bestAsk < position.entry_price:
      EMIT DecisionReport(intent_emitted=false, reason='LATE_RES_NO_AVERAGE_DOWN')
      CONTINUE

    // --- 7. Sizing ---
    depth = book.asks[0].size_pusd
    clipSize = toPusdUnits(min(depth, params.max_clip_usd))
    IF minutesLeft < 30:
      WARN('LATE_RES_APPROACHING')
      clipSize = toPusdUnits(clipSize * 0.8)  // thin book near close

    // --- 8. Emit OrderIntent (V2: no feeRateBps; builder field; taker order) ---
    EMIT OrderIntent(
      market_id     = market.conditionId,
      outcome       = 'YES',
      side          = 'buy',
      price         = bestAsk,
      size_pUSD     = clipSize,
      tif           = 'GTC',
      post_only     = false,
      builder       = { code: config.builder_code, fee_bps: 25 },
      negrisk_aware = market.negRisk
    )
    EMIT DecisionReport(
      intent_emitted       = true,
      spread_cents         = spreadCents,
      minutes_to_resolution = minutesLeft,
      oracle_clear         = true,
      reasons              = ['LATE_RES_SPREAD_ENTRY']
    )

SDK calls used

• gamma.GET('/markets?endDateFrom=...&endDateTo=...&active=true')
• fetchClobPublic('/book?market=' + conditionId)
• internal.oracleRiskMonitor.status(conditionId)
• clob_auth.GET('/positions?market=' + conditionId)
• onchain.NegRiskAdapter.isConditionRegistered(conditionId)
• toPusdUnits(rawFloat)
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• internal.killswitch.status()
• internal.builder_code

Complexity: O(M) per poll cycle where M = number of near-resolution markets

11. Wire Examples

Input — what arrives on the wire

Gamma API near-resolution market — gamma

{
  "conditionId": "0xef012345678901abcdef01234567890abcdef01234567890abcdef01234567890e",
  "endDate": "2026-05-09T13:00:00Z",
  "negRisk": true,
  "active": true,
  "resolutionSource": "UMA Optimistic Oracle"
}

CLOB public book — leading outcome — clob_public

{
  "market_id": "0xef012345678901abcdef01234567890abcdef01234567890abcdef01234567890e",
  "best_ask": "0.976",
  "depth_pusd": "420.00",
  "spread_cents": "2.4",
  "fetched_at_ms": 1746789900000
}

Output — what the bot emits

OrderIntent — late-resolution buy (GTC, taker, builder-attributed)

{
  "intent_id": "oi_01HX9LRSP3C1A1B",
  "trace_id": "tr_01HX9LRSP3C1VR5",
  "market_id": "0xef012345678901abcdef01234567890abcdef01234567890abcdef01234567890e",
  "outcome": "YES",
  "side": "buy",
  "price": "0.976",
  "size_pUSD": "300.00",
  "tif": "GTC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": true,
  "decision": {
    "edge_bps": 14.0,
    "spread_cents": 2.4,
    "minutes_to_resolution": 87,
    "oracle_clear": true,
    "reasons": [
      "LATE_RES_SPREAD_ENTRY"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HX9LRSP3C1A1B",
  "trace_id": "tr_01HX9LRSP3C1VR5",
  "market_id": "0xef012345678901abcdef01234567890abcdef01234567890abcdef01234567890e",
  "outcome": "YES",
  "side": "buy",
  "price": "0.976",
  "size_pUSD": "300.00",
  "tif": "GTC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": true,
  "decision": {
    "edge_bps": 14.0,
    "spread_cents": 2.4,
    "minutes_to_resolution": 87,
    "oracle_clear": true,
    "reasons": [
      "LATE_RES_SPREAD_ENTRY"
    ]
  },
  "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

Dashboards

• Grafana — Strategy / LateResSpread time-to-resolution and spread distribution
• Grafana — Strategy / LateResSpread oracle skip rate and entry throughput

16. Developer Reporting

{
  "bot_id": "strat.late_resolution_spread",
  "market_id": "0xef012345678901abcdef01234567890abcdef01234567890abcdef01234567890e",
  "end_date": "2026-05-09T13:00:00Z",
  "minutes_to_resolution": 87.3,
  "best_ask": 0.976,
  "spread_cents": 2.4,
  "neg_risk": true,
  "oracle_challenge_active": false,
  "clip_size_pusd": 300.0,
  "intent_emitted": true,
  "reason": "LATE_RES_SPREAD_ENTRY",
  "emitted_at_ms": 1746789900000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, entry prices are re-read from clob_auth positions. Oracle status is re-fetched on first evaluation per market. Gamma endDate is re-polled from Gamma API.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Gamma API endDate manipulation: a falsified endDate could push a market artificially into the near-resolution window
• Oracle status spoofing: a false 'oracle clear' signal could cause entry during an active dispute
• Average-down bypass: a crafted position read could make entry_price appear lower than current price, bypassing the never_average_down check

Mitigations

• Gamma endDate is cross-validated against clob_public market.closeTime before use
• Oracle status read is from OracleRiskMonitor (authenticated internal service), not from public feed
• Position entry_price is read from clob_auth (authenticated); not from public feed
• V2 order timestamp(ms) prevents replay of signed orders
• Fail-closed on oracle state: any read error treats oracle as challenged

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

LateResSpread incidents involve Gamma API staleness (most common), oracle challenge-related skips, or occasional stale-endDate entries. Gamma staleness is resolved via infra; oracle challenges require monitoring until the UMA 2h window clears.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/late-resolution-spread -> 200 if Gamma API last_seen < 60s, OracleRiskMonitor reachable, KillSwitch inactive, and at least one market evaluated in last 5 minutes.

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%