Welcome to Botmarley

Botmarley is a self-hosted, sovereign cryptocurrency trading bot built in Rust. It runs entirely on your own hardware, giving you full control over your trading strategies, API keys, and market data. No cloud services, no third-party access to your funds, no monthly subscriptions.

You install it, you run it, you own it.

What Botmarley Does

At its core, Botmarley automates cryptocurrency trading based on rules you define. You write a strategy that says things like "buy BTC when RSI drops below 30" or "sell 50% of my position when price rises 5% from entry," and Botmarley executes those rules 24/7 without you needing to watch charts.

Here is how the pieces fit together:

graph LR
    Browser["Browser<br/>(Web Interface)"]
    Bot["Botmarley<br/>(Trading Bot)"]
    PG["PostgreSQL<br/>(Your Data)"]
    Exchange["Exchange API<br/>(Kraken / Binance)"]

    Browser <-->|"http://localhost:3000"| Bot
    Bot <-->|"State & Logs"| PG
    Bot <-->|"Market Data & Orders"| Exchange

• Browser -- You interact with Botmarley through a web interface at http://localhost:3000. Pages update in real time as your bot trades.
• Botmarley -- A blazing-fast trading engine built in Rust with Tokio and Axum. Handles strategy execution, order placement, data fetching, and serves a reactive web interface powered by HTMX.
• PostgreSQL -- Stores your accounts, trading sessions, backtest results, PnL history, activity logs, and configuration.
• Exchange API -- Botmarley connects to Kraken and Binance to fetch market data and place orders on your behalf.

Key Features

Who This Manual Is For

This manual is for cryptocurrency traders -- both beginners exploring automated trading for the first time and experienced traders who want full control over their bot.

• If you are new to trading bots, start with the Getting Started section. It walks you through installation, your first run, and a tour of every page.
• If you want to jump straight into building strategies, head to Strategies.
• If you are deploying Botmarley on a server, see Deployment.

How to Use This Manual

The sidebar on the left organizes content into sections:

• Getting Started -- Installation, first run walkthrough, and a tour of the interface.
• Features -- Deep dives into each major feature: Dashboard, Accounts, Strategies, Backtesting, Live Trading, and Market Data.
• System -- Settings, task queue, activity logs, authentication, and Telegram integration.
• Deployment -- Running Botmarley locally and in production environments.
• Reference -- Strategy TOML specification, indicator reference, and glossary.

Use the search bar at the top to find specific topics. Each page is self-contained, so you can read them in any order.

Installation

This page walks you through installing Botmarley on your machine. By the end, you will have the bot running and accessible in your browser.

What You Need Before Starting

Botmarley is distributed as a pre-built binary. The only external dependency is PostgreSQL for data storage.

The easiest way to run PostgreSQL is with Docker:

Installing Docker

If you do not have Docker installed:

macOS:

brew install --cask docker

Ubuntu/Debian Linux:

sudo apt update
sudo apt install docker.io docker-compose-v2

Windows:

Download and install Docker Desktop for Windows.

Download Botmarley

Download the latest release for your platform:

Download Latest Release

Extract the Archive

Linux / macOS:

# Replace with your downloaded archive name
tar -xzf botmarley-arm64.tar.gz
cd botmarley

Windows (PowerShell):

tar -xzf botmarley-windows-amd64.tar.gz
cd botmarley

This creates the following files:

Initialize Botmarley

Before running for the first time, initialize the data directory:

Linux / macOS:

./server init

Windows (PowerShell):

.\server.exe init

This creates ~/.botmarley/ (or %USERPROFILE%\.botmarley\ on Windows) with:

• Default settings.toml configuration
• Built-in trading strategies
• Example strategies for learning
• Data directories for market history

Start PostgreSQL

Botmarley stores all its state in PostgreSQL. The quickest way to get started is with Docker:

docker run -d \
  --name botmarley-db \
  -e POSTGRES_USER=botmarley \
  -e POSTGRES_PASSWORD=botmarley_dev \
  -e POSTGRES_DB=botmarley \
  -p 5432:5432 \
  postgres:17

Verify the database is running:

docker ps | grep botmarley-db

Run Botmarley

Linux / macOS:

./server

Windows (PowerShell):

.\server.exe

Botmarley initializes the database schema on first run and starts listening on port 3000.

Verify the Installation

Open your browser and navigate to:

http://localhost:3000

You will see the license setup page. Follow the instructions in First Run to configure your API key and start trading.

Stopping Botmarley

To stop the server, press Ctrl+C in the terminal where it is running.

To stop PostgreSQL:

docker stop botmarley-db

Next Steps

With Botmarley running, continue to First Run for a guided walkthrough of the initial setup — including license activation and exchange configuration.

First Run

You have Botmarley installed and running at http://localhost:3000. This page walks you through the essential first-time setup: configuring settings, adding an account, downloading market data, creating a strategy, and running your first backtest.

By the end, you will have tested a strategy against historical data without risking any real money.

graph LR
    A["1. Settings"] --> B["2. Add Account"]
    B --> C["3. Download Data"]
    C --> D["4. Create Strategy"]
    D --> E["5. Run Backtest"]

When you open http://localhost:3000 for the first time, you will see the main dashboard. This is your starting point for everything that follows.

License Setup

Botmarley requires an API key to unlock all features.

1. Visit lipinski.work to request your API key
2. Open Settings in the Botmarley web interface
3. Enter your API key in the License section
4. Click Save

Botmarley validates your key immediately. Once validated, all features become available.

Without a valid key, only the Settings page is accessible.

Step 1: Configure Settings

