Bybit Trend Bot

Automated trend-following execution on Bybit V5 (USDT linear perpetuals)

Repository: github.com/VtrAha/bybit-trading-bot

New to bots? Start with the Beginner guide: using this bot (step-by-step: install, keys, dry-run, testnet, then mainnet).

---

Overview

This repository implements a single-symbol, trend-following trading loop for Bybit linear USDT perpetuals. The strategy combines EMA crossover for directional bias, ADX and directional movement (+DI/−DI) for regime filtering, and ATR for stop distance, take-profit levels, and risk-based position sizing. Market data and execution are separated from indicator and strategy logic to support testnet, dry-run, and signed live trading on a predictable polling cadence.

This is research and execution software, not a product with guaranteed returns. Past or hypothetical results do not predict live performance. Cryptocurrency derivatives are high risk; you are solely responsible for API keys, margin, compliance, and capital deployed.

---

Beginner guide: using this bot

If you have never run a trading bot before, follow these steps in order. Do not skip testnet and dry-run until you know what the logs mean.

0) Get the project on your computer (very first step)

Goal: a folder on your machine that contains package.json and a src/ directory — that is the project root for every later command.

Option A — Git clone (recommended if the code is on GitHub, GitLab, or similar):

1. Install Git if you do not have it. Check with:

   git --version
   

2. In a folder where you keep projects, clone the repository (replace the URL with your repo or fork):

   git clone https://github.com/VtrAha/bybit-trading-bot.git
   cd YOUR_REPO
   

   If you use SSH (with keys on your Git account):

   git clone git@github.com:VtrAha/bybit-trading-bot.git
   cd YOUR_REPO
   

3. You should see package.json in the current directory:

   # Windows (PowerShell or cmd)
   dir package.json
   
   # macOS / Linux
   ls package.json
   

4. Later, to pull updates (new commits from the same remote), use:

   cd YOUR_REPO
   git pull
   

   Then run npm install again in case package.json changed.

If the folder name has spaces (e.g. bybit trading bot), always quote the path when you cd:

cd "bybit trading bot"

Option B — You already have the folder (ZIP, USB, Cursor/Copilot, or copy from a friend):

• Unzip or open that folder, then in a terminal go into the folder that directly contains package.json and src/. That folder is your project root — same as after git clone + cd.

Option C — You opened this project in an IDE:

• Open the integrated terminal in the project root (the directory with package.json) so npm commands run in the right place.

Then continue to step 1 below.

1) What you need before you start

| You need | Notes | |----------|--------| | A computer with Node.js 20+ | Download Node (LTS is fine). In a terminal, run node -v — it should show v20 or higher. | | The project root (from step 0) | The folder with package.json and src/. All commands like npm install run here. | | Git (optional) | Only required if you use Option A in step 0. | | A Bybit account | You will create API keys on Bybit (main) or Testnet (fake money for learning). | | Patience to read the logs | The bot only prints text to the terminal. There is no built-in website or app UI. |

You do not need to know the math behind EMA/ADX/ATR on day one — but you do need to understand testnet vs mainnet and dry-run vs real orders (see below).

2) Four switches every beginner should understand

| Switch | Set to | What it means in plain language | |--------|--------|---------------------------------| | BYBIT_TESTNET | true first | Talk to Bybit’s practice server; balances are not real mainnet money. | | BYBIT_TESTNET | false | Talk to real Bybit — real money and real risk. | | DRY_RUN | true | The bot may read prices and (with keys) your balance, but it will not place orders or set stop-loss/take-profit. Safest to learn signals. | | DRY_RUN | false | The bot will place real orders (when keys are set and the strategy wants to trade). Use only on testnet first, then small size on mainnet if you accept the risk. |

Rule of thumb: learn with DRY_RUN=true, then test orders with BYBIT_TESTNET=true and DRY_RUN=false, only then consider mainnet with BYBIT_TESTNET=false.

4) Install dependencies and the .env file (one time)

1. In the project root (where package.json is; see 0) Get the project on your computer above), run:

   npm install
   

2. If that fails, check that you are in the correct directory and that Node 20+ is installed.

3. Create your local settings file (do not share or upload this file):

   # Windows (Command Prompt)
   copy .env.example .env
   
   # macOS / Linux
   cp .env.example .env
   

4. Open .env in a text editor. You will come back to this file many times.

5) Create Bybit API keys (beginner-friendly)

1. Use testnet first: go to Bybit testnet, create or log in, and go to the API section (wording may vary: “Create API key”).
2. Create a key with trading permission for the account type you use (e.g. unified / contract as required by the exchange). Do not enable withdrawal for a bot that only trades — that limits damage if a key leaks.
3. Save the key and secret in a safe place. You may only see the secret once.
4. Paste them into .env as BYBIT_API_KEY and BYBIT_API_SECRET (no quotes, no extra spaces, one key per line).
5. In .env, set BYBIT_TESTNET=true so the bot uses the testnet API host. Keys from testnet and mainnet are not interchangeable.

If something says “unauthorized” or “invalid key,” the host (BYBIT_TESTNET) and the key origin (testnet vs main) must match.

6) First run: signals only (no orders)

Goal: see Starting, Instrument rules loaded, and Signal lines without spending anything.

1. In .env, set:

   • DRY_RUN=true
   • BYBIT_TESTNET=true
   • You may leave keys empty for a pure dry run of signals, or add keys to also see equityUsd / qty in dry-run logs.

2. Start the bot:

   npm start
   

3. Good signs: lines like Signal with signal, close, adx, atr. If you see Not enough data or indicators warming up, wait — the first bars may still be loading.

4. Stop the bot: press Ctrl+C in the same terminal. It is normal to start and stop often while learning.

If the program exits immediately with an error, read the message; often it is a missing/invalid FAST_EMA/SLOW_EMA pair or a typo in .env. See Troubleshooting.

7) Second run: same as live, but no orders (recommended)

1. Keep DRY_RUN=true and BYBIT_TESTNET=true.
2. With testnet keys in .env, the bot can read your testnet balance and show DRY_RUN (no orders) with a computed qty.
3. Check that qty is not always null (if it is, your balance may be too small for the minimum order size or your risk settings are too low — see Configuration and the sizing table in User reference).

This step proves your API key works and sizing is in a sensible range before any click-to-trade.

8) Testnet live trading (real API orders, not real money on mainnet)

1. In .env set: DRY_RUN=false, BYBIT_TESTNET=true, and your testnet keys.
2. On Bybit testnet, set leverage and position mode (one-way) the way you want before relying on the bot. This repo does not set them for you.
3. Set small values in .env while learning, e.g. low RISK_PER_TRADE and a tight MAX_ORDER_QTY, and an interval you understand (e.g. INTERVAL=15 minutes).
4. Run npm start and watch the terminal. You should only move on when you have seen an open, brackets (SL/TP), and understand how a flip or error looks in the log.
5. Stop with Ctrl+C when done.

Testnet can behave differently from mainnet (liquidity, fills). It is for process learning, not for proving profit.

9) When you are ready for mainnet (read twice)

1. You have completed 8) and you understand what each log line means.
2. Create separate mainnet API keys; never reuse testnet keys on main.
3. Set BYBIT_TESTNET=false and point .env to mainnet keys.
4. Use only capital you can afford to lose; start with the smallest RISK_PER_TRADE and MAX_ORDER_QTY you can.
5. Keep your machine and .env private; read Security.

10) On the Bybit app when the bot is running

You can always log in to Bybit (web or app) in parallel and check positions, open orders, and wallet balance. If the bot says it opened a position but you do not see it, wait a few seconds, refresh, and confirm the symbol and account (testnet vs main) match your .env.

11) Common beginner mistakes

| Mistake | How to avoid | |--------|---------------| | Mainnet key on testnet host (or the reverse) | BYBIT_TESTNET and key source must match. | | DRY_RUN=false on the first run | Start with DRY_RUN=true to learn. | | Expecting the bot to “set leverage” for you | Set leverage and one-way mode on Bybit before relying on size and risk. | | Flat signal with an open position | Flat does no