2.12 PriceBandValidator

1. Bot Identity

Operational profile

2. Purpose

PriceBandValidator is a fat-finger and decimal-shift catcher. It rejects or warns on any order priced outside a sanity band relative to the current top-of-book mid, preventing obviously erroneous prices from reaching the CLOB V2 signing step.

3. Why This Bot Matters

• Fat-finger price not caught

  An order priced at 0.06 instead of 0.60 submits at a tenfold mispricing, immediately filling against informed counterparties at a large loss.

• Decimal shift not detected

  A misconfigured strategy submitting pUSD amounts as probabilities (e.g. 45.0 instead of 0.45) creates orders orders of magnitude outside market range.

• NegRisk sum-to-one constraint not checked

  Orders across a negRisk market group that sum to above 1.0 in probability are fundamentally mis-priced and represent an arb against the strategy.

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

{ "max_offset_from_mid_pct": 10 }

if abs(price - mid) / mid * 100 > params.max_offset_from_mid_pct: emit(PRICE_BAND_BREACH)

{ "require_band_for": ["GTC", "GTD"] }

if plan.order_type in params.require_band_for: validateBand(plan.price, mid)

{ "action_on_breach": "reject" }

if breach and params.action_on_breach == 'reject': discard(plan)

{ "warn_only_in_shadow": true }

if isInShadow() and params.warn_only_in_shadow: action = 'warn'

8. Default Configuration

{
  "bot_id": "exec.pricebandvalidator",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "max_offset_from_mid_pct": 10,
    "require_band_for": [
      "GTC",
      "GTD"
    ],
    "action_on_breach": "reject",
    "warn_only_in_shadow": true
  },
  "locked": {
    "max_offset_from_mid_pct": {
      "max": 25
    }
  }
}

9. Implementation Flow

1. Receive ExecutionPlan from SmartRouter.
2. If mode=shadow and warn_only_in_shadow=true, set effective_action=warn.
3. If plan.order_type NOT IN require_band_for, skip band check.
4. Fetch top-of-book snapshot from clob_public; compute mid = (best_bid + best_ask) / 2.
5. Compute offset_pct = abs(plan.price - mid) / mid * 100.
6. If offset_pct > max_offset_from_mid_pct: apply action_on_breach (reject/warn/reshape).
7. If market.neg_risk: check that all leg prices for this market group sum to <= 1.0.
8. Emit ExecutionReport with verdict, offset_pct, mid_used, and reason_code.

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 validatePriceBand(plan):
  // Determine effective action
  action = params.action_on_breach
  IF isInShadow() AND params.warn_only_in_shadow:
    action = 'warn'

  // Skip check for non-required order types
  IF plan.order_type NOT IN params.require_band_for:
    EMIT ExecutionReport(PRICE_BAND_PASS)
    RETURN plan

  // Fetch top-of-book mid
  book = FETCH clob_public.GET('/book?market=' + plan.market_id)
  IF book IS NULL:
    DISCARD plan; reason=STALE_MARKET_DATA
    RETURN
  mid = (book.best_bid + book.best_ask) / 2

  // Compute offset
  offsetPct = abs(plan.price - mid) / mid * 100

  // NegRisk sum-to-one check
  IF plan.neg_risk:
    market = FETCH gamma.getMarket(plan.market_id)
    legPrices = [plan.price] + [p FOR p IN market.other_leg_prices]
    IF sum(legPrices) > 1.0:
      DISCARD plan; reason=PRICE_BAND_NEGRISK_BREACH
      RETURN

  // Band check
  IF offsetPct > params.max_offset_from_mid_pct:
    IF action == 'reject':
      DISCARD plan; reason=PRICE_BAND_BREACH
      RETURN
    ELIF action == 'reshape':
      snapDirection = 1 IF plan.price > mid ELSE -1
      plan.price = mid * (1 + snapDirection * params.max_offset_from_mid_pct / 100)
      EMIT ExecutionReport(PRICE_BAND_RESHAPED)
    ELIF action == 'warn':
      EMIT ExecutionReport(PRICE_BAND_WARN)
  ELSE:
    EMIT ExecutionReport(PRICE_BAND_PASS)

  RETURN plan

SDK calls used

• clob_public.GET('/book?market=' + plan.market_id)
• gamma.getMarket(plan.market_id)

Complexity: O(L) where L = number of negRisk outcome legs (typically 2–4)

11. Wire Examples

Input — what arrives on the wire

ExecutionPlan from SmartRouter — exec.smart_router

{
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "price": 0.68,
  "size_usd": 300,
  "order_type": "GTC",
  "side": "BUY",
  "neg_risk": false,
  "collateral": "pUSD"
}

Output — what the bot emits

ExecutionReport — PRICE_BAND_PASS

{
  "report_id": "rep_7a8b9c0d1e2f3a4b",
  "bot_id": "exec.pricebandvalidator",
  "order_price": 0.68,
  "mid_price": 0.62,
  "offset_pct": 9.7,
  "verdict": "PRICE_BAND_PASS",
  "collateral": "pUSD",
  "evaluated_at_ms": 1746770500000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionReport object. See ExecutionReport schema.

{
  "report_id": "rep_7a8b9c0d1e2f3a4b",
  "trace_id": "trc_6f7a8b9c0d1e2f3a",
  "bot_id": "exec.pricebandvalidator",
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "order_price": 0.68,
  "mid_price": 0.62,
  "offset_pct": 9.7,
  "verdict": "PRICE_BAND_PASS",
  "collateral": "pUSD",
  "evaluated_at_ms": 1746770500000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "order_price": 0.68,
  "mid_price": 0.62,
  "offset_pct": 9.7,
  "max_offset_from_mid_pct": 10,
  "verdict": "PRICE_BAND_PASS",
  "action_on_breach": "reject",
  "mode": "shadow_only",
  "warn_only_in_shadow": true
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Cache empty on restart; first validation per market triggers fresh fetch.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Poisoning the top-of-book cache to make a mispriced order appear within band
• Submitting orders with prices just within the hard threshold to avoid detection

Mitigations

• Top-of-book fetched directly from clob_public per evaluation; cache TTL limits staleness to 60s
• Warning threshold at 50% of hard threshold provides early detection before hard limit is reached

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

PriceBandValidator breaches indicate either strategy mispricing bugs or stale top-of-book data. NegRisk breaches require immediate strategy review.

On-call actions

Manual overrides

• polytraders bot set-param exec.pricebandvalidator --param max_offset_from_mid_pct --value 20 — Wide-spread market requires temporary band widening; requires Exec pod lead approval.

Healthcheck

GET /internal/health/pricebandvalidator -> 200 if clob_public reachable, top-of-book cache fresh (< 60s), breach_rate < 0.01/min. Red: clob_public unreachable (STALE_MARKET_DATA rejecting all orders), negrisk_breach_rate > 0.

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%