{ "schema_version": "1.0.0", "bot_id": "3.23", "bot_name": "BasisTrader", "slug": "basistrader", "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 with an identified off-platform reference (sportsbook, futures, poll) sharing identical resolution rules, where the basis exceeds min_basis_bps after fees", "default_mode": "shadow_only", "user_visible": "Advanced details only", "developer_owner": "Polytraders core \u2014 Strategy pod" }, "purpose": "BasisTrader identifies and trades the price basis between a Polymarket market and an off-platform reference (sportsbook line, futures price, or consensus poll) when the resolution rules of both platforms are provably identical. The bot buys the Polymarket leg when it is cheap relative to the reference and the basis exceeds min_basis_bps after fees.", "why_it_matters": [ { "failure": "Reference instrument diverges post-entry due to rule change", "consequence": "If the off-platform reference changes its resolution criteria after the basis trade is entered, the position is no longer hedged and becomes an unprotected directional bet." }, { "failure": "Stale input data", "consequence": "Acting on stale signals for BasisTrader 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": "BasisTrader analytics signal", "source": "internal (analytics engine)", "required": true, "use": "Provides the core BasisTrader 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": [ "min_basis_bps \u00b7 int", "require_rule_parity \u00b7 bool", "max_position_per_leg \u00b7 int", "halt_on_reference_stale \u00b7 bool" ], "parameters": [ { "name": "min_basis_bps", "default": 150, "warning": 75, "hard": 25, "controls": "Minimum basis in bps between Polymarket and the reference instrument required to emit an OrderIntent.", "why_default_matters": "150 bps provides margin after fees on both legs (~50 bps each).", "threshold_logic": [ { "condition": ">= 150 bps", "action": "EMIT IOC basis trade" }, { "condition": "75\u2013150 bps", "action": "WARN BT_BASIS_MARGINAL; halve size" }, { "condition": "< 25 bps", "action": "SKIP BT_NO_BASIS" } ], "dev_check": "if basis_bps < params.hard: return skip('BT_NO_BASIS')", "user_facing": "The basis was too small after fees to justify a trade." }, { "name": "require_rule_parity", "default": true, "warning": null, "hard": null, "controls": "Both Polymarket and the reference must have provably identical resolution rules before trading. Locked true.", "why_default_matters": "Without rule parity the basis is not a true hedge; trading on it creates directional risk.", "threshold_logic": [ { "condition": "rules differ", "action": "HARD_REJECT BT_RULE_MISMATCH" } ], "dev_check": "if not rules_match(pm, reference): return skip('BT_RULE_MISMATCH')", "user_facing": "The resolution rules differ between platforms \u2014 basis trade blocked." }, { "name": "max_position_per_leg", "default": 400, "warning": 600, "hard": 800, "controls": "Maximum pUSD per leg of the basis trade.", "why_default_matters": "400 pUSD limits single-leg exposure in the basis pair.", "threshold_logic": [ { "condition": "<= 400 pUSD", "action": "Normal sizing" }, { "condition": "> 800 pUSD", "action": "Reject config" } ], "dev_check": "if params.max_position_per_leg > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')", "user_facing": "Position size capped at per-leg maximum." }, { "name": "halt_on_reference_stale", "default": true, "warning": null, "hard": null, "controls": "If true, halt all basis trades when the reference instrument price is stale (> 30s).", "why_default_matters": "Stale reference prices create phantom basis gaps that evaporate before the Polymarket order lands.", "threshold_logic": [ { "condition": "reference stale > 30s", "action": "HARD_REJECT BT_REFERENCE_STALE" } ], "dev_check": "if reference_age_s > 30: return skip('BT_REFERENCE_STALE')", "user_facing": "The reference instrument price was too old to trade on." } ], "default_config": { "bot_id": "strat.basistrader", "version": "0.1.0", "mode": "shadow_only", "defaults": { "min_basis_bps": 150, "require_rule_parity": true, "max_position_per_leg": 400, "halt_on_reference_stale": true }, "locked": { "min_basis_bps": { "min": 25 }, "max_position_per_leg": { "min": 800 } } }, "implementation_flow": [ "Check KillSwitch; if active, emit no OrderIntents.", "FETCH BasisTrader analytics signal from internal engine.", "IF signal below hard floor: SKIP, emit sampled DecisionReport BT_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 BT_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=BT_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_01HBT0000001A", "trace_id": "tr_01HBT000TR001", "market_id": "0xbasistra000000000000000000000000000000000000000000000000000000000001", "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": [ "BT_TRADE" ] }, "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order" }, "developer_log": { "bot_id": "strat.basistrader", "market_id": "0xbasistra000000000000000000000000000000000000000000000000000000000001", "signal_score": 0.75, "intent_emitted": true, "reason": "BT_TRADE", "emitted_at_ms": 1746790800000 }, "user_explanations": [ { "situation": "BasisTrader trade placed", "message": "The BasisTrader 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 off-platform reference changes its resolution criteria after the basis trade is entered, the position is no longer hedged and becomes an unprotected directional bet.", "false_positive_risk": "Signal mis-fires when market conditions change rapidly, producing trades that quickly move against the BasisTrader 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 BasisTrader 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=BT_TRADE" }, { "test": "Skip when signal below hard floor", "setup": "signal=below_hard", "expected": "No OrderIntent; sampled reason=BT_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": "Trade the basis between Polymarket and an off-platform reference (sportsbook line, futures, poll) when the rules permit.", "legacy_pm_signals": [ "Mid vs. external reference, normalised to common probability", "Resolution-rule parity check (same source-of-truth or close)", "Cost-of-funding adjustment per leg" ], "legacy_external_feeds": [ "Configured reference feeds (read-only, no live trading)" ], "reporting_groups": [ "strategy_decision" ], "reason_codes": [ { "code": "BT_TRADE", "severity": "INFO", "meaning": "All gates passed. IOC OrderIntent emitted for BasisTrader.", "action": "Emit IOC OrderIntent.", "user_message": "A BasisTrader trade was placed." }, { "code": "BT_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 BasisTrader trade was placed." }, { "code": "BT_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": "BT_RULE_MISMATCH", "severity": "HARD_REJECT", "meaning": "Resolution rules differ between Polymarket and reference instrument.", "action": "Skip; no OrderIntent.", "user_message": "The resolution rules differ \u2014 basis trade blocked." }, { "code": "BT_REFERENCE_STALE", "severity": "HARD_REJECT", "meaning": "Reference instrument price is stale (> 30s).", "action": "Skip; no OrderIntent.", "user_message": "The reference price was too old for a basis trade." }, { "code": "BT_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_basistrader_decisions_total", "type": "counter", "unit": "count", "labels": [ "verdict", "reason_code" ], "meaning": "Total evaluation cycles by verdict and reason code." }, { "name": "polytraders_strat_basistrader_signal_score", "type": "histogram", "unit": "score", "labels": [], "meaning": "Distribution of analytics signal scores at evaluation." }, { "name": "polytraders_strat_basistrader_intents_emitted_total", "type": "counter", "unit": "count", "labels": [ "outcome" ], "meaning": "Total IOC OrderIntents emitted." }, { "name": "polytraders_strat_basistrader_eval_latency_ms", "type": "histogram", "unit": "milliseconds", "labels": [], "meaning": "Latency from signal receipt to OrderIntent emit." } ], "alerts": [ { "name": "BasisTraderStaleFeed", "condition": "rate(polytraders_strat_basistrader_decisions_total{reason_code='STALE_MARKET_DATA'}[5m]) > 0.1", "severity": "warn", "runbook": "#runbook-basistrader-stale" }, { "name": "BasisTraderKillSwitch", "condition": "rate(polytraders_strat_basistrader_decisions_total{reason_code='KILL_SWITCH_ACTIVE'}[1m]) > 0", "severity": "page", "runbook": "#runbook-killswitch" }, { "name": "BasisTraderNoEdge", "condition": "rate(polytraders_strat_basistrader_decisions_total{verdict='skip',reason_code='BT_NO_EDGE'}[10m]) / rate(polytraders_strat_basistrader_decisions_total[10m]) > 0.95", "severity": "warn", "runbook": "#runbook-basistrader-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 BasisTrader 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 BasisTrader trades", "Order sizing parameter manipulation to exceed position limits" ], "mitigations": [ "BasisTrader 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=BT_HARD_REJECT emitted", "recovery": "Automatic when engine reconnects." }, { "scenario": "HARD_FLOOR_BREACH", "how_to_inject": "Inject signal below hard floor", "expected_behaviour": "BT_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": "BasisTrader incidents are typically stale analytics feeds or kill-switch activations. Hard-floor skips are normal.", "oncall_actions": [ { "alert": "BasisTraderStaleFeed", "first_action": "Check internal BasisTrader analytics engine connectivity and feed health.", "escalate_to": "Infra on-call if feed lag > 5 min." }, { "alert": "BasisTraderKillSwitch", "first_action": "Confirm KillSwitch activation was intentional.", "escalate_to": "Risk pod lead immediately." }, { "alert": "BasisTraderNoEdge", "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 BasisTrader signal." } ], "healthcheck": "GET /internal/health/basistrader -> 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_basistrader_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": "BasisTrader analytics signal", "source": "internal (analytics engine)", "payload": { "market_id": "0xbasistra000000000000000000000000000000000000000000000000000000000001", "signal_score": "0.75", "received_at_ms": 1746790800000 } } ], "output": [ { "label": "OrderIntent \u2014 BasisTrader IOC buy YES", "payload": { "intent_id": "oi_01HBT0000001A", "market_id": "0xbasistra000000000000000000000000000000000000000000000000000000000001", "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": [ "BT_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.min_basis_bps_hard:\n IF random() < 0.01:\n EMIT DecisionReport(intent_emitted=false, reason='BT_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.min_basis_bps_warn ELSE 1.0\n IF sizeMultiplier < 1.0: WARN('BT_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.require_rule_parity * 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='BT_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" } }