Declaring and Reading Edge Data

This page is the key-by-key reference for the edge: block in custom strategies on Kalshi and Polymarket US: how to declare an alias, and how rule conditions read its values. For how edge data fits into a strategy, where it works and what happens when data is late, see Edge Data and Derived Metrics.

The YAML examples on this page are rejected on purpose, to show the error each mistake produces.

Declaring an edge alias

Alias names

The alias is your own label. It does not pick the data: btc does not imply BTC-USD, so you always declare the symbol too.

• Names must match ^[a-z][a-z0-9_]{0,31}$: start with a lowercase letter, then lowercase letters, digits or underscores, 32 characters at most. btc and nyc_temp work; BTC and bad-alias are rejected.
• You can declare up to 8 aliases. An empty edge: {} is accepted.
• Declare only aliases your rules use. Live, the Bot reads every declared alias on every tick (fetching it when its refresh is due), and a failing alias blocks entries even if no rule reads it.

Providers and selectors

Each provider has exactly one selector key. Set that key directly on the alias, and no other selector.

• Provider names are lowercase and exact. NWS or binance fails with unknown provider.
• A missing selector fails (provider "coinbase" requires selector "symbol"), and so does the wrong one (provider "nws" expects selector "station", not "symbol") or more than one (exactly one selector allowed).
• Only the format is checked. A product or station that does not exist, such as ZZZZ, passes validation, then every live fetch fails and every entry is blocked. Double-check the id before you deploy.
• Selectors are case-sensitive: btc-usd, kmdw and fomc are rejected with does not match required format.

Fields

fields lists the provider values this alias exposes. It must be a non-empty list of names from the provider's catalog: Coinbase, NWS or economic calendar.

• A name outside the catalog fails, for example provider "nws" has no field "temp_hour_13".
• Rules and derived metrics can read only fields listed here. Reading an unlisted one fails with edge field "..." not listed in alias "...".
• The list does not change what is downloaded. Each refresh fetches the provider's full data set.
• For Coinbase, listing any candle-based field raises the minimum refresh from 1s to 5s.
• Listing a field does not make it backtestable. See Backtest support.

Refresh

refresh is how long the Bot reuses a fetched value before fetching the alias again. It also sets the stale limit: if a fetch fails, the last good values are reused until they are 3 × refresh old. After that the alias is missing and entries are blocked. See The refresh cache.

Write it as a duration with a unit: 10s, 5m, 1m30s or 2.5s. Valid units are ns, us, ms, s, m and h. A bare number (5) fails with missing unit, and days (1d) fail with unknown unit "d". There is no maximum.

The cache is only checked when your loop runs, so a refresh shorter than loop.interval means "fetch on every loop" and gains nothing more. Each Coinbase refresh makes six requests (stats, book and four candle sizes) whatever fields you list.

# Rejected: a candle-based field (change_5m) needs a refresh of at least 5s
# error: refresh 2s below provider minimum 5s
version: 1
platform: kalshi
strategy: custom
strategy_name: Refresh too fast for candle fields
market:
  series_ticker: KXBTC15M
edge:
  btc:
    provider: coinbase
    symbol: BTC-USD
    fields: [price, change_5m]
    refresh: 2s
risk:
  max_position: 1
  price_floor: 0.10
  price_ceiling: 0.90
loop:
  interval: 15
rules:
  - name: exit_on_down_move
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: edge.btc.change_5m, op: "<", value: 0}
    action: sell_all
  - name: enter_on_up_move
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: edge.btc.change_5m, op: ">", value: 0.001}
    action: buy_yes
    size: 1

Keys Studio does not check

Inside an alias, keys other than provider, symbol, station, event, fields and refresh are ignored without an error. A typo such as refesh: 30s silently falls back to the default refresh, and a selector: wrapper is ignored (the alias then fails for a missing selector). Check spelling carefully.

If you write an alias on one line with braces, quote a two-event list. In {provider: economic_calendar, event: FOMC,CPI, fields: [seconds_to_next]} the unquoted comma splits the value, so only FOMC is kept and CPI is dropped with no error. Write event: "FOMC,CPI" or use block style, as in the blackout recipe.

Reading edge values in rules

Each condition needs exactly one of value or value_field. Edge references must have exactly three parts: edge.btc or edge.btc.price.x fails with edge field must be edge.<alias>.<field>, and an undeclared alias fails with edge alias "..." not declared.

Numbers and units

Every edge value except the four text fields is a plain number, and value must be one too.

