{ "schema_version": "1.0.0", "bot_id": "3.17", "bot_name": "ResolutionCurveTrader", "slug": "resolutioncurvetrader", "layer": "Strategy", "layer_key": "strat", "bot_class": "Alpha Strategy", "authority": [ "Trade" ], "status": "planned", "readiness": "Spec started", "flagship": false, "is_reference": false, "public_export": false, "identity": { "layer": "Strategy", "bot_class": "Alpha Strategy", "authority": "Trade", "runs_before": "Risk guardrail pipeline", "runs_after": "Observation bus / internal analytics", "applies_to": "Polymarket binary markets where the time-path probability model diverges from the CLOB price by more than divergence_entry_bps and at least min_days_remaining days remain before resolution", "default_mode": "shadow_only", "user_visible": "Advanced details only", "developer_owner": "Polytraders core \u2014 Strategy pod" }, "purpose": "ResolutionCurveTrader models the expected time-path of a Polymarket binary market's probability from the current moment to resolution, then trades when the market price deviates significantly from the model's projected curve. It captures mispricing in the temporal dimension rather than just the endpoint.", "why_it_matters": [ { "failure": "Model curve mis-calibrated for event type", "consequence": "If the probability curve template is wrong for the market category (e.g. sudden-event vs. gradual), the model consistently trades against the market's rational path." }, { "failure": "Stale input data", "consequence": "Acting on stale signals for ResolutionCurveTrader produces trades based on outdated market conditions, generating adverse fills." }, { "failure": "KillSwitch not respected", "consequence": "Emitting OrderIntents while KillSwitch is active bypasses risk controls." } ], "polymarket_inputs": [ { "input": "CLOB book (mid, depth, spread)", "source": "ws_market", "required": true, "use": "Read current market price and available depth for order sizing." }, { "input": "Market status (open/closed/resolved)", "source": "clob_public", "required": true, "use": "Skip closed or resolved markets." } ], "internal_inputs": [ { "input": "KillSwitch active flag", "source": "KillSwitch", "required": true, "use": "Abort all intent emission if KillSwitch active." }, { "input": "ResolutionCurveTrader analytics signal", "source": "internal (analytics engine)", "required": true, "use": "Provides the core ResolutionCurveTrader signal that drives trade decisions." }, { "input": "Builder code bytes32", "source": "internal config", "required": true, "use": "Injected into builder field on every signed V2 OrderIntent." } ], "raw_params": [ "curve_template \u00b7 enum", "divergence_entry_bps \u00b7 int", "min_days_remaining \u00b7 int", "exit_on_curve_revert \u00b7 bool" ], "parameters": [ { "name": "divergence_entry_bps", "default": 150, "warning": 75, "hard": 25, "controls": "Minimum bps divergence between the CLOB price and the modeled curve value required to enter.", "why_default_matters": "150 bps ensures meaningful edge above fee drag.", "threshold_logic": [ { "condition": ">= 150 bps", "action": "EMIT IOC entry" }, { "condition": "75\u2013150 bps", "action": "WARN RCT_DIVERGENCE_MARGINAL; halve size" }, { "condition": "< 25 bps", "action": "SKIP RCT_NO_DIVERGENCE" } ], "dev_check": "if div_bps < params.hard: return skip('RCT_NO_DIVERGENCE')", "user_facing": "The market price was too close to the curve model value." }, { "name": "min_days_remaining", "default": 3, "warning": 1, "hard": 0, "controls": "Minimum days until market resolution before the bot will enter a new position.", "why_default_matters": "3 days provides enough time for the curve trade to resolve in the expected direction.", "threshold_logic": [ { "condition": ">= 3 days", "action": "Allow entry" }, { "condition": "1\u20133 days", "action": "WARN RCT_SHORT_WINDOW; halve size" }, { "condition": "< 1 day", "action": "HARD_REJECT RCT_RESOLUTION_TOO_CLOSE" } ], "dev_check": "if days_remaining < params.hard: return skip('RCT_RESOLUTION_TOO_CLOSE')", "user_facing": "Too close to resolution for a new curve trade." }, { "name": "exit_on_curve_revert", "default": true, "warning": null, "hard": null, "controls": "If true, the bot emits an exit OrderIntent when the CLOB price converges back to the model curve.", "why_default_matters": "Automatic exit when edge disappears prevents overstaying a position.", "threshold_logic": [ { "condition": "curve reverts", "action": "Emit exit OrderIntent if true" } ], "dev_check": "if exit_on_curve_revert and div_bps < exit_threshold: emit exit", "user_facing": "Position was closed when the market converged to the model curve." }, { "name": "max_position_per_market", "default": 400, "warning": 600, "hard": 800, "controls": "Maximum pUSD per market for curve trades.", "why_default_matters": "400 pUSD limits single-market curve exposure.", "threshold_logic": [ { "condition": "<= 400 pUSD", "action": "Normal sizing" }, { "condition": "> 800 pUSD", "action": "Reject config \u2014 PARAMETER_CHANGE_REQUIRES_APPROVAL" } ], "dev_check": "if params.max_position_per_market > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')", "user_facing": "Position size was capped at the per-market maximum." } ], "default_config": { "bot_id": "strat.resolutioncurvetrader", "version": "0.1.0", "mode": "shadow_only", "defaults": { "divergence_entry_bps": 150, "min_days_remaining": 3, "exit_on_curve_revert": true, "max_position_per_market": 400 }, "locked": { "divergence_entry_bps": { "min": 25 }, "min_days_remaining": { "min": 0 }, "max_position_per_market": { "min": 800 } } }, "implementation_flow": [ "Check KillSwitch; if active, emit no OrderIntents.", "FETCH ResolutionCurveTrader analytics signal from internal engine.", "IF signal below hard floor: SKIP, emit sampled DecisionReport RCT_NO_EDGE.", "FETCH clob_public market status; skip if closed or resolved.", "FETCH ws_market book; compute current mid and available depth.", "IF signal < warning threshold: WARN RCT_MARGINAL; reduce size 50%.", "Compute order size = min(max_size_param, available_depth).", "EMIT IOC OrderIntent with builder code.", "EMIT DecisionReport with intent_emitted=true, reason=RCT_TRADE." ], "decision_logic": { "approve": "All gates passed, KillSwitch inactive, market open. Emit IOC OrderIntent.", "reshape_required": "Not applicable \u2014 reshaping handled by downstream Risk guardrail.", "reject": "Signal below hard floor; stale data; market closed; KillSwitch active.", "warning_only": "Signal in warning zone triggers 50% size reduction." }, "decision_output_schema": "OrderIntent", "decision_output_example": { "intent_id": "oi_01HRCT0000001A", "trace_id": "tr_01HRCT000TR001", "market_id": "0xresoluti000000000000000000000000000000000000000000000000000000000001", "outcome": "YES", "side": "buy", "price": "0.540", "size_pUSD": "200.00", "tif": "IOC", "post_only": false, "builder": { "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "fee_bps": 25 }, "negrisk_aware": false, "decision": { "signal_score": 0.75, "reasons": [ "RCT_TRADE" ] }, "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order" }, "developer_log": { "bot_id": "strat.resolutioncurvetrader", "market_id": "0xresoluti000000000000000000000000000000000000000000000000000000000001", "signal_score": 0.75, "intent_emitted": true, "reason": "RCT_TRADE", "emitted_at_ms": 1746790800000 }, "user_explanations": [ { "situation": "ResolutionCurveTrader trade placed", "message": "The ResolutionCurveTrader strategy detected a suitable opportunity and placed a trade." }, { "situation": "Edge too small \u2014 no trade", "message": "The signal was below the minimum threshold. No trade was placed." }, { "situation": "Safety gate active \u2014 no trade", "message": "A safety condition (stale data, kill switch, or parameter limit) blocked the trade." } ], "failure_modes": { "main_failure_mode": "If the probability curve template is wrong for the market category (e.g. sudden-event vs. gradual), the model consistently trades against the market's rational path.", "false_positive_risk": "Signal mis-fires when market conditions change rapidly, producing trades that quickly move against the ResolutionCurveTrader thesis.", "false_negative_risk": "Hard floor set too conservatively misses genuine opportunities.", "safe_fallback": "If ws_market feed stale or analytics signal unavailable, skip without emitting any OrderIntent.", "required_dependencies": [ "ws_market", "clob_public", "internal ResolutionCurveTrader analytics engine", "KillSwitch", "internal builder code" ] }, "acceptance_tests": { "unit": [ { "test": "Emit IOC when signal=0.75 and all gates pass", "setup": "standard config", "expected": "IOC OrderIntent; reason=RCT_TRADE" }, { "test": "Skip when signal below hard floor", "setup": "signal=below_hard", "expected": "No OrderIntent; sampled reason=RCT_NO_EDGE" }, { "test": "Skip when KillSwitch active", "setup": "killswitch.active=true", "expected": "No OrderIntents emitted" } ], "integration": [ { "test": "Full cycle: signal \u2192 computation \u2192 IOC OrderIntent on Polygon testnet", "expected": "Order has builder.code, no feeRateBps, EIP-712 domain v2" } ], "property": [ { "property": "Bot never emits OrderIntent when KillSwitch is active", "required": "Always true" }, { "property": "feeRateBps never present on any signed OrderIntent", "required": "Always true" } ] }, "checklist_overrides": {}, "legacy_goal": "Price the path of probability between now and resolution, not just the endpoint.", "legacy_pm_signals": [ "Mid history vs. fitted resolution-curve template", "Time-weighted divergence from theoretical drift", "Open-interest concentration along the curve" ], "legacy_external_feeds": [], "reporting_groups": [ "strategy_decision" ], "reason_codes": [ { "code": "RCT_TRADE", "severity": "INFO", "meaning": "All gates passed. IOC OrderIntent emitted for ResolutionCurveTrader.", "action": "Emit IOC OrderIntent.", "user_message": "A ResolutionCurveTrader trade was placed." }, { "code": "RCT_MARGINAL", "severity": "WARN", "meaning": "Edge is within the warning threshold; size reduced 50%.", "action": "Emit at 50% size; log warning.", "user_message": "A small edge was found; a reduced-size ResolutionCurveTrader trade was placed." }, { "code": "RCT_NO_EDGE", "severity": "INFO", "meaning": "Edge below hard floor. Skipping.", "action": "Skip; emit sampled DecisionReport.", "user_message": "The edge was too small to justify a trade." }, { "code": "RCT_HARD_REJECT", "severity": "HARD_REJECT", "meaning": "A critical gate condition blocked the trade (stale data, kill switch, or hard parameter breach).", "action": "Skip; no OrderIntent.", "user_message": "A safety condition blocked the trade." }, { "code": "KILL_SWITCH_ACTIVE", "severity": "HARD_REJECT", "meaning": "Global kill switch is active.", "action": "Skip all markets; no OrderIntents emitted.", "user_message": "Trading is currently paused." } ], "metrics": { "emitted": [ { "name": "polytraders_strat_resolutioncurvetrader_decisions_total", "type": "counter", "unit": "count", "labels": [ "verdict", "reason_code" ], "meaning": "Total evaluation cycles by verdict and reason code." }, { "name": "polytraders_strat_resolutioncurvetrader_signal_score", "type": "histogram", "unit": "score", "labels": [], "meaning": "Distribution of analytics signal scores at evaluation." }, { "name": "polytraders_strat_resolutioncurvetrader_intents_emitted_total", "type": "counter", "unit": "count", "labels": [ "outcome" ], "meaning": "Total IOC OrderIntents emitted." }, { "name": "polytraders_strat_resolutioncurvetrader_eval_latency_ms", "type": "histogram", "unit": "milliseconds", "labels": [], "meaning": "Latency from signal receipt to OrderIntent emit." } ], "alerts": [ { "name": "ResolutionCurveTraderStaleFeed", "condition": "rate(polytraders_strat_resolutioncurvetrader_decisions_total{reason_code='STALE_MARKET_DATA'}[5m]) > 0.1", "severity": "warn", "runbook": "#runbook-resolutioncurvetrader-stale" }, { "name": "ResolutionCurveTraderKillSwitch", "condition": "rate(polytraders_strat_resolutioncurvetrader_decisions_total{reason_code='KILL_SWITCH_ACTIVE'}[1m]) > 0", "severity": "page", "runbook": "#runbook-killswitch" }, { "name": "ResolutionCurveTraderNoEdge", "condition": "rate(polytraders_strat_resolutioncurvetrader_decisions_total{verdict='skip',reason_code='RCT_NO_EDGE'}[10m]) / rate(polytraders_strat_resolutioncurvetrader_decisions_total[10m]) > 0.95", "severity": "warn", "runbook": "#runbook-resolutioncurvetrader-edge" } ] }, "state": { "store": "redis", "shape": "Per market: last signal score, last evaluated timestamp; keyed by market_id", "ttl": "60s per signal snapshot", "recovery": "On cold start, signals rebuilt from next analytics engine poll.", "size_estimate": "~150 bytes per tracked market; < 500 KB total" }, "concurrency": { "execution_model": "actor-per-market", "max_in_flight": 25, "idempotency_key": "intent_id", "timeout_ms": 300, "backpressure": "drop oldest signal per market_id when queue > 2", "locking": "per-market_id mutex for signal state" }, "dependencies": { "depends_on": [ { "bot_id": "risk.kill_switch", "why": "Checked first; blocks all intent emission when active." } ], "emits_to": [ { "bot_id": "risk.portfolio_guard", "what": "IOC OrderIntents for risk guardrail evaluation." }, { "bot_id": "gov.builder_attribution", "what": "builder.code bytes32 on every OrderIntent." } ], "sibling": [], "external": [ { "service": "Polymarket CLOB WebSocket (ws_market)", "sla": "best-effort", "fallback": "Skip all OrderIntent emission on disconnect." }, { "service": "Internal ResolutionCurveTrader analytics engine", "sla": "internal SLA", "fallback": "If signal unavailable, treat as below hard floor and skip." } ] }, "security_surfaces": { "signs_orders": true, "private_key_access": "signing-only", "abuse_vectors": [ "Signal injection to produce false ResolutionCurveTrader trades", "Order sizing parameter manipulation to exceed position limits" ], "mitigations": [ "ResolutionCurveTrader analytics signals sourced from authenticated internal engine only", "Hard limits on position size enforced before OrderIntent emission", "Builder code injected from secure internal config" ] }, "failure_injection": [ { "scenario": "SIGNAL_UNAVAILABLE", "how_to_inject": "Cut internal analytics engine connection", "expected_behaviour": "No entries; DecisionReport with reason=RCT_HARD_REJECT emitted", "recovery": "Automatic when engine reconnects." }, { "scenario": "HARD_FLOOR_BREACH", "how_to_inject": "Inject signal below hard floor", "expected_behaviour": "RCT_NO_EDGE; no OrderIntent", "recovery": "Automatic on next valid signal." }, { "scenario": "KILL_SWITCH_ON", "how_to_inject": "Set killswitch.active=true", "expected_behaviour": "No OrderIntents emitted for any market", "recovery": "Automatic on manual KillSwitch reset." } ], "runbook": { "summary": "ResolutionCurveTrader incidents are typically stale analytics feeds or kill-switch activations. Hard-floor skips are normal.", "oncall_actions": [ { "alert": "ResolutionCurveTraderStaleFeed", "first_action": "Check internal ResolutionCurveTrader analytics engine connectivity and feed health.", "escalate_to": "Infra on-call if feed lag > 5 min." }, { "alert": "ResolutionCurveTraderKillSwitch", "first_action": "Confirm KillSwitch activation was intentional.", "escalate_to": "Risk pod lead immediately." }, { "alert": "ResolutionCurveTraderNoEdge", "first_action": "Review signal calibration; check if market conditions have changed.", "escalate_to": "Strategy pod lead if prolonged." } ], "manual_overrides": [ { "name": "exclude_market", "how": "Add market_id to config.excluded_markets", "when": "Market is showing anomalous conditions that invalidate the ResolutionCurveTrader signal." } ], "healthcheck": "GET /internal/health/resolutioncurvetrader -> 200 if Analytics engine active; signal age < 60s; KillSwitch inactive.. Red: Analytics engine down or KillSwitch active.." }, "promotion_gates": { "to_shadow": [ { "gate": "Unit tests pass including hard-floor skip and kill-switch block", "how_measured": "CI test run", "threshold": "100% pass" } ], "to_limited_live": [ { "gate": "p99 eval latency < 300ms over 24h shadow run", "how_measured": "polytraders_strat_resolutioncurvetrader_eval_latency_ms histogram", "threshold": "p99 < 300ms" } ], "to_general_live": [ { "gate": "E2E: signal \u2192 computation \u2192 IOC OrderIntent on Polygon testnet with builder.code and no feeRateBps", "how_measured": "E2E test", "threshold": "Pass" } ] }, "wire_examples": { "input": [ { "label": "ResolutionCurveTrader analytics signal", "source": "internal (analytics engine)", "payload": { "market_id": "0xresoluti000000000000000000000000000000000000000000000000000000000001", "signal_score": "0.75", "received_at_ms": 1746790800000 } } ], "output": [ { "label": "OrderIntent \u2014 ResolutionCurveTrader IOC buy YES", "payload": { "intent_id": "oi_01HRCT0000001A", "market_id": "0xresoluti000000000000000000000000000000000000000000000000000000000001", "outcome": "YES", "side": "buy", "price": "0.540", "size_pUSD": "200.00", "tif": "IOC", "builder": { "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "fee_bps": 25 }, "decision": { "signal_score": 0.75, "reasons": [ "RCT_TRADE" ] } } } ] }, "reference_implementation": { "pseudocode": "FUNCTION onSignalUpdate(market_id, signal):\n ks = FETCH internal.killswitch.status\n IF ks.active: RETURN\n\n // Hard floor gate\n IF signal.score < params.divergence_entry_bps_hard:\n IF random() < 0.01:\n EMIT DecisionReport(intent_emitted=false, reason='RCT_NO_EDGE')\n RETURN\n\n mkt = FETCH clob_public.GET('/markets/' + market_id)\n IF mkt.closed OR mkt.resolved: RETURN\n\n // Warning threshold check\n sizeMultiplier = 0.5 IF signal.score < params.divergence_entry_bps_warn ELSE 1.0\n IF sizeMultiplier < 1.0: WARN('RCT_MARGINAL')\n\n // Book snapshot\n book = FETCH ws_market.book(market_id)\n mid = (book.best_bid + book.best_ask) / 2\n depth = FETCH clob_public.depth(market_id)\n\n // Size computation\n orderSize = toPusdUnits(min(params.min_days_remaining * sizeMultiplier, depth.available))\n\n EMIT OrderIntent(market=market_id, outcome='YES', side='buy', price=mid,\n size_pUSD=orderSize, tif='IOC', builder=internalBuilderCode)\n EMIT DecisionReport(intent_emitted=true, signal_score=signal.score,\n reason='RCT_TRADE')", "sdk_calls": [ "ws_market.subscribe('book', [market_id])", "fetchClobPublic('/markets/' + market_id)", "internal.analyticsEngine.signal(market_id)", "buildOrderTypedData(orderParams, {name:'CTFExchange', version:'2', chainId:137})", "internal.builder_code" ], "complexity": "O(1) per signal update per market" }, "api_surface": [ "clob_public", "clob_auth", "ws_market", "internal" ], "network": [ "polygon" ], "version": { "spec": "2.0.0", "implementation": "0.1.0", "schema": "2", "released": null, "planned_release": "Q3-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": true, "negrisk_aware": false, "multichain_ready": false, "sdk_used": "py-clob-client-v2", "settlement_contract": "CTFExchangeV2", "notes": "Bot not yet implemented; designed against V2 schema (pUSD, builder codes, V2 EIP-712 domain). feeRateBps not present on any signed OrderIntent." }, "reporting": { "emits_kinds": [ "DecisionReport" ], "topics": [ "polytraders.reports.decision" ], "cadence": "every-event", "retention_class": "2y", "sampling_rule": "emit-every", "bus_failure_action": "fail-closed", "user_visible": "yes", "consumes_kinds": [ "ObservationReport", "RiskVote" ] }, "capital_impact": "Direct", "v3_status": { "phase": 8, "phase_name": "Additional strategies", "docs": { "done": 27, "total": 27, "state": "done" }, "impl": { "done": 0, "total": 15, "state": "pending" }, "runtime": { "done": 0, "total": 8, "state": "pending" }, "overall": "pending" } }