Coinbase Edge Fields

A coinbase alias reads public Coinbase Exchange market data for one product (symbol: BTC-USD). All 39 fields are numbers. Prices are in the product's quote currency; changes and _pct distances are fractions.

This page lists every field by group, with its unit and backtest support, then explains the candles setting and when candle-based fields go unavailable. Custom strategies on Kalshi and Polymarket US 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. Kalshi Perps reads the six MACD fields by name instead; see Kalshi Perps.

Price and quote fields

These come from Coinbase's 24-hour stats and top of book. They are the only fields that allow a 1s refresh.

Historical backtests make each candle's final values available only after that candle closes. Between closes, they reuse the last available value. Live fields that include a forming candle can change before its close, so those intraminute signals cannot be reconstructed from historical candles. To make live and backtest values line up, see Live or closed candles. A 10-second strategy loop does not turn one-minute Coinbase history into 10-second price history.

Change windows

Each change compares the latest close, including the candle still forming, with an earlier close. All are fractions (0.004 = +0.4%).

High and low windows

Highest high or lowest low over recent candles, in the quote currency, including the candle still forming. With less history, fewer candles are used.

Moving averages

Averages of candle closes, in the quote currency.

EMA distance

Each EMA has two ready-made distance fields that measure how far price sits from it. Positive means spot is above the average, negative below.

A distance is unavailable whenever its EMA or price is. The _pct versions are handy across products, because a 0.2% band means the same on BTC and ETH, while a dollar band does not. All six are backtestable. Backtests use the latest completed one-minute close as spot for every distance field, including ema_26_15m distances.

To compare an EMA with a Kalshi strike rather than with spot, use the raw EMA field in a derived metric. See Recipe: spot and EMA vs. strike.

VWAP and velocity

MACD

MACD compares a fast and a slow exponential average of completed candle closes. Each timeframe has three fields, all in signed quote currency.

Each timeframe needs at least 34 completed candles (26 for the slow average plus 9 for the signal, minus the one they share), and every candle in the roughly 250 the Bot downloads must be back-to-back. One missing candle leaves all three fields unavailable until it is more than 250 candles old: about 4 hours for the _1m fields, about 21 hours for _5m. All six fields are backtestable and use completed candles only, in live and historical runs alike, unless the alias sets candles: live.

MACD values are in the product's quote currency (dollars for -USD pairs), not percent, so their size scales with the product's price. A histogram threshold that fits BTC means something very different on ETH or SOL.

Live or closed candles

By default, fields read candles in two different ways. MACD and ema_26_15m (with its distances) use completed candles only. Every other candle-based field also reads the candle still forming on Coinbase. Backtests use completed candles for all of them. The optional candles key on a Coinbase alias makes every candle-based field read candles the same way:

price, bid, ask, spread, spread_bps, change_24h and volume_24h are not built from candles and do not change with the setting.

Choose live when a signal should count before its candle closes, for example acting on a 5-minute MACD turn as it happens. The cost:

• Earlier signals can reverse. A MACD that turns positive halfway through a candle can turn back before the candle closes, so expect more false signals and more trades than with completed candles.
• A short gap at each close. Right after a candle closes, every field built from that candle size is unavailable for a few seconds, until Coinbase publishes the completed candle.
• Backtests read once a minute. At each minute mark the backtest rebuilds the forming 5-minute, 15-minute and hourly candles exactly from completed one-minute candles. A one-minute candle has only just opened at that moment, so one-minute fields cannot show a signal firing inside a minute, which a live Bot can act on. The result says so: "1m live fields are read once a minute in backtests; a live Bot also sees moves inside the minute." velocity_1m would always read 0 at those moments, so a live alias that reads it cannot be backtested; backtest that strategy with candles: closed instead.

Choose closed to align the candle selection with the backtest, at the cost of reacting later. This does not guarantee the same signals or fills: live refresh timing, available history, prices and execution can differ.

version: 1
platform: kalshi
strategy: custom
strategy_name: BTC 15-minute MACD on the forming 5-minute candle
market:
  series_ticker: KXBTC15M
edge:
  btc:
    provider: coinbase
    symbol: BTC-USD
    fields: [macd_5m, macd_signal_5m, macd_histogram_5m]
    refresh: 5s
    candles: live
risk:
  max_position: 2
  price_floor: 0.10
  price_ceiling: 0.90
loop:
  interval: 10
rules:
  - name: exit_when_momentum_turns_down
    when:
      all:
        - {field: yes_position_size, op: ">", value: 0}
        - {field: edge.btc.macd_histogram_5m, op: "<", value: 0}
    action: sell_yes
  - name: buy_yes_on_bullish_momentum
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: time_to_expiry, op: ">=", value: "5m"}
        - {field: edge.btc.macd_5m, op: ">", value_field: edge.btc.macd_signal_5m}
        - {field: yes_best_ask, op: "<=", value: 0.60}
    action: buy_yes
    size: 1

candles is only valid on a coinbase alias, and only as live or closed:

# Rejected: candles on an NWS alias
# error: candles is only available for provider coinbase
version: 1
platform: kalshi
strategy: custom
market:
  series_ticker: KXHIGHNY
edge:
  weather:
    provider: nws
    station: KNYC
    fields: [current_temp_f]
    candles: live
risk:
  max_position: 2
  price_floor: 0.10
  price_ceiling: 0.90
loop:
  interval: 30
rules:
  - name: buy_when_warm
    when:
      all:
        - {field: edge.weather.current_temp_f, op: ">", value: 80}
    action: buy_yes
    size: 1

Changing candles changes the Bot's code. A running Bot keeps reading candles the old way until you redeploy it.

Candle history and freshness

If remote edge-history preparation reaches its deadline, it resumes once automatically when enough preparation time remains. Completed Coinbase chunks are retained, so the resume can reuse that progress. If preparation still fails, the run stops without a completed result and does not retry again automatically. Choose Retry history preparation to retry the same strategy later; if it keeps failing, contact support with the job ID. This is a history preparation failure, so the card does not offer Fix with AI to change the strategy's rules.

For live Bots, there is no warm-up wait. On every refresh the Bot downloads about the last 250 candles of each size (1 minute, 5 minutes, 15 minutes, 1 hour), so indicators have values from the first fetch after you deploy. A field is unavailable only when:

• Coinbase's history is too short, for example a newly listed product.
• The history has gaps. Coinbase omits candles for intervals with no trades, which is common on thin products. MACD and ema_26_15m need every downloaded candle to be back-to-back, so a single gap leaves them unavailable for hours (see MACD).
• The latest candle is late or missing. If the most recently completed candle is not in Coinbase's data within 10 seconds of its close, every field built from that candle size is unavailable for that refresh. Coinbase publishes no candle for an interval with no trades, so on thin products a quiet minute has the same effect as a late candle. The alias itself stays healthy.