• Fractions, not percents. Coinbase change_* and *_distance_pct fields are fractions: write 0.004 for 0.4%. NWS humidity and every precip_prob* field run from 0 to 1: write 0.70 for 70%.
• Checked ranges. A literal for NWS humidity, precip_prob, precip_prob_day_2, precip_prob_day_3, precip_prob_hour_1 to precip_prob_hour_12 or alert_active must be between 0 and 1, or the save fails with expects a fraction in [0,1] (or expects a flag in [0,1] for alert_active).
• No quotes. value: "100000" is rejected with requires a numeric value (got string) — remove the surrounding quotes. Calendar fields are plain seconds, so value: "30m" is rejected too; write 1800.
• Finite only. .inf and .nan fail with must be finite.
• Currency. Coinbase prices are in the product's quote currency: USD for -USD pairs, USDT for -USDT, BTC for ETH-BTC. Field names ending in _usd also mean the quote currency.

# Rejected: precipitation probability is a 0-1 fraction, so 40 is out of range (write 0.40)
# error: expects a fraction in [0,1] (use 0.80 for 80%)
version: 1
platform: kalshi
strategy: custom
strategy_name: Rain odds written as a percent
market:
  series_ticker: KXHIGHCHI
edge:
  chi:
    provider: nws
    station: KMDW
    fields: [forecast_high_f, precip_prob]
risk:
  max_position: 1
  price_floor: 0.05
  price_ceiling: 0.80
loop:
  interval: 60
rules:
  - name: exit_on_rain_risk
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: edge.chi.precip_prob, op: ">", value: 0.60}
    action: sell_all
  - name: enter_on_dry_forecast
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: edge.chi.forecast_high_f, op: ">=", value: 80}
        - {field: edge.chi.precip_prob, op: "<", value: 40}
    action: buy_yes
    size: 1

Comparing two fields

value_field compares a field with another field on the same tick, for example edge.btc.macd_1m against edge.btc.macd_signal_1m, or edge.eth.change_24h against edge.btc.change_24h from a second alias.

• Studio does not check that both sides use the same units or timeframe. Comparing edge.btc.price (dollars) with the contract price (0 to 1), or macd_1m with macd_signal_5m, saves fine but means little.
• The 0-to-1 range check does not apply to value_field comparisons.
• There is no crossover operator. macd_1m > macd_signal_1m tests the current relationship on every tick, not a one-time cross.

Text fields

Four fields hold text rather than numbers: NWS precip_type and alert_severity, and calendar next_event_type and previous_event_type. A rule can test one for equality with a value it can take:

• Use == or !=. Text can't be ordered, so <, >, <= and >= fail with is a text field; use == or !=.
• Write one of the listed values. Quotes are optional: value: warning and value: "warning" are the same. Values are case-sensitive, so Warning or fomc fails with is not one of, and a number fails with is a text field; value must be one of.
• No value_field. A text field can't be compared with another field, on either side.

Text conditions work live and in backtests.

version: 1
platform: kalshi
strategy: custom
strategy_name: Exit on a weather warning
market:
  series_ticker: KXHIGHCHI
edge:
  chi:
    provider: nws
    station: KMDW
    fields: [forecast_high_f, alert_severity]
risk:
  max_position: 1
  price_floor: 0.05
  price_ceiling: 0.80
loop:
  interval: 60
rules:
  - name: exit_on_warning
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: edge.chi.alert_severity, op: "==", value: warning}
    action: sell_all
  - name: enter_on_warm_forecast
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: edge.chi.forecast_high_f, op: ">=", value: 80}
        - {field: edge.chi.alert_severity, op: "!=", value: warning}
    action: buy_yes
    size: 1

Text has no order, so "at least a watch" has to list the values:

# Rejected: text fields can't be compared with >=; list the values with == in an any rule instead
# error: edge.chi.alert_severity is a text field; use == or !=
version: 1
platform: kalshi
strategy: custom
strategy_name: Ordering a text field
market:
  series_ticker: KXHIGHCHI
edge:
  chi:
    provider: nws
    station: KMDW
    fields: [forecast_high_f, alert_severity]
risk:
  max_position: 1
  price_floor: 0.05
  price_ceiling: 0.80
loop:
  interval: 60
rules:
  - name: exit_on_watch_or_worse
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: edge.chi.alert_severity, op: ">=", value: watch}
    action: sell_all
  - name: enter_on_warm_forecast
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: edge.chi.forecast_high_f, op: ">=", value: 80}
    action: buy_yes
    size: 1

Unavailable values

A healthy alias can still hold individual values that are unavailable for a moment: a Coinbase candle is late, an NWS forecast lookup fails, a station does not report humidity. A condition that reads an unavailable value is false for every operator, including !=, live and in backtests. That holds on either side of a value_field comparison.

The condition fails, so an all rule does not match, while an any rule can still match through its other conditions. Later rules still run.