Timeframes

Timeframes determine which candle interval is used to calculate an indicator's value. Botmarley supports multi-timeframe analysis, allowing you to combine signals from different time resolutions within a single strategy.

What Are Timeframes?

A timeframe defines the duration of each candle used for indicator calculation. A 1h candle aggregates 60 minutes of price action into a single open/high/low/close bar; a 1d candle aggregates an entire day.

Different timeframes reveal different aspects of the market:

Available Timeframes

Botmarley supports six timeframes:

• 1m -- 1-minute candles
• 5m -- 5-minute candles
• 15m -- 15-minute candles
• 1h -- 1-hour candles
• 4h -- 4-hour candles
• 1d -- 1-day (daily) candles

Default Timeframe

If you omit the timeframe field from a trigger, it defaults to the base candle timeframe (typically 1m). This means the indicator is calculated on 1-minute candles:

# No timeframe specified -- uses the default (1m)
[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "30"

To explicitly use a different timeframe, add the timeframe field:

# RSI calculated on 1-hour candles
[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "30"
timeframe = "1h"

How Multi-Timeframe Works

Botmarley always fetches and stores 1-minute candles as the base data. Higher timeframes are computed from 1-minute data by aggregating candles:

flowchart TD
    A["1m Candles<br/>(Source Data)"] --> B["5m Candles<br/>(5 x 1m aggregated)"]
    A --> C["15m Candles<br/>(15 x 1m aggregated)"]
    A --> D["1h Candles<br/>(60 x 1m aggregated)"]
    A --> E["4h Candles<br/>(240 x 1m aggregated)"]
    A --> F["1d Candles<br/>(1440 x 1m aggregated)"]

    B --> G["Calculate Indicators<br/>on 5m candles"]
    C --> H["Calculate Indicators<br/>on 15m candles"]
    D --> I["Calculate Indicators<br/>on 1h candles"]
    E --> J["Calculate Indicators<br/>on 4h candles"]
    F --> K["Calculate Indicators<br/>on 1d candles"]

    style A fill:#4a9eff,color:#fff

This means:

1. You do not need separate data downloads for each timeframe.
2. All timeframes are derived from the same underlying 1-minute data.
3. Indicators on higher timeframes use fewer data points but represent longer periods of market action.

Using Timeframes in Triggers

Single-Timeframe Strategy

Most simple strategies use a single timeframe (or the default):

[meta]
name = "Simple_RSI"

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

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = "<"
  target = "30"
  # No timeframe -- uses default 1m candles

Multi-Timeframe Strategy

The real power comes from combining multiple timeframes. A common pattern is to use a higher timeframe for trend direction and a lower timeframe for entry timing:

[meta]
name = "Multi_TF_Trend_Entry"
description = "Use 1h RSI for trend, 5m for entry timing"
max_open_positions = 2

# ENTRY: 1h RSI oversold + 5m StochRSI extremely oversold
[[actions]]
type = "open_long"
amount = "100 USDC"

  # Higher timeframe: confirms oversold on the 1h chart
  [[actions.triggers]]
  indicator = "rsi_14"
  operator = "<"
  target = "35"
  timeframe = "1h"

  # Lower timeframe: precise entry on the 5m chart
  [[actions.triggers]]
  indicator = "stoch_rsi_14"
  operator = "<"
  target = "10"
  timeframe = "5m"

# EXIT: +3% profit
[[actions]]
type = "sell"
amount = "100%"

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

Timeframe Mixing Within an Action

Within a single action, different triggers can use different timeframes. Since triggers are AND-combined, ALL must be true simultaneously:

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

  # Trigger 1: Daily uptrend confirmed
  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

  # Trigger 2: Hourly RSI oversold
  [[actions.triggers]]
  indicator = "rsi_14"
  operator = "<"
  target = "40"
  timeframe = "1h"

  # Trigger 3: 5-minute momentum dip
  [[actions.triggers]]
  indicator = "roc_10"
  operator = "<"
  target = "-3"
  timeframe = "5m"

This action fires only when ALL three conditions are true at the same time:

• The daily trend is bullish (SMA 50 above SMA 200)
• The hourly RSI shows an oversold condition
• The 5-minute momentum shows a sharp dip

Timeframes with Non-Technical Triggers

The timeframe field also works with price_change and next_candle triggers:

price_change with timeframe

A price change trigger with a timeframe evaluates the percentage change over that candle interval:

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

This triggers when price drops 3% within the 1-hour window.

next_candle with timeframe

A next_candle trigger with a timeframe waits for the next candle close on that specific interval:

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

This triggers on every 4-hour candle close.

Choosing the Right Timeframe

Here is a guide to help you select timeframes for different purposes: