3.9 Sports Model

1. Bot Identity

2. Purpose

Sports Model computes a quantitative fair-value probability for Polymarket sports markets using an internal power-rating model fed by league APIs (NBA, NFL, EPL, ATP/WTA, MLB), lineup and injury data via SportsFeed-Adapter, and weather data for outdoor events. When the CLOB mid-price diverges from the model price by more than min_edge_bps_vs_model, the bot sizes an IOC OrderIntent using a fractional-Kelly position sizing formula (kelly_fraction) bounded by max_per_bet_usd. The bot targets the Apr 2026 $5M pUSD maker rebate pool for sports+esports markets when the edge direction permits maker posting. This is a user-controlled execution tool that automates quantitative sports market trading decisions. No performance claims are made.

3. Why This Bot Matters

• Model price computed with stale lineup or injury data

  A key player's injury changes the model price substantially. Trading on the stale model produces a position in the wrong direction relative to the true updated probability.

• Kelly fraction set too high

  Fractional Kelly with a high fraction creates large positions that overwhelm the top-of-book depth, causing significant slippage and potentially exceeding the Risk guardrail's position limits.

• In-play market state not accounted for

  For in-play markets, the CLOB price updates continuously with live game state. Trading on a model price calibrated for pre-game conditions during in-play produces systematically mispriced entries.

• feeRateBps present on signed order (V1 pattern)

  CTFExchangeV2 rejects orders with feeRateBps. Fees are operator-set at match time. The signed order must not contain this field.

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

{ "min_edge_bps_vs_model": 200 }

if edge_bps < params.hard: return skip('SPORTS_MODEL_NO_EDGE')

{ "kelly_fraction": 0.1 }

if params.kelly_fraction > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "max_per_bet_usd": 500 }

if params.max_per_bet_usd > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "drawdown_guard_bps": 500 }

if session_drawdown_bps >= params.hard: return skip('SPORTS_MODEL_DRAWDOWN_GUARD_TRIGGERED')

8. Default Configuration

