Install CryptoByPlan on macOS

macOS installation

Install CryptoByPlan on a Mac you manage. The bot runs locally and keeps your exchange credentials and bot history on that Mac.

Before you begin

• macOS and Python 3.12.x; install Python only from the official Python for macOS page.
• A stable internet connection for the pinned Python dependencies.
• A dedicated local folder such as ~/CryptoByPlan. Keep it out of iCloud Drive, Dropbox, and other synced folders.
• Your own Telegram bot and Bitvavo API key. Enable trading and disable withdrawals. Do not run another CryptoByPlan instance against the same Bitvavo account at the same time; a separate API key does not isolate exchange orders. For independent testing, use a separate Bitvavo account.

1. Download and verify

When the public beta opens, download the Mac archive and its matching .sha256 file from the official CryptoByPlan release page. Keep both files in the same folder. Use the exact filename shown on that page:

shasum -a 256 -c CryptoByPlan-macOS-v3.25.10.tar.gz.sha256

Continue only when the result says OK. Example filename uses private-tester version v3.25.10; follow the filename and checksum supplied with the package you receive.

2. Extract and set up

In Terminal, go to the folder containing the downloaded archive, then run:

tar -xzf CryptoByPlan-macOS-v3.25.10.tar.gz
cd CryptoByPlan-macOS-v3.25.10
./scripts/setup.sh

Setup creates the virtual environment and starter files if they are absent. It does not start the bot, create a background job, or place an order. Use a new empty folder for a clean installation; never copy another user’s .env, configuration, databases, or logs.

3. Create your Telegram bot and configure credentials

1. In Telegram, open @BotFather, send /newbot, and follow its prompts.
2. Open Terminal in the CryptoByPlan folder and edit .env with nano .env. Put your token on the existing TELEGRAM_TOKEN= line and save.
3. Open your new bot in Telegram and send /start. Then, in Terminal, retrieve the numeric chat ID without printing your whole credentials file:

TELEGRAM_TOKEN="$(sed -n 's/^TELEGRAM_TOKEN=//p' .env)"
curl --fail --silent "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getUpdates"
unset TELEGRAM_TOKEN

Copy the digits in chat.id into the existing TELEGRAM_CHAT_ID= line. If the result list is empty, message your bot and repeat. Do not share the token or response.

Complete the Bitvavo API key, secret, Telegram token, numeric chat ID, and optional CoinMarketCap key using the exact .env instructions. Use your own key with withdrawals disabled. Never send credentials or screenshots containing them.

4. Review and run the first check

Review config.yaml. The clean starter configuration has no DCA plan or manual Smart order. Start one foreground instance from the installation folder:

./venv/bin/python bot.py

In your own Telegram chat, check /start, /status, /balances, /orders, and /help. These checks are read-only. Do not create an order or DCA plan for this test. Stop the process with Control+C in Terminal. Keep one running instance per Telegram bot token.

Optional: start at Mac login

Do this only after the first check passes and you have reviewed your configuration. A LaunchAgent starts the bot when loaded and at your next login; it does not run before login and does not restart the bot after a crash.

Choose a permanent folder, for example /Users/YOUR_SHORT_USERNAME/CryptoByPlan. In Terminal, run whoami to find your short account name and pwd from inside the install folder to confirm the full path. Create a plain-text LaunchAgent file:

mkdir -p "$HOME/Library/LaunchAgents"
nano "$HOME/Library/LaunchAgents/com.cryptobyplan.bot.plist"

In the XML below, replace each occurrence of YOUR_SHORT_USERNAME with your Mac short account name. Keep the angle brackets that are part of XML tags.

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.cryptobyplan.bot</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOUR_SHORT_USERNAME/CryptoByPlan/venv/bin/python</string>
    <string>/Users/YOUR_SHORT_USERNAME/CryptoByPlan/bot.py</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/YOUR_SHORT_USERNAME/CryptoByPlan</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <false/>
  <key>StandardOutPath</key>
  <string>/Users/YOUR_SHORT_USERNAME/CryptoByPlan/bot.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/YOUR_SHORT_USERNAME/CryptoByPlan/bot.err</string>
</dict>
</plist>

Check the XML, then load it deliberately. Loading starts the bot immediately:

plutil -lint "$HOME/Library/LaunchAgents/com.cryptobyplan.bot.plist"
launchctl load "$HOME/Library/LaunchAgents/com.cryptobyplan.bot.plist"

To stop it and disable login startup, unload the same file:

launchctl unload "$HOME/Library/LaunchAgents/com.cryptobyplan.bot.plist"

← Back to installation overview

Do not use a second Mac instance with the same Telegram token while another instance is running. Private-tester guide for package v3.25.10. Public download is pending Mac acceptance testing.