Price Change Trigger

The price_change trigger fires when the market price has moved by a specified percentage over a lookback window. It compares the current candle's close to a candle from N minutes ago. This trigger is global — it does not require an open position.

Use it for momentum entries ("buy after a 5% dip in the last 4 hours") or breakout detection ("price is up 3% over the last day").

TOML Syntax

[[actions.triggers]]
type = "price_change"
value = "-5%"           # Required: ±N% threshold
timeframe = "1h"        # Optional: candle size (default: 1m)
lookback = 24           # Optional: number of candles to look back (default: 1)
max_value = "-15%"      # Optional: maximum allowed change (range cap)
max_count = 1           # Optional: max fires per position

Parameters

How It Works

The engine computes a total lookback in 1-minute candles:

total_lookback = lookback × timeframe_in_minutes

When lookback is omitted, it defaults to 1 — meaning the window equals exactly one timeframe period. This is backwards-compatible with the original behavior.

The engine then calculates:

change_pct = (current_close - close_N_candles_ago) / close_N_candles_ago × 100

• Negative value (e.g., "-5%"): trigger fires when change_pct <= -5.0
• Positive value (e.g., "+3%"): trigger fires when change_pct >= 3.0

graph TD
    A["Current candle close"] --> C{"Calculate % change<br/>over lookback window"}
    B["Close from N candles ago<br/>(N = lookback × timeframe)"] --> C
    C --> D{"change meets<br/>threshold?"}
    D -->|Yes| E{"Within max_value<br/>range?"}
    D -->|No| F["No action"]
    E -->|Yes or no max_value| G["Trigger fires"]
    E -->|No — too extreme| F

The value Format

The value field uses a "±N%" string format:

The lookback Parameter

The lookback parameter controls how many timeframe-sized candles to look back. Without it, the engine looks back exactly one timeframe period.

# Without lookback: compares to 1 hour ago
type = "price_change"
value = "-5%"
timeframe = "1h"

# With lookback: compares to 24 hours ago (24 × 1h)
type = "price_change"
value = "-5%"
timeframe = "1h"
lookback = 24

This is useful when you want a long lookback window but the timeframe options don't cover it directly. For example, "did the price drop 10% over the last 3 days?" can be expressed as:

type = "price_change"
value = "-10%"
timeframe = "1d"
lookback = 3

The max_value Parameter (Range Capping)

max_value caps how extreme the price change can be for the trigger to fire. It creates a range instead of a simple threshold — useful for avoiding "falling knife" entries.

# Fire when price drops between 5% and 15%
# (skip if it dropped MORE than 15% — that's a falling knife)
type = "price_change"
value = "-5%"
max_value = "-15%"
timeframe = "4h"

How it works:

• For negative thresholds: value is the minimum drop, max_value is the maximum drop
• For positive thresholds: value is the minimum rise, max_value is the maximum rise

Valid Timeframes

The timeframe field accepts: 1m, 5m, 15m, 1h, 4h, 1d.

When omitted, the trigger uses 1m — meaning it compares the current close to the close 1 minute ago. This is rarely useful on its own. In practice, you almost always want a larger timeframe.

Examples

Buy After a 5% Dip Over 4 Hours

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

[[actions.triggers]]
type = "price_change"
value = "-5%"
timeframe = "4h"

Buy After a 10% Dip Over 24 Hours (With Lookback)

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

[[actions.triggers]]
type = "price_change"
value = "-10%"
timeframe = "1h"
lookback = 24

Sell After a 3% Rise Over 1 Hour

[[actions]]
type = "sell"
amount = "100%"

[[actions.triggers]]
type = "price_change"
value = "+3%"
timeframe = "1h"

DCA Entry on Hourly Dip (Fire Once)

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

[[actions.triggers]]
type = "price_change"
value = "-3%"
timeframe = "1h"
max_count = 1

Buy the Dip — But Not the Crash (Range Cap)

# Enter on 5-15% dips over 4 hours, skip if it's a free fall
[[actions]]
type = "open_long"
amount = "100 USDC"

[[actions.triggers]]
type = "price_change"
value = "-5%"
max_value = "-15%"
timeframe = "4h"

Combine with Technical Indicator

# Buy when price dropped 3% in the last hour AND RSI is oversold
[[actions]]
type = "open_long"
amount = "100 USDC"

[[actions.triggers]]
type = "price_change"
value = "-3%"
timeframe = "1h"

[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "30"
timeframe = "1h"

Tips

Related Triggers