Sports Edge Fields

A sports alias reads the live state of one Kalshi game: whether it has started, the period and clock, and the score. Values come from Kalshi's own live game feed, the same one behind the scoreboard on Kalshi's site, and are read from the side of the team you choose, so lead is positive when that team is ahead.

This page covers choosing the team market, the thirteen fields and how each sport maps onto them, the timing caveats, and a recipe that stops new entries late in a game and closes out a blowout. An espn alias adds ESPN's live win probability for NFL and NBA games, so a strategy can buy when that model rates the team well above the Kalshi price; see ESPN win probability. Custom strategies on Kalshi read a field as edge.<alias>.<field> once it is listed in the alias's fields. For the alias keys and refresh minimums, see Declaring and Reading Edge Data.

Choosing the team market

Set symbol to a Kalshi team market ticker: the market that pays out if one team wins, such as KXNFLGAME-26OCT18ARILAR-LAR (the Rams in Cardinals at Rams). Usually this is the same ticker as market.ticker, so the score fields describe the team your YES contracts are on.

• Football (NFL and college), basketball, hockey and soccer games are supported. A market in another sport, or one with no live game data, makes the alias fail, and entries are blocked.
• An event ticker such as KXNFLGAME-26OCT18ARILAR fails validation with does not match required format: name a team market.
• A tie or draw market (...-TIE) has no team, so the alias fails at runtime with is not one team's market.

Sports fields

Flags only take 0 or 1; a condition such as team_has_ball >= 2 fails validation with flag in [0,1].

Regulation lengths: NFL and college football 4 × 15 minutes, NBA 4 × 12, college basketball 2 × 20 halves, other basketball 4 × 10, hockey 3 × 20. Soccer reads the match minute: 45 minutes per half, so stoppage time reads as 0 seconds left until the next half starts.

Timing caveats

• The clock moves when the feed records a play, not every second. Between plays, period_seconds_left and game_seconds_left hold their last value.
• Values are fetched once per refresh (default 10s, minimum 5s) and do not count down between fetches, plus up to one loop.interval.
• The end of a period is confirmed a few seconds after it happens, so a rule keyed to period changing fires slightly late.
• When Kalshi marks the game's live data as delayed (live_data_delayed), the alias treats that fetch as failed instead of reading the stale score. Kalshi sets this flag only once a board is well behind, and not every feed sets it.
• If fetches fail, the last good values are reused for up to 3 × refresh; after that the alias is missing and entries are blocked while exits keep running. See When an alias goes missing.

Backtests

Live game state has no replayable history, so a strategy that reads a sports or espn field cannot be backtested. Run it in Paper first.

The market itself can also block a backtest: Studio rejects recognized Kalshi sports market, event and series tickers even when the strategy uses prices alone, such as a tennis Stop and Target with no live-score alias. These market prices are not recorded for replay. See Kalshi backtest support.

In-game cutoff and closeout recipe

This strategy trades one team's market: it buys a dip only while the game is live with at least 15 minutes of regulation left, takes profit into a recovery, and sells if the team is still down by more than one score with 5 minutes left.

version: 1
platform: kalshi
strategy: custom
market:
  ticker: KXNFLGAME-26OCT18ARILAR-LAR
risk:
  max_position: 200
  price_floor: 0.05
  price_ceiling: 0.95
  max_entries_per_market: 1
loop:
  interval: 10
edge:
  game:
    provider: sports
    symbol: KXNFLGAME-26OCT18ARILAR-LAR
    fields: [status, game_seconds_left, lead]
    refresh: 10s
rules:
  - name: late_closeout
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: edge.game.game_seconds_left, op: "<=", value: 300}
        - {field: edge.game.lead, op: "<", value: -7}
    action: sell_all
  - name: take_profit
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: yes_best_bid, op: ">=", value: 0.57}
    action: sell_all
  - name: buy_dip
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: edge.game.status, op: "==", value: live}
        - {field: edge.game.game_seconds_left, op: ">=", value: 900}
        - {field: yes_best_ask, op: "<=", value: 0.43}
    action: buy_yes
    size: 200

The thresholds are in football points; a one-score margin is about 10 points in basketball and 1 goal in hockey or soccer. Exits sit above the entry so they win when both match.

ESPN win probability

An espn alias reads ESPN's live win probability for the game behind a Kalshi NFL or NBA team market: ESPN's own in-game model, free to compare with what Kalshi charges. ESPN's scoreboard API is public but unofficial, with no service guarantee, so it is a separate alias: if ESPN is down or the game cannot be matched, only the espn alias fails, and a sports alias on the same game keeps working.

edge:
  model:
    provider: espn
    symbol: KXNFLGAME-26OCT22NECHI-CHI
    fields: [team_win_prob]
    refresh: 15s

Probabilities are fractions: write 0.60 for 60%. A condition such as team_win_prob > 60 fails validation with probability in [0,1].

Which games it covers

• symbol must be a Kalshi NFL or NBA team market: KXNFLGAME-... or KXNBAGAME-.... Any other league fails validation with does not match required format. ESPN publishes no live win probability for hockey or soccer, and college games are not supported yet.
• The game is matched on the ticker's date and both teams, read from the ticker. Kalshi and ESPN spell a few teams differently (Kalshi JAC is ESPN JAX, GSW is GS), and those are translated. If ESPN lists no game, or more than one, for those two teams that day, the alias fails with found N ESPN games ... want exactly 1 rather than guess, and entries are blocked.
• A tie market (...-TIE) names no team and fails with cannot read both teams.

When there is no probability

• Before the start ESPN publishes no live probability, so the fields are unavailable and a rule on them never matches.
• During the game the value is ESPN's latest play. If ESPN has no probability for a play, the fields are unavailable until the next one.
• After the final the winner reads 1 and the loser 0 (an NFL tie reads tie_prob 1). A postponed or cancelled game stays unavailable.
• ESPN caches its scoreboard for about 10 seconds, so refresh has a 10s minimum and defaults to 15s. A failed fetch is retried like any other alias: the last values are reused for up to 3 × refresh.

Model above the price recipe

To buy only when ESPN rates the team at least 8 points above the YES ask, declare a minus_yes_ask derived metric. It is the probability minus the ask, so 0.08 is 8 points. While ESPN has no probability the metric is unavailable and entries are blocked; exits that don't read it keep running.

version: 1
platform: kalshi
strategy: custom
market:
  ticker: KXNFLGAME-26OCT22NECHI-CHI
risk:
  max_position: 100
  price_floor: 0.05
  price_ceiling: 0.95
  max_entries_per_market: 1
loop:
  interval: 15
edge:
  model:
    provider: espn
    symbol: KXNFLGAME-26OCT22NECHI-CHI
    fields: [team_win_prob]
    refresh: 15s
derived:
  model_edge: {kind: minus_yes_ask, observed: edge.model.team_win_prob}
rules:
  - name: model_fades
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: edge.model.team_win_prob, op: "<", value_field: yes_best_bid}
    action: sell_all
  - name: model_above_price
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: derived.model_edge, op: ">=", value: 0.08}
    action: buy_yes
    size: 100

The exit sells once ESPN rates the team below what the market would pay for the position. ESPN's model is not a guarantee: it misses news, injuries and the market's own information, so test the gap in Paper before trading real money.