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.

Botmarley dashboard after first launch

License Setup

Botmarley requires an API key to unlock all features.

Visit lipinski.work to request your API key
Open Settings in the Botmarley web interface
Enter your API key in the License section
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

Tip

Start with one or two pairs. You can always add more later. BTC/USDC is a good starting point because it has the most historical data and liquidity.

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.

Note

You can skip the Telegram Bot and Authentication sections for now. They are useful for production deployments but not required for getting started.

Step 2: Add Your First Account

Navigate to Accounts in the sidebar.

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

Field	What to enter
Name	A friendly name, e.g., "Paper Trading"
Description	Optional, e.g., "For testing strategies"
Account Type	Select Paper (Simulated)

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.

Warning

Do not use a live exchange account with real API keys until you are comfortable with how strategies behave. Always test with a paper account first.

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)

Danger

Your API keys are stored locally in Botmarley's PostgreSQL database. Never share your API secret. When generating keys on your exchange, grant only the permissions you need (query funds, create orders) and avoid granting withdrawal permissions.

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.

Select an exchange (Kraken or Binance) in the dropdown.
Your active pairs (configured in Settings) appear as checkboxes. Make sure the pairs you want are checked.
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.

Note

The initial download can take several minutes depending on how far back your history start date is. Subsequent syncs are incremental -- they only fetch new candles since the last sync.

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:

Field	What to enter
Pair	Select a pair you downloaded data for (e.g., BTC/USDC)
Initial Capital	`10000` (USD)
Start Date	The start of your downloaded data range
End Date	The end of your downloaded data range

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.

Tip

Your first strategy probably will not be profitable -- and that is perfectly fine. Backtesting is about learning and iterating. Go back to the Strategy Editor, adjust the RSI thresholds or add additional triggers, and run another backtest. Repeat until you find settings that produce results you are comfortable with.

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.

Botmarley User Manual