{
  "bot_id": "strat.sports_model",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "min_edge_bps_vs_model": 200,
    "kelly_fraction": 0.1,
    "max_per_bet_usd": 500,
    "drawdown_guard_bps": 500
  },
  "locked": {
    "min_edge_bps_vs_model": {
      "min": 50
    },
    "kelly_fraction": {
      "max": 0.3
    },
    "max_per_bet_usd": {
      "max": 1000
    },
    "drawdown_guard_bps": {
      "max": 1200
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, emit no OrderIntents.
2. Subscribe to ws_market book updates and ws_sports live state for all active sports markets.
3. On each model update or book tick: compute CLOB mid; measure edge_bps = |model_price - clob_mid| * 10000.
4. Check session drawdown guard: if session_drawdown_bps >= drawdown_guard_bps hard (1200 bps), skip all new entries.
5. Gate 1 — Edge check: if edge_bps < 50 bps hard, emit sampled DecisionReport SPORTS_MODEL_NO_EDGE; skip.
6. Gate 2 — Data freshness: confirm SportsFeed-Adapter data is current (lineup_last_updated < 30 min); if stale, emit SPORTS_MODEL_STALE_DATA; skip.
7. Gate 3 — In-play check: if market is in-play, confirm ws_sports game state is current (< 5s); if stale, skip.
8. Gate 4 — Market status: confirm market is open and not approaching resolution (< 15 min to close for pre-game; skip in-play if halted).
9. If edge_bps < warning (200 bps): WARN SPORTS_MODEL_EDGE_MARGINAL; reduce kelly_fraction to 50%.
10. Compute Kelly size: kelly_size_usd = kelly_fraction * bankroll * edge_bps / (model_price * (1 - model_price) * 10000).
11. Set orderSize = toPusdUnits(min(kelly_size_usd, max_per_bet_usd, available_depth)) using sizeMultiplier.
12. Determine direction: buy YES if model_price > clob_mid (market underpricing YES); buy NO otherwise.
13. Emit OrderIntent: outcome=YES/NO, side=buy, price=best_ask, size_pUSD=orderSize, tif=IOC, builder={code, fee_bps:25}.
14. Note: fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order. Sports maker rebate pool eligible.
15. Update session_drawdown tracking in state.
16. Emit DecisionReport with intent_emitted=true, edge_bps, model_price, clob_mid, kelly_size_usd, reason SPORTS_MODEL_EDGE_TRADE.

10. Reference Implementation

Consumes model price updates from the internal power-rating engine, computes edge against CLOB mid-price, and emits IOC OrderIntents when edge exceeds min_edge_bps_vs_model using fractional-Kelly sizing bounded by max_per_bet_usd.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

FUNCTION onModelUpdate(market_id, modelUpdate):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // --- 1. Drawdown guard ---
  sessionDrawdown = FETCH state.sessionDrawdownBps()
  IF sessionDrawdown >= params.drawdown_guard_bps_hard:  // 1200 bps
    EMIT DecisionReport(intent_emitted=false, reason='SPORTS_MODEL_DRAWDOWN_GUARD_TRIGGERED')
    RETURN

  // --- 2. Data freshness check ---
  sportsFeed = FETCH internal.sportsfeed.marketData(market_id)
  lineupAge = (now_ms() - sportsFeed.lineup_last_updated_ms) / 60000
  IF lineupAge > 30:
    EMIT DecisionReport(intent_emitted=false, reason='SPORTS_MODEL_STALE_DATA')
    RETURN

  // --- 3. In-play state check ---
  IF market_id.is_inplay:
    gameState = FETCH ws_sports.liveState(market_id)
    IF isStale(gameState, maxAgeS=5): RETURN
    IF gameState.halted: RETURN

  // --- 4. Market status check ---
  mkt = FETCH clob_public.GET('/markets/' + market_id)
  IF mkt.closed OR mkt.resolved OR mkt.minutes_to_close < 15: RETURN

  // --- 5. Edge computation ---
  book = FETCH ws_market.book(market_id)
  clobMid = (book.best_bid + book.best_ask) / 2
  modelPrice = modelUpdate.model_price
  edgeBps = abs(modelPrice - clobMid) * 10000

  // --- 6. Hard floor check ---
  IF edgeBps < params.min_edge_bps_vs_model_hard:  // 50 bps
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='SPORTS_MODEL_NO_EDGE', edge_bps=edgeBps)
    RETURN

  // --- 7. Kelly sizing ---
  kellyMultiplier = 0.5 IF edgeBps < params.min_edge_bps_vs_model ELSE 1.0
  IF kellyMultiplier < 1.0: WARN('SPORTS_MODEL_EDGE_MARGINAL')
  IF sessionDrawdown > params.drawdown_guard_bps: kellyMultiplier *= 0.5  // progressive reduction
  bankroll = FETCH internal.accountState.bankroll_usd
  kellySizeUSD = params.kelly_fraction * bankroll * edgeBps / (modelPrice * (1 - modelPrice) * 10000)
  depth = FETCH clob_public.depth(market_id)
  orderSize = toPusdUnits(min(kellySizeUSD, params.max_per_bet_usd, depth) * kellyMultiplier)

  // --- 8. Direction ---
  outcome = 'YES' IF modelPrice > clobMid ELSE 'NO'
  price = book.best_ask IF outcome == 'YES' ELSE book.best_ask_NO

  // --- 9. Emit IOC OrderIntent (V2: no feeRateBps) ---
  EMIT OrderIntent(
    market_id = market_id, outcome = outcome, side = 'buy',
    price = price, size_pUSD = orderSize, tif = 'IOC', post_only = false,
    builder = {code: internal.builder_code, fee_bps: 25}
    // sports maker rebate pool eligible when fee_bps applied to resting side
  )

  // --- 10. Update session drawdown tracking ---
  UPDATE state.sessionDrawdownBps(market_id, orderSize, modelPrice, price)

  EMIT DecisionReport(intent_emitted=true, edge_bps=edgeBps,
                      model_price=modelPrice, clob_mid=clobMid,
                      kelly_size_usd=kellySizeUSD, reason='SPORTS_MODEL_EDGE_TRADE')

SDK calls used

• ws_market.subscribe('book', [market_id])
• ws_sports.subscribe('live_state', [market_id])
• fetchClobPublic('/markets/' + market_id)
• internal.sportsfeed.marketData(market_id)
• internal.killswitch.status()
• internal.accountState.bankroll_usd()
• toPusdUnits(rawFloat)
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• internal.builder_code

Complexity: O(1) per model update or book tick per market

11. Wire Examples

Input — what arrives on the wire

Model update — NBA market, edge=245 bps — internal (model engine)

{
  "market_id": "0xsportsmd00000000000000000000000000000000000000000000000000000001",
  "model_price": "0.537",
  "clob_mid": "0.512",
  "edge_bps": "245.0",
  "sport": "NBA",
  "lineup_last_updated_min": "8.2",
  "is_inplay": false,
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — sports model IOC buy YES (builder-attributed)

{
  "intent_id": "oi_01HXSPM0000001A",
  "trace_id": "tr_01HXSPM000TR001",
  "market_id": "0xsportsmd00000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.512",
  "size_pUSD": "220.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "edge_bps": 245.0,
    "model_price": 0.537,
    "clob_mid": 0.512,
    "kelly_size_usd": 220.0,
    "sport": "NBA",
    "reasons": [
      "SPORTS_MODEL_EDGE_TRADE"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

DecisionReport — skipped (no edge), sampled 1/100

{
  "report_id": "dr_01HXSPM999ZZZZ",
  "bot_id": "strat.sports_model",
  "market_id": "0xsportsmd00000000000000000000000000000000000000000000000000000001",
  "intent_emitted": false,
  "edge_bps": 22.0,
  "reasons": [
    "SPORTS_MODEL_NO_EDGE"
  ],
  "sampled": true,
  "evaluated_at_ms": 1746790801000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HXSPM0000001A",
  "trace_id": "tr_01HXSPM000TR001",
  "market_id": "0xsportsmd00000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.512",
  "size_pUSD": "220.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "edge_bps": 245.0,
    "model_price": 0.537,
    "clob_mid": 0.512,
    "kelly_size_usd": 220.0,
    "sport": "NBA",
    "reasons": [
      "SPORTS_MODEL_EDGE_TRADE"
    ]
  },
  "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Strategy / SportsModel edge distribution per sport
• Grafana — Strategy / SportsModel session drawdown and Kelly sizing

16. Developer Reporting

{
  "bot_id": "strat.sports_model",
  "market_id": "0xsportsmd00000000000000000000000000000000000000000000000000000001",
  "model_price": 0.537,
  "clob_mid": 0.512,
  "edge_bps": 245.0,
  "kelly_fraction": 0.1,
  "kelly_size_usd": 220.0,
  "max_per_bet_usd": 500,
  "sport": "NBA",
  "lineup_last_updated_min": 8.2,
  "session_drawdown_bps": 120.0,
  "intent_emitted": true,
  "reason": "SPORTS_MODEL_EDGE_TRADE",
  "emitted_at_ms": 1746790800000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, session drawdown resets to 0. Market state rebuilt from first ws_market tick and model update.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Adversary manipulates SportsFeed-Adapter data to produce false model prices, triggering trades in the wrong direction
• In-play market state spoofing via ws_sports injection to trigger model recalculation
• Front-running: adversary infers model price by monitoring bot's IOC orders on specific markets

Mitigations

• SportsFeed-Adapter data is authenticated from official league API sources; injection requires compromising the internal feed
• ws_sports data validated against clob_public market metadata before use in model
• IOC orders do not rest on the book; adversary cannot exploit known bid/ask placement
• Drawdown guard limits total session exposure from systematic model attacks
• V2 order timestamp(ms) invalidates replayed signed orders

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

Sports Model incidents are typically drawdown guard triggers (requiring manual session review), stale SportsFeed data (blocking all trades until feed refreshes), or stale in-play feeds. Drawdown guard triggers require ops review before session reset.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/sports-model -> 200 if ws_market feed last_seen < 5s, SportsFeed-Adapter data age < 30 min, session drawdown < 500 bps, KillSwitch inactive.

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%