{ "schema_version": "1.0.0", "bot_id": "2.12", "bot_name": "PriceBandValidator", "slug": "pricebandvalidator", "layer": "Execution", "layer_key": "exec", "bot_class": "Execution Utility", "authority": [ "Reshape" ], "status": "planned", "readiness": "Spec started", "flagship": false, "is_reference": false, "public_export": false, "identity": { "layer": "Execution", "bot_class": "Execution Utility", "authority": "Reshape", "runs_before": "Order signing and CLOB V2 submission", "runs_after": "SmartRouter (ExecutionPlan assembled)", "applies_to": "Every ExecutionPlan before order signing", "default_mode": "shadow_only", "user_visible": "yes", "developer_owner": "Polytraders core \u2014 Execution pod" }, "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.", "why_it_matters": [ { "failure": "Fat-finger price not caught", "consequence": "An order priced at 0.06 instead of 0.60 submits at a tenfold mispricing, immediately filling against informed counterparties at a large loss." }, { "failure": "Decimal shift not detected", "consequence": "A misconfigured strategy submitting pUSD amounts as probabilities (e.g. 45.0 instead of 0.45) creates orders orders of magnitude outside market range." }, { "failure": "NegRisk sum-to-one constraint not checked", "consequence": "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." } ], "polymarket_inputs": [ { "input": "CLOB V2 top-of-book snapshot", "source": "clob_public", "required": true, "use": "Compute current mid price for band validation." }, { "input": "Market negRisk flag", "source": "gamma", "required": false, "use": "Apply sum-to-one constraint for negRisk markets." } ], "internal_inputs": [ { "input": "ExecutionPlan from SmartRouter", "source": "exec.smart_router", "required": true, "use": "Validate plan.price against current mid \u00b1 max_offset_from_mid_pct." } ], "raw_params": [ "max_offset_from_mid_pct \u00b7 0\u2013100", "require_band_for \u00b7 list", "action_on_breach \u00b7 enum", "warn_only_in_shadow \u00b7 bool" ], "parameters": [ { "name": "max_offset_from_mid_pct", "default": 10, "warning": 15, "hard": 25, "controls": "Maximum allowed percentage offset of the order price from the current top-of-book mid. Orders outside this band are rejected or warned.", "why_default_matters": "10% offset allows normal spread and intentional aggressive pricing while catching decimal shifts and fat-finger errors.", "threshold_logic": [ { "condition": "offset_pct <= 10", "action": "PASS \u2014 price within band" }, { "condition": "10 < offset_pct <= 15", "action": "WARN \u2014 PRICE_BAND_WARN; proceed" }, { "condition": "offset_pct > 25 (hard)", "action": "HARD_REJECT \u2014 PRICE_BAND_BREACH; discard order" } ], "dev_check": "if abs(price - mid) / mid * 100 > params.max_offset_from_mid_pct: emit(PRICE_BAND_BREACH)", "user_facing": "Your order price was checked against current market conditions before submission." }, { "name": "require_band_for", "default": [ "GTC", "GTD" ], "warning": "\u2014", "hard": "\u2014", "controls": "Order types for which the price band check is mandatory. FOK orders may be exempt if strategy explicitly opts out.", "why_default_matters": "GTC and GTD orders rest in the book and may fill far from intent if mispriced; FOK orders self-cancel if unfilled so the risk is lower.", "threshold_logic": [ { "condition": "order_type IN require_band_for", "action": "Band check mandatory" }, { "condition": "order_type NOT IN require_band_for", "action": "Band check optional (WARN only in shadow mode)" } ], "dev_check": "if plan.order_type in params.require_band_for: validateBand(plan.price, mid)", "user_facing": "Price checks are applied to all resting orders." }, { "name": "action_on_breach", "default": "reject", "warning": "\u2014", "hard": "\u2014", "controls": "Action to take on a price band breach: reject (discard order), warn (annotate and proceed), or reshape (snap price to band edge).", "why_default_matters": "Reject is the safest default for production; warn is useful in shadow mode to build confidence in the band calibration.", "threshold_logic": [ { "condition": "action=reject", "action": "Discard ExecutionPlan; emit HARD_REJECT" }, { "condition": "action=warn", "action": "Annotate ExecutionPlan; proceed" }, { "condition": "action=reshape", "action": "Snap price to band edge; emit RESHAPE" } ], "dev_check": "if breach and params.action_on_breach == 'reject': discard(plan)", "user_facing": "A price check failed. Your order was not submitted." }, { "name": "warn_only_in_shadow", "default": true, "warning": "\u2014", "hard": "\u2014", "controls": "In shadow mode, treat all breaches as WARN rather than HARD_REJECT, regardless of action_on_breach, to allow band calibration without blocking orders.", "why_default_matters": "Shadow-mode data is needed to tune max_offset_from_mid_pct before going live; blocking orders in shadow prevents this.", "threshold_logic": [ { "condition": "mode=shadow AND warn_only_in_shadow=true", "action": "All breaches \u2192 WARN only" }, { "condition": "mode=live OR warn_only_in_shadow=false", "action": "Apply action_on_breach normally" } ], "dev_check": "if isInShadow() and params.warn_only_in_shadow: action = 'warn'", "user_facing": "" } ], "default_config": { "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 } } }, "implementation_flow": [ "Receive ExecutionPlan from SmartRouter.", "If mode=shadow and warn_only_in_shadow=true, set effective_action=warn.", "If plan.order_type NOT IN require_band_for, skip band check.", "Fetch top-of-book snapshot from clob_public; compute mid = (best_bid + best_ask) / 2.", "Compute offset_pct = abs(plan.price - mid) / mid * 100.", "If offset_pct > max_offset_from_mid_pct: apply action_on_breach (reject/warn/reshape).", "If market.neg_risk: check that all leg prices for this market group sum to <= 1.0.", "Emit ExecutionReport with verdict, offset_pct, mid_used, and reason_code." ], "decision_logic": { "approve": "offset_pct within max_offset_from_mid_pct; PRICE_BAND_PASS emitted.", "reshape_required": "action_on_breach=reshape: price snapped to band edge (mid \u00b1 max_offset pct); PRICE_BAND_RESHAPED emitted.", "reject": "action_on_breach=reject and offset_pct > hard threshold; PRICE_BAND_BREACH emitted; order discarded.", "warning_only": "action_on_breach=warn or mode=shadow; PRICE_BAND_WARN emitted; plan proceeds unchanged." }, "decision_output_schema": "ExecutionReport", "decision_output_example": { "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 }, "developer_log": { "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 }, "user_explanations": [ { "situation": "Price check passed", "message": "Your order price was within the expected range for the current market." }, { "situation": "Order rejected \u2014 price too far from market", "message": "Your order price was significantly different from the current market price and was rejected to protect you from a likely error." }, { "situation": "Order price snapped to band edge", "message": "Your order price was adjusted to be within the safe range for this market." } ], "failure_modes": { "main_failure_mode": "Top-of-book snapshot is stale, causing mid to be calculated from a stale price that doesn't reflect the current market, producing false positive band breaches or false negatives.", "false_positive_risk": "A legitimate aggressive price on a wide-spread market triggers PRICE_BAND_BREACH because max_offset_from_mid_pct is calibrated for liquid markets.", "false_negative_risk": "A fat-finger with offset exactly at max_offset_from_mid_pct passes without warning.", "safe_fallback": "If clob_public top-of-book is unavailable, reject the order with STALE_MARKET_DATA rather than proceeding without a band check.", "required_dependencies": [ "clob_public top-of-book snapshot", "ExecutionPlan from SmartRouter" ] }, "acceptance_tests": { "unit": [ { "test": "PASS when order price within 10% of mid", "setup": "order_price=0.68, mid=0.62, max_offset=10%", "expected": "offset_pct=9.7 < 10; PRICE_BAND_PASS" }, { "test": "REJECT when offset > hard threshold (25%)", "setup": "order_price=0.06, mid=0.62, action=reject", "expected": "offset_pct=90.3 > 25; PRICE_BAND_BREACH; order discarded" }, { "test": "WARN only in shadow mode regardless of action_on_breach", "setup": "mode=shadow, warn_only_in_shadow=true, offset_pct=30", "expected": "PRICE_BAND_WARN; order not discarded" } ], "integration": [ { "test": "Reshape: price snapped to band edge", "setup": "action=reshape, order_price=0.10, mid=0.62, max_offset=10%", "expected": "reshaped_price = mid * (1 - 0.10) = 0.558; PRICE_BAND_RESHAPED" }, { "test": "NegRisk sum-to-one check: leg prices sum > 1.0 triggers PRICE_BAND_NEGRISK_BREACH", "expected": "HARD_REJECT if negRisk market and sum_of_leg_prices > 1.0" } ], "property": [ { "property": "When action_on_breach=reject and offset > hard, order is never signed", "required": "Always true" }, { "property": "Reshaped price always within [mid*(1-max_offset/100), mid*(1+max_offset/100)]", "required": "Always true" } ] }, "checklist_overrides": {}, "legacy_goal": "Refuse orders priced outside a sanity band relative to mid \u2014 fat-finger / decimal-shift catcher.", "legacy_pm_signals": [ "Top-of-book mid and recent trade VWAP", "Strategy-declared edge envelope", "Outright vs. neg-risk constraints (sum-to-one band)" ], "legacy_external_feeds": [], "reporting_groups": [ "execution" ], "network": [ "polygon" ], "api_surface": [ "clob_public", "gamma", "internal" ], "version": { "spec": "2.0.0", "implementation": "0.1.0", "schema": "2", "released": null, "planned_release": "Q4-2026" }, "migration_history": [ { "date": "2026-04-28", "from": "n/a", "to": "v2-spec", "reason": "Spec drafted post-CLOB-V2 cutover; bot not yet implemented", "action_taken": "Designed against V2 schema (pUSD, builder codes, V2 EIP-712 domain)" } ], "polymarket_v2_compat": { "clob_version": "v2", "collateral": "pUSD", "eip712_domain_version": "2", "builder_code_aware": false, "negrisk_aware": true, "multichain_ready": false, "sdk_used": "py-clob-client-v2", "settlement_contract": "CTFExchangeV2", "notes": "For negRisk markets, PriceBandValidator enforces the sum-to-one constraint across all outcome legs in addition to the per-order price band check. NegRisk flag read from Gamma API." }, "reference_implementation": { "pseudocode": "FUNCTION validatePriceBand(plan):\n // Determine effective action\n action = params.action_on_breach\n IF isInShadow() AND params.warn_only_in_shadow:\n action = 'warn'\n\n // Skip check for non-required order types\n IF plan.order_type NOT IN params.require_band_for:\n EMIT ExecutionReport(PRICE_BAND_PASS)\n RETURN plan\n\n // Fetch top-of-book mid\n book = FETCH clob_public.GET('/book?market=' + plan.market_id)\n IF book IS NULL:\n DISCARD plan; reason=STALE_MARKET_DATA\n RETURN\n mid = (book.best_bid + book.best_ask) / 2\n\n // Compute offset\n offsetPct = abs(plan.price - mid) / mid * 100\n\n // NegRisk sum-to-one check\n IF plan.neg_risk:\n market = FETCH gamma.getMarket(plan.market_id)\n legPrices = [plan.price] + [p FOR p IN market.other_leg_prices]\n IF sum(legPrices) > 1.0:\n DISCARD plan; reason=PRICE_BAND_NEGRISK_BREACH\n RETURN\n\n // Band check\n IF offsetPct > params.max_offset_from_mid_pct:\n IF action == 'reject':\n DISCARD plan; reason=PRICE_BAND_BREACH\n RETURN\n ELIF action == 'reshape':\n snapDirection = 1 IF plan.price > mid ELSE -1\n plan.price = mid * (1 + snapDirection * params.max_offset_from_mid_pct / 100)\n EMIT ExecutionReport(PRICE_BAND_RESHAPED)\n ELIF action == 'warn':\n EMIT ExecutionReport(PRICE_BAND_WARN)\n ELSE:\n EMIT ExecutionReport(PRICE_BAND_PASS)\n\n RETURN plan", "sdk_calls": [ "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\u20134)" }, "wire_examples": { "input": [ { "label": "ExecutionPlan from SmartRouter", "source": "exec.smart_router", "payload": { "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", "price": 0.68, "size_usd": 300, "order_type": "GTC", "side": "BUY", "neg_risk": false, "collateral": "pUSD" } } ], "output": [ { "label": "ExecutionReport \u2014 PRICE_BAND_PASS", "payload": { "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 } } ] }, "reason_codes": [ { "code": "PRICE_BAND_PASS", "severity": "INFO", "meaning": "Order price within max_offset_from_mid_pct of current mid.", "action": "Forward ExecutionPlan to signing.", "user_message": "" }, { "code": "PRICE_BAND_WARN", "severity": "WARN", "meaning": "Order price between warning and hard threshold; or shadow mode warn-only.", "action": "Annotate ExecutionPlan; proceed.", "user_message": "Your order price is close to the edge of the normal range." }, { "code": "PRICE_BAND_BREACH", "severity": "HARD_REJECT", "meaning": "Order price exceeds max_offset_from_mid_pct and action_on_breach=reject.", "action": "Discard ExecutionPlan; emit no order.", "user_message": "Your order price was too far from the current market price and was rejected." }, { "code": "PRICE_BAND_RESHAPED", "severity": "RESHAPE", "meaning": "Order price snapped to band edge; action_on_breach=reshape.", "action": "Update plan.price to band edge; forward to signing.", "user_message": "Your order price was adjusted to stay within the valid range." }, { "code": "PRICE_BAND_NEGRISK_BREACH", "severity": "HARD_REJECT", "meaning": "NegRisk market: sum of outcome leg prices > 1.0.", "action": "Discard ExecutionPlan.", "user_message": "Your order prices across this market's outcomes exceeded the valid total." } ], "metrics": { "emitted": [ { "name": "polytraders_exec_pricebandvalidator_decisions_total", "type": "counter", "unit": "count", "labels": [ "verdict" ], "meaning": "Total price band decisions by verdict." }, { "name": "polytraders_exec_pricebandvalidator_offset_pct", "type": "histogram", "unit": "pct", "labels": [], "meaning": "Distribution of order price offsets from mid at evaluation time." }, { "name": "polytraders_exec_pricebandvalidator_breaches_total", "type": "counter", "unit": "count", "labels": [ "reason_code" ], "meaning": "Total price band breaches by reason code." } ], "alerts": [ { "name": "PBVHighBreachRate", "condition": "rate(polytraders_exec_pricebandvalidator_breaches_total[5m]) > 0.05", "severity": "P2", "runbook": "#runbook-pbv-breach-rate" }, { "name": "PBVNegRiskBreaches", "condition": "rate(polytraders_exec_pricebandvalidator_breaches_total{reason_code='PRICE_BAND_NEGRISK_BREACH'}[5m]) > 0", "severity": "P1", "runbook": "#runbook-pbv-negrisk" } ] }, "state": { "store": "in-memory top-of-book cache keyed by market_id (60s TTL)", "shape": "{market_id: {best_bid, best_ask, mid, fetched_at_ms}}", "ttl": "60s per market entry", "recovery": "Cache empty on restart; first validation per market triggers fresh fetch.", "size_estimate": "~100 bytes per market; ~10 KB for 100 active markets" }, "concurrency": { "execution_model": "per-plan goroutine", "max_in_flight": 100, "idempotency_key": "trace_id + market_id + price", "timeout_ms": 200, "backpressure": "shed if > 100 plans queued", "locking": "per-market_id read-lock for cache reads" }, "dependencies": { "depends_on": [ { "bot_id": "exec.smart_router", "why": "Source of ExecutionPlan to validate.", "contract": "PriceBandValidator must run before order signing." } ], "emits_to": [ { "bot_id": "exec.orderlifecyclemanager", "why": "Passed-through ExecutionPlan forwarded to signing and lifecycle tracking.", "contract": "Only PASS or RESHAPE plans forwarded; BREACH plans discarded." } ], "sibling": [], "external": [ { "service": "CLOB V2 public API", "endpoint": "https://clob.polymarket.com", "sla": "99.9% / 200ms p99", "failure_mode": "If top-of-book unavailable, reject order with STALE_MARKET_DATA." }, { "service": "Gamma API", "endpoint": "https://gamma-api.polymarket.com", "sla": "99.9% / 500ms p99", "failure_mode": "If negRisk flag unavailable, skip sum-to-one check and emit WARN." } ] }, "security_surfaces": { "signs_orders": false, "private_key_access": "none", "abuse_vectors": [ "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" ] }, "failure_injection": [ { "scenario": "STALE_TOP_OF_BOOK", "how_to_inject": "Block clob_public and let cache TTL expire", "expected_behaviour": "ExecutionPlan discarded with STALE_MARKET_DATA; no order signed", "recovery": "clob_public restored; next plan triggers fresh fetch" }, { "scenario": "FAT_FINGER_PRICE", "how_to_inject": "Submit ExecutionPlan with price=0.06, mid=0.62 (90% offset), action=reject", "expected_behaviour": "offset_pct=90.3 > 25; PRICE_BAND_BREACH; order discarded", "recovery": "Automatic; strategy corrects price" }, { "scenario": "NEGRISK_SUM_BREACH", "how_to_inject": "Submit negRisk ExecutionPlan with leg prices [0.60, 0.55, 0.10] summing to 1.25", "expected_behaviour": "PRICE_BAND_NEGRISK_BREACH; order discarded", "recovery": "Automatic; strategy corrects leg prices" } ], "runbook": { "summary": "PriceBandValidator breaches indicate either strategy mispricing bugs or stale top-of-book data. NegRisk breaches require immediate strategy review.", "oncall_actions": [ { "alert": "PBVHighBreachRate", "first_step": "Identify which strategy is generating breaches; check if max_offset_from_mid_pct is calibrated for current market spread.", "diagnosis": "", "mitigation": "", "escalation": "Strategy pod lead" }, { "alert": "PBVNegRiskBreaches", "first_step": "Immediately pause the strategy generating negRisk breaches; review leg price calculation logic.", "diagnosis": "", "mitigation": "", "escalation": "Exec pod lead + Strategy pod lead" } ], "manual_overrides": [ { "name": "widen_band_temporarily", "how": "polytraders bot set-param exec.pricebandvalidator --param max_offset_from_mid_pct --value 20", "when": "Wide-spread market requires temporary band widening; requires Exec pod lead approval.", "command": "polytraders bot set-param exec.pricebandvalidator --param max_offset_from_mid_pct --value 20", "effect": "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." }, "promotion_gates": { "to_shadow": [ { "gate": "Band computation unit tests pass with known fat-finger and negRisk scenarios", "how_measured": "CI test run", "threshold": "100% pass" } ], "to_limited_live": [ { "gate": "False-positive breach rate < 0.1% over 48h shadow run", "how_measured": "Cross-reference PRICE_BAND_BREACH events with manual price audit", "threshold": "< 0.1% false positives" } ], "to_general_live": [ { "gate": "No negRisk sum-to-one breach false positives over 7-day limited-live", "how_measured": "polytraders_exec_pricebandvalidator_breaches_total{reason_code='PRICE_BAND_NEGRISK_BREACH'}", "threshold": "Zero false positives" } ] }, "reporting": { "emits_kinds": [ "ExecutionReport" ], "topics": [ "polytraders.reports.execution" ], "partition_key": "trace_id", "cadence": "every-event", "retention_class": "7y", "sampling_rule": "emit-every", "bus_failure_action": "wal-then-retry", "user_visible": "yes", "consumes_kinds": [ "DecisionReport" ] }, "capital_impact": "Direct", "mode_support": [ "quarantine" ], "v3_status": { "phase": 5, "phase_name": "Execution rails", "docs": { "done": 27, "total": 27, "state": "done" }, "impl": { "done": 0, "total": 15, "state": "pending" }, "runtime": { "done": 0, "total": 8, "state": "pending" }, "overall": "pending" } }