Freqtrade NFI 봇
설치부터 24시간 운영까지

01설치 전에 반드시 준비할 것

이 세팅은 바이낸스 USDT 선물, Python 3.12, macOS 또는 Linux 환경을 기준으로 한다. Freqtrade 공식 문서는 Python 3.11 이상을 요구하지만, 새로 세팅한다면 3.12로 맞추는 편이 깔끔하다. Windows 사용자는 네이티브 설치보다 WSL 또는 Docker 쪽이 덜 꼬인다.

초보자라면 먼저 목표를 분명히 해야 한다. 이 글의 목표는 “바로 돈을 벌기”가 아니라 로컬 또는 서버에서 봇이 안전하게 켜지고, 모의 거래가 돌고, 텔레그램과 WebUI로 상태 확인이 되는 환경을 만드는 것이다. 이 단계가 안정적으로 끝나기 전에는 실거래 버튼을 누르면 안 된다.

• ✓바이낸스 선물 계정: 선물 거래가 활성화되어 있어야 한다. 현물 API만 있으면 USDT 선물 봇은 정상 주문을 넣을 수 없다.
• ✓고정 실행 위치: 노트북으로 테스트할 수는 있지만 24시간 운영은 꺼지지 않는 서버, 미니 PC, VPS가 더 적합하다.
• ✓시간 동기화: 거래소 API는 시간 오차에 민감하다. 서버 시간이 크게 틀어져 있으면 인증 오류나 주문 오류가 날 수 있다.

02Python 환경과 Freqtrade 설치

봇은 하나의 독립된 작업 폴더 안에서 운영한다. 가상환경을 분리해두면 시스템 Python이나 다른 프로젝트 패키지와 충돌하지 않는다. 먼저 내 컴퓨터가 Python 3.12를 제대로 인식하는지 확인한다.

python3.12 --version
# Python 3.12.x 가 나오면 진행

`python3.12: command not found`가 나오면 Python 설치부터 해결해야 한다. macOS라면 Homebrew로 Python 3.12를 설치하고, Ubuntu라면 배포판에 맞는 Python 3.12 패키지 또는 pyenv를 쓰는 방식이 일반적이다.

# 작업 디렉토리 생성
mkdir ~/freqtrade-bot
cd ~/freqtrade-bot

# Python 3.12 가상환경 생성
python3.12 -m venv .venv

# 가상환경 활성화
source .venv/bin/activate

# pip 업그레이드 후 Freqtrade 설치
pip install -U pip setuptools wheel
pip install freqtrade

설치가 끝나면 두 가지를 확인한다. 첫째, 지금 쓰는 Python이 `.venv` 안의 Python인지 확인한다. 둘째, `freqtrade` 명령이 정상으로 뜨는지 확인한다.

which python
which freqtrade
freqtrade --version

다음으로 Freqtrade가 사용할 기본 폴더 구조를 만든다.

freqtrade create-userdir --userdir user_data
ls user_data/

정상이라면 `backtest_results`, `data`, `hyperopts`, `logs`, `models`, `notebooks`, `strategies`, `templates` 같은 폴더가 생성된다. 우리가 전략 파일을 넣을 위치는 `user_data/strategies`임.

여기까지 끝났을 때의 성공 기준은 단순하다. `~/freqtrade-bot` 폴더 안에 `.venv`와 `user_data`가 있고, 가상환경을 켠 상태에서 `freqtrade --version`이 실행되면 다음 단계로 넘어가면 된다.

03NFI X7 전략 파일과 config 구성

NFI는 NostalgiaForInfinity 전략 계열이고, 여기서는 `NostalgiaForInfinityX7.py` 파일을 사용한다. 전략 파일은 `strategies` 폴더 안에 있어야 Freqtrade가 인식한다.

cd user_data/strategies
curl -LO https://raw.githubusercontent.com/iterativv/NostalgiaForInfinity/main/NostalgiaForInfinityX7.py
ls -lh NostalgiaForInfinityX7.py
cd ../..

`ls -lh` 결과에서 파일 크기가 너무 작으면 다운로드가 실패했거나 404 페이지를 저장했을 가능성이 있다. 파일을 열었을 때 Python 코드가 아니라 HTML 에러 페이지처럼 보이면 다시 내려받아야 한다.

그 다음 핵심은 `user_data/config.json`이다. 아래는 바이낸스 USDT 선물, 격리 마진, Static PairList, 텔레그램, WebUI를 전제로 한 기본 골격이다. API 키와 텔레그램 토큰은 여기에 직접 넣지 않고 다음 섹션에서 환경변수로 분리한다. 처음 세팅하는 사람은 종목 수를 너무 많이 넣지 말고, BTC/ETH/SOL/XRP 정도로 시작해서 봇의 움직임을 먼저 관찰하는 편이 낫다.