Navigate to Settings in the sidebar (or go to http://localhost:3000/settings).

The Settings page has several sections. For your first run, focus on these:

Trading Pairs

In the Trading card, set your Active Pairs. These are the cryptocurrency pairs you want to trade and download data for. Enter them comma-separated in the format BASE/QUOTE:

BTC/USDC, ETH/USDC

Data Storage

The Storage Path tells Botmarley where to save Arrow files (historical candle data). The default path works for most setups. If you want to store data on a different drive, change it here.

History Start Date

Set History Start Date to control how far back Botmarley fetches historical data. A reasonable starting point is 6-12 months ago. The more history you have, the more thorough your backtests will be, but downloading takes longer.

Save

Click Save Settings at the bottom. A green success banner confirms your settings were saved.

Step 2: Add Your First Account

Navigate to Accounts in the sidebar.

Click the Add Account button. A modal dialog appears with these fields:

A paper account simulates trades without connecting to any exchange. No API keys are needed. This is the safest way to learn how Botmarley works.

Click Create to save the account.

When You Are Ready for Live Trading

When you eventually want to trade with real funds, create a new account with:

• Account Type: Kraken or Binance
• API Key and API Secret: Generated from your exchange account (see Managing Accounts for step-by-step instructions for each exchange)

Step 3: Download Market Data

Navigate to History in the sidebar.

Before you can backtest, Botmarley needs historical candle data. The History Sync page lets you download it from Kraken or Binance.

1. Select an exchange (Kraken or Binance) in the dropdown.
2. Your active pairs (configured in Settings) appear as checkboxes. Make sure the pairs you want are checked.
3. Click Start Sync.

Botmarley downloads 1-minute candles from the selected exchange and stores them in Apache Arrow format. This runs as a background task -- you can watch progress on the same page, which auto-refreshes every 2 seconds.

Once the sync completes, navigate to Data in the sidebar to verify. You should see entries in the table showing your pairs, the number of records, date range, and file size.

Step 4: Create Your First Strategy

Navigate to Strategies in the sidebar and click + New Strategy.

The Strategy Editor opens with two modes:

• Visual (default) -- A form-based builder with dropdowns and input fields.
• TOML -- A raw text editor for the strategy configuration file.

For your first strategy, use the Visual mode. Here is a simple RSI-based strategy to start with:

Strategy Info

• Name: RSI Bounce
• Description: Buy when RSI is oversold, sell when overbought
• Max Open Positions: 1

Action 1: Open Long

Click + Add Action, then configure:

• Action Type: Open Long
• Amount: 100 USDC

Now add a trigger: Click + Trigger within this action.

• Type: Technical Indicator
• Indicator: RSI 14
• Operator: Less Than (<)
• Target: 30
• Timeframe: 1h

This means: "Open a long position worth 100 USDC when the 1-hour RSI(14) drops below 30."

Action 2: Sell

Click + Add Action again:

• Action Type: Sell
• Amount: 100%

Add a trigger:

• Type: Technical Indicator
• Indicator: RSI 14
• Operator: Greater Than (>)
• Target: 70
• Timeframe: 1h

This means: "Sell the entire position when the 1-hour RSI(14) rises above 70."

Validate and Save

As you build, the right panel shows a live TOML Preview of your strategy and a validation status. It should show a green "Valid strategy: 2 action(s)" banner.

The generated TOML looks like this:

[meta]
name = "RSI Bounce"
description = "Buy when RSI is oversold, sell when overbought"
max_open_positions = 1

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

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

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

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = ">"
  target = "70"
  timeframe = "1h"

Click Save Strategy to store it.

Step 5: Run Your First Backtest

Go back to the Strategies list. You should see "RSI Bounce" in the table. Click the Backtest button on its row.

A modal dialog appears asking for:

Click Run Backtest. Botmarley runs the strategy against the historical data and redirects you to the Backtests page.

Find your backtest in the list and click View to see the results:

• PnL -- Total profit or loss in dollars and as a percentage.
• Trade count -- How many buy/sell actions were executed.
• Win rate -- Percentage of profitable trades.
• Chart -- A candlestick chart with trade markers showing where each action occurred.
• Actions table -- A detailed log of every trade with timestamps, prices, and amounts.

What to Do Next

You now understand the core workflow: settings, accounts, data, strategies, backtesting. From here:

• Quick Tour -- Walk through every page in the interface.
• Strategies -- Learn about all the trigger types, indicators, and strategy patterns.
• Backtesting -- Understand backtest results in depth and run bulk backtests.
• Live Trading -- When you are ready, start a live session with a paper, Kraken, or Binance account.

Quick Tour

This quick tour walks you through every major section of Botmarley so you know where everything lives.

Navigation

The sidebar on the left provides access to all sections:

Dashboard

The dashboard (/) shows a summary of your portfolio value and any active trading sessions. It's your home base for monitoring at a glance.

Accounts

Navigate to Accounts to connect your Kraken or Binance exchange account or create a Paper (simulated) account for testing. Each account stores API credentials securely and can be verified with a balance check.

Strategies

The Strategies section lets you create, edit, and manage trading strategies defined in TOML format. Each strategy consists of:

• Actions — buy/sell operations, each with their own trigger conditions
• Indicators — technical analysis tools (SMA, EMA, RSI, Bollinger Bands, MACD, OBV, OBV-SMA, TTM Trend, StochRSI, ROC, ATR, Vol SMA, Price)
• Position management — DCA settings, max open positions, allocation percentages

Backtesting

Before going live, test your strategies against historical data in the Backtesting section. You'll see:

• Profit/Loss (absolute and percentage)
• Win rate and trade count
• Maximum drawdown
• An interactive chart showing entries and exits

Live Trading

When you're confident in a strategy, start a Trading Session. Select an account, a strategy, and a trading pair, then hit Start. You can:

• Pause — temporarily halt execution
• Resume — continue from where you paused
• Stop — end the session permanently

Real-time updates stream via SSE (Server-Sent Events), so the page updates automatically.

Market Data

The Data section lets you download historical candle data from Kraken or Binance. Data is stored in Apache Arrow format for fast access. You can browse downloaded datasets and run indicator calculations.

Settings

Configure application-wide settings including:

• Server host and port
• Telegram bot notifications
• Password protection
• Data storage paths

What's Next?

Now that you know the layout, dive into the specific sections that interest you most. We recommend starting with Accounts to set up your first connection, then exploring Strategies to build your first trading strategy.

Dashboard

The Dashboard is your home page — the first thing you see when you open Botmarley at http://localhost:3000.

What You'll See

The dashboard provides a high-level overview of your trading operation:

Portfolio Summary

If you have accounts connected and portfolio sync running, you'll see:

• Total Portfolio Value (USD) — combined value across all accounts
• Total Portfolio Value (BTC) — your holdings measured in Bitcoin
• BTC Price — current Bitcoin price in USD
• Last Sync — when portfolio data was last refreshed

Active Trading Sessions

Any currently running or paused trading sessions appear here with:

• Session name and trading pair
• Current status (Running, Paused)
• Profit/Loss so far
• Number of actions executed

Empty State

If this is your first time using Botmarley, the dashboard will show helpful links to get started:

1. Add an Account — connect to Kraken or create a Paper account
2. Create a Strategy — build your first trading strategy
3. Download Data — fetch historical market data for backtesting

Auto-Refresh

The dashboard uses HTMX polling to stay up-to-date. Active session stats refresh automatically without needing to reload the page.

Navigation

From the dashboard, you can quickly navigate to any section using the sidebar. The most common workflows from here:

graph LR
    D[Dashboard] --> A[Accounts]
    D --> S[Strategies]
    D --> T[Trading]
    D --> B[Backtesting]
    A --> T
    S --> B
    B --> T

This flow represents the typical journey: set up accounts, create strategies, backtest them, then go live.

Accounts

Accounts are the bridge between Botmarley and the outside world. Every action the bot takes -- whether it is placing a live trade on an exchange or simulating one locally -- happens through an account. Before you can backtest a strategy, run a live session, or track a portfolio, you need at least one account configured.

What Is an Account?

An account in Botmarley represents a single source of funds. It stores:

• Name and description -- a human-readable label you choose (e.g. "My Kraken Spot" or "Paper Testing").
• Account type -- determines whether the account connects to a real exchange or runs in simulation.
• API credentials -- only required for real exchange accounts.
• Verification status -- tells you whether Botmarley has successfully tested the credentials.
• Assets -- the token balances held in that account (BTC, ETH, USD, etc.).

You can have as many accounts as you like. A common setup is one Paper account for testing and one Kraken account for live trading.

Account Types

Botmarley supports three account types. Each behaves differently with respect to credentials, verification, and trading.

Paper (Simulated)

Paper accounts are purely local. No money leaves your machine, and no API calls are made to any exchange. Paper accounts are ideal for:

• Learning how Botmarley works without financial risk.
• Testing a new strategy before going live.
• Running backtests against historical data.

When you create a Paper account, Botmarley assigns it a starting balance that you can adjust manually. Trades executed against a Paper account update its local balances but never touch a real order book.

Kraken (Real Exchange)

Kraken accounts connect Botmarley to your real Kraken exchange account using API credentials that you generate on Kraken's website. Once verified, Botmarley can:

• Sync balances -- pull your current holdings from Kraken.
• Place orders -- execute buy/sell orders during live trading sessions.
• Fetch market data -- download candle history via the Kraken REST API.

You control what Botmarley is allowed to do by setting the appropriate API key permissions on Kraken (see the Managing Accounts chapter for details).

Binance

A Binance account connects to the Binance exchange using your API key and secret. Botmarley supports:

• Verify credentials -- test the connection with a signed request.
• Sync balances -- pull your current holdings from Binance.
• Place orders -- execute spot market orders (BUY with quoteOrderQty, SELL with quantity).
• Fetch market data -- download candle history via the Binance REST API.

Botmarley automatically applies LOT_SIZE and MARKET_LOT_SIZE filters from Binance exchangeInfo to ensure order quantities are valid.

Verification States

Every account has a verification status that reflects whether Botmarley has successfully tested the connection to the exchange.

Verification is performed by making a signed API request to the exchange's private balance endpoint. If the exchange responds without errors, the credentials are marked Verified. If the exchange returns an authentication error or the request fails, the status is set to Failed.

When to Use Paper vs. Real Accounts

flowchart TD
    A["New strategy idea"] --> B{"Tested in backtesting?"}
    B -- No --> C["Run backtest with Paper account"]
    C --> B
    B -- Yes --> D{"Happy with results?"}
    D -- No --> E["Adjust strategy parameters"]
    E --> C
    D -- Yes --> F{"Ready for real money?"}
    F -- No --> G["Run live Paper session\n(simulated orders)"]
    G --> F
    F -- Yes --> H["Switch to Kraken account\nfor live trading"]

The recommended workflow:

1. Backtest first -- use a Paper account and historical data to validate your strategy logic.
2. Paper-trade live -- run the strategy in live mode against a Paper account. This exercises the real-time data feed without risking funds.
3. Go live -- once confident, create or select a verified Kraken account and start a live trading session.

This progression lets you catch problems early, before any real capital is at stake.

Managing Accounts

This chapter walks through every account management operation: creating, verifying, syncing, editing, and deleting accounts. All of these actions are performed from the Accounts page at /accounts.

Creating a New Account

The Accounts page lists all your configured accounts with their type, verification status, and available actions.

1. Navigate to the Accounts page using the sidebar or by visiting /accounts.
2. Click the Add Account button in the top-right corner. A modal dialog opens.
3. Fill in the form fields:

4. Click Create.

Botmarley redirects you back to the accounts list. Your new account appears in the table with a verification status of Unverified (for exchange accounts) or N/A (for Paper accounts).

Getting Exchange API Keys

To connect an exchange account, you need an API key pair generated from the exchange's website.

Kraken API Keys

1. Log in to your Kraken account at https://www.kraken.com.
2. Navigate to Settings (gear icon) then API.
3. Click Create API Key (or Generate New Key).
4. Give the key a descriptive name (e.g. "Botmarley Trading Bot").
5. Set the permissions (see below).
6. Click Generate Key.
7. Copy both the API Key and the Private Key (secret) immediately. Kraken only shows the secret once. If you lose it, you must generate a new key pair.
8. Paste the key and secret into Botmarley's account creation form.

Binance API Keys

1. Log in to your Binance account at https://www.binance.com.
2. Navigate to Account then API Management.
3. Click Create API and give the key a label (e.g. "Botmarley Trading Bot").
4. Complete any required security verification (2FA).
5. Copy both the API Key and the Secret Key immediately. Binance only shows the secret at creation time.
6. Paste the key and secret into Botmarley's account creation form.

Setting API Key Permissions

Both Kraken and Binance let you control what each API key can do. The permissions you need depend on how you plan to use Botmarley.

Kraken Permissions

Read-only (monitoring and portfolio tracking)

If you only want to sync balances and track your portfolio, enable:

• Query Funds -- allows Botmarley to read your account balances.
• Query Open Orders & Trades -- allows Botmarley to read trade history.

This is the safest option. The key cannot place or cancel orders.

Trading (live bot execution)

If you want Botmarley to place orders on your behalf during live trading sessions, you also need:

• Create & Modify Orders -- allows Botmarley to submit new orders.
• Cancel/Close Orders -- allows Botmarley to cancel open orders.

Permissions to avoid

Unless you have a specific reason, do not enable:

• Withdraw Funds -- Botmarley never needs withdrawal access.
• Access WebSockets API -- not currently required for Botmarley's Kraken integration (REST is used).

Binance Permissions

Read-only (monitoring and portfolio tracking)

• Enable Reading -- allows Botmarley to read your account balances and trade history.

Trading (live bot execution)

• Enable Spot & Margin Trading -- allows Botmarley to place spot market orders.

Permissions to avoid

• Enable Withdrawals -- Botmarley never needs withdrawal access.
• Enable Futures -- Botmarley currently supports spot trading only.

Verifying Credentials

After creating an exchange account, its status is Unverified. Verification confirms that the API key and secret are correct and that Botmarley can reach the exchange.

How to verify

1. On the Accounts page, find the account row in the table.
2. Click the Verify button (checkmark icon or "Verify" label).
3. Botmarley enqueues an AccountVerify task and redirects you to the Tasks page.
4. The task worker picks up the job and makes a signed request to the exchange's balance endpoint. Kraken uses HMAC-SHA512 signing against /0/private/Balance; Binance uses HMAC-SHA256 signing against /api/v3/account.
5. If the exchange responds successfully, the account status changes to Verified.
6. If authentication fails, the status changes to Failed.

You can check the result by returning to the Accounts page or watching the task complete on the Tasks page.

Troubleshooting verification failures

Syncing Account Assets

Syncing pulls the current token balances from the exchange into Botmarley's database. This is how Botmarley knows what you hold.

How to sync

1. On the Accounts page, click the Sync button on the account row.
2. Botmarley enqueues an AccountSync task.
3. The task worker calls the exchange API (Kraken's /0/private/Balance or Binance's /api/v3/account), retrieves all non-zero balances, normalizes the token names, and upserts them into the account_assets table.
4. Once complete, the account's asset list is updated.

You can expand an account row to see its assets, or visit the Portfolio page for an aggregated view across all accounts.

Token name normalization

Kraken uses internal token names that differ from standard symbols. Botmarley normalizes them automatically during sync:

Tokens that do not match a known pattern (e.g. DOT, USDC) are stored as-is.

Binance uses standard token symbols (BTC, ETH, USDC, etc.), so no normalization is needed for Binance accounts.

Editing an Account

1. On the Accounts page, click the Edit button (pencil icon) on the account row.
2. The edit modal opens with the current name, description, and type pre-filled.
3. Modify the fields you want to change.
4. For credentials: leave the API Key and API Secret fields empty to keep the existing values. Only fill them in if you want to replace them.
5. Click Save Changes.

After editing credentials, you should re-verify the account to confirm the new keys work.

Deleting an Account

1. On the Accounts page, click the Delete button on the account row.
2. Botmarley deletes the account and all associated assets from the database.

Deletion also cascades to portfolio snapshots associated with that account. Aggregate (cross-account) portfolio snapshots are not deleted, but they will no longer include the removed account in future syncs.

API Key Security

Botmarley stores API credentials in the local PostgreSQL database. Here are the safeguards in place and the precautions you should take.

What Botmarley does

• Secrets are never sent to the browser. The Account struct has a to_view() method that masks the API key (showing only the first and last 4 characters) and omits the secret entirely.
• Credentials stay local. Botmarley is a single-tenant application running on your machine. There is no cloud service, no third-party server, and no telemetry that transmits your keys.

What you should do

Portfolio Tracking

The Portfolio page gives you a consolidated view of everything you hold across all your accounts -- Paper and exchange alike -- valued in both USD and BTC, updated automatically over time.

What Is Portfolio Tracking?

Portfolio tracking answers a simple question: how much is everything worth, right now and over time?

Botmarley periodically takes a "snapshot" of your portfolio. Each snapshot records:

• The total value in USD across all accounts.
• The total value in BTC (your USD total divided by the current BTC price).
• The BTC/USD price at that moment.
• A per-token breakdown showing balance and USD value for each asset.

By storing snapshots over time, Botmarley can draw charts showing how your portfolio value has changed -- and whether you are gaining or losing ground relative to Bitcoin itself.

How It Works

Portfolio syncing follows a pipeline that runs on a fixed schedule and can also be triggered manually.

Automatic sync schedule

A background scheduler starts when the Botmarley server boots. After an initial 60-second startup delay, it enqueues a PortfolioSync task every 1 hour. The task worker picks it up and runs the full sync pipeline.

The sync pipeline

flowchart LR
    A["Scheduler\n(every 1h)"] -->|enqueues task| B["Task Worker"]
    B --> C["Sync Exchange\nAccounts"]
    C --> D["Query All\nAccount Assets"]
    D --> E["Fetch USD Prices\n(Kraken Ticker API)"]
    E --> F["Compute Totals\n(USD + BTC)"]
    F --> G["Store Snapshot\n(PostgreSQL)"]

In detail, each sync performs these steps:

1. Sync verified exchange accounts -- for every exchange account with status "Verified", Botmarley calls the exchange API to pull the latest balances. Failed syncs for individual accounts are logged but do not stop the pipeline.
2. Query all account assets -- reads every non-zero asset balance across all accounts (including Paper) from the database.
3. Fetch USD prices -- calls the Kraken public Ticker API to get current USD prices for each unique token. Stablecoins and fiat are handled locally (see below).
4. Compute totals -- sums up balance * price for every asset to get total_value_usd. Fetches the BTC/USD price separately and calculates total_value_btc = total_value_usd / btc_price.
5. Store snapshot -- inserts one aggregate row (with account_id = NULL) into the portfolio_snapshots table, including a JSON breakdown of per-token values.

The Portfolio Page

The portfolio page is located at /portfolio. It has several sections, described from top to bottom.

Summary Cards

Four stat cards appear at the top of the page:

If no snapshots exist yet (fresh install), the page shows an empty state with buttons to manage accounts or run a first sync.

Range Selector

Below the summary cards, a row of small buttons lets you control the time range for the charts:

Switching ranges fetches new data from /api/portfolio/chart?range=... and updates both charts without a full page reload. A small label next to the buttons shows how many data points are in the current view.

USD Chart: Portfolio Value + BTC Price Overlay

The first chart displays two lines on a dual-axis layout:

• Portfolio USD (blue, right axis) -- your total portfolio value over time in US dollars.
• BTC Price (amber/dashed, left axis) -- the Bitcoin price over the same period.

This overlay lets you visually compare whether your portfolio is outperforming or underperforming a simple Bitcoin hold. The charts are rendered using Lightweight Charts loaded from a CDN.

BTC Chart: Portfolio Value in BTC

The second chart shows a single amber line: your portfolio's value expressed in Bitcoin. If this line trends upward, you are accumulating more BTC-equivalent value over time, even if the USD value moves sideways.

Asset Breakdown Table

Below the charts, a table lists every token you hold across all accounts:

The table includes a Refresh button that fetches the latest data via HTMX without reloading the page. Assets are sorted by USD value in descending order, so your largest holdings appear first.

Manual Sync

You do not have to wait for the hourly scheduler. To trigger a portfolio sync on demand:

1. Go to the Portfolio page (/portfolio).
2. Click the Sync Now button in the top-right corner.
3. Botmarley enqueues a PortfolioSync task and redirects you back to the portfolio page.
4. The task worker processes the sync (usually completes within a few seconds).
5. Refresh the page to see updated values and charts.

How Prices Are Fetched

Botmarley uses the Kraken public Ticker API to fetch USD prices. This endpoint requires no authentication and has generous rate limits.

The API call

A single request is made to https://api.kraken.com/0/public/Ticker?pair=XXBTZUSD,XETHZUSD,... with all needed trading pairs joined by commas. The response includes the last trade price for each pair, which Botmarley uses as the current price.

Token-to-pair mapping

Botmarley maps normalized token names to Kraken trading pair identifiers:

For tokens that Kraken does not list, the price falls back to 0.0 and a warning is logged.

Stablecoin Handling

Stablecoins and fiat currencies are handled without an API call:

Architecture: Full Sync Flow

The following diagram shows the complete lifecycle of a portfolio sync, from trigger through to the stored snapshot.

sequenceDiagram
    participant S as Scheduler (1h) /<br>Manual Button
    participant Q as Task Queue
    participant W as Task Worker
    participant K as Kraken API
    participant DB as PostgreSQL

    S->>Q: Enqueue PortfolioSync task
    Q->>W: Dequeue task

    Note over W: Step 1: Sync exchange accounts
    W->>DB: List verified exchange accounts
    DB-->>W: [Kraken accounts]
    loop Each verified account
        W->>K: POST /0/private/Balance (signed)
        K-->>W: Token balances
        W->>DB: Upsert account_assets
    end

    Note over W: Step 2: Gather all assets
    W->>DB: SELECT token, balance FROM account_assets
    DB-->>W: All non-zero balances

    Note over W: Step 3: Fetch prices
    W->>K: GET /0/public/Ticker?pair=...
    K-->>W: USD prices per pair

    Note over W: Step 4-5: Compute and store
    W->>W: total_usd = SUM(balance * price)<br>total_btc = total_usd / btc_price
    W->>DB: INSERT INTO portfolio_snapshots
    DB-->>W: Snapshot ID

    W->>Q: Mark task complete

Strategies Overview

What Is a Trading Strategy?

A trading strategy is a set of rules that tell Botmarley when to buy and when to sell a cryptocurrency. Instead of watching charts all day and making emotional decisions, you define your rules once, and Botmarley follows them automatically -- 24 hours a day, 7 days a week.

Think of a strategy as a recipe:

• Ingredients are market data (prices, indicators, candle patterns).
• Instructions are the rules (if RSI drops below 30, buy).
• The result is consistent, disciplined trading without human emotion.

The Strategies List

The web interface provides a central place to manage all your strategies. From the list page you can edit, duplicate, delete, backtest, or start live trading for any strategy with a single click.

How Botmarley Strategies Work

Botmarley strategies are defined as TOML files -- simple, human-readable text files that describe a rule engine. Each strategy file lives in the strats/ directory and contains:

1. Metadata -- the strategy's name, description, and position limits.
2. Actions -- a list of things the bot can do (open a position, add to it, or sell).
3. Triggers -- conditions that must be true for each action to fire.

Strategy Evaluation Flow

Every time a new candle closes, Botmarley evaluates your strategy. Here is how the evaluation loop works:

flowchart TD
    A["New Candle Received"] --> B["For Each Action in Strategy"]
    B --> C{"Check ALL Triggers<br/>(AND logic)"}
    C -- "All triggers TRUE" --> D["Execute Action<br/>(open_long / buy / sell)"]
    C -- "Any trigger FALSE" --> E["Skip This Action"]
    D --> F["Update Position State"]
    E --> F
    F --> G{"More Actions?"}
    G -- "Yes" --> B
    G -- "No" --> H["Wait for Next Candle"]
    H --> A

    style A fill:#4a9eff,color:#fff
    style D fill:#22c55e,color:#fff
    style E fill:#6b7280,color:#fff
    style H fill:#4a9eff,color:#fff

Key points about evaluation:

• Each action is evaluated independently -- one strategy can have multiple buy and sell actions, and each is checked every tick.
• Triggers within an action are AND-combined -- ALL triggers must be true for the action to fire.
• Actions are evaluated in order -- from first to last as written in the TOML file.

Basic Strategy Anatomy

A Botmarley strategy TOML file has two main sections:

1. The [meta] Section

This defines your strategy's identity and global settings:

[meta]
name = "My First Strategy"
description = "A simple RSI-based entry and exit"
max_open_positions = 3

2. The [[actions]] Array

Each [[actions]] block defines one thing the bot can do, along with the conditions that must be met:

[[actions]]
type = "open_long"          # What to do: open_long, buy, or sell
amount = "100 USDC"         # How much: fixed amount or percentage
average_price = false        # Whether to average the entry price (DCA)

  [[actions.triggers]]       # When to do it: one or more trigger conditions
  indicator = "rsi_14"
  operator = "<"
  target = "30"

A Simple Complete Example

Here is a complete, working strategy that buys when RSI is oversold and sells when it recovers:

[meta]
name = "RSI_Scalper"

# ACTION 1: Open a position when RSI drops below 30
[[actions]]
type = "open_long"
amount = "100 USDC"

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

# ACTION 2: Sell half when RSI recovers to 50
[[actions]]
type = "sell"
amount = "50%"

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = ">"
  target = "50"

# ACTION 3: Sell everything when RSI reaches 70
[[actions]]
type = "sell"
amount = "100%"

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = ">"
  target = "70"

What this strategy does, step by step:

1. Action 1 watches RSI(14). When it drops below 30 (oversold territory), the bot opens a new position by buying 100 USDC worth of the asset.
2. Action 2 watches for RSI to rise above 50. When it does, the bot sells 50% of the position to lock in partial profit.
3. Action 3 watches for RSI to rise above 70 (overbought territory). When it does, the bot sells the remaining 100% of the position to fully exit.

What's Next?

Now that you understand how strategies are structured, explore the following topics:

• Strategy Editor -- how to create and edit strategies in the web interface.
• Actions -- detailed explanation of open_long, buy, and sell.
• Indicators Reference -- every indicator Botmarley supports.
• Timeframes -- how multi-timeframe analysis works.
• Position Management -- DCA, position limits, and partial sells.
• Strategy Examples -- complete, battle-tested strategies you can use as starting points.

Strategy Editor

The Strategy Editor is where you create, edit, and manage your trading strategies. Access it from the sidebar by clicking Strategies or navigating directly to /strats.

The Strategies List Page

The strategies list page (/strats) shows all your saved strategies. For each strategy you can see:

• The strategy name and description
• When it was created and last updated
• Action buttons for editing, duplicating, backtesting, and deleting

flowchart LR
    A["Strategies List<br/>/strats"] --> B["Edit<br/>/strats/edit/{id}"]
    A --> C["New Strategy<br/>/strats/new"]
    A --> D["Duplicate"]
    A --> E["Delete"]
    A --> F["Backtest"]
    B --> G["Save"]
    C --> G
    G --> A

    style A fill:#4a9eff,color:#fff
    style G fill:#22c55e,color:#fff

Creating a New Strategy

To create a new strategy:

1. Navigate to /strats (click Strategies in the sidebar).
2. Click the New Strategy button.
3. The editor opens with an empty TOML document.
4. Write your strategy in TOML format (see Strategy Overview for the structure).
5. Click Save.

The editor assigns a unique ID (UUID) to your new strategy automatically.

The Visual Strategy Editor

The visual editor provides a form-based interface for building strategies without writing TOML by hand. You can add actions, configure triggers, set indicator parameters, and define position management rules -- all through a structured UI.

The TOML Text Editor

The strategy editor at /strats/edit/{id} provides a text-based TOML editor where you write your strategy directly. The editor shows the raw TOML content of your strategy file.

A typical editing session looks like this:

1. The [meta] section is at the top -- set your strategy's name and description here.
2. Below that, define your [[actions]] blocks with their triggers.
3. As you type, the editor validates your TOML in real time.

Editor Layout

The editor page provides:

• Strategy name displayed at the top
• TOML text area for editing the strategy content
• Save button to persist changes
• Back to list link to return to /strats

Real-Time Validation

Every time you save or validate your strategy, Botmarley checks the TOML content for errors. The validation endpoint (POST /api/strats/validate) checks:

• TOML syntax -- is the file valid TOML?
• Required fields -- does [meta] have a name? Does each action have a type and amount?
• Valid action types -- only open_long, buy, and sell are accepted.
• Amount format -- must be "100 USDC" (fixed) or "50%" (percentage).
• Indicator format -- must match known patterns like rsi_14, sma_50, bb_lower.
• Operator validity -- must be one of >, <, =, cross_above, cross_below.
• Timeframe validity -- if specified, must be 1m, 5m, 15m, 1h, 4h, or 1d.
• Period ranges -- indicator periods must be between 1 and 200.
• max_open_positions -- if set, must be 1 or greater.

When validation fails, the error response includes:

Common Validation Errors

Saving Strategies

When you click Save, Botmarley:

1. Validates the TOML content server-side.
2. If valid, writes the TOML file to the strats/ directory with the strategy's UUID as the filename.
3. Returns a success response with the strategy ID.
4. Logs the save action to the activity log.

If the strategy is new (no ID yet), a new UUID is generated. If you are editing an existing strategy, the same ID is reused and the file is overwritten.

Duplicating Strategies

To duplicate a strategy:

1. Go to the strategies list (/strats).
2. Click the Duplicate button on the strategy you want to copy.
3. Botmarley creates a copy with " (Copy)" appended to the name.
4. You are redirected to the editor for the new copy.

This is useful when you want to create variations of an existing strategy (for example, testing different RSI thresholds or DCA levels).

Deleting Strategies

To delete a strategy:

1. Go to the strategies list (/strats).
2. Click the Delete button on the strategy you want to remove.
3. The TOML file is removed from the strats/ directory.
4. You are redirected back to the list.

Bulk Delete

You can also select multiple strategies and delete them all at once using the bulk delete feature on the strategies list page. Select the checkboxes next to the strategies you want to remove, then click the bulk delete button.

Discovering Available Pairs

When you open the backtest modal from the strategies list page, Botmarley automatically scans your downloaded market data to show you which trading pairs are available. This is based on the .arrow files in your data storage directory.

The available pairs and their date ranges are shown in the backtest form, so you can select:

• Which pair to backtest against (e.g., XBTUSD, ETHUSD)
• Start and end dates -- pre-filled based on your actual data range

Actions

Actions are the building blocks of your strategy. Each action defines what the bot should do when its trigger conditions are met. A strategy can have any number of actions, and each is evaluated independently on every candle.

The Three Action Types

Botmarley supports three action types, each serving a distinct purpose in the lifecycle of a trade:

flowchart LR
    A["open_long<br/>Open new position"] --> B["buy<br/>Add to position (DCA)"]
    B --> C["sell<br/>Exit position"]

    style A fill:#22c55e,color:#fff
    style B fill:#4a9eff,color:#fff
    style C fill:#ef4444,color:#fff

open_long -- Open a New Position

The open_long action creates a new position by buying an asset. This is the entry point of any trade.

When to use: Use open_long for the initial entry into a trade. This action only fires when there is no existing open position (or when max_open_positions has not been reached).

Example:

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

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

This opens a new position worth 100 USDC when RSI(14) drops below 30.

buy -- Add to an Existing Position (DCA)

The buy action adds to an already open position. This is how you implement Dollar-Cost Averaging (DCA) -- buying more when the price drops to lower your average entry price.

When to use: Use buy to add to a position that was opened by open_long. This action only fires when a position is already open.

Example:

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

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

This adds 200 USDC to the existing position when the price drops 2% from the entry price. The average_price = true flag means the entry price is recalculated (see average_price explained below). The max_count = 1 ensures this DCA level only triggers once per position.

sell -- Exit a Position

The sell action exits part or all of an open position. You can sell a percentage of your position or sell everything.

When to use: Use sell for taking profit, cutting losses (stop-loss), or any exit condition.

Example -- partial exit:

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

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = ">"
  target = "50"

This sells half the position when RSI rises above 50, locking in partial profit while letting the rest ride.

Example -- full exit:

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

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

This sells the entire position when the price rises 3% from entry, closing the trade completely.

Amount Formats

Every action requires an amount field that specifies how much to buy or sell. Botmarley supports two formats:

Fixed Amount: "100 USDC"

A fixed dollar amount. The bot buys or sells exactly this much.

amount = "100 USDC"

When to use: For entries and DCA levels where you want predictable position sizing. Most strategies use fixed amounts for open_long and buy actions.

Supported currencies: USDC, USD, BTC, ETH, and other standard ticker symbols.

Percentage Amount: "50%"

A percentage of either the available balance (for buys) or the current position size (for sells).

amount = "50%"    # Sell half the position
amount = "100%"   # Sell the entire position

When to use:

• For sell actions: "50%" means sell half your position; "100%" means exit completely.
• For buy actions: "50%" means use 50% of available balance.

Amount Format Rules

average_price Explained

The average_price flag controls whether the bot recalculates the position's entry price after a buy or open_long action. This is the core mechanism behind Dollar-Cost Averaging (DCA).

How It Works

When average_price = true and the bot buys more of an asset, the entry price is recalculated as a weighted average:

new_entry_price = (old_qty * old_price + new_qty * new_price) / (old_qty + new_qty)

Example:

1. You open a position: buy 100 USDC worth of BTC at $50,000. Entry price = $50,000.
2. Price drops to $48,000. A DCA buy triggers: buy 200 USDC more at $48,000.
3. With average_price = true, the new entry price becomes:
   • Total cost: $100 + $200 = $300
   • Total BTC: 0.002 + 0.004167 = 0.006167 BTC
   • New entry price: $300 / 0.006167 = $48,649
4. Now the price only needs to rise to $48,649 (not $50,000) to break even.

When to Use It

Multiple Actions: How They Work Together

A strategy typically has multiple actions -- at least one entry (open_long) and one exit (sell). Here is how they interact:

Evaluation Order

Actions are evaluated independently and in order on every candle:

flowchart TD
    A["Candle Closes"] --> B["Evaluate Action 1<br/>(open_long)"]
    B --> C["Evaluate Action 2<br/>(buy / DCA level 1)"]
    C --> D["Evaluate Action 3<br/>(buy / DCA level 2)"]
    D --> E["Evaluate Action 4<br/>(sell / take profit)"]
    E --> F["Evaluate Action 5<br/>(sell / stop loss)"]

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

Key Rules

1. open_long only fires when no position is open (or when max_open_positions allows another).
2. buy only fires when a position IS open -- it has nothing to add to otherwise.
3. sell only fires when a position IS open -- you cannot sell what you do not have.
4. Multiple sell actions can coexist -- you might have a take-profit sell at +3% AND a stop-loss sell at -8%. Whichever condition is met first will fire.
5. After a 100% sell, the position is closed -- subsequent buy triggers will not fire until open_long creates a new position.

Typical Action Structure

Most strategies follow this pattern:

# 1. Entry
[[actions]]
type = "open_long"
amount = "100 USDC"
# ... entry triggers ...

# 2. DCA Level 1 (optional)
[[actions]]
type = "buy"
amount = "200 USDC"
average_price = true
# ... dip trigger ...

# 3. DCA Level 2 (optional)
[[actions]]
type = "buy"
amount = "300 USDC"
average_price = true
# ... deeper dip trigger ...

# 4. Take Profit
[[actions]]
type = "sell"
amount = "100%"
# ... profit trigger ...

# 5. Stop Loss
[[actions]]
type = "sell"
amount = "100%"
# ... loss trigger ...

Triggers Overview

Triggers are the decision engine of every Botmarley strategy. An action (buy, sell, open position) only executes when its triggers say "go." Without triggers, an action would never fire. Without the right triggers, your strategy would trade at the wrong time.

Think of it this way:

• An action answers what to do (buy 100 USDC, sell 50%, open a long position).
• A trigger answers when to do it (RSI dropped below 30, price fell 3% from entry, the 4h candle just closed).

Every action has one or more triggers attached to it. When all of them are satisfied at the same moment, the action fires.

The Three Trigger Types

Botmarley supports three categories of triggers. Each watches a different kind of market signal:

You will often combine these types on the same action. For example, "buy when the 4h candle closes AND RSI is below 35" uses a NextCandle trigger together with a Technical trigger.

The dedicated chapters cover each type in depth:

• Technical Indicators -- indicator comparisons and crossovers
• Price Change -- price movement, P&L tracking, trailing stops, time exits
• Next Candle -- scheduled candle-close events

AND Logic: Multiple Triggers on One Action

When you attach multiple triggers to a single action, Botmarley treats them as AND conditions. Every trigger must be true simultaneously for the action to fire.

graph LR
    T1["Trigger 1<br/>RSI(14) < 30"]
    T2["Trigger 2<br/>SMA(50) > SMA(200)"]
    T3["Trigger 3<br/>Price fell -3%"]
    AND{{"ALL must<br/>be true"}}
    A["Action fires:<br/>Buy 100 USDC"]

    T1 --> AND
    T2 --> AND
    T3 --> AND
    AND --> A

In TOML, this looks like multiple [[actions.triggers]] blocks under the same [[actions]]:

# This action requires ALL THREE triggers to be true
[[actions]]
type = "open_long"
amount = "100 USDC"

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

[[actions.triggers]]
indicator = "sma_50"
operator = ">"
target = "sma_200"
timeframe = "1d"

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

The max_count Field

Every trigger type supports an optional max_count field. It limits how many times that trigger can fire per position.

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

This is essential for DCA (Dollar-Cost Averaging) strategies where you want layered entries. Without max_count, a DCA trigger at -2% would keep firing every time the price bounces back and forth across the -2% threshold. With max_count = 1, it fires once, and you rely on the next DCA level (-4%, -6%) to add more capital.

How Triggers Reset

Trigger fire counts reset when a new position opens. If a trigger on a DCA action has max_count = 1 and it fires once during Position A, that counter goes back to zero when Position A is closed and Position B is opened later.

The lifecycle looks like this:

graph TD
    A["Position opens"] --> B["Triggers active<br/>fire counts = 0"]
    B --> C{"Trigger<br/>conditions met?"}
    C -- "Yes" --> D["Action fires<br/>fire count += 1"]
    D --> E{"fire count<br/>< max_count?"}
    E -- "Yes" --> C
    E -- "No (or max_count reached)" --> F["Trigger disabled<br/>for this position"]
    C -- "No" --> G["Wait for<br/>next evaluation"]
    G --> C
    F --> H["Position closes"]
    H --> I["All fire counts<br/>reset to 0"]
    I --> A

Putting It All Together

Here is a minimal strategy that demonstrates all three trigger types working together:

[meta]
name = "Triggers Overview Demo"
description = "Shows all three trigger types in one strategy"
max_open_positions = 2

# ENTRY: open when RSI is oversold (Technical)
[[actions]]
type = "open_long"
amount = "100 USDC"

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

# DCA: buy more if position drops 3% (PriceChange)
[[actions]]
type = "buy"
amount = "100 USDC"
average_price = true

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

# ACCUMULATE: buy on every 4h candle close (NextCandle)
[[actions]]
type = "buy"
amount = "25 USDC"
average_price = true

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

# EXIT: sell when position is up 2% (PriceChange)
[[actions]]
type = "sell"
amount = "100%"

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

This strategy opens a position when RSI dips, adds to it on dips and on a schedule, and exits at +2% profit. The max_count values prevent runaway accumulation: the DCA fires once, and the scheduled buys stop after 5 candles.

Continue reading the dedicated chapters for each trigger type to learn all the available fields and see more examples.

Technical Indicator Triggers

Technical triggers compare an indicator's current value against a target. They answer questions like "is RSI below 30?", "did the 50-day SMA just cross above the 200-day SMA?", or "is price above the upper Bollinger Band?"

These are the most common triggers in any strategy. If you have used TradingView alerts or any charting tool, you will recognize the logic immediately.

Anatomy of a Technical Trigger

A technical trigger has four fields:

[[actions.triggers]]
indicator = "rsi_14"        # What to measure
operator = "<"              # How to compare
target = "30"               # What to compare against
timeframe = "1h"            # On which candle timeframe (optional)
max_count = 1               # How many times it can fire per position (optional)

Available Indicators

All of these can be used in the indicator field or as a target:

Operators Explained

> (Greater Than) and < (Less Than)

Simple threshold comparisons. The trigger is true whenever the indicator is above or below the target value.

# True whenever RSI(14) is below 30
[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "30"

These fire on every candle where the condition is true, not just the moment it crosses the threshold. If RSI stays below 30 for ten candles, the trigger is "active" on all ten. (Use max_count if you only want it to fire once.)

cross_above and cross_below (Crossover Detection)

A crossover trigger fires at the moment of transition. It checks two consecutive candles:

• cross_above: The indicator was at or below the target on the previous candle, and is above it on the current candle.
• cross_below: The indicator was at or above the target on the previous candle, and is below it on the current candle.

graph LR
    subgraph "cross_above"
        P1["Previous candle:<br/>SMA(50) <= SMA(200)"]
        C1["Current candle:<br/>SMA(50) > SMA(200)"]
        P1 -->|"transition"| C1
    end
    subgraph "cross_below"
        P2["Previous candle:<br/>SMA(50) >= SMA(200)"]
        C2["Current candle:<br/>SMA(50) < SMA(200)"]
        P2 -->|"transition"| C2
    end

# Golden cross: SMA(50) crosses above SMA(200)
[[actions.triggers]]
indicator = "sma_50"
operator = "cross_above"
target = "sma_200"
timeframe = "1d"

= (Equal)

Exact match comparison. This is rarely used because indicator values are continuous floating-point numbers and exact equality is unlikely. The primary use case is the TTM Trend indicator, which outputs discrete integer values:

• 1 = bullish trend
• -1 = bearish trend

# TTM Trend is bullish
[[actions.triggers]]
indicator = "ttm_trend"
operator = "="
target = "1"

Target Types

The target field accepts two kinds of values:

Numeric Target

A fixed number. Used for absolute thresholds like RSI levels, zero-line crossings, or price levels.

target = "30"      # RSI threshold
target = "0"       # MACD zero-line
target = "-3"      # Negative value (ROC dropped below -3%)
target = "50000"   # A specific price level

Indicator Target

Another indicator. Used for comparing two moving averages, checking if price is above/below a band, or volume breakout detection.

target = "sma_200"     # Compare against 200-period SMA
target = "ema_50"      # Compare against 50-period EMA
target = "bb_upper"    # Compare against upper Bollinger Band
target = "price"       # Compare indicator against current price
target = "obv_sma_20"  # Compare OBV against its SMA
target = "macd_signal" # Compare MACD line against its signal line

Examples

Example 1: RSI Oversold Entry

Open a position when RSI(14) drops below 30 on the 1-hour chart.

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

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

When to use: Classic mean-reversion entry. RSI below 30 suggests the asset is oversold and may bounce.

Example 2: Golden Cross (SMA 50/200)

Open a position when the daily SMA(50) crosses above SMA(200).

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

[[actions.triggers]]
indicator = "sma_50"
operator = "cross_above"
target = "sma_200"
timeframe = "1d"

When to use: Long-term trend following. The golden cross is one of the most widely watched signals in traditional finance and crypto alike.

Example 3: Death Cross Exit

Sell the entire position when SMA(50) crosses below SMA(200), signaling a trend reversal.

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

[[actions.triggers]]
indicator = "sma_50"
operator = "cross_below"
target = "sma_200"
timeframe = "1d"

When to use: As a safety exit. Even if your take-profit has not been reached, a death cross suggests the uptrend is over.

Example 4: Bollinger Band Bounce

Open a position when price drops below the lower Bollinger Band on the 1-hour chart (and RSI confirms oversold conditions on the daily chart).

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

[[actions.triggers]]
indicator = "bb_lower"
operator = ">"
target = "price"
timeframe = "1h"

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

When to use: Volatility-based entry. When price punches below the lower band, it has moved more than two standard deviations from the mean. Combining with RSI filters out false signals during strong downtrends.

Example 5: MACD Zero-Line Crossover

Buy when the MACD line crosses above zero, confirming bullish momentum.

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

[[actions.triggers]]
indicator = "macd_line"
operator = "cross_above"
target = "0"
timeframe = "4h"

When to use: Momentum confirmation. The MACD crossing above zero means the short-term EMA has moved above the long-term EMA, confirming upward momentum.

Example 6: TTM Trend Filter with RSI

Only enter when RSI is oversold AND the TTM Trend confirms bullish direction.

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

[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "35"

[[actions.triggers]]
indicator = "ttm_trend"
operator = "="
target = "1"

When to use: Filtered entries. RSI alone can give false signals in a strong downtrend. Adding TTM Trend = 1 ensures you only buy dips during an overall uptrend.

Example 7: EMA Crossover (Fast over Slow)

Enter when EMA(9) crosses above EMA(21) on the 5-minute chart for short-term scalping.

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

[[actions.triggers]]
indicator = "ema_9"
operator = "cross_above"
target = "ema_21"
timeframe = "5m"

When to use: Short-term momentum trading. Faster EMA pairs (9/21, 12/26) react more quickly than SMA pairs, making them suitable for scalping on lower timeframes.

Example 8: Uptrend Filter (SMA 50 Above SMA 200)

Use as a guard condition on another action. Only allow entries while the macro trend is bullish.

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

[[actions.triggers]]
indicator = "sma_50"
operator = ">"
target = "sma_200"
timeframe = "1d"

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

When to use: Multi-timeframe filtering. The daily SMA check acts as a macro trend gate (only buy in uptrends), while the hourly RSI finds dip entries within that uptrend. This is the foundation of the "trend-safe DCA" pattern.

Timeframe Considerations

When you set a timeframe on a technical trigger, Botmarley evaluates the indicator on candles of that timeframe. A few things to keep in mind:

• If you omit timeframe, the trigger uses the trading session's default timeframe.
• You can mix timeframes on the same action. For example, one trigger checks the daily SMA while another checks the hourly RSI. Both must be true for the action to fire.
• Valid timeframes are: 1m, 5m, 15m, 1h, 4h, 1d.
• Lower timeframes (1m, 5m) produce more signals but are noisier. Higher timeframes (4h, 1d) produce fewer signals but are more reliable.

Deep-Dive: Indicators Reference

For in-depth explanations of each indicator — with annotated chart screenshots, operator behavior, and TOML examples — see the Indicators Reference and its sub-pages:

• SMA — Simple Moving Average — Golden Cross, Death Cross, trend filters
• EMA — Exponential Moving Average — Fast crossovers, scalping pairs
• RSI — Relative Strength Index — Oversold/overbought zones, recovery signals
• MACD — Crossovers, histogram, zero-line signals
• Bollinger Bands — Bounce, squeeze, mean reversion
• StochRSI, ROC, ATR, OBV, VolSMA, TTM Trend, Price
• Operators Reference — Complete guide to >, <, =, cross_above, cross_below

Indicators Reference

Botmarley supports 27 technical indicators that you can use in strategy triggers. Each indicator has a dedicated page with in-depth explanations and TOML trigger examples.

Quick Reference Table

Classic Technical Indicators

Statistical Indicators

Indicator Categories

Trend Indicators

• SMA — The classic moving average. Equal weight to all candles. Best for identifying long-term trends and support/resistance levels.
• EMA — Weighted toward recent prices. Reacts faster than SMA. Best for short-term trading and entry timing.
• TTM Trend — Simplified trend direction (1 = bullish, -1 = bearish). Great as a filter on other triggers.

Momentum Indicators

• RSI — Measures overbought/oversold conditions on a 0-100 scale. The most popular momentum indicator.
• MACD — Tracks the relationship between two EMAs. Shows both trend direction and momentum strength.
• StochRSI — More sensitive version of RSI. Catches short-term reversals.
• ROC — Percentage price change. Detects sharp dips and pumps.
• Autocorrelation — Measures momentum persistence. Positive = trends continue; near zero = random; negative = reversals likely.

Volatility Indicators

• Bollinger Bands — Dynamic envelope around price. Widens in volatility, narrows in calm. Great for mean-reversion strategies.
• ATR — Measures volatility magnitude. Use for position sizing and volatility filters.
• RSTD — Rolling standard deviation of price. The raw building block of volatility measurement.
• Parkinson — Volatility from high-low range. More efficient than close-to-close estimators.
• Garman-Klass — Volatility from full OHLC data. Even more efficient than Parkinson.
• Yang-Zhang — The most comprehensive volatility estimator. Combines overnight gaps + intraday range.
• Vol Regime — Classifies volatility into low/normal/high regimes. Self-calibrating across all assets.

Statistical / Mean-Reversion Indicators

• Z-Score — How many standard deviations from the mean. Universal thresholds across all assets. The core mean-reversion signal.
• Percentile Rank — Where current price sits in its rolling range (0-100). Great for detecting historically rare levels.
• Hurst — THE regime detector. Tells you if the market is trending, mean-reverting, or random walk.
• Half-Life — How fast price reverts to the mean (in candles). Determines if mean reversion happens fast enough to trade.

Institutional / Fair Value Indicators

• VWAP — Volume Weighted Average Price. The benchmark institutions use for fair value.
• VWAP Dev — Percentage deviation from VWAP. Measures how far price has strayed from institutional fair value.

Distribution Intelligence

• Skewness — Measures return distribution asymmetry. Positive = upside surprises likely; negative = crash risk elevated.
• Kurtosis — Measures tail fatness. Low = predictable; high = extreme moves likely. A pure risk indicator.

Volume Indicators

• OBV — Cumulative volume flow. Confirms trends and detects divergences.
• VolSMA — Average volume. Detect unusual volume spikes.

Special

• Price — Current candle close. Compare against any indicator or absolute level.

Operators

All indicators are compared using one of five operators. See the Operators Reference for the complete guide, including the critical difference between state-based operators (>, <, =) that fire on every matching candle and event-based operators (cross_above, cross_below) that fire once at the moment of crossing.

Period Constraints

• Minimum period: 1
• Maximum period: 200
• Invalid period (0 or >200): validation error

SMA -- Simple Moving Average

Contents

• Format
• Common Periods
• Understanding Operators with SMA
  • > Greater Than
  • < Less Than
  • = Equal
  • cross_above
  • cross_below
• TOML Examples
  • Golden Cross Entry
  • Death Cross Exit
  • Price Above SMA(200) as Trend Filter
  • Price Drops Below Short-Term SMA
  • Multi-SMA Trend Confirmation
• Tips

The Simple Moving Average is the most fundamental technical indicator in trading. It calculates the arithmetic mean of the last N closing prices, giving equal weight to every candle in the window. If you set the period to 50, the SMA takes the last 50 closing prices, adds them up, and divides by 50. Each new candle drops the oldest price and adds the newest.

Because every candle carries the same weight, SMA is a smooth, stable line that filters out short-term noise. The trade-off is lag -- SMA reacts slowly to sudden price changes because old prices influence the average just as much as the most recent one.

BTC/USDC 1-hour chart with SMA(50) (orange) and SMA(200) (blue). The faster SMA(50) reacts more quickly to price changes while the slower SMA(200) shows the long-term trend.

Format

sma_{period}

The period must be an integer between 1 and 200.

Examples:

Common Periods

Understanding Operators with SMA

Every trigger in Botmarley compares an indicator to a target using an operator. Here is what each operator means visually on the chart when used with SMA.

> (Greater Than)

"Price is ABOVE the SMA line on the chart."

As long as the candle closes above the line, this condition is true. Think of it as "price is in bullish territory." This is a state-based operator -- it remains true on every candle where the condition holds, not just the first one.

Price candles closing above the SMA(200) line. The green zone represents "bullish territory" — every candle here makes price > sma_200 true.

# True on every candle where price closes above the SMA(200)
[[actions.triggers]]
indicator = "price"
operator = ">"
target = "sma_200"

< (Less Than)

"Price is BELOW the SMA line on the chart."

The mirror image of >. When the candle closes below the SMA line, this condition is true. Think of it as "price is in bearish territory."

Price candles closing below the SMA(200) line. The red zone represents "bearish territory" — every candle here makes price < sma_200 true.

# True on every candle where price closes below the SMA(20)
[[actions.triggers]]
indicator = "price"
operator = "<"
target = "sma_20"

= (Equal)

Rarely useful with SMA. Since SMA values are floating-point decimals (e.g., 67,432.18), exact equality with another floating-point value almost never happens. This operator exists mainly for discrete indicators like TTM Trend. Use > or < instead when working with SMA.

cross_above

"The MOMENT the indicator line crosses from below to above the target."

On the chart, look for where two lines intersect and the indicator moves from underneath to on top. This fires once at the crossing candle, not continuously. It checks two consecutive candles: the indicator was at or below the target on the previous candle, and is above it on the current candle.

This is the famous Golden Cross when SMA(50) crosses above SMA(200) -- one of the most widely watched signals in both traditional finance and crypto.

The moment SMA(50) crosses above SMA(200) — the Golden Cross. This event-based signal fires once at the crossing candle.

# Golden Cross: fires once when SMA(50) crosses above SMA(200)
[[actions.triggers]]
indicator = "sma_50"
operator = "cross_above"
target = "sma_200"
timeframe = "1d"

cross_below

"The MOMENT the indicator line crosses from above to below the target."

The opposite crossing -- from above to below. On the chart, the indicator line drops through the target line. Like cross_above, this fires once at the crossing candle.

This is the Death Cross when SMA(50) crosses below SMA(200) -- a widely watched bearish signal.

The moment SMA(50) crosses below SMA(200) — the Death Cross. The bearish mirror of the Golden Cross.

# Death Cross: fires once when SMA(50) crosses below SMA(200)
[[actions.triggers]]
indicator = "sma_50"
operator = "cross_below"
target = "sma_200"
timeframe = "1d"

TOML Examples

Golden Cross Entry

Buy when the 50-period SMA crosses above the 200-period SMA on the daily chart. This is a classic long-term trend-following signal.

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

[[actions.triggers]]
indicator = "sma_50"
operator = "cross_above"
target = "sma_200"
timeframe = "1d"

Death Cross Exit

Sell the entire position when SMA(50) crosses below SMA(200). Even if your take-profit has not been reached, a death cross signals the uptrend may be over.

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

[[actions.triggers]]
indicator = "sma_50"
operator = "cross_below"
target = "sma_200"
timeframe = "1d"

Price Above SMA(200) as Trend Filter

Use the 200-period SMA as a macro trend gate. Only allow entries while price is above the long-term average. This is a state-based filter that stays active as long as the condition holds. Combined with an RSI dip on a lower timeframe, this creates the classic "trend-safe DCA" pattern.

The SMA(200) divides the chart into a bullish zone (above) and a bearish zone (below). Only buy RSI dips when price is in the bullish zone. This multi-indicator, multi-timeframe pattern avoids buying into falling markets.

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

# Macro filter: only buy when price is above the 200 SMA
[[actions.triggers]]
indicator = "price"
operator = ">"
target = "sma_200"
timeframe = "1d"

# Entry signal: RSI dip on lower timeframe
[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "35"
timeframe = "1h"

Price Drops Below Short-Term SMA

Detect when price falls below the 50-period SMA. This can be used as an early warning or exit signal on shorter timeframes.

Price falling below the SMA(50) line — an early warning that the short-term trend may be weakening. This sell trigger lets you reduce exposure before a larger drop develops.

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

[[actions.triggers]]
indicator = "price"
operator = "<"
target = "sma_20"
timeframe = "4h"

Multi-SMA Trend Confirmation

Combine multiple SMA conditions. This entry requires all three SMAs to be in the correct alignment (fast above medium above slow), confirming a strong uptrend before entering.

Perfect SMA alignment: price > SMA(20) > SMA(50) > SMA(200). When all three layers stack in the correct order, it confirms a strong uptrend across all timeframes.

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

# SMA(20) above SMA(50) -- short-term trend is bullish
[[actions.triggers]]
indicator = "sma_20"
operator = ">"
target = "sma_50"
timeframe = "1d"

# SMA(50) above SMA(200) -- medium-term trend is bullish
[[actions.triggers]]
indicator = "sma_50"
operator = ">"
target = "sma_200"
timeframe = "1d"

# Price above SMA(20) -- price is in the strongest zone
[[actions.triggers]]
indicator = "price"
operator = ">"
target = "sma_20"
timeframe = "1d"

Tips

EMA -- Exponential Moving Average

Contents

• Format
• SMA vs EMA -- When to Use Each
• Understanding Operators with EMA
  • > Greater Than
  • < Less Than
  • = Equal
  • cross_above
  • cross_below
• TOML Examples
  • EMA Crossover Scalping
  • EMA Crossover Exit
  • EMA as Dynamic Support
  • Trend-Filtered EMA Entry
  • EMA + RSI Confluence Entry
  • Classic MACD-Style Crossover
• Tips

The Exponential Moving Average is a weighted moving average that gives more weight to recent prices. Unlike SMA, which treats every candle in the window equally, EMA applies a multiplier that makes the most recent price data count more. This means EMA reacts faster to price changes, hugging the price line more closely and reducing lag.

The weighting is exponential: the most recent candle has the highest weight, the second most recent has slightly less, and so on -- with the influence of older candles decaying smoothly rather than dropping off a cliff. The formula uses a smoothing factor of 2 / (period + 1), so a 9-period EMA gives roughly 20% weight to the latest candle, while a 50-period EMA gives roughly 4%.

BTC/USDC 1-hour chart with EMA(9) (orange) and EMA(21) (purple). The fast EMA(9) hugs price more closely and generates more frequent crossover signals than SMA pairs.

Format

ema_{period}

The period must be an integer between 1 and 200.

Examples:

SMA vs EMA -- When to Use Each

Both SMA and EMA smooth price data to identify trends, but they behave differently in practice.

Rule of thumb: Use SMA when you want a stable, macro view of the trend (is the market bullish or bearish over weeks/months?). Use EMA when you want to time entries and exits more precisely, especially on shorter timeframes where speed matters.

Many strategies combine both: an SMA(200) as a macro trend gate with EMA crossovers for entry timing within that trend.

Understanding Operators with EMA

The operators work identically to SMA, but because EMA reacts faster, crossover signals happen earlier and more frequently than with equivalent SMA periods.

> (Greater Than)

"Price is ABOVE the EMA line on the chart."

A state-based check that remains true on every candle where the condition holds. Since EMA tracks price more closely than SMA, the line stays nearer to the candle bodies and acts as tighter dynamic support.

Price candles closing above the EMA(21) line. The green zone represents "bullish territory" — every candle here makes price > ema_21 true.

# True on every candle where price closes above EMA(21)
[[actions.triggers]]
indicator = "price"
operator = ">"
target = "ema_21"

< (Less Than)

"Price is BELOW the EMA line on the chart."

The bearish mirror. Because EMA is more responsive, price falling below a short-period EMA is a faster warning signal than falling below the same-period SMA.

Price candles closing below the EMA(9) line. The red zone represents "bearish territory" — an early warning that momentum is fading.

# Price has dropped below the fast EMA -- early warning
[[actions.triggers]]
indicator = "price"
operator = "<"
target = "ema_9"
timeframe = "1h"

= (Equal)

Rarely useful with EMA. Like SMA, EMA values are floating-point decimals, and exact equality almost never occurs. Use > or < instead.

cross_above

"The MOMENT the fast EMA line crosses from below to above the slow EMA (or target)."

Because EMA reacts faster, crossovers happen sooner than with SMA. An EMA(9)/EMA(21) crossover catches trend shifts earlier than an SMA(50)/SMA(200) crossover -- but also produces more false signals in choppy, sideways markets.

EMA(9) crosses above EMA(21) — a bullish momentum shift. Notice how EMA crossovers happen earlier and more frequently than SMA crossovers.

# Fast EMA crosses above slow EMA -- bullish momentum shift
[[actions.triggers]]
indicator = "ema_9"
operator = "cross_above"
target = "ema_21"
timeframe = "1h"

cross_below

"The MOMENT the fast EMA line crosses from above to below the target."

The bearish crossover. With short-period EMAs this can fire multiple times in a ranging market, so consider adding a trend filter or max_count to prevent repeated signals.

EMA(9) crosses below EMA(21) — a bearish momentum shift. The fast EMA dropping below the slow EMA signals that short-term momentum has turned negative.

# Fast EMA crosses below slow EMA -- bearish momentum shift
[[actions.triggers]]
indicator = "ema_9"
operator = "cross_below"
target = "ema_21"
timeframe = "1h"

TOML Examples

EMA Crossover Scalping

Enter when the 9-period EMA crosses above the 21-period EMA on the 5-minute chart. This is a classic short-term momentum entry for scalping strategies.

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

[[actions.triggers]]
indicator = "ema_9"
operator = "cross_above"
target = "ema_21"
timeframe = "5m"

EMA Crossover Exit

Close the position when the fast EMA crosses back below the slow EMA, signaling momentum has reversed.

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

[[actions.triggers]]
indicator = "ema_9"
operator = "cross_below"
target = "ema_21"
timeframe = "5m"

EMA as Dynamic Support

Use the 21-period EMA as a dynamic support level. If price drops below it on the 1-hour chart, reduce your position as a precaution.

The EMA(21) acts as a dynamic support level. Price repeatedly bounces off this line during an uptrend. When it finally breaks below, it can signal a trend weakening.

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

[[actions.triggers]]
indicator = "price"
operator = "<"
target = "ema_21"
timeframe = "1h"
max_count = 1

Trend-Filtered EMA Entry

Combine a macro SMA trend filter with a fast EMA crossover for entry timing. This only buys EMA crossovers when the overall market is in an uptrend.

Multi-timeframe confirmation: the daily SMA(200) confirms the macro uptrend (green zone), while the hourly EMA(9)/EMA(21) crossover provides the precise entry timing. This pattern avoids buying EMA crossovers in bear markets.

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

# Macro filter: only trade in confirmed uptrend
[[actions.triggers]]
indicator = "price"
operator = ">"
target = "sma_200"
timeframe = "1d"

# Entry signal: fast EMA crossover on lower timeframe
[[actions.triggers]]
indicator = "ema_9"
operator = "cross_above"
target = "ema_21"
timeframe = "1h"

EMA + RSI Confluence Entry

Wait for the EMA crossover AND RSI to confirm oversold conditions before entering. Multiple confirmations reduce false signals.

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

# Momentum shift: EMA crossover
[[actions.triggers]]
indicator = "ema_12"
operator = "cross_above"
target = "ema_26"
timeframe = "1h"

# Confirmation: RSI was recently in oversold territory
[[actions.triggers]]
indicator = "rsi_14"
operator = "<"
target = "40"
timeframe = "1h"

Classic MACD-Style Crossover

The MACD indicator is built from EMA(12) and EMA(26). You can replicate MACD-like signals directly with EMA crossovers, giving you visual confirmation on the price chart itself rather than a separate oscillator panel.

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

# This is equivalent to watching the MACD line cross above zero
[[actions.triggers]]
indicator = "ema_12"
operator = "cross_above"
target = "ema_26"
timeframe = "4h"

Tips

RSI -- Relative Strength Index

Contents

• Format
• RSI Zones
• Understanding Operators with RSI
  • < Less Than
  • > Greater Than
  • cross_below
  • cross_above
  • = Equal
• TOML Examples
  • Buy on Oversold RSI
  • Sell on Overbought RSI
  • Buy on RSI Recovery
  • Sell on Leaving Overbought
  • StochRSI Extreme Dip
  • RSI with Trend Filter
• Tips

Overview

The Relative Strength Index (RSI) is a momentum oscillator that measures the speed and magnitude of recent price changes. It answers one question: how strong is the current move compared to recent moves?

RSI is calculated by comparing the average size of recent gains to the average size of recent losses over a lookback period. The result is normalized to a scale of 0 to 100:

• RSI near 100 means almost all recent candles were bullish (strong upward momentum).
• RSI near 0 means almost all recent candles were bearish (strong downward momentum).
• RSI near 50 means gains and losses are roughly equal (no clear momentum).

The standard RSI period is 14, which looks at the last 14 candles. Shorter periods make RSI more reactive; longer periods make it smoother.

BTC/USDC 1-hour chart with RSI(14) displayed as a separate oscillator below the price chart. The horizontal lines at 70 (overbought) and 30 (oversold) mark the classic trading zones.

Format

rsi_{period}

The period defines how many candles RSI looks back to calculate average gains and losses.

Period range: 1 to 200.

Value range: 0 to 100 (always).

RSI Zones

Understanding Operators with RSI

Each operator behaves differently with RSI. Understanding the distinction is critical for building strategies that fire when you intend.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where RSI is below the threshold.

On the chart: Imagine the RSI line sitting below the horizontal 30 line. For as long as the line stays below 30, this trigger is active. If RSI stays below 30 for eight consecutive candles, the trigger fires on all eight.

RSI(14) dipping below the 30 threshold — the oversold zone highlighted in red. While RSI remains below 30, the < operator fires on every candle.

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

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where RSI is above the threshold.

On the chart: The RSI line is above the horizontal 70 line. Every candle it stays there, this trigger fires.

RSI(14) pushing above the 70 threshold — the overbought zone highlighted in orange. This is where selling pressure may start building.

[[actions.triggers]]
indicator = "rsi_14"
operator = ">"
target = "70"

Typical use: Sell when RSI is overbought. Combined with max_count = 1, it fires once when RSI first exceeds 70 and then stops.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where RSI transitions from above the threshold to below it. The previous candle had RSI >= the target, and the current candle has RSI < the target.

On the chart: Picture the RSI line descending through the 70 line. The moment it pierces the line from above to below, this trigger fires -- and then goes silent until the next crossing.

RSI(14) crossing below the 70 threshold — the moment momentum starts fading. This event-based signal fires once at the crossing candle.

[[actions.triggers]]
indicator = "rsi_14"
operator = "cross_below"
target = "70"

Typical use: Detect when RSI "leaves overbought territory." This is often a stronger sell signal than simply being above 70, because it captures the turning point -- the moment momentum starts fading.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where RSI transitions from below the threshold to above it. The previous candle had RSI <= the target, and the current candle has RSI > the target.

On the chart: The RSI line climbing up through the 30 line. The moment it crosses from below to above, the trigger fires once.

RSI(14) crossing above the 30 threshold — recovery from oversold. Rather than buying while RSI is still falling, this waits for the first sign of recovery.

[[actions.triggers]]
indicator = "rsi_14"
operator = "cross_above"
target = "30"

Typical use: Detect when RSI "recovers from oversold." Rather than buying while RSI is still falling, this waits for the first sign of recovery -- RSI turning back up through 30.

= (Equal) -- Not Recommended for RSI

Why: RSI produces floating-point values like 29.87 or 70.12. Exact equality (rsi_14 = 30) will almost never be true. Use < or > instead.

TOML Examples

Buy on Oversold RSI

The simplest RSI strategy. Enter when RSI drops below 30 on the 1-hour chart.

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

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

Sell on Overbought RSI

Exit when RSI exceeds 70. The max_count = 1 ensures this only fires once per position.

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

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = ">"
  target = "70"
  max_count = 1

Buy on RSI Recovery (Cross Above 30)

Instead of buying while RSI is still falling, wait for the first sign of recovery.

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

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

Sell on Leaving Overbought (Cross Below 70)

Sell at the moment RSI drops back below 70 -- the overbought momentum is fading.

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

  [[actions.triggers]]
  indicator = "rsi_14"
  operator = "cross_below"
  target = "70"
  timeframe = "1h"

StochRSI Extreme Dip

StochRSI is more sensitive than regular RSI and reaches extremes more often. This catches deep short-term dips.

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

  [[actions.triggers]]
  indicator = "stoch_rsi_14"
  operator = "<"
  target = "10"
  timeframe = "5m"
  max_count = 1

RSI with Trend Filter

Only buy RSI dips when the macro trend is bullish (daily SMA 50 above SMA 200).

Multi-timeframe confirmation: the daily SMA crossover confirms the macro uptrend, while the hourly RSI catches dip entries within that trend. This "trend-safe DCA" pattern avoids buying into falling markets.

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

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

  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

Tips

MACD -- Moving Average Convergence Divergence

Contents

• Components
• Reading the MACD Chart
• Understanding Operators with MACD
  • cross_above
  • cross_below
  • > Greater Than
  • < Less Than
• TOML Examples
  • Bullish Crossover Entry
  • Bearish Crossover Exit
  • Zero-Line Cross Entry
  • Histogram Turns Positive
  • MACD as Trend Filter with RSI Entry
  • Full MACD Strategy (Entry + Exit)
• Tips

Overview

MACD is a trend-following momentum indicator that reveals the relationship between two exponential moving averages of price. It answers the question: is short-term momentum accelerating or decelerating relative to the longer-term trend?

MACD produces three components that work together:

1. MACD Line -- the difference between the 12-period EMA and the 26-period EMA. When the fast EMA pulls away from the slow EMA, the MACD line moves further from zero. When they converge, it moves toward zero.
2. Signal Line -- a 9-period EMA of the MACD line itself. It acts as a smoothed version of the MACD line and is used for crossover signals.
3. Histogram -- the difference between the MACD line and the signal line, displayed as bars. It visualizes how far apart the two lines are and how quickly they are converging or diverging.

The interplay between these three components gives traders a rich view of momentum, trend direction, and potential turning points.

BTC/USDC 1-hour chart with MACD displayed below. The MACD line (cyan), signal line (pink), and histogram (green bars) show momentum and trend direction. The zero line separates bullish (above) from bearish (below) territory.

Components

Value range: MACD values are unbounded. They can be positive or negative, and the magnitude depends on the asset's price. For BTC, MACD values might range from -500 to +500 on hourly candles. The zero line is the critical reference point: MACD above zero means the 12-period EMA is above the 26-period EMA (bullish); below zero means bearish.

Reading the MACD Chart

Understanding how the three components relate visually is key to using MACD effectively.

MACD Line above Signal Line:

• The histogram bars are positive (above the zero line).
• Momentum is bullish -- short-term price action is outpacing the smoothed average.

MACD Line below Signal Line:

• The histogram bars are negative (below the zero line).
• Momentum is bearish -- short-term price action is lagging behind the smoothed average.

MACD Line above Zero:

• The 12-period EMA is above the 26-period EMA.
• The overall short-to-medium-term trend is bullish.

MACD Line below Zero:

• The 12-period EMA is below the 26-period EMA.
• The overall short-to-medium-term trend is bearish.

Histogram growing (bars getting taller):

• The MACD line is pulling away from the signal line.
• Momentum is accelerating in the current direction.

Histogram shrinking (bars getting shorter):

• The MACD line is moving toward the signal line.
• Momentum is decelerating. A crossover may be approaching.

The MACD histogram visualizes momentum direction. Green bars above zero = bullish momentum. Red bars below zero = bearish momentum. Watch for bars shrinking as an early warning of a crossover.

Understanding Operators with MACD

cross_above -- Event-Based

This is the most important MACD operator. It fires at the exact candle where one component crosses above another.

MACD Line crosses above Signal Line (Bullish Crossover):

On the chart, look for where the blue MACD line crosses above the orange signal line. At that moment, the histogram flips from negative to positive. This is the classic MACD buy signal -- short-term momentum has turned bullish.

The MACD line (cyan) crosses above the signal line (pink) — a bullish crossover. The histogram flips from negative to positive at this moment.

[[actions.triggers]]
indicator = "macd_line"
operator = "cross_above"
target = "macd_signal"
timeframe = "1h"

MACD Line crosses above the Zero Line:

On the chart, the MACD line moves from below zero to above zero. This is a stronger confirmation than the signal crossover -- it means the 12-period EMA has actually crossed above the 26-period EMA. The trend itself has shifted bullish, not just the momentum.

[[actions.triggers]]
indicator = "macd_line"
operator = "cross_above"
target = "0"
timeframe = "4h"

cross_below -- Event-Based

The mirror of cross_above. Fires at the moment of a downward crossing.

MACD Line crosses below Signal Line (Bearish Crossover):

The MACD line dips below the signal line. The histogram flips negative. Momentum has turned bearish.

The MACD line crosses below the signal line — a bearish crossover. Momentum has turned negative and the histogram bars flip to the downside.

[[actions.triggers]]
indicator = "macd_line"
operator = "cross_below"
target = "macd_signal"
timeframe = "1h"

MACD Line crosses below Zero:

The trend itself has shifted bearish. The 12-period EMA has dropped below the 26-period EMA.

[[actions.triggers]]
indicator = "macd_line"
operator = "cross_below"
target = "0"
timeframe = "4h"

> (Greater Than) -- State-Based

True on every candle where the condition holds. Useful for trend filters rather than entry signals.

MACD Line above Zero = Bullish bias:

MACD line above the zero line — the 12-period EMA is above the 26-period EMA, confirming a bullish bias. Use this as a trend filter for other entry triggers.

[[actions.triggers]]
indicator = "macd_line"
operator = ">"
target = "0"

This fires on every candle where MACD is positive. Use it as a filter alongside other entry triggers -- "only buy when the overall MACD trend is bullish."

Histogram above Zero = Bullish momentum:

[[actions.triggers]]
indicator = "macd_histogram"
operator = ">"
target = "0"

The histogram is positive whenever the MACD line is above the signal line. Using > with the histogram is equivalent to saying "MACD momentum is currently bullish."

< (Less Than) -- State-Based

True on every candle where the condition holds.

MACD Line below Zero = Bearish bias:

MACD line below the zero line — bearish bias. The 12-period EMA is below the 26-period EMA, confirming a downtrend.

[[actions.triggers]]
indicator = "macd_line"
operator = "<"
target = "0"

Histogram below Zero = Bearish momentum:

[[actions.triggers]]
indicator = "macd_histogram"
operator = "<"
target = "0"

TOML Examples

Bullish Crossover Entry

Enter when the MACD line crosses above the signal line on the 1-hour chart. This is the most common MACD strategy.

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = "cross_above"
  target = "macd_signal"
  timeframe = "1h"

Bearish Crossover Exit

Exit the position when MACD momentum reverses. This acts as a dynamic stop-loss -- instead of a fixed percentage, you exit when the momentum signal that justified your entry flips bearish.

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = "cross_below"
  target = "macd_signal"
  timeframe = "1h"

Zero-Line Cross Entry

A more conservative entry than the signal crossover. Waits for the MACD line to cross above zero, confirming that the 12-period EMA is above the 26-period EMA.

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = "cross_above"
  target = "0"
  timeframe = "4h"

Histogram Turns Positive

Buy when the MACD histogram crosses above zero. This is equivalent to the MACD line crossing above the signal line but expressed through the histogram component.

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

  [[actions.triggers]]
  indicator = "macd_histogram"
  operator = "cross_above"
  target = "0"
  timeframe = "1h"

MACD as Trend Filter with RSI Entry

Use MACD above zero as a bullish trend gate, and RSI for timing the entry. This avoids buying RSI dips in a bearish trend.

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = ">"
  target = "0"
  timeframe = "1h"

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

Full MACD Strategy (Entry + Exit)

Enter on bullish crossover, exit on bearish crossover or fixed profit target -- whichever comes first.

[meta]
name = "MACD_Momentum"
description = "Enter on MACD bullish cross, exit on bearish cross or +3%"

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = "cross_above"
  target = "macd_signal"
  timeframe = "1h"

# TAKE PROFIT
[[actions]]
type = "sell"
amount = "100%"

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

# MOMENTUM EXIT
[[actions]]
type = "sell"
amount = "100%"

  [[actions.triggers]]
  indicator = "macd_line"
  operator = "cross_below"
  target = "macd_signal"
  timeframe = "1h"

Tips

Bollinger Bands

Contents

• Components
• Understanding Operators with Bollinger Bands
  • < Price Below a Band
  • > Price Above a Band
  • cross_below Crossing Below a Band
  • cross_above Crossing Above a Band
• TOML Examples
  • Buy When Price Drops Below Lower Band
  • Alternative Form -- Lower Band Above Price
  • Sell When Price Breaks Above Upper Band
  • Mean Reversion -- Price Crosses Back Above Middle Band
  • Bollinger Bounce with RSI Confirmation
• Tips

Overview

Bollinger Bands are a volatility-based indicator that creates a dynamic envelope around price. The indicator consists of three lines:

• Middle band -- a 20-period Simple Moving Average (SMA) of the closing price.
• Upper band -- the middle band plus 2 standard deviations.
• Lower band -- the middle band minus 2 standard deviations.

Because the bands are derived from standard deviation, they automatically widen when the market is volatile and narrow (squeeze) when the market is calm. Roughly 95% of price action stays within the bands under normal conditions, so a move outside them is statistically significant.

A Bollinger Squeeze — the bands narrow when volatility drops. This compression often precedes a strong breakout move in either direction.

BTC/USDC 1-hour chart with Bollinger Bands. The upper band (bb_upper), middle band (SMA 20), and lower band (bb_lower) create a dynamic envelope around price. Notice how the bands widen during volatile periods and squeeze during consolidation.

Components

All three components can be used as either the indicator or the target in a trigger.

Understanding Operators with Bollinger Bands

Bollinger Bands are price-level indicators, so they pair naturally with comparison and crossover operators. Here is how each operator behaves in context:

< -- Price Below a Band

price < bb_lower

Price drops below the lower band. On the chart, the candle closes below the bottom line of the envelope. This is the classic Bollinger Bounce buy signal -- price has moved more than 2 standard deviations below the mean and is statistically likely to revert.

Price dropping to touch the lower Bollinger Band — a potential mean-reversion buy signal. The upper and lower bands define the 2-standard-deviation envelope.

This is a state-based operator. It fires on every candle where price remains below the band. Use max_count if you only want it to fire once per position.

> -- Price Above a Band

price > bb_upper

Price breaks above the upper band. This can signal either a breakout (strong momentum continuing upward) or an overbought condition (price extended too far and likely to pull back). Context matters -- in a strong uptrend, price can ride the upper band for extended periods.

Price extending above the upper Bollinger Band — overbought territory. The red zone highlights where price has moved more than 2 standard deviations above the mean.

cross_below -- Crossing Below a Band

price cross_below bb_lower

Price crosses from above to below the lower band. This is an event-based operator -- it fires exactly once at the moment the crossing happens. On the previous candle, price was at or above bb_lower; on the current candle, price is below it.

The moment price breaks below the lower Bollinger Band — an event-based signal that fires once at the crossing candle. Use this instead of < when you want the precise breakout moment.

Use this instead of < when you want to catch the precise moment price breaks below the band rather than the sustained condition of being below it.

cross_above -- Crossing Above a Band

price cross_above bb_middle

Price crosses from below to above the middle band. This is a mean reversion confirmation signal -- after a dip below the lower band, price crossing back above the middle band confirms that the reversion is underway. This is an event-based operator and fires once at the crossing.

Price crossing back above the middle Bollinger Band (SMA 20) — mean reversion confirmed. After touching the lower band, this crossing signals the recovery is underway.

TOML Examples

Buy When Price Drops Below Lower Band

The classic Bollinger Bounce entry. Price below the lower band means it is extended more than 2 standard deviations from the mean.

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

[[actions.triggers]]
indicator = "price"
operator = "<"
target = "bb_lower"
timeframe = "1h"

Alternative Form -- Lower Band Above Price

This is identical in meaning to the example above but written with the indicator and target swapped:

[[actions.triggers]]
indicator = "bb_lower"
operator = ">"
target = "price"
timeframe = "1h"

Sell When Price Breaks Above Upper Band

Price above the upper band may indicate an overbought condition -- a good time to take profit.

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

[[actions.triggers]]
indicator = "price"
operator = ">"
target = "bb_upper"
timeframe = "1h"

Mean Reversion -- Price Crosses Back Above Middle Band

After a dip below the lower band, wait for price to cross back above the middle band before entering. This confirms the reversion is in progress rather than catching a still-falling knife.

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

[[actions.triggers]]
indicator = "price"
operator = "cross_above"
target = "bb_middle"
timeframe = "1h"

Bollinger Bounce with RSI Confirmation

Combine Bollinger Bands with RSI to filter out false signals. Only buy when price is below the lower band AND RSI confirms oversold conditions.

Multi-indicator confirmation: price below the lower Bollinger Band AND RSI below 35. Combining two independent signals filters out false positives and increases the reliability of the entry.

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

[[actions.triggers]]
indicator = "price"
operator = "<"
target = "bb_lower"
timeframe = "1h"

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

Tips

StochRSI -- Stochastic RSI

Contents

• Format
• StochRSI Zones
• Understanding Operators with StochRSI
  • < Less Than
  • > Greater Than
  • cross_below
  • cross_above
  • = Equal
• TOML Examples
  • Buy on Deeply Oversold StochRSI
  • Sell on Overbought StochRSI
  • Buy on StochRSI Recovery
  • StochRSI with RSI Filter
• Tips

Overview

Stochastic RSI (StochRSI) applies the Stochastic oscillator formula to RSI values instead of raw price. The result is an indicator that is significantly more sensitive than standard RSI -- it reaches extreme values (0 and 100) far more frequently.

Where RSI might hover around 40--60 for extended periods, StochRSI will swing aggressively between 0 and 100 within the same timeframe. This makes it ideal for catching short-term reversals, but it also means more false signals.

Think of it this way:

• RSI answers: "How strong is the current momentum compared to recent history?"
• StochRSI answers: "Where is RSI right now relative to its own recent range?"

If RSI has ranged between 35 and 65 over the last 14 candles and currently sits at 35, StochRSI would be near 0 -- even though RSI itself is not at a traditional "oversold" level. This relative measurement is what makes StochRSI more reactive.

Format

stoch_rsi_{period}

The period defines the lookback window for both the underlying RSI calculation and the stochastic normalization applied on top.

Period range: 1 to 200.

Value range: 0 to 100 (always).

StochRSI Zones

Understanding Operators with StochRSI

Each operator behaves differently with StochRSI. Because StochRSI oscillates rapidly, operator choice has a major impact on signal frequency.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where StochRSI is below the threshold.

On the chart: StochRSI drops below the 10 line. For every candle it remains below 10, this trigger fires. Because StochRSI moves fast, these episodes tend to be short-lived (2--5 candles), but they can still fire multiple times.

[[actions.triggers]]
indicator = "stoch_rsi_14"
operator = "<"
target = "10"
timeframe = "5m"

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where StochRSI is above the threshold.

On the chart: StochRSI climbs above the 80 or 90 line. Every candle it stays there, this trigger fires.

[[actions.triggers]]
indicator = "stoch_rsi_14"
operator = ">"
target = "85"
timeframe = "5m"

Typical use: Exit or take profit when StochRSI signals short-term overbought conditions. Combine with max_count = 1 to fire once.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where StochRSI transitions from above the threshold to below it. The previous candle had StochRSI >= the target, and the current candle has StochRSI < the target.

On the chart: StochRSI pierces the 20 line from above to below. This single moment is the trigger -- it then goes silent until the next crossing.

[[actions.triggers]]
indicator = "stoch_rsi_14"
operator = "cross_below"
target = "20"
timeframe = "5m"

Typical use: Detect the moment StochRSI enters oversold territory. More precise than < because it fires exactly once per entry into the zone, making it useful for timing dip-buy entries without repeated signals.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where StochRSI transitions from below the threshold to above it. The previous candle had StochRSI <= the target, and the current candle has StochRSI > the target.

On the chart: StochRSI climbing up through the 20 line from below. The moment it crosses, the trigger fires once.

[[actions.triggers]]
indicator = "stoch_rsi_14"
operator = "cross_above"
target = "20"
timeframe = "5m"

Typical use: Detect when StochRSI recovers from oversold. Instead of buying while the indicator is still falling, this waits for the first sign of reversal -- StochRSI turning back up through the oversold boundary. This is often a safer entry than raw < 10.

= (Equal) -- Not Recommended for StochRSI

Why: StochRSI produces floating-point values. Exact equality (e.g., stoch_rsi_14 = 50) will almost never match. Use < or > instead.

TOML Examples

Buy on Deeply Oversold StochRSI

Catch short-term dips when StochRSI drops below 10 on the 5-minute chart. The max_count = 1 prevents repeated entries while StochRSI remains pinned near zero.

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

  [[actions.triggers]]
  indicator = "stoch_rsi_14"
  operator = "<"
  target = "10"
  timeframe = "5m"
  max_count = 1

Sell on Overbought StochRSI

Take profit when short-term momentum peaks. StochRSI above 85 on the 5-minute chart signals the move may be overextended.

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

  [[actions.triggers]]
  indicator = "stoch_rsi_14"
  operator = ">"
  target = "85"
  timeframe = "5m"
  max_count = 1

Buy on StochRSI Recovery (Cross Above 20)

Instead of buying while StochRSI is still falling, wait for the first sign of recovery. This catches the reversal rather than the bottom.

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

  [[actions.triggers]]
  indicator = "stoch_rsi_14"
  operator = "cross_above"
  target = "20"
  timeframe = "5m"

StochRSI with RSI Filter

Combine the sensitivity of StochRSI with the broader context of RSI. Only enter when StochRSI is deeply oversold and RSI confirms the broader momentum is also depressed. This filters out the many false signals StochRSI generates in trending markets.

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

  [[actions.triggers]]
  indicator = "stoch_rsi_14"
  operator = "<"
  target = "10"
  timeframe = "5m"
  max_count = 1

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

Tips

ROC -- Rate of Change

Contents

• Format
• ROC Interpretation
• Understanding Operators with ROC
  • < Less Than
  • > Greater Than
  • cross_below
  • cross_above
  • = Equal
• TOML Examples
  • Buy After a Sharp Dip
  • Sell When Momentum Weakens
  • Buy on Zero-Line Recovery
  • Sharp Dip with Consecutive Candle Confirmation
• Tips

Overview

Rate of Change (ROC) measures the percentage change in price over the last N candles. It answers a simple question: how much has the price moved, in percentage terms, over a fixed lookback period?

The calculation is straightforward:

ROC = ((current_price - price_N_candles_ago) / price_N_candles_ago) * 100

• ROC of -5 means price has dropped 5% over the lookback period.
• ROC of 3 means price has risen 3% over the lookback period.
• ROC of 0 means price is unchanged.

Unlike bounded oscillators (RSI, StochRSI), ROC has no fixed range. It can be any positive or negative value. A flash crash could produce ROC of -20 or worse. This makes ROC uniquely suited for detecting the magnitude of price moves -- you set the threshold based on what you consider a significant move for the asset and timeframe you are trading.

Format

roc_{period}

The period defines how many candles back ROC compares the current price to.

Period range: 1 to 200.

Value range: Unbounded (any positive or negative number, expressed as a percentage).

ROC Interpretation

Understanding Operators with ROC

Each operator behaves differently with ROC. Because ROC is unbounded, careful threshold selection is critical.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where ROC is below the threshold.

On the chart: Price has been dropping. ROC dips below your threshold (say, -5). For every candle that ROC remains below -5, this trigger fires. This captures the entire duration of the dip, not just the initial plunge.

[[actions.triggers]]
indicator = "roc_10"
operator = "<"
target = "-5"
timeframe = "15m"

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where ROC is above the threshold.

On the chart: Price has been rising. ROC exceeds your threshold (say, 3). Every candle it stays above 3, this trigger fires.

[[actions.triggers]]
indicator = "roc_10"
operator = ">"
target = "3"
timeframe = "15m"

Typical use: Momentum confirmation for exits -- sell when upward momentum is strong. Or as a breakout filter -- only enter when price is moving decisively upward.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where ROC transitions from above the threshold to below it. The previous candle had ROC >= the target, and the current candle has ROC < the target.

On the chart: ROC was hovering above zero and suddenly drops below zero. The moment it crosses the line, the trigger fires once.

[[actions.triggers]]
indicator = "roc_10"
operator = "cross_below"
target = "0"
timeframe = "1h"

Typical use: Detect the zero-line crossing. ROC crossing below 0 means price is now lower than it was N candles ago -- momentum has turned negative. This is a clean trend-change signal without the noise of staying in a zone.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where ROC transitions from below the threshold to above it. The previous candle had ROC <= the target, and the current candle has ROC > the target.

On the chart: ROC was negative and climbs back above zero. The crossing moment is the trigger.

[[actions.triggers]]
indicator = "roc_10"
operator = "cross_above"
target = "0"
timeframe = "1h"

Typical use: Detect momentum recovery. ROC crossing above 0 means price is now higher than it was N candles ago -- momentum has turned positive. This signals the beginning of a potential upward move.

= (Equal) -- Not Recommended for ROC

Why: ROC produces floating-point values. Exact equality (e.g., roc_10 = 0) will almost never be true because ROC values are calculated to many decimal places. Use cross_above or cross_below with a target of 0 to detect zero-line crossings instead.

TOML Examples

Buy After a Sharp Dip

Enter when price has dropped 5% over the last 10 candles on the 15-minute chart. This targets sharp, rapid dips that often precede bounces.

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

  [[actions.triggers]]
  indicator = "roc_10"
  operator = "<"
  target = "-5"
  timeframe = "15m"
  max_count = 1

Sell When Momentum Weakens

Exit the position when upward momentum fades. ROC crossing below 0 means the recent rally has stalled and price is now below where it was 10 candles ago.

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

  [[actions.triggers]]
  indicator = "roc_10"
  operator = "cross_below"
  target = "0"
  timeframe = "1h"

Buy on Zero-Line Recovery

Wait for ROC to cross back above zero after a dip. This confirms that the price drop is over and momentum is turning positive, rather than trying to catch a still-falling knife.

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

  [[actions.triggers]]
  indicator = "roc_10"
  operator = "cross_above"
  target = "0"
  timeframe = "15m"

Sharp Dip with Consecutive Candle Confirmation

Combine ROC with a consecutive red candles trigger for higher-conviction dip entries. This fires only when price has dropped 3% and there have been 5 consecutive bearish candles -- confirming a real sell-off rather than a single volatile candle.

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

  [[actions.triggers]]
  indicator = "roc_10"
  operator = "<"
  target = "-3"
  timeframe = "15m"
  max_count = 1

  [[actions.triggers]]
  type = "consecutive_candles"
  direction = "bearish"
  count = 5
  timeframe = "15m"

Tips

ATR -- Average True Range

Contents

• Format
• Understanding ATR Values
• Understanding Operators with ATR
  • > Greater Than
  • < Less Than
  • cross_above
  • cross_below
  • = Equal
• TOML Examples
  • Only Trade When Volatility Is Elevated
  • Low Volatility Squeeze Detection
  • ATR Filter Combined with RSI Entry
  • Volatility Regime Change
• Tips

Overview

Average True Range (ATR) measures the average range of price movement over the last N candles. It tells you how much the price typically moves per candle -- it measures volatility, not direction.

ATR uses "True Range" rather than simple high-low range. True Range accounts for gaps between candles by taking the maximum of:

1. Current high minus current low
2. Absolute value of current high minus previous close
3. Absolute value of current low minus previous close

This ensures that a gap-up or gap-down is reflected as volatility even if the current candle's body is small.

The key insight about ATR:

• High ATR means the market is making large moves per candle -- high volatility. More risk and more reward per trade.
• Low ATR means the market is quiet -- low volatility. Prices are moving in small increments. Breakouts from low-ATR environments can be explosive.
• ATR says nothing about direction. A high ATR during a crash is the same as a high ATR during a rally. It only measures the size of moves, not whether they are up or down.

Format

atr_{period}

The period defines how many candles ATR averages the True Range over.

Period range: 1 to 200.

Value range: 0 to infinity (always positive, denominated in the asset's price currency).

Understanding ATR Values

Unlike RSI or StochRSI, ATR values are not normalized to a fixed scale. They are expressed in the same units as the asset's price. This has a critical implication: ATR thresholds must be set relative to the asset and timeframe you are trading.

Understanding Operators with ATR

Each operator behaves differently with ATR. Because ATR is a filter indicator (it describes market conditions, not trading signals), it is almost always used in combination with other triggers.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where ATR is above the threshold.

On the chart: Volatility is elevated. The market is making large moves per candle. This trigger stays active for as long as ATR remains above the threshold.

[[actions.triggers]]
indicator = "atr_14"
operator = ">"
target = "500"
timeframe = "1h"

Typical use: "Only trade when the market is volatile enough." High ATR means there is enough price movement to make a trade worthwhile. If ATR is too low, the profit potential may not justify the spread and fees.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where ATR is below the threshold.

On the chart: Volatility is compressed. The market is quiet, moving in small increments. This is often called a "volatility squeeze."

[[actions.triggers]]
indicator = "atr_14"
operator = "<"
target = "200"
timeframe = "1h"

Typical use: Detect low-volatility environments. Extended periods of low ATR often precede explosive breakouts. Some strategies wait for a squeeze (low ATR) and then enter on a directional signal, expecting the breakout to produce outsized moves.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where ATR transitions from below the threshold to above it. The previous candle had ATR <= the target, and the current candle has ATR > the target.

[[actions.triggers]]
indicator = "atr_14"
operator = "cross_above"
target = "400"
timeframe = "1h"

Typical use: Detect the moment volatility expands. This captures the transition from a quiet market to an active one -- a potential breakout is underway. Combine with a directional indicator to determine whether to go long or short.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where ATR transitions from above the threshold to below it. The previous candle had ATR >= the target, and the current candle has ATR < the target.

[[actions.triggers]]
indicator = "atr_14"
operator = "cross_below"
target = "300"
timeframe = "1h"

Typical use: Detect the moment volatility contracts. This captures the transition from an active market to a quiet one. Can be used to exit positions if you only want to be in trades during volatile periods, or to start watching for squeeze-breakout setups.

= (Equal) -- Not Recommended for ATR

Why: ATR produces floating-point values that are rarely exactly equal to any specific number. Use > or < instead.

TOML Examples

Only Trade When Volatility Is Elevated

Use ATR as a gate on an RSI dip-buy strategy. Only enter when ATR confirms the market is moving enough to make the trade worthwhile.

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

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

  [[actions.triggers]]
  indicator = "atr_14"
  operator = ">"
  target = "500"
  timeframe = "1h"

Low Volatility Squeeze Detection

Identify compression periods where the market is unusually quiet. When ATR drops below the threshold and then a directional breakout occurs (price breaks above the upper Bollinger Band), enter the trade.

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

  [[actions.triggers]]
  indicator = "atr_14"
  operator = "<"
  target = "200"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "price"
  operator = ">"
  target = "bb_upper"
  timeframe = "1h"

ATR Filter Combined with RSI Entry

A comprehensive dip-buying strategy: only buy when RSI is oversold, ATR shows sufficient volatility (so the bounce potential is meaningful), and the daily trend is bullish.

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

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

  [[actions.triggers]]
  indicator = "atr_14"
  operator = ">"
  target = "400"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

Volatility Regime Change

Detect the moment volatility expands from a quiet period. When ATR crosses above the threshold, it signals that the market is waking up -- combine with momentum direction for entry.

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

  [[actions.triggers]]
  indicator = "atr_14"
  operator = "cross_above"
  target = "400"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "roc_10"
  operator = ">"
  target = "1"
  timeframe = "1h"

Tips

Parkinson Volatility -- Parkinson Historical Volatility Estimator

Contents

• Format
• Understanding Parkinson Values
• Understanding Operators with Parkinson
  • < Less Than
  • > Greater Than
  • cross_below
  • cross_above
  • = Equal
• TOML Examples
  • Low Volatility Squeeze with Bullish RSI
  • High Volatility Filter -- Avoid Entry
  • Squeeze Breakout with Trend Confirmation
  • Volatility Compression DCA
• Tips

Overview

Parkinson Volatility is a historical volatility estimator that uses only the high and low prices of each candle. It was developed by physicist Michael Parkinson in 1980 as a more efficient alternative to the traditional close-to-close volatility calculation.

The formula is:

Parkinson = sqrt( (1 / (4 * N * ln(2))) * sum( ln(H_i / L_i) )^2 )

Where H_i and L_i are the high and low prices for each candle, and N is the lookback period. The result is an annualized volatility estimate.

The key insight: Parkinson volatility is approximately 5x more efficient than close-to-close volatility. "Efficient" here means it extracts more information from the same amount of data. Consider a candle with a huge wick -- price spiked up and came back down, closing near its open. A close-to-close volatility estimator sees almost no movement. Parkinson catches the full intraday range, revealing the true volatility that close-only methods miss entirely. This makes it exceptionally useful for detecting volatility squeezes and expansions in cryptocurrency markets where wicks are common.

Format

parkinson_{period}

The period defines how many candles the estimator averages over.

Period range: 5 to 500.

Value range: 0 to infinity (annualized volatility, always positive). Typical crypto range: 0.005 to 0.10.

Understanding Parkinson Values

Parkinson values are annualized volatility estimates expressed as decimals. They are not normalized to a fixed scale like RSI. The values depend on the asset, timeframe, and current market conditions.

Understanding Operators with Parkinson

Each operator behaves differently with Parkinson volatility. Because Parkinson is a filter indicator (it describes market conditions, not trading direction), it is almost always used in combination with directional triggers.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where Parkinson volatility is below the threshold.

On the chart: Volatility is compressed. Candle ranges are small and consistent. The market is in a squeeze state, which often precedes explosive breakouts.

[[actions.triggers]]
indicator = "parkinson_20"
operator = "<"
target = "0.02"
timeframe = "1h"

Typical use: Detect volatility squeezes. When Parkinson drops to unusually low levels, the market is coiling. Combine with a directional trigger (RSI dip, EMA cross, Bollinger breakout) to enter at the moment the squeeze resolves.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where Parkinson volatility is above the threshold.

On the chart: Volatility is elevated. Candles have large ranges with significant wicks. The market is making big moves.

[[actions.triggers]]
indicator = "parkinson_20"
operator = ">"
target = "0.07"
timeframe = "1h"

Typical use: High-volatility filter. Use > to either (1) avoid entering new positions during chaotic markets, or (2) only trade when volatility is high enough for profitable moves. The interpretation depends on your strategy design.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where Parkinson transitions from above the threshold to below it. The previous candle had Parkinson >= the target, and the current candle has Parkinson < the target.

[[actions.triggers]]
indicator = "parkinson_20"
operator = "cross_below"
target = "0.03"
timeframe = "1h"

Typical use: Detect the moment the market enters a squeeze. Volatility has just dropped below your calm-market threshold. This signals the beginning of a compression phase -- start watching for directional breakout triggers.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where Parkinson transitions from below the threshold to above it. The previous candle had Parkinson <= the target, and the current candle has Parkinson > the target.

[[actions.triggers]]
indicator = "parkinson_20"
operator = "cross_above"
target = "0.05"
timeframe = "1h"

Typical use: Detect the moment volatility expands. The market was quiet and has just started making larger moves. This often marks the beginning of a trending phase -- combine with a momentum indicator to determine direction.

= (Equal) -- Not Recommended for Parkinson

Why: Parkinson produces floating-point values calculated to many decimal places. Exact equality will almost never be true. Use < or > instead.

TOML Examples

Low Volatility Squeeze with Bullish RSI

When Parkinson volatility is ultra-low (squeeze) and RSI signals oversold conditions, enter long. The logic: a quiet market with a dip often precedes a strong bounce.

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

  [[actions.triggers]]
  indicator = "parkinson_20"
  operator = "<"
  target = "0.02"
  timeframe = "1h"

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

High Volatility Filter -- Avoid Entry

Use Parkinson as a safety gate. Only enter when volatility is not extreme. This protects against buying into violent, unpredictable markets.

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

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

  [[actions.triggers]]
  indicator = "parkinson_20"
  operator = "<"
  target = "0.08"
  timeframe = "1h"

Squeeze Breakout with Trend Confirmation

Wait for the market to be in a volatility squeeze, then enter when price breaks above the upper Bollinger Band with a bullish daily trend.

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

  [[actions.triggers]]
  indicator = "parkinson_20"
  operator = "<"
  target = "0.025"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "price"
  operator = ">"
  target = "bb_upper"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

Volatility Compression DCA

During ultra-calm markets, dollar-cost average into positions. When the squeeze resolves, you will have accumulated at compressed prices.

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

  [[actions.triggers]]
  indicator = "parkinson_50"
  operator = "<"
  target = "0.015"
  timeframe = "4h"
  max_count = 3

Tips

GK Vol -- Garman-Klass Volatility Estimator

Contents

• Format
• Understanding GK Vol Values
• Understanding Operators with GK Vol
  • < Less Than
  • > Greater Than
  • cross_below
  • cross_above
  • = Equal
• TOML Examples
  • Moderate Volatility with Trend Entry
  • GK Vol Band Filter -- Goldilocks Zone
  • EMA Cross with Volatility Confirmation
  • Volatility Regime Change Detection
• Tips

Overview

Garman-Klass Volatility is the most efficient single-estimator for historical volatility because it uses all four OHLC prices -- open, high, low, and close -- from each candle. Developed by Mark Garman and Michael Klass in 1980, it extracts the maximum amount of volatility information from standard OHLC data.

The formula incorporates two components:

GK = sqrt( (1/N) * sum( 0.5 * ln(H/L)^2 - (2*ln(2) - 1) * ln(C/O)^2 ) )

The first term ln(H/L)^2 captures the intraday range (similar to Parkinson). The second term ln(C/O)^2 captures the open-to-close movement. By combining both, Garman-Klass achieves approximately 7.4x the efficiency of close-to-close volatility -- meaning it produces equally accurate estimates with far fewer data points.

This makes Garman-Klass the gold standard among single-estimator volatility measures. It is strictly better than Parkinson because it uses additional information (open and close) at no extra cost. The only limitation it does not address is overnight gaps -- the drift between one candle's close and the next candle's open. For that, you need Yang-Zhang volatility.

Format

gk_vol_{period}

The period defines how many candles the estimator averages over.

Period range: 5 to 500.

Value range: 0 to infinity (annualized volatility, always positive). Typical crypto range: 0.005 to 0.15.

Understanding GK Vol Values

Like Parkinson, GK Vol values are annualized volatility estimates expressed as decimals. They are not bounded to a fixed range. Values depend on the asset, timeframe, and market conditions.

Understanding Operators with GK Vol

Each operator behaves differently with GK Vol. As a filter indicator measuring market conditions rather than direction, GK Vol is almost always combined with directional triggers.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where GK Vol is below the threshold.

On the chart: Volatility is compressed across all dimensions -- small wicks and small candle bodies. The market is coiling. This state-based trigger stays active for as long as GK Vol remains below the threshold.

[[actions.triggers]]
indicator = "gk_vol_20"
operator = "<"
target = "0.03"
timeframe = "1h"

Typical use: Squeeze detection. When GK Vol is low, both the range and the body of candles are small. This is an even more comprehensive squeeze signal than Parkinson alone, because it confirms that neither the wicks nor the closes are showing significant movement.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where GK Vol is above the threshold.

On the chart: Volatility is elevated. Candles have large bodies, large wicks, or both. The market is making decisive moves.

[[actions.triggers]]
indicator = "gk_vol_20"
operator = ">"
target = "0.08"
timeframe = "1h"

Typical use: High-volatility filter. Either avoid entries during chaotic conditions, or require that enough volatility exists for trades to be profitable after fees and slippage.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where GK Vol transitions from above the threshold to below it. The previous candle had GK Vol >= the target, and the current candle has GK Vol < the target.

[[actions.triggers]]
indicator = "gk_vol_20"
operator = "cross_below"
target = "0.04"
timeframe = "1h"

Typical use: Detect the transition into a low-volatility regime. The market has just calmed down after a volatile period. This can signal the beginning of a consolidation phase that will eventually resolve with a breakout.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where GK Vol transitions from below the threshold to above it. The previous candle had GK Vol <= the target, and the current candle has GK Vol > the target.

[[actions.triggers]]
indicator = "gk_vol_20"
operator = "cross_above"
target = "0.06"
timeframe = "1h"

Typical use: Detect the moment volatility expands. This captures the exact transition from a quiet market to an active one. A volatility expansion often marks the start of a new trend -- combine with a directional indicator (RSI, ROC, EMA cross) to determine which side to trade.

= (Equal) -- Not Recommended for GK Vol

Why: GK Vol produces floating-point values calculated to many decimal places. Exact equality will almost never be true. Use < or > instead.

TOML Examples

Moderate Volatility with Trend Entry

Enter when GK Vol shows the market is in a healthy range (not too quiet, not too chaotic) and the EMA signals a bullish trend.

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

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = ">"
  target = "0.02"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = "<"
  target = "0.08"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "ema_21"
  operator = ">"
  target = "ema_55"
  timeframe = "1h"

GK Vol Band Filter -- Goldilocks Zone

Only trade when volatility is in the "goldilocks zone" -- enough movement for profitable trades, but not so much that risk is uncontrollable. Combine with an RSI dip entry.

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

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = ">"
  target = "0.025"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = "<"
  target = "0.07"
  timeframe = "1h"

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

EMA Cross with Volatility Confirmation

Only act on an EMA crossover when GK Vol confirms the market has enough energy for the trend to follow through.

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

  [[actions.triggers]]
  indicator = "ema_9"
  operator = "cross_above"
  target = "ema_21"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = ">"
  target = "0.03"
  timeframe = "1h"

Volatility Regime Change Detection

Detect the exact moment the market transitions from low to higher volatility. When GK Vol crosses above the threshold while momentum is positive, ride the expansion.

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

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = "cross_above"
  target = "0.04"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "roc_10"
  operator = ">"
  target = "1"
  timeframe = "1h"

Tips

YZ Vol -- Yang-Zhang Volatility Estimator

Contents

• Format
• Understanding YZ Vol Values
• Understanding Operators with YZ Vol
  • < Less Than
  • > Greater Than
  • cross_below
  • cross_above
  • = Equal
• TOML Examples
  • Ultra-Calm Market RSI Dip Buy
  • YZ Vol Spike -- Exit or Avoid
  • Triple Volatility Confirmation Squeeze
  • Regime-Based Trend Entry
• Tips

Overview

Yang-Zhang Volatility is the most comprehensive classical volatility estimator. Developed by Dennis Yang and Qiang Zhang in 2000, it combines three separate volatility components into a single, robust measure:

1. Overnight volatility -- the variance of the open relative to the previous close (captures inter-candle drift).
2. Open-to-close volatility -- the variance of the close relative to the open (captures intraday directional movement).
3. Rogers-Satchell volatility -- a component similar to Garman-Klass that uses high, low, open, and close (captures intraday range efficiently).

The formula optimally weights these three components to minimize the estimator's variance:

YZ = sqrt( overnight_var + k * open_close_var + (1 - k) * rogers_satchell_var )

Where k is chosen to minimize the total variance of the estimator.

What makes Yang-Zhang unique is its handling of overnight drift -- the gap between one candle's close and the next candle's open. Parkinson and Garman-Klass both assume this gap is zero, which is incorrect whenever there are jumps between candles. While cryptocurrency markets trade 24/7 (no true "overnight" close), there are still meaningful open-vs-previous-close differences caused by rapid price movement between candles, exchange maintenance windows, and liquidity gaps. Yang-Zhang captures this drift, producing the most robust volatility estimate when market patterns are irregular.

Format

yz_vol_{period}

The period defines how many candles the estimator averages over.

Period range: 5 to 500.

Value range: 0 to infinity (annualized volatility, always positive). Typical crypto range: 0.005 to 0.12.

Understanding YZ Vol Values

Yang-Zhang values are annualized volatility estimates expressed as decimals. Like all volatility estimators, they are not bounded to a fixed range and depend on the asset, timeframe, and market conditions.

Understanding Operators with YZ Vol

Each operator behaves differently with YZ Vol. As the most comprehensive volatility filter indicator, YZ Vol is almost always combined with directional entry signals.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where YZ Vol is below the threshold.

On the chart: The market is calm on every dimension -- small wicks, small bodies, and minimal drift between candles. This is the most thorough squeeze confirmation available from a single indicator.

[[actions.triggers]]
indicator = "yz_vol_20"
operator = "<"
target = "0.025"
timeframe = "1h"

Typical use: High-confidence squeeze detection. When YZ Vol is low, it means not only are the candles small, but there is minimal jump between consecutive candle opens and prior closes. The market is truly quiet. Combine with a directional trigger to enter when the squeeze resolves.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where YZ Vol is above the threshold.

On the chart: Volatility is elevated across all components. The market is making large moves and potentially gapping between candles.

[[actions.triggers]]
indicator = "yz_vol_20"
operator = ">"
target = "0.08"
timeframe = "1h"

Typical use: Volatile market filter. Use > to avoid entering new positions when the market is chaotic, or to exit existing positions when volatility spikes to dangerous levels. YZ Vol > threshold as an exit trigger captures risk expansion that other estimators might miss.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where YZ Vol transitions from above the threshold to below it. The previous candle had YZ Vol >= the target, and the current candle has YZ Vol < the target.

[[actions.triggers]]
indicator = "yz_vol_20"
operator = "cross_below"
target = "0.04"
timeframe = "1h"

Typical use: Detect the exact moment the market settles into a calm regime. Volatility has just dropped below the threshold -- the market is transitioning from active to quiet. This begins the watch period for a squeeze breakout setup.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where YZ Vol transitions from below the threshold to above it. The previous candle had YZ Vol <= the target, and the current candle has YZ Vol > the target.

[[actions.triggers]]
indicator = "yz_vol_20"
operator = "cross_above"
target = "0.06"
timeframe = "1h"

Typical use: Detect the moment volatility expands from a calm state. The market was quiet and is now making larger, more gapped moves. This regime change often marks the beginning of a significant trending move. Combine with direction indicators to trade the expansion.

= (Equal) -- Not Recommended for YZ Vol

Why: YZ Vol produces floating-point values calculated to many decimal places. Exact equality will almost never be true. Use < or > instead.

TOML Examples

Ultra-Calm Market RSI Dip Buy

When YZ Vol confirms an ultra-calm market and RSI drops into oversold territory, buy the dip. The logic: in a truly quiet market, an RSI dip is more likely a temporary pullback than the start of a crash.

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

  [[actions.triggers]]
  indicator = "yz_vol_20"
  operator = "<"
  target = "0.02"
  timeframe = "1h"

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

YZ Vol Spike -- Exit or Avoid

When volatility explodes above the danger threshold, exit the position. A sudden YZ Vol spike means the market has become unpredictable, with large gaps between candles.

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

  [[actions.triggers]]
  indicator = "yz_vol_20"
  operator = "cross_above"
  target = "0.10"
  timeframe = "1h"

Triple Volatility Confirmation Squeeze

The highest-confidence squeeze setup: require all three volatility estimators (Parkinson, GK Vol, and YZ Vol) to confirm low volatility simultaneously. When all three agree, enter on a bullish RSI signal.

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

  [[actions.triggers]]
  indicator = "parkinson_20"
  operator = "<"
  target = "0.02"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "gk_vol_20"
  operator = "<"
  target = "0.025"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "yz_vol_20"
  operator = "<"
  target = "0.025"
  timeframe = "1h"

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

Regime-Based Trend Entry

Use YZ Vol to confirm the market is in a moderate volatility regime (trending, not chaotic), then enter on an EMA crossover with a macro trend filter.

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

  [[actions.triggers]]
  indicator = "yz_vol_20"
  operator = ">"
  target = "0.02"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "yz_vol_20"
  operator = "<"
  target = "0.07"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "ema_9"
  operator = "cross_above"
  target = "ema_21"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

Tips

OBV -- On-Balance Volume

Contents

• Format
• How OBV Works
• Understanding Operators with OBV
  • cross_above OBV Crosses Above Its SMA
  • cross_below OBV Crosses Below Its SMA
  • > OBV Above Its SMA
  • < OBV Below Its SMA
• TOML Examples
  • Buying Pressure Emerges
  • Volume Momentum Exit
  • OBV Crossover with Price Breakout
  • Full OBV Strategy (Entry + Exit)
• Tips

Overview

On-Balance Volume (OBV) is a cumulative volume indicator that connects volume flow to price direction. It answers a simple question: is more volume flowing into the asset (buying pressure) or out of it (selling pressure)?

The calculation is straightforward:

• If the current candle closes higher than the previous candle, the candle's volume is added to the running OBV total.
• If the current candle closes lower than the previous candle, the candle's volume is subtracted from the running OBV total.
• If the close is unchanged, OBV stays the same.

The result is a running total that rises when buying dominates and falls when selling dominates. The absolute value of OBV is meaningless on its own -- what matters is its direction and how it relates to price.

Why OBV matters: Volume leads price. If OBV is rising while price is flat, smart money may be accumulating -- a breakout could follow. If price makes a new high but OBV does not, the rally lacks conviction and may reverse.

Format

OBV has two related formats:

OBV SMA examples:

Value range: Unbounded. OBV can be any positive or negative number depending on cumulative volume flow. The scale depends entirely on the asset's trading volume.

How OBV Works

Rising OBV: Volume is flowing into the asset on up-candles more than it is flowing out on down-candles. Buyers are in control. If price is also rising, the uptrend is healthy and supported by volume.

Falling OBV: Volume is flowing out on down-candles more than it is flowing in on up-candles. Sellers are in control. If price is also falling, the downtrend has conviction.

OBV Divergence: The most powerful OBV signal. When price and OBV move in opposite directions, something is changing beneath the surface:

• Bullish divergence: Price makes a lower low, but OBV makes a higher low. Selling pressure is diminishing despite the price drop. A reversal upward may be imminent.
• Bearish divergence: Price makes a higher high, but OBV makes a lower high. Buying pressure is weakening despite the price rise. A reversal downward may follow.

OBV vs. OBV SMA: The raw OBV line is noisy. Smoothing it with an SMA creates a baseline for crossover signals -- the same way a moving average smooths price. When OBV crosses above its SMA, volume momentum is turning bullish. When it crosses below, volume momentum is turning bearish.

Understanding Operators with OBV

OBV is most commonly used with crossover operators against its own SMA. This is its primary signal mechanism.

cross_above -- OBV Crosses Above Its SMA

What it does: Fires once at the exact candle where OBV transitions from below its SMA to above it. Volume momentum has just turned bullish.

On the chart: The OBV line was sitting below its smoothed average, then climbs above it. This moment marks the shift from net selling pressure to net buying pressure (relative to recent history).

[[actions.triggers]]
indicator = "obv"
operator = "cross_above"
target = "obv_sma_20"
timeframe = "1h"

Typical use: Entry signal. OBV crossing above its SMA confirms that buying volume is increasing. This is the primary OBV buy signal and pairs well with price-based triggers.

cross_below -- OBV Crosses Below Its SMA

What it does: Fires once at the exact candle where OBV transitions from above its SMA to below it. Volume momentum has just turned bearish.

On the chart: The OBV line drops below its smoothed average. Selling volume is now outpacing buying volume relative to recent history.

[[actions.triggers]]
indicator = "obv"
operator = "cross_below"
target = "obv_sma_20"
timeframe = "1h"

Typical use: Exit signal or short entry. When OBV drops below its SMA, the buying pressure that supported the price move is fading.

> OBV Above Its SMA -- State-Based

What it does: True on every candle where OBV remains above its SMA. Volume momentum is currently bullish.

[[actions.triggers]]
indicator = "obv"
operator = ">"
target = "obv_sma_20"
timeframe = "1h"

Typical use: Trend filter. Use this alongside another entry trigger to gate trades so they only execute when volume momentum is favorable. "Buy RSI dips only when OBV is above its SMA."

< OBV Below Its SMA -- State-Based

What it does: True on every candle where OBV remains below its SMA. Volume momentum is currently bearish.

[[actions.triggers]]
indicator = "obv"
operator = ">"
target = "obv_sma_20"
timeframe = "1h"

Typical use: Bearish filter. Avoid opening long positions when selling pressure dominates. Can also be used as an exit condition.

TOML Examples

Buying Pressure Emerges

Enter when OBV crosses above its 20-period SMA on the 1-hour chart. This signals that buying volume is starting to dominate.

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

  [[actions.triggers]]
  indicator = "obv"
  operator = "cross_above"
  target = "obv_sma_20"
  timeframe = "1h"

Volume Momentum Exit

Exit the position when OBV drops below its SMA. The buying pressure that justified the entry has faded.

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

  [[actions.triggers]]
  indicator = "obv"
  operator = "cross_below"
  target = "obv_sma_20"
  timeframe = "1h"

OBV Crossover with Price Breakout

Combine OBV with a Bollinger Band breakout to confirm that the price move has real volume behind it. This filters out low-conviction breakouts.

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

  [[actions.triggers]]
  indicator = "price"
  operator = "cross_above"
  target = "bb_upper"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "obv"
  operator = ">"
  target = "obv_sma_20"
  timeframe = "1h"

Full OBV Strategy (Entry + Exit)

Enter on bullish OBV crossover with RSI confirmation, exit on bearish OBV crossover or fixed profit.

[meta]
name = "OBV_Volume_Momentum"
description = "Enter on OBV bullish cross + RSI dip, exit on bearish cross or +3%"

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

  [[actions.triggers]]
  indicator = "obv"
  operator = "cross_above"
  target = "obv_sma_20"
  timeframe = "1h"

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

# TAKE PROFIT
[[actions]]
type = "sell"
amount = "100%"

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

# VOLUME EXIT
[[actions]]
type = "sell"
amount = "100%"

  [[actions.triggers]]
  indicator = "obv"
  operator = "cross_below"
  target = "obv_sma_20"
  timeframe = "1h"

Tips

Volume SMA

Contents

• Format
• How Volume SMA Works
• Understanding Operators with Volume SMA
  • > Above Average Volume
  • < Below Average Volume
  • cross_above Volume Spike Begins
  • cross_below Volume Returns to Normal
• TOML Examples
  • Confirm Breakout with High Volume
  • Detect Low-Volume Consolidation
  • Volume Spike Entry
  • Multi-Signal Breakout with Volume Confirmation
• Tips

Overview

Volume SMA calculates the Simple Moving Average of trading volume over the last N candles. It establishes a baseline for what "normal" volume looks like, so you can detect when trading activity is unusually high or unusually low.

Volume is the fuel behind price moves. A price breakout on high volume carries conviction -- many participants are driving the move. A breakout on low volume is suspect -- it may lack the momentum to sustain itself and could reverse quickly.

By comparing current volume to its average, you turn raw volume into an actionable signal: is trading activity above or below normal right now?

Format

vol_sma_{period}

The period defines how many candles are averaged to establish the "normal" volume baseline.

Period range: 1 to 200.

Value range: 0+ (always positive, volume-denominated). The actual values depend entirely on the asset and timeframe. BTC on hourly candles might have a vol_sma_20 of 500 BTC. A small-cap altcoin might have a vol_sma_20 of 10,000 tokens. Never compare Volume SMA values across different pairs.

How Volume SMA Works

Current volume above Volume SMA: Trading activity is above the recent average. Something is happening -- a breakout, news event, or institutional activity. Price moves during above-average volume are more likely to sustain.

Current volume below Volume SMA: Trading activity is below the recent average. The market is quiet. Price moves during below-average volume often lack follow-through and may reverse. This is typical of consolidation phases.

Volume spike: When current volume crosses from below to above its SMA, a volume surge has begun. This is the event-based way to detect the start of unusual activity.

Volume drying up: When current volume drops below its SMA, the market is settling down. If this happens after a big move, it may signal that the move is losing steam.

Understanding Operators with Volume SMA

Volume SMA is typically used as a confirmation filter -- you pair it with a price-based trigger to ensure the price move has volume backing it.

> Above Average Volume -- State-Based

What it does: True on every candle where current volume exceeds the Volume SMA. Trading activity is above average.

[[actions.triggers]]
indicator = "vol_sma_20"
operator = ">"
target = "0"
timeframe = "1h"

Typical use: Confirmation layer. Add this trigger to a price breakout action so it only fires when volume is elevated. "Buy when price breaks above the upper Bollinger Band AND volume is above average."

< Below Average Volume -- State-Based

What it does: True on every candle where current volume is below the Volume SMA. The market is quiet.

Typical use: Detect consolidation. Low-volume periods often precede breakouts. You can also use this to avoid entering trades during dead markets where price moves are unreliable.

cross_above -- Volume Spike Begins

What it does: Fires once at the exact candle where volume transitions from below the SMA to above it. A volume surge has just started.

[[actions.triggers]]
indicator = "vol_sma_20"
operator = "cross_above"
target = "0"
timeframe = "1h"

Typical use: Detect the start of a volume spike. Combine with a trend filter to determine if the spike is bullish or bearish. Volume alone does not tell you direction -- it tells you that something significant is happening.

cross_below -- Volume Returns to Normal

What it does: Fires once when volume drops from above the SMA to below it. The surge is ending.

Typical use: Detect when a high-volume event is winding down. Can be used as a trailing exit signal -- if you entered on a volume spike, exit when volume normalizes.

TOML Examples

Confirm Breakout with High Volume

Only enter on a Bollinger Band breakout when volume confirms the move. Price above the upper band with elevated volume signals a genuine breakout, not a low-conviction spike.

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

  [[actions.triggers]]
  indicator = "price"
  operator = "cross_above"
  target = "bb_upper"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "vol_sma_20"
  operator = ">"
  target = "0"
  timeframe = "1h"

Detect Low-Volume Consolidation

Avoid buying RSI dips during dead markets. Low volume + oversold RSI often means the market is drifting, not reversing. Wait for volume to confirm interest.

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

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

  [[actions.triggers]]
  indicator = "obv"
  operator = ">"
  target = "obv_sma_20"
  timeframe = "1h"

Volume Spike Entry

Enter when a volume surge begins during an uptrend. The MACD filter ensures the trend is bullish, and the volume crossover catches the moment activity spikes.

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = ">"
  target = "0"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "vol_sma_20"
  operator = "cross_above"
  target = "0"
  timeframe = "1h"

Multi-Signal Breakout with Volume Confirmation

A high-confidence entry: price crosses above the 50-period SMA, MACD is bullish, and volume is above average. Three independent signals aligning greatly reduces false positives.

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

  [[actions.triggers]]
  indicator = "price"
  operator = "cross_above"
  target = "sma_50"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "macd_line"
  operator = ">"
  target = "0"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "vol_sma_20"
  operator = ">"
  target = "0"
  timeframe = "1h"

Tips

TTM Trend

Contents

• Format
• TTM Trend Values
• Understanding Operators with TTM Trend
  • = Equals -- The Primary Operator
  • > Greater Than
  • < Less Than
  • cross_above / cross_below
• TOML Examples
  • Only Enter During Uptrend
  • Exit on Downtrend Confirmation
  • RSI Dip Buy with Trend Filter
  • Full Trend-Filtered Strategy (Entry + Exit)
• Tips

Overview

TTM Trend is a simplified trend direction indicator that distills the current market regime into one of three discrete values: bullish, neutral, or bearish. Instead of producing a continuous range of values like RSI or MACD, TTM Trend gives you a clean, unambiguous answer: what direction is the trend?

This makes TTM Trend uniquely suited for use as a trend gate -- a filter that allows or blocks trades based on the current trend direction. Rather than trying to time exact entries with TTM Trend, you use it to ensure that your other signals (RSI dips, MACD crossovers, Bollinger touches) only fire when the broader trend supports the trade.

Format

ttm_trend

TTM Trend has no period parameter. It uses a fixed internal calculation to determine trend direction. The format is always just ttm_trend.

Value range: Discrete integers only -- 1, 0, or -1.

TTM Trend Values

Understanding Operators with TTM Trend

TTM Trend is the primary use case for the = operator. Its discrete values make equality comparisons meaningful and reliable.

= (Equals) -- The Primary Operator

What it does: True on every candle where TTM Trend equals the specified value. This is a state-based operator -- it fires as long as the condition holds.

Bullish gate (= 1):

[[actions.triggers]]
indicator = "ttm_trend"
operator = "="
target = "1"
timeframe = "1h"

This fires on every candle where the hourly trend is bullish. Use it as a filter alongside entry triggers to prevent buying in downtrends or neutral markets.

Bearish gate (= -1):

[[actions.triggers]]
indicator = "ttm_trend"
operator = "="
target = "-1"
timeframe = "1h"

This fires on every candle where the trend is bearish. Use it as an exit condition -- when the trend turns against your position, close it.

Neutral gate (= 0):

[[actions.triggers]]
indicator = "ttm_trend"
operator = "="
target = "0"
timeframe = "1h"

This fires when the market has no clear direction. Useful for avoiding trades during choppy, directionless periods.

> (Greater Than) -- Not Bearish

What it does: True when TTM Trend is greater than the target value. Since TTM Trend only outputs -1, 0, and 1:

• ttm_trend > 0 is true when TTM Trend = 1 (bullish only).
• ttm_trend > -1 is true when TTM Trend = 0 or 1 (not bearish).

[[actions.triggers]]
indicator = "ttm_trend"
operator = ">"
target = "0"
timeframe = "1h"

Typical use: A slightly looser filter than = 1. Allows trades when the trend is bullish. Since there is only one integer above 0 (which is 1), this behaves identically to = 1 in practice.

The more useful form is > -1 (not bearish), which allows trades in both bullish and neutral conditions:

[[actions.triggers]]
indicator = "ttm_trend"
operator = ">"
target = "-1"
timeframe = "1h"

< (Less Than) -- Not Bullish

What it does: True when TTM Trend is less than the target value.

• ttm_trend < 0 is true when TTM Trend = -1 (bearish only).
• ttm_trend < 1 is true when TTM Trend = 0 or -1 (not bullish).

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

Typical use: Exit filter. Close positions when the trend is no longer bullish. Using < 1 catches both the neutral and bearish states -- a more conservative exit than waiting for full bearish confirmation.

cross_above / cross_below -- Trend Transitions

What they do: Fire once at the moment TTM Trend transitions through a value. Because TTM Trend changes in discrete steps (e.g., from 0 to 1), these operators catch the exact candle where the trend regime shifts.

# Trend just turned bullish
[[actions.triggers]]
indicator = "ttm_trend"
operator = "cross_above"
target = "0"
timeframe = "1h"

# Trend just turned bearish
[[actions.triggers]]
indicator = "ttm_trend"
operator = "cross_below"
target = "0"
timeframe = "1h"

Typical use: Catching the moment a trend change occurs. Unlike = which fires on every candle during the trend, cross_above fires once at the transition. This is useful for one-time entries or exits at the trend shift.

TOML Examples

Only Enter During Uptrend

Gate RSI entries so they only fire when the hourly trend is bullish. This prevents buying oversold dips in a downtrend -- a common trap.

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

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

  [[actions.triggers]]
  indicator = "ttm_trend"
  operator = "="
  target = "1"
  timeframe = "1h"

Exit on Downtrend Confirmation

Sell the entire position when the trend turns bearish. This acts as a trend-based stop-loss.

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

  [[actions.triggers]]
  indicator = "ttm_trend"
  operator = "="
  target = "-1"
  timeframe = "1h"

RSI Dip Buy with Trend Filter

A refined dip-buying strategy. The daily TTM Trend confirms the macro direction is bullish, while the hourly RSI catches oversold dips for entry timing. Multi-timeframe confirmation.

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

  [[actions.triggers]]
  indicator = "ttm_trend"
  operator = "="
  target = "1"
  timeframe = "1d"

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

  [[actions.triggers]]
  indicator = "macd_line"
  operator = ">"
  target = "0"
  timeframe = "1h"

Full Trend-Filtered Strategy (Entry + Exit)

Enter on RSI dips in an uptrend, exit when the trend turns bearish or a profit target is hit.

[meta]
name = "Trend_Filtered_DCA"
description = "Buy RSI dips in uptrend, exit on trend reversal or +4%"

# ENTRY -- only in uptrend
[[actions]]
type = "open_long"
amount = "100 USDC"

  [[actions.triggers]]
  indicator = "ttm_trend"
  operator = "="
  target = "1"
  timeframe = "1h"

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

# TAKE PROFIT
[[actions]]
type = "sell"
amount = "100%"

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

# TREND EXIT
[[actions]]
type = "sell"
amount = "100%"

  [[actions.triggers]]
  indicator = "ttm_trend"
  operator = "="
  target = "-1"
  timeframe = "1h"

Tips

Price

Contents

• Format
• How Price Works in Triggers
• Understanding Operators with Price
  • < Price Below a Level
  • > Price Above a Level
  • cross_above Price Crossing Above
  • cross_below Price Crossing Below
  • = Exact Price -- Rarely Useful
• TOML Examples
  • Price Below Bollinger Lower Band
  • Price Above Long-Term Moving Average
  • Price Crosses Above EMA
  • Absolute Price Target
• Tips

Overview

price is not a calculated indicator -- it is the current candle's closing price. It allows you to compare raw price directly against indicator values, moving averages, Bollinger Bands, or fixed numeric levels.

Every other indicator in Botmarley derives a signal from price. Sometimes, though, you want to work with price itself: "Is the price above the 200-period SMA?" or "Has price dropped below the lower Bollinger Band?" or "Is price above 100,000?" The price field makes these comparisons possible.

This gives you the building block for classic technical analysis rules: support/resistance levels, moving average crossovers from price's perspective, and price-relative-to-band signals.

Format

price

Price has no period parameter. It always represents the close of the current candle on the specified timeframe. The format is simply price.

Value range: The actual market price of the asset. For BTC, this might be 50,000--100,000+. For a small-cap altcoin, it might be 0.001. Values are always positive.

How Price Works in Triggers

Price is unique because it can be used on either side of a trigger -- as the indicator or as the target.

Price as the indicator:

indicator = "price"
operator = "<"
target = "bb_lower"

Read as: "price is below the lower Bollinger Band."

Price as the target:

indicator = "bb_lower"
operator = ">"
target = "price"

Read as: "the lower Bollinger Band is above price." This is logically identical to the first form -- both mean price is below the lower Bollinger Band.

Price compared to a fixed value:

indicator = "price"
operator = ">"
target = "100000"

Read as: "price is above 100,000." This allows you to set absolute level-based triggers.

The flexibility of price means you can express the same condition in multiple ways. Choose whichever reads most naturally to you. Most traders find indicator = "price" with the comparison target to be the most intuitive form.

Understanding Operators with Price

All five operators work with price. The behavior follows the same state-based vs. event-based rules as other indicators.

< Price Below a Level -- State-Based

What it does: True on every candle where price is below the target value. This is a sustained condition.

[[actions.triggers]]
indicator = "price"
operator = "<"
target = "bb_lower"
timeframe = "1h"

On the chart: Price is sitting below the lower Bollinger Band. For as long as it stays there, this trigger fires on every candle. Use max_count to limit repeated firing, or switch to cross_below if you only want the initial break.

Common pairings:

• price < bb_lower -- below the volatility envelope (oversold by Bollinger standards)
• price < sma_200 -- below the long-term moving average (bearish territory)
• price < ema_50 -- below the medium-term trend line

> Price Above a Level -- State-Based

What it does: True on every candle where price is above the target value. This is a sustained condition.

[[actions.triggers]]
indicator = "price"
operator = ">"
target = "sma_200"
timeframe = "1d"

Typical use: Trend filter. "Only allow entries when price is above the 200-day SMA" -- a classic bull-market confirmation. Because this is state-based, it works perfectly as a background filter for other entry signals.

Common pairings:

• price > sma_200 -- above the long-term trend (bullish territory)
• price > bb_upper -- above the volatility envelope (breakout or overbought)
• price > ema_20 -- above the short-term trend

cross_above -- Price Crossing Above

What it does: Fires once at the exact candle where price transitions from below the target to above it. The previous candle's close was at or below the target; the current candle's close is above it.

[[actions.triggers]]
indicator = "price"
operator = "cross_above"
target = "ema_50"
timeframe = "1h"

On the chart: Price was below the EMA(50) line, then closes above it. This crossing moment fires the trigger once. This is the classic "golden cross from price's perspective" -- the moment price reclaims a key moving average.

Typical use: Breakout entries. When price crosses above a significant level (moving average, Bollinger middle band), it signals a potential trend shift. Event-based operators fire once, making them ideal for entry signals without needing max_count.

cross_below -- Price Crossing Below

What it does: Fires once at the exact candle where price transitions from above the target to below it.

[[actions.triggers]]
indicator = "price"
operator = "cross_below"
target = "sma_50"
timeframe = "1h"

Typical use: Breakdown signals. Price dropping below a key moving average can signal trend weakness. Use as an exit trigger or as a warning that the trend is changing.

= Exact Price -- Rarely Useful

What it does: True only when price exactly equals the target value.

[[actions.triggers]]
indicator = "price"
operator = "="
target = "100000"

TOML Examples

Price Below Bollinger Lower Band

The classic Bollinger Bounce entry. Price has extended more than 2 standard deviations below the mean -- a statistically significant move that often reverts.

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

  [[actions.triggers]]
  indicator = "price"
  operator = "<"
  target = "bb_lower"
  timeframe = "1h"

Price Above Long-Term Moving Average

Use price above the 200-period SMA on the daily chart as a macro trend filter. Only allow entries when the market is in confirmed bullish territory.

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

  [[actions.triggers]]
  indicator = "price"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

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

Price Crosses Above EMA

Enter when price reclaims the 50-period EMA. This catches the moment price moves back above the medium-term trend line -- a potential trend resumption signal.

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

  [[actions.triggers]]
  indicator = "price"
  operator = "cross_above"
  target = "ema_50"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "macd_line"
  operator = ">"
  target = "0"
  timeframe = "1h"

Absolute Price Target

Sell when price breaks above a specific level. Useful for taking profit at a predetermined price target.

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

  [[actions.triggers]]
  indicator = "price"
  operator = "cross_above"
  target = "100000"
  timeframe = "1h"
  max_count = 1

Tips

RSTD -- Rolling Standard Deviation

Contents

• Format
• Understanding RSTD Values
• Understanding Operators with RSTD
  • > Greater Than
  • < Less Than
  • cross_above
  • cross_below
  • = Equal
• TOML Examples
  • Volatility Expansion: Short vs Long Period
  • Low Volatility Squeeze Entry
  • RSI Dip Buy with Volatility Filter
• Tips

Overview

Rolling Standard Deviation (RSTD) measures the dispersion of closing prices around their rolling mean over the last N candles. In simple terms, it tells you how spread out recent prices are -- it quantifies volatility based on close-to-close variation.

The calculation is straightforward: take the last N closing prices, compute their mean, then compute the standard deviation. A high RSTD means closing prices have been scattered far from their average -- the market is volatile. A low RSTD means closing prices are clustered tightly around their average -- the market is quiet and compressed.

The key distinction from ATR: ATR uses the high-low-close True Range, capturing intrabar volatility (wicks, gaps). RSTD uses only closing prices, capturing close-to-close variation. This makes RSTD the foundation for both Z-Score and Bollinger Bands. If you think of ATR as "how wide do candles get," think of RSTD as "how much do closes jump around." Both are volatility measures, but they capture different dimensions of it.

Format

rstd_{period}

The period defines the lookback window -- how many closing prices are included in the standard deviation calculation.

Period range: 5 to 500.

Value range: 0 to infinity (always positive, denominated in the asset's price currency -- same units as price and ATR).

Understanding RSTD Values

Like ATR, RSTD values are not normalized to a fixed scale. They are denominated in the same currency as the asset's price. This means RSTD thresholds must be calibrated per asset and timeframe.

Understanding Operators with RSTD

Each operator behaves differently with RSTD. Because RSTD is a volatility filter (it describes the market's current dispersion, not direction), it is almost always used in combination with directional triggers.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where RSTD is above the threshold.

On the chart: Price dispersion is elevated. Closing prices are jumping around significantly from candle to candle. This trigger stays active for as long as RSTD remains above the threshold.

[[actions.triggers]]
indicator = "rstd_20"
operator = ">"
target = "400"
timeframe = "1h"

Typical use: "Only trade when close-to-close variation is high enough." High RSTD means there is enough directional movement in closing prices to justify entry. This filters out sideways chop where candles have large wicks but close near each other.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where RSTD is below the threshold.

On the chart: Price dispersion is compressed. Closes are clustering tightly around the mean -- a volatility squeeze. This is the setup phase before many breakouts.

[[actions.triggers]]
indicator = "rstd_20"
operator = "<"
target = "150"
timeframe = "1h"

Typical use: Detect low-dispersion squeeze environments. When RSTD drops to unusually low levels, it means prices are coiling. Combine with a directional breakout trigger to enter when the squeeze resolves.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where RSTD transitions from below the threshold to above it. The previous candle had RSTD <= the target, and the current candle has RSTD > the target.

[[actions.triggers]]
indicator = "rstd_20"
operator = "cross_above"
target = "300"
timeframe = "1h"

Typical use: Detect the moment volatility expands. This captures the transition from a compressed market to a dispersed one -- the squeeze is breaking. Combine with a directional indicator (RSI, ROC, or MACD) to determine entry direction.

cross_below -- Event-Based

What it does: Fires once, at the exact candle where RSTD transitions from above the threshold to below it. The previous candle had RSTD >= the target, and the current candle has RSTD < the target.

[[actions.triggers]]
indicator = "rstd_20"
operator = "cross_below"
target = "200"
timeframe = "1h"

Typical use: Detect the moment volatility contracts. Useful for exiting positions when the market quiets down, or for initiating squeeze-detection logic -- once RSTD drops below the threshold, start watching for a breakout.

= (Equal) -- Not Recommended for RSTD

Why: RSTD produces floating-point values that are rarely exactly equal to any specific number. Use > or < instead.

TOML Examples

Volatility Expansion: Short vs Long Period

Compare short-period RSTD against long-period RSTD to detect volatility expansion. When the fast RSTD exceeds the slow RSTD, recent volatility is accelerating relative to the longer-term norm -- a breakout may be underway. Combine with positive momentum to enter long.

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

  [[actions.triggers]]
  indicator = "rstd_20"
  operator = ">"
  target = "rstd_50"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "roc_10"
  operator = ">"
  target = "1.5"
  timeframe = "1h"

Low Volatility Squeeze Entry

Wait for a volatility squeeze (RSTD drops to unusually low levels) and then enter when price breaks above the upper Bollinger Band. The combination of compressed volatility + directional breakout often produces outsized moves.

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

  [[actions.triggers]]
  indicator = "rstd_20"
  operator = "<"
  target = "150"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "price"
  operator = ">"
  target = "bb_upper"
  timeframe = "1h"

RSI Dip Buy with Volatility Filter

A classic dip-buy strategy enhanced with an RSTD filter. Only enter when RSI is oversold AND close-to-close dispersion is high enough that a meaningful bounce is likely. This avoids buying dips in dead, flat markets where the "bounce" is a few cents.

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

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

  [[actions.triggers]]
  indicator = "rstd_20"
  operator = ">"
  target = "300"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

Tips

Z-Score -- Standard Score

Contents

• Format
• Understanding Z-Score Values
• Understanding Operators with Z-Score
  • > Greater Than
  • < Less Than
  • cross_above
  • cross_below
  • = Equal
• TOML Examples
  • Mean Reversion at Statistical Extreme
  • Exit When Mean Reversion Completes
  • Z-Score with Trend Filter
  • Multi-Timeframe Z-Score Confluence
• Tips

Overview

Z-Score measures how many standard deviations the current price is from its rolling mean. The formula is: Z = (price - mean) / standard_deviation, where both the mean and standard deviation are calculated over the last N closing prices.

The result translates raw price into a universal, dimensionless scale. A Z-Score of -2 means the current price is 2 standard deviations below the recent average -- statistically, this puts it in approximately the bottom 2.5% of the recent price distribution (assuming normality). A Z-Score of +2 means the opposite: price is in the top 2.5%.

This universality is what makes Z-Score powerful. Unlike ATR or RSTD, where thresholds must be recalibrated for every asset and timeframe, Z-Score thresholds are asset-agnostic. A Z-Score of -2 means "statistically cheap relative to recent history" whether you are trading BTC at $60,000 or SOL at $150. This makes Z-Score one of the most portable indicators for mean-reversion strategies -- you write the logic once, and it works across any pair.

Format

zscore_{period}

The period defines the lookback window used to calculate both the rolling mean and the rolling standard deviation.

Period range: 5 to 500.

Value range: Typically -4 to +4 (theoretically unbounded). 0 = price is exactly at its rolling mean. Negative = below mean. Positive = above mean.

Understanding Z-Score Values

Z-Score values are normalized and universal. The same thresholds apply across all assets and timeframes, which is a major advantage over price-denominated indicators like ATR and RSTD.

Understanding Operators with Z-Score

Z-Score is primarily a mean-reversion indicator. It tells you when price has deviated "too far" from its recent average. The operators let you define what "too far" means for your strategy.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where Z-Score is above the threshold.

On the chart: Price is elevated relative to its recent mean. The higher the Z-Score, the more statistically extended the price is. This trigger stays active for as long as the Z-Score remains above the threshold.

[[actions.triggers]]
indicator = "zscore_20"
operator = ">"
target = "2.0"
timeframe = "1h"

Typical use: "Price is statistically overbought -- consider taking profit or selling." When Z-Score exceeds +2.0, price is in the top ~2.5% of its recent range. For mean-reversion strategies, this is a sell or exit signal.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where Z-Score is below the threshold.

On the chart: Price is depressed relative to its recent mean. The more negative the Z-Score, the more statistically cheap the price is. This trigger stays active for as long as Z-Score remains below the threshold.

[[actions.triggers]]
indicator = "zscore_20"
operator = "<"
target = "-2.0"
timeframe = "1h"

Typical use: "Price is statistically oversold -- consider buying." When Z-Score drops below -2.0, price is in the bottom ~2.5% of its recent range. This is the classic mean-reversion buy signal. The assumption is that price will revert toward the mean.

cross_above -- Event-Based

What it does: Fires once, at the exact candle where Z-Score transitions from below the threshold to above it. The previous candle had Z-Score <= the target, and the current candle has Z-Score > the target.

[[actions.triggers]]
indicator = "zscore_20"
operator = "cross_above"
target = "0"
timeframe = "1h"

Typical use: Detect the moment price crosses back above the mean (Z-Score crosses above 0). In a mean-reversion strategy, this can signal that the reversion is complete -- price has returned to "normal." Also useful for detecting the moment price transitions into overbought territory (crossing above +2.0).

cross_below -- Event-Based

What it does: Fires once, at the exact candle where Z-Score transitions from above the threshold to below it. The previous candle had Z-Score >= the target, and the current candle has Z-Score < the target.

[[actions.triggers]]
indicator = "zscore_20"
operator = "cross_below"
target = "-2.0"
timeframe = "1h"

Typical use: Detect the exact moment price enters the oversold zone. Unlike < which stays active the entire time Z-Score is below -2.0, cross_below fires only at the transition -- ensuring you enter once per dip rather than on every candle during an extended decline.

= (Equal) -- Not Recommended for Z-Score

Why: Z-Score produces floating-point values that are rarely exactly equal to any specific number. Use > or < instead.

TOML Examples

Mean Reversion at Statistical Extreme

The classic Z-Score trade: buy when price drops to 2 standard deviations below the mean. This is a statistically rare event (~2.5% of the time under normal assumptions), and prices tend to revert toward the mean. Add a trend filter to avoid catching falling knives in a downtrend.

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

  [[actions.triggers]]
  indicator = "zscore_20"
  operator = "<"
  target = "-2.0"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "sma_50"
  operator = ">"
  target = "sma_200"
  timeframe = "1d"

Exit When Mean Reversion Completes

Close the position when Z-Score crosses back above +1.0 -- price has not only returned to the mean but has moved one standard deviation above it. This captures the full reversion move plus some continuation.

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

  [[actions.triggers]]
  indicator = "zscore_20"
  operator = "cross_above"
  target = "1.0"
  timeframe = "1h"

Z-Score with Trend Filter

Buy statistically cheap price levels, but only when the broader trend supports it. The Z-Score provides the entry timing (price is 2.5 standard deviations below the mean), while the EMA crossover confirms the macro trend is bullish. This prevents mean-reversion entries during sustained downtrends.

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

  [[actions.triggers]]
  indicator = "zscore_50"
  operator = "<"
  target = "-2.5"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "ema_21"
  operator = ">"
  target = "ema_55"
  timeframe = "1d"

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

Multi-Timeframe Z-Score Confluence

Enter only when Z-Score is oversold on BOTH the hourly and 4-hour timeframes. When two timeframes agree that price is statistically cheap, the mean-reversion signal is much stronger than a single-timeframe reading.

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

  [[actions.triggers]]
  indicator = "zscore_20"
  operator = "<"
  target = "-2.0"
  timeframe = "1h"

  [[actions.triggers]]
  indicator = "zscore_20"
  operator = "<"
  target = "-1.5"
  timeframe = "4h"

Tips

PRANK -- Percentile Rank

Contents

• Format
• Understanding Percentile Rank Values
• Understanding Operators with Percentile Rank
  • > Greater Than
  • < Less Than
  • cross_above
  • cross_below
  • = Equal
• TOML Examples
  • Buy the Bottom 5th Percentile
  • Exit at 60th Percentile
  • Percentile Rank with RSI Confluence
  • DCA at Different Percentile Levels
• Tips

Overview

Percentile Rank measures where the current closing price ranks among the last N closing prices, expressed as a percentage from 0 to 100. If the current price is the lowest close in the lookback window, the Percentile Rank is 0. If it is the highest, the Percentile Rank is 100. A value of 25 means the current price is higher than 25% of the closes in the window.

The calculation is simple: count how many of the last N closes are less than or equal to the current close, divide by N, and multiply by 100. No assumptions about distribution shape, no parameters beyond the lookback period. This simplicity is its strength.

The key advantage of Percentile Rank over Z-Score: it is distribution-free. Z-Score assumes prices are approximately normally distributed to interpret its thresholds (e.g., "Z = -2 means bottom 2.5%"). Percentile Rank makes no such assumption. A Percentile Rank of 5 means "the current price is in the bottom 5% of the last N closes" regardless of whether prices are normally distributed, skewed, or have fat tails. For crypto markets, where returns are decidedly non-normal, this non-parametric property is valuable. Percentile Rank tells you exactly what it says -- no statistical assumptions required.

Format

prank_{period}

The period defines the lookback window -- how many recent closing prices are compared against the current close.

Period range: 10 to 500.

Value range: 0 to 100 (always). 0 = current price is the lowest close in the window. 100 = current price is the highest close in the window.

Understanding Percentile Rank Values

Percentile Rank values are bounded between 0 and 100 and have an intuitive interpretation that does not depend on the asset or timeframe. A value of 10 means "cheaper than 90% of recent closes" whether you are looking at BTC on the hourly chart or ETH on the daily chart.

Understanding Operators with Percentile Rank

Percentile Rank is a contrarian positioning indicator. It tells you where price sits in the context of recent history. Extreme lows suggest buying opportunities; extreme highs suggest selling opportunities.

> (Greater Than) -- State-Based

What it does: The trigger is true on every candle where Percentile Rank is above the threshold.

On the chart: Price is ranking high among recent closes. The closer to 100, the closer price is to its recent high watermark. This trigger stays active for as long as the Percentile Rank remains above the threshold.

[[actions.triggers]]
indicator = "prank_100"
operator = ">"
target = "95"
timeframe = "1h"

Typical use: "Price is near the top of its recent range -- consider taking profit or reducing exposure." When Percentile Rank exceeds 95, the current price is higher than 95% of the last 100 closes. This is a contrarian signal that the move may be overextended.

< (Less Than) -- State-Based

What it does: The trigger is true on every candle where Percentile Rank is below the threshold.

On the chart: Price is ranking low among recent closes. The closer to 0, the closer price is to its recent low point. This trigger stays active for as long as Percentile Rank remains below the threshold.

[[actions.triggers]]
indicator = "prank_100"
operator = "<"
target = "5"
timeframe = "1h"

Typical use: "Price is near the bottom of its recent range -- consider buying." When Percentile Rank drops below 5, the current price is lower than 95% of the last 100 closes. This is the core contrarian buy signal. Price is historically cheap within the lookback window.

cross_above -- Event-Based