Next Candle Trigger

The next_candle trigger fires when a candle closes at the specified timeframe. It introduces a scheduling element — instead of reacting immediately, the action waits for a candle boundary.

Use it for:

  • Scheduled accumulation: buy on every 4-hour candle close
  • Signal confirmation: wait for the current candle to close before acting on other triggers
  • Time-paced execution: space out actions by candle intervals

TOML Syntax

[[actions.triggers]]
type = "next_candle"
timeframe = "4h"        # Optional: candle size (default: 1m)
max_count = 5           # Optional: max fires per position

Parameters

ParameterTypeRequiredDefaultDescription
typestringYes—Must be "next_candle"
timeframestringNo"1m"Candle size to wait for
max_countintegerNounlimitedMaximum times this trigger can fire per position

How It Works

The engine evaluates on every 1-minute candle. When the current tick aligns with a candle boundary for the specified timeframe, the trigger fires.

For example, with timeframe = "4h":

  • The trigger fires on every candle that falls on a 4-hour boundary (every 240th 1-minute candle)
  • Between boundaries, the trigger evaluates to false
graph TD
    A["Every 1m candle"] --> B{"On timeframe<br/>boundary?"}
    B -->|Yes| C["Trigger fires"]
    B -->|No| D["No action"]

When no timeframe is specified, the trigger fires on every 1-minute candle — effectively on every evaluation tick.

Valid Timeframes

TimeframeFires Every
"1m"Every candle (every evaluation)
"5m"Every 5 minutes
"15m"Every 15 minutes
"1h"Every hour
"4h"Every 4 hours
"1d"Every day

Examples

Scheduled Accumulation: Buy Every 4 Hours

[[actions]]
type = "buy"
amount = "25 USDC"
average_price = true

[[actions.triggers]]
type = "next_candle"
timeframe = "4h"
max_count = 5

This buys $25 every 4 hours, up to 5 times per position. Total additional investment: $125.

Signal Confirmation: RSI + Wait for Candle Close

When combined with other triggers (AND logic), next_candle acts as a "wait for confirmation" gate:

[[actions]]
type = "open_long"
amount = "100 USDC"

# Signal: RSI oversold on 1h candles
[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "30"
timeframe = "1h"

# Confirmation: wait for 1h candle to close
[[actions.triggers]]
type = "next_candle"
timeframe = "1h"

Both triggers must be true simultaneously. The action only fires when the hourly candle closes AND RSI is below 30 at that moment.

EMA Crossover with Candle Confirmation

[[actions]]
type = "open_long"
amount = "100 USDC"

# EMA fast crosses above EMA slow
[[actions.triggers]]
indicator = "ema_9"
operator = "cross_above"
target = "ema_21"
timeframe = "1h"

# Wait for hourly candle close
[[actions.triggers]]
type = "next_candle"
timeframe = "1h"

Daily DCA (Buy Every Day)

[[actions]]
type = "buy"
amount = "50 USDC"
average_price = true

[[actions.triggers]]
type = "next_candle"
timeframe = "1d"

Tips

Tip

Using next_candle with the same timeframe as your technical indicators makes backtest results more realistic. In live trading, you cannot act on a candle that has not closed yet — next_candle enforces that discipline.

Tip

max_count is essential for accumulation patterns. Without it, a next_candle trigger on "4h" would keep buying every 4 hours indefinitely. Set max_count to limit total accumulation per position.

Note

All triggers in an action use AND logic. When next_candle is combined with other triggers, both must be true at the same moment — the candle boundary must coincide with the other conditions being met. If RSI dips below 30 mid-candle but recovers before the candle close, the combined trigger does not fire.

TriggerWhat It Measures
Time in PositionDuration-based exit (time since entry)
Consecutive CandlesStreaks of red/green candles
Price ChangeGlobal price movement over time