Freqtrade Strategy

How to connect freqtrade to Bybit (API keys, spot and futures)

Updated 31 Oct 2026 · 3 min read

Bybit is one of the exchanges freqtrade officially supports for both spot and futures trading. It also has a demo mode that freqtrade can use, which makes it a good choice for testing a bot against real market conditions without real money.

This guide assumes you already have freqtrade running. If not, start with installing freqtrade with Docker.

Bybit is not available in every country, including the United States. Check that you are allowed to use it where you live before signing up.

Step 1: Create and secure your Bybit account

  1. Sign up for Bybit and complete identity verification. Most API features need a verified account.
  2. Turn on two-factor authentication (2FA) under account security.
  3. Deposit only what you are prepared to lose. Treat a bot account as risk capital.

Step 2: Use a dedicated sub-account

Freqtrade's documentation says it assumes the account is dedicated to the bot, and recommends one sub-account per bot, especially on unified accounts. Running two bots, or trading manually, on the same account can cause errors and wrong balances.

In Bybit, open the sub-account section of your account menu, create a sub-account and transfer the funds the bot will trade into it.

Step 3: Create the API key

While logged into the sub-account (or creating the key for it from the main account):

  1. Open API management and create a new system-generated API key.
  2. Choose Read-Write.
  3. Give it only the trading permissions it needs:
    • Spot trading: enable trade permission for spot / unified trading.
    • Futures trading: freqtrade's docs list Contract – Orders and Contract – Positions as required.
  4. Never enable withdrawal or transfer permissions. A bot has no reason to move funds out.
  5. Restrict the key to your server's IP address. Freqtrade strongly recommends this. You can find your VPS IP with curl -4 ifconfig.me.
  6. Save the API key and secret somewhere safe. Bybit shows the secret only once.

Bybit's menu names change from time to time. If a label differs, choose the closest equivalent: read-write, trade only, no withdrawals, IP-restricted.

Step 4: Add the key to your config

Edit user_data/config.json. For spot trading:

"trading_mode": "spot",
"exchange": {
    "name": "bybit",
    "key": "YOUR_API_KEY",
    "secret": "YOUR_API_SECRET",
    "pair_whitelist": ["BTC/USDT", "ETH/USDT", "SOL/USDT"],
    "pair_blacklist": []
}

For futures (USDT perpetuals), freqtrade uses isolated margin and the futures pair format:

"trading_mode": "futures",
"margin_mode": "isolated",
"exchange": {
    "name": "bybit",
    "key": "YOUR_API_KEY",
    "secret": "YOUR_API_SECRET",
    "pair_whitelist": ["BTC/USDT:USDT", "ETH/USDT:USDT"]
}

A few futures details from the freqtrade docs worth knowing:

  • On startup, freqtrade sets the account's position mode to One-way Mode. Changing it by hand later can cause errors.
  • Bybit supports stoploss on exchange for futures, which places your stop on Bybit itself so it still works if your server goes down. Enable it with "stoploss_on_exchange": true in order_types.
  • Your strategy must set can_short = True to open short positions. Every strategy on this site is long-only spot.
  • Read the freqtrade leverage documentation before using leverage. Leverage multiplies losses as well as gains.

Keep "dry_run": true until you have finished testing.

Step 5: Test with Bybit demo mode

Freqtrade can trade on Bybit's demo environment, which simulates fills on live markets:

"dry_run": false,
"exchange": {
    "name": "bybit",
    "demo_trading": true,
    "key": "DEMO_API_KEY",
    "secret": "DEMO_API_SECRET"
}

Demo trading needs separate API keys created on Bybit's demo trading page, and it cannot be combined with dry-run, which is why dry_run is false above. It is a good final check that your keys, permissions and order types work before you use real funds.

Step 6: Start and check

docker compose up -d
docker compose logs -f

Look for a line confirming the exchange is bybit and no authentication errors. If you set up Telegram, send /balance to confirm the bot sees your account.

Common errors

Invalid API key or permission denied. The key is wrong, was created on the main account instead of the sub-account, or is missing trade permission.

IP-related errors. The IP restriction does not match your server's public IP. Check it with curl -4 ifconfig.me and update the key.

Timestamp for this request is outside of the recvWindow. Your server clock has drifted. Run sudo timedatectl set-ntp true.

Unexpected balances. Manual trades or another bot are using the same account. Move the bot to its own sub-account.

Before you go live

  • Run dry-run or demo for several weeks and compare the results with your backtest.
  • Start with a small balance.
  • Set up Telegram alerts so you know when trades open and close.

Ready to connect an exchange?

Freqtrade needs an exchange account with API access. Bybit supports both spot and futures in freqtrade and offers a demo mode for testing.

Open a Bybit accountBrowse tested strategies

Affiliate link: we may earn a commission if you sign up, at no cost to you.

Related guides