{
  "trading_mode": "futures",
  "margin_mode": "isolated",
  "max_open_trades": 12,
  "stake_currency": "USDT",
  "stake_amount": "unlimited",
  "tradable_balance_ratio": 0.99,
  "fiat_display_currency": "USD",
  "dry_run": true,
  "dry_run_wallet": 1000,
  "cancel_open_orders_on_exit": false,
  "timeframe": "5m",
  "use_exit_signal": true,
  "exit_profit_only": false,
  "ignore_roi_if_entry_signal": true,
  "exchange": {
    "name": "binance",
    "key": "",
    "secret": "",
    "enable_ws": true,
    "markets_refresh_interval": 240,
    "pair_whitelist": [
      "BTC/USDT:USDT",
      "ETH/USDT:USDT",
      "SOL/USDT:USDT",
      "XRP/USDT:USDT"
    ],
    "pair_blacklist": [
      "BNB/USDT:USDT",
      "(AEUR|FDUSD|BUSD|CUSD|CUSDT|DAI|SUSD|TUSD|USDC|USDN|USDP|USDT|UST|USTC|AUSD|EURI|USDS)/USDT:USDT",
      ".*3L/USDT:USDT",
      ".*3S/USDT:USDT",
      ".*BULL/USDT:USDT",
      ".*BEAR/USDT:USDT"
    ]
  },
  "pairlists": [{ "method": "StaticPairList" }],
  "telegram": {
    "enabled": true,
    "allow_custom_messages": true,
    "token": "",
    "chat_id": ""
  },
  "api_server": {
    "enabled": true,
    "listen_ip_address": "127.0.0.1",
    "listen_port": 8080,
    "verbosity": "error",
    "enable_openapi": false,
    "jwt_secret_key": "",
    "CORS_origins": [],
    "username": "",
    "password": ""
  },
  "bot_name": "freqtrade_Nostalgia",
  "initial_state": "running",
  "force_entry_enable": false,
  "internals": {
    "process_throttle_secs": 2,
    "heartbeat_interval": 60
  }
}

config를 저장한 뒤에는 JSON 문법이 깨지지 않았는지 먼저 확인한다. Python이 설치되어 있다면 아래 명령으로 쉼표 누락, 따옴표 오류 같은 기본 실수를 바로 잡을 수 있다.

python -m json.tool user_data/config.json > /tmp/freqtrade-config-check.json

04민감정보 분리와 실행 스크립트

API 키, 텔레그램 토큰, WebUI 비밀번호는 `config.json`에 직접 쓰지 않는 편이 좋다. Freqtrade는 `FREQTRADE__섹션__키` 형태의 환경변수로 config 값을 덮어쓸 수 있다.

# .env.freqtrade
FREQTRADE__EXCHANGE__KEY=발급받은_바이낸스_API_KEY
FREQTRADE__EXCHANGE__SECRET=발급받은_바이낸스_SECRET
FREQTRADE__TELEGRAM__TOKEN=BotFather에서_받은_토큰
FREQTRADE__TELEGRAM__CHAT_ID=본인_Chat_ID_숫자
FREQTRADE__API_SERVER__USERNAME=freqtrader
FREQTRADE__API_SERVER__PASSWORD=안전한_비밀번호_설정
FREQTRADE__API_SERVER__JWT_SECRET_KEY=랜덤_긴_문자열_직접_입력

chmod 600 .env.freqtrade

다음은 실행 스크립트다. 매번 환경변수를 직접 불러오고 명령어를 길게 입력할 필요가 없어진다.

#!/bin/sh
set -eu

SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
ENV_FILE="$SCRIPT_DIR/.env.freqtrade"

if [ ! -f "$ENV_FILE" ]; then
  echo "Error: .env.freqtrade 파일이 없습니다: $ENV_FILE" >&2
  exit 1
fi

set -a
. "$ENV_FILE"
set +a

cd "$SCRIPT_DIR"
exec "$SCRIPT_DIR/.venv/bin/python" -m freqtrade trade \
  --config user_data/config.json \
  --strategy NostalgiaForInfinityX7

chmod +x start_freqtrade.sh

실행 전에 최종 config가 의도대로 합쳐졌는지도 확인한다. Freqtrade는 환경변수가 config보다 우선 적용되므로, 아래 명령으로 key, telegram, api_server 값이 들어갔는지 확인할 수 있다. 기본 출력은 민감값을 가려서 보여주므로 검증용으로 쓰기 좋다.

set -a
. ./.env.freqtrade
set +a
freqtrade show-config --config user_data/config.json

여기서 `dry_run`이 `true`인지, `exchange.name`이 `binance`인지, `trading_mode`가 `futures`인지, `telegram.enabled`가 `true`인지 확인한다. 초보자는 이 확인을 생략하지 않는 게 좋다. 실제로 많은 문제는 봇 코드가 아니라 환경변수 이름 오타에서 발생한다.

05Dry Run 검증, 실거래 전환, PM2 운영

처음 실행은 Dry Run으로 한다. 여기서 확인할 것은 수익이 아니라 봇이 제대로 시장 데이터를 받고, 전략 파일을 인식하고, 텔레그램과 WebUI가 정상 작동하는지임.

source .venv/bin/activate
./start_freqtrade.sh

• 1로그 확인: `Dry run is enabled`, `Using strategy: NostalgiaForInfinityX7`, `Bot heartbeat`가 보이면 기본 가동은 성공이다.
• 2WebUI 확인: 브라우저에서 `http://127.0.0.1:8080`에 접속하고 `.env.freqtrade`에 넣은 계정으로 로그인한다.
• 3텔레그램 확인: 봇에게 `/status`를 보내 응답이 오면 알림과 원격 제어가 연결된 것이다.

Dry Run을 켠 첫날에는 수익률을 보지 말고 운영 체크리스트를 봐야 한다. 로그가 계속 쌓이는지, 텔레그램 명령이 먹히는지, WebUI가 끊기지 않는지, 봇이 어떤 종목을 감시하는지, 포지션이 열릴 때 stake가 의도한 크기인지 확인한다.

실거래 전환은 `user_data/config.json`에서 `dry_run`을 `false`로 바꾸고 재시작하면 된다. 다만 이 단계는 최소 2주 이상 Dry Run을 돌리고, 전략의 진입 빈도와 손실 구간을 눈으로 확인한 뒤 진행해야 한다.

"dry_run": false

장시간 운영은 PM2로 관리한다. 터미널을 닫아도 프로세스가 유지되고, 재시작과 로그 확인이 편해진다.

npm install -g pm2

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'freqtrade_Nostalgia',
      script: './start_freqtrade.sh',
      cwd: '/절대경로/freqtrade-bot',
      interpreter: 'none',
      autorestart: true,
      watch: false,
      max_restarts: 10,
      restart_delay: 5000,
      log_date_format: 'YYYY-MM-DD HH:mm:ss',
      out_file: './user_data/logs/freqtrade-out.log',
      error_file: './user_data/logs/freqtrade-err.log',
      merge_logs: true
    }
  ]
};

pm2 start ecosystem.config.js
pm2 save
pm2 startup

PM2로 올린 뒤에는 터미널을 닫기 전에 반드시 프로세스 상태와 로그를 확인한다. `online`으로 떠 있고 heartbeat가 계속 찍히면 무중단 운영의 기본 조건은 충족된 것이다.

pm2 list
pm2 logs freqtrade_Nostalgia

06운영 중 자주 보는 명령어와 오류

텔레그램은 운영자의 리모컨이다. 특히 서버에 직접 접속하지 못하는 상황에서 상태 확인과 긴급 대응을 빠르게 할 수 있다.

NFI X7를 이해할 때 중요한 지점

NFI X7는 단순한 하나의 조건식이 아니라 여러 진입 조건을 조합하는 앙상블형 전략에 가깝다. RSI, EMA, 볼린저 밴드, 거래량 같은 조건이 복합적으로 작동하고, 포지션이 불리해졌을 때는 Derisk와 Grinding 방식으로 포지션을 관리한다.

그래서 하드 스톱로스가 매우 넓게 잡혀 있어도 그것을 “손절을 안 한다”로 이해하면 안 된다. 전략 내부의 방어 로직이 먼저 작동하고, 하드 스톱로스는 마지막 방어선에 가깝다. 선물에서는 이 구조를 이해하지 못한 상태로 큰 금액을 넣으면 위험하다.

자주 발생하는 오류

• !`ModuleNotFoundError: No module named 'freqtrade'`
  가상환경이 활성화되지 않았거나 다른 Python으로 실행 중인 상태다. `source .venv/bin/activate`를 다시 확인한다.
• !`Exchange returned invalid JSON`
  API 키 권한, IP 화이트리스트, 거래소 접속 상태를 확인한다.
• !텔레그램 응답 없음
  대부분 Chat ID 입력 오류다. `@userinfobot`으로 다시 확인한다.
• !`Strategy NostalgiaForInfinityX7 not found`
  `user_data/strategies/` 안에 `NostalgiaForInfinityX7.py`가 있는지 확인한다.
• !WebUI 접속 안 됨
  `api_server.enabled`가 `true`인지, 포트가 `8080`인지, 이미 다른 프로그램이 같은 포트를 쓰고 있지 않은지 확인한다.
• !config 값이 예상과 다름
  환경변수가 config 값을 덮어썼을 수 있다. `freqtrade show-config --config user_data/config.json`으로 최종 적용값을 확인한다.