Position Price Change Trigger

The pos_price_change trigger fires based on the price change relative to your open position's average entry price. It only activates when you have an open position. Use it for take-profit and stop-loss logic.

Note

For market-wide price movement (no position required), see Price Change instead. pos_price_change watches your P&L; price_change watches the market.

TOML Syntax

[[actions.triggers]]
type = "pos_price_change"
value = "-2%"           # Required: ±N% from entry price
max_count = 1           # Optional: max fires per position

Parameters

Parameter	Type	Required	Default	Description
`type`	string	Yes	—	Must be `"pos_price_change"`
`value`	string	Yes	—	Percentage threshold from entry price in `"±N%"` format
`max_count`	integer	No	unlimited	Maximum times this trigger can fire per position

Warning

pos_price_change does not support the timeframe field. It always compares the current price to the position's entry price, regardless of candle size.

How It Works

The engine calculates the percentage change from the position's average entry price:

change_pct = (current_close - entry_price) / entry_price * 100

Positive value (e.g., "2%"): fires when the position is profitable by at least 2%
Negative value (e.g., "-2%"): fires when the position is losing by at least 2%

graph TD
    A["Current candle close"] --> C{Calculate % from entry}
    B["Position entry price<br/>(average if DCA'd)"] --> C
    C --> D{"change meets<br/>threshold?"}
    D -->|Yes| E["Trigger fires"]
    D -->|No| F["No action"]

Average Price with DCA

When average_price = true is set on buy actions, the entry price is recalculated as a weighted average after each DCA buy. This means the trigger threshold shifts with each additional purchase.

For example, if you enter at $100 and DCA at $96, your average entry becomes ~$98. A pos_price_change of "2%" now fires at ~$99.96 instead of $102.

The `value` Format

Value	Meaning
`"2%"`	Position is up at least 2% from entry
`"+5%"`	Position is up at least 5% from entry
`"-2%"`	Position is down at least 2% from entry
`"-4%"`	Position is down at least 4% from entry

Examples

Simple Take-Profit at +2%

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

[[actions.triggers]]
type = "pos_price_change"
value = "2%"

Simple Stop-Loss at -5%

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

[[actions.triggers]]
type = "pos_price_change"
value = "-5%"

Layered DCA: Buy More on Dips

A classic DCA pattern — buy more as the position drops, each level firing once:

# DCA Level 1: buy more at -2%
[[actions]]
type = "buy"
amount = "100 USDC"
average_price = true

[[actions.triggers]]
type = "pos_price_change"
value = "-2%"
max_count = 1

# DCA Level 2: buy more at -4%
[[actions]]
type = "buy"
amount = "200 USDC"
average_price = true

[[actions.triggers]]
type = "pos_price_change"
value = "-4%"
max_count = 1

# DCA Level 3: buy more at -6%
[[actions]]
type = "buy"
amount = "300 USDC"
average_price = true

[[actions.triggers]]
type = "pos_price_change"
value = "-6%"
max_count = 1

Tip

Always use max_count = 1 on DCA levels. Without it, the trigger fires repeatedly as price oscillates around the threshold, causing unintended double-buys.

Full Strategy: Entry + DCA + Take-Profit

[meta]
name = "Position Price DCA"
description = "RSI entry with layered DCA and profit target"
max_open_positions = 5

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

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

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

[[actions.triggers]]
type = "pos_price_change"
value = "-2%"
max_count = 1

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

[[actions.triggers]]
type = "pos_price_change"
value = "-4%"
max_count = 1

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

[[actions.triggers]]
type = "pos_price_change"
value = "2%"

Tips

Tip

pos_price_change is evaluated per-position in multi-position strategies. If you have max_open_positions = 5, each position independently tracks its own entry price and fires its own DCA/TP/SL triggers.

Warning

Remember that DCA changes the average entry price. After buying more at a lower price, your take-profit target shifts closer to the current price. This is by design — it's the whole point of averaging down.

Trigger	What It Measures
Price Change	Global market price movement (no position needed)
Trailing Stop	% drop from position's peak price
Trailing Take-Profit	Dynamic TP that follows price up, exits on retrace
Time in Position	Duration-based exit

Botmarley User Manual