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.