Strategy TOML Reference

This is the complete reference for the Botmarley strategy TOML format. Every field, type, and valid value is documented here.

Structure Overview

[meta]
name = "Strategy Name"
description = "Optional description"
max_open_positions = 5

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

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

A strategy consists of:

[meta] — metadata and global settings
[[actions]] — one or more trading actions, each with triggers

`[meta]` Section

Field	Type	Required	Default	Description
`name`	String	Yes	—	Strategy name (1–255 characters, must be unique)
`description`	String	No	`""`	Human-readable description
`max_open_positions`	Integer	No	Unlimited	Maximum concurrent open positions (must be >= 1)

[meta]
name = "BTC_DCA_Conservative"
description = "RSI oversold entry with DCA on dips, trailing stop exit"
max_open_positions = 3

`[[actions]]` Section

Each action defines what to do and when (via triggers).

Field	Type	Required	Default	Description
`type`	String	Yes	—	Action type: `open_long`, `buy`, or `sell`
`amount`	String	Yes	—	Trade amount (see format below)
`average_price`	Boolean	No	`false`	Enable DCA averaging (`open_long` and `buy` only)

Action Types

Type	Purpose	Notes
`open_long`	Open a new long position	Initial entry
`buy`	Additional buy within position	DCA / averaging
`sell`	Exit position (full or partial)	Close trade

Amount Format

Currency amount:

amount = "100 USDC"
amount = "50.5 BTC"
amount = "200 USD"

Percentage:

amount = "50%"      # 50% of position
amount = "100%"     # Full exit

Warning

Negative amounts are rejected. Percentage must be between 0 and 100.

Triggers

Each action requires at least one trigger. All triggers within an action use AND logic — all must be true simultaneously for the action to execute.

Three Trigger Categories

Technical Indicator — compare indicator values
Price Change — react to price movements
Next Candle — delay execution

Technical Indicator Triggers

Compare a technical indicator against a target value or another indicator.

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

Field	Type	Required	Description
`indicator`	String	Yes	Indicator name with period (e.g., `rsi_14`, `ema_20`)
`operator`	String	Yes	Comparison: `>`, `<`, `=`, `cross_above`, `cross_below`
`target`	String	Yes	Numeric value or another indicator
`timeframe`	String	No	Evaluation timeframe (`1m`, `5m`, `15m`, `1h`, `4h`, `1d`)
`max_count`	Integer	No	Maximum times this trigger fires per position

Operators

Operator	Meaning
`>`	Indicator is greater than target
`<`	Indicator is less than target
`=`	Indicator equals target
`cross_above`	Indicator crosses above target (was below, now above)
`cross_below`	Indicator crosses below target (was above, now below)

Target Values

Numeric:

target = "30"       # RSI value
target = "67500.0"  # Price level

Another indicator:

target = "sma_50"   # Compare EMA to SMA
target = "bb_upper" # Compare to Bollinger upper band

Price Change Triggers

React to price movements relative to position entry or market-wide.

`pos_price_change`

Fires when position P&L reaches a threshold.

[[actions.triggers]]
type = "pos_price_change"
value = "+3%"       # Take profit at +3%
max_count = 1

`pos_price_change_follow`

Trailing trigger — tracks the peak price since entry, fires on retracement.

[[actions.triggers]]
type = "pos_price_change_follow"
value = "+3.0%"
tolerance = "-0.2%"

`price_change`

Market-wide price change (not position-relative).

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

`trailing_stop`

Follows price up, triggers on drawdown from peak.

[[actions.triggers]]
type = "trailing_stop"
value = "-3%"

Price Change Fields

Field	Type	Required	Description
`type`	String	Yes	Trigger type (see variants above)
`value`	String	Yes	Percentage threshold (e.g., `"+3%"`, `"-5%"`)
`tolerance`	String	No	Retrace tolerance (`pos_price_change_follow` only)
`timeframe`	String	No	For `price_change` and `consecutive_candles`
`max_count`	Integer	No	Maximum fires per position

Next Candle Trigger

Delays action execution until the next candle closes.

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

Field	Type	Required	Description
`type`	String	Yes	Must be `"next_candle"`
`timeframe`	String	No	Candle timeframe to wait for
`max_count`	Integer	No	Maximum fires per position

Indicators Reference

Format	Name	Notes
`rsi_{period}`	Relative Strength Index	e.g., `rsi_14`
`sma_{period}`	Simple Moving Average	e.g., `sma_50`
`ema_{period}`	Exponential Moving Average	e.g., `ema_20`
`bb_lower`, `bb_upper`, `bb_mid`	Bollinger Bands	Band component
`macd_line`, `macd_signal`, `macd_hist`	MACD	Component
`stoch_rsi_{period}`	Stochastic RSI	e.g., `stoch_rsi_14`
`roc_{period}`	Rate of Change	e.g., `roc_10`
`atr_{period}`	Average True Range	e.g., `atr_14`
`obv`	On Balance Volume	No parameters
`obv_sma_{period}`	OBV with SMA	e.g., `obv_sma_20`
`vol_sma_{period}`	Volume SMA	e.g., `vol_sma_20`
`ttm_trend`	TTM Trend	Alternative: `ttmtrend`
`price`	Current Price	Special: market price

Period range: 1–200 (inclusive). Values outside this range cause a validation error.

Valid Timeframes

Value	Meaning
`1m`	1 minute
`5m`	5 minutes
`15m`	15 minutes
`1h`	1 hour
`4h`	4 hours
`1d`	1 day

Complete Example

[meta]
name = "Multi_Timeframe_DCA_v1"
description = "RSI oversold entry on 1h, DCA on dips, trailing stop exit"
max_open_positions = 3

# ENTRY: RSI < 30 on 1h timeframe
[[actions]]
type = "open_long"
amount = "100 USDC"
average_price = false

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

# DCA: Buy more on -2% drop
[[actions]]
type = "buy"
amount = "100 USDC"
average_price = true

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

# DCA: Buy more on -4% drop
[[actions]]
type = "buy"
amount = "200 USDC"
average_price = true

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

# TAKE PROFIT: +3% from average entry
[[actions]]
type = "sell"
amount = "100%"

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

# STOP LOSS: -5% from average entry
[[actions]]
type = "sell"
amount = "100%"

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

Validation Errors

Error	Cause
`REQUIRED`	Missing required field
`INVALID_ACTION_TYPE`	Type not `open_long`, `buy`, or `sell`
`INVALID_AMOUNT_FORMAT`	Doesn't match `"NUMBER CURRENCY"` or `"NUMBER%"`
`INVALID_OPERATOR`	Unknown operator
`INVALID_INDICATOR`	Unknown indicator format
`INVALID_PERIOD`	Non-numeric period
`INVALID_PERIOD_RANGE`	Period outside 1–200
`INVALID_BAND_TYPE`	Bollinger band not `lower`/`upper`/`mid`
`INVALID_MACD_COMPONENT`	MACD component not `line`/`signal`/`hist`
`INVALID_TIMEFRAME`	Timeframe not in valid list

Botmarley User Manual