1.15 SettlementExposureGuard

1. Bot Identity

Operational profile

2. Purpose

SettlementExposureGuard tracks how much pUSD is committed in markets that share the same UMA resolution window and blocks or downsizes new orders that would push the concurrent settlement exposure above the configured ceiling. It prevents the user from having more equity at risk in a single 2-hour UMA settlement window than they can afford to lose if all markets in that window resolve adversely.

3. Why This Bot Matters

• Multiple markets resolving in same UMA window

  Markets resolving in the same 2-hour UMA window create a concentration of settlement risk; an adverse outcome across all of them results in simultaneous losses the user did not anticipate.

• No cap on concurrent settlement exposure

  Without a settlement window cap, strategies can inadvertently concentrate the majority of the portfolio in a single 2-hour settlement batch.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "max_concurrent_settlement_usd": 3000 }

if (windowExposure + intent.size_usd > params.max_concurrent_settlement_usd) return reshape_or_reject('SETTLEMENT_EXPOSURE_EXCEEDED');

{ "uma_window_hours": 2.0 }

const bucketKey = Math.floor(market.end_date_ms / (params.uma_window_hours * 3600000));

{ "warn_pct": 0.8 }

if (windowExposure / params.max_concurrent_settlement_usd > params.warn_pct) annotations.push(WARN);

8. Default Configuration

{
  "bot_id": "risk.settlement_exposure_guard",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_concurrent_settlement_usd": 3000,
    "uma_window_hours": 2.0,
    "warn_pct": 0.8
  },
  "locked": {
    "max_concurrent_settlement_usd": {
      "min": 100
    },
    "uma_window_hours": {
      "min": 2.0
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent with market_id, size_usd.
2. Check KillSwitch; if active, HARD_REJECT(KILL_SWITCH_ACTIVE).
3. Fetch target market end_date from Gamma to determine its UMA settlement window bucket.
4. Fetch all open positions; group by UMA window bucket (floor(end_date_ms / window_ms)).
5. Compute window_exposure = sum of notional for all positions in the same bucket as the target market.
6. If window_exposure + intent.size_usd > max_concurrent_settlement_usd: compute safe_size.
7. If safe_size > 0: RESHAPE(max_size_usd=safe_size). Else HARD_REJECT(SETTLEMENT_EXPOSURE_EXCEEDED).
8. If window_exposure / max > warn_pct: attach WARN annotation.
9. APPROVE with window_exposure and bucket_key attached.

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 evaluateSettlementExposure(intent):
  ks = FETCH internal.killswitch.status
  IF ks.active: EMIT RiskVote(HARD_REJECT, KILL_SWITCH_ACTIVE); RETURN

  market = FETCH gamma.getMarket(intent.market_id)
  IF market IS NULL:
    EMIT RiskVote(HARD_REJECT, SETTLEMENT_EXPOSURE_DATA_UNAVAILABLE); RETURN

  windowMs = params.uma_window_hours * 3600000
  bucketKey = floor(market.end_date_ms / windowMs)

  positions = FETCH clob_public.positions(intent.user_id)
  IF positions IS NULL:
    EMIT RiskVote(HARD_REJECT, SETTLEMENT_EXPOSURE_DATA_UNAVAILABLE); RETURN

  windowExposure = 0
  FOR pos IN positions:
    posMarket = FETCH gamma.getMarket(pos.market_id)
    IF floor(posMarket.end_date_ms / windowMs) == bucketKey:
      windowExposure += pos.notional_usd

  IF windowExposure + intent.size_usd > params.max_concurrent_settlement_usd:
    safeSize = params.max_concurrent_settlement_usd - windowExposure
    IF safeSize > 0:
      EMIT RiskVote(RESHAPE_REQUIRED, SETTLEMENT_EXPOSURE_EXCEEDED,
                    constraints={max_size_usd: safeSize}); RETURN
    EMIT RiskVote(HARD_REJECT, SETTLEMENT_EXPOSURE_EXCEEDED); RETURN

  utilisation = windowExposure / params.max_concurrent_settlement_usd
  IF utilisation > params.warn_pct:
    annotations.append(WARN(SETTLEMENT_EXPOSURE_APPROACHING))

  EMIT RiskVote(APPROVE, window_exposure=windowExposure, bucket_key=bucketKey)

SDK calls used

• gamma.getMarket(market_id)
• clob_public.positions(user_id)
• internal.killswitch.status()

Complexity: O(N) where N = open positions

11. Wire Examples

Input — what arrives on the wire

OrderIntent — window cap reached — internal

{
  "intent_id": "int_a7b8c9d0e1f20007",
  "market_id": "0x5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
  "size_usd": 400,
  "generated_at_ms": 1746800000000
}

Output — what the bot emits

RiskVote — RESHAPE_REQUIRED

{
  "guard_id": "risk.settlement_exposure_guard",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "SETTLEMENT_EXPOSURE_EXCEEDED",
  "message": "Window bucket exposure 2800 pUSD + 400 exceeds 3000. Resized to 200.",
  "constraints": {
    "max_size_usd": 200
  },
  "checked_at": "2026-05-10T14:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.settlement_exposure_guard",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "SETTLEMENT_EXPOSURE_EXCEEDED",
  "message": "UMA window bucket has 2800 pUSD exposure; adding 400 pUSD exceeds 3000 ceiling. Resized to 200 pUSD.",
  "constraints": {
    "max_size_usd": 200
  },
  "inputs_used": [
    "gamma.market.end_date",
    "clob_public.positions",
    "internal.config"
  ],
  "checked_at": "2026-05-10T14:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "risk.settlement_exposure_guard",
  "decision": "RESHAPE_REQUIRED",
  "reason_code": "SETTLEMENT_EXPOSURE_EXCEEDED",
  "inputs_used": [
    "gamma.market.end_date",
    "clob_public.positions"
  ],
  "metrics": {
    "bucket_key": "1746799200",
    "window_exposure_usd": 2800,
    "intent_size_usd": 400,
    "ceiling_usd": 3000,
    "safe_size_usd": 200
  },
  "checked_at": "2026-05-10T14:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Position cache rebuilt from CLOB on cold start. Gamma cache populated on first market lookup.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Submitting concurrent intents for the same UMA window bucket to bypass per-intent idempotency
• Selecting markets with staggered end_dates that fall just outside the window bucket to accumulate higher effective exposure

Mitigations

• Per-bucket optimistic lock ensures at most one intent is processed at a time per bucket
• Market end_date is fetched from Gamma at evaluation time, not trusted from the intent payload

24. Polymarket V2 Compatibility

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

SettlementExposureGuard incidents typically involve a strategy concentrating orders in a single UMA window. Verify the bucket distribution in Grafana before adjusting the ceiling.

On-call actions

Manual overrides

• polytraders risk refresh-positions --user-id <id> — After a known CLOB sync delay causing stale position data.

Healthcheck

GET /internal/health/settlementexposureguard → green: Gamma cache populated, position cache age < 15s, no buckets within 20% of ceiling; red: Gamma or CLOB unavailable, position cache age > 60s

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%