CoinTrader

Binance Futures 자동매매 봇. 복합 기술 지표와 LightGBM ML 필터를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다.

---

주요 기능

• 복합 기술 지표 신호: RSI, MACD 크로스, 볼린저 밴드, EMA 정/역배열, Stochastic RSI, 거래량 급증 — 3개 이상 일치 시 진입
• ML 필터 (LightGBM): 기술 지표 신호를 한 번 더 검증하여 오진입 차단 (모델 없으면 자동 폴백)
• ATR 기반 손절/익절: 변동성에 따라 동적으로 SL/TP 계산 (1.5× / 3.0× ATR)
• 리스크 관리: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도 제어
• 포지션 복구: 봇 재시작 시 기존 포지션 자동 감지 및 상태 복원
• Discord 알림: 진입·청산·오류 이벤트 실시간 웹훅 알림
• CI/CD: Jenkins + Gitea Container Registry 기반 Docker 이미지 자동 빌드·배포

---

프로젝트 구조

cointrader/
├── main.py                  # 진입점
├── src/
│   ├── bot.py               # 메인 트레이딩 루프
│   ├── config.py            # 환경변수 기반 설정
│   ├── exchange.py          # Binance Futures API 클라이언트
│   ├── data_stream.py       # WebSocket 1분봉 스트림
│   ├── indicators.py        # 기술 지표 계산 및 신호 생성
│   ├── ml_filter.py         # LightGBM 진입 필터
│   ├── ml_features.py       # ML 피처 빌더
│   ├── label_builder.py     # 학습 레이블 생성
│   ├── dataset_builder.py   # 벡터화 데이터셋 빌더 (학습용)
│   ├── risk_manager.py      # 리스크 관리
│   ├── notifier.py          # Discord 웹훅 알림
│   └── logger_setup.py      # Loguru 로거 설정
├── scripts/
│   ├── fetch_history.py     # 과거 데이터 수집
│   └── train_model.py       # ML 모델 수동 학습
├── models/                  # 학습된 모델 저장 (.pkl)
├── data/                    # 과거 데이터 캐시
├── logs/                    # 로그 파일
├── tests/                   # 테스트 코드
├── Dockerfile
├── docker-compose.yml
├── Jenkinsfile
└── requirements.txt

---

빠른 시작

1. 환경변수 설정

cp .env.example .env

.env 파일을 열어 아래 값을 채웁니다.

BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret
SYMBOL=XRPUSDT
LEVERAGE=10
RISK_PER_TRADE=0.02
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

2. 로컬 실행

pip install -r requirements.txt
python main.py

3. Docker Compose로 실행

docker compose up -d

로그 확인:

docker compose logs -f cointrader

---

ML 모델 학습

봇은 모델 파일(models/lgbm_filter.pkl)이 없으면 ML 필터 없이 동작합니다. 최초 실행 전 또는 수동 재학습 시 아래 순서로 진행합니다.

# 1. 과거 데이터 수집
python scripts/fetch_history.py

# 2. 모델 학습 (LightGBM, CPU)
python scripts/train_model.py

학습된 모델은 models/lgbm_filter.pkl에 저장됩니다. 재학습이 필요하면 맥미니에서 위 스크립트를 다시 실행하고 모델 파일을 컨테이너에 배포합니다.

Apple Silicon GPU 가속 학습 (M1/M2/M3/M4)

M 시리즈 맥에서는 MLX를 사용해 통합 GPU(Metal)로 학습할 수 있습니다.

설치: mlx는 Apple Silicon 전용이며 requirements.txt에 포함되지 않습니다. 맥미니에서 별도 설치: pip install mlx

# MLX 별도 설치 (맥미니 전용)
pip install mlx

# MLX 신경망 필터 학습 (GPU 자동 사용)
python scripts/train_mlx_model.py

# train_and_deploy.sh에서 MLX 백엔드 사용
TRAIN_BACKEND=mlx bash scripts/train_and_deploy.sh

참고: LightGBM은 Apple Silicon GPU를 공식 지원하지 않습니다. MLX는 Apple이 만든 ML 프레임워크로 통합 GPU를 자동으로 활용합니다. Neural Engine(NPU)은 Apple 내부 전용으로 Python에서 직접 제어할 수 없습니다.

---

매매 전략

지표	롱 조건	숏 조건	가중치
RSI (14)	< 35	> 65	1
MACD 크로스	골든크로스	데드크로스	2
볼린저 밴드	하단 이탈	상단 돌파	1
EMA 정배열 (9/21/50)	정배열	역배열	1
Stochastic RSI	< 20 + K>D	> 80 + K<D	1
거래량	20MA × 1.5 이상 시 신호 강화	—	보조

진입 조건: 가중치 합계 ≥ 3 + (거래량 급증 또는 가중치 합계 ≥ 4)
손절/익절: ATR × 1.5 / ATR × 3.0 (리스크:리워드 = 1:2)
ML 필터: LightGBM 예측 확률 ≥ 0.60 이어야 최종 진입

---

CI/CD

main 브랜치에 푸시하면 Jenkins 파이프라인이 자동으로 실행됩니다.

1. Checkout — 소스 체크아웃
2. Build Image — Docker 이미지 빌드 (:{BUILD_NUMBER} + :latest 태그)
3. Push — Gitea Container Registry(10.1.10.28:3000)에 푸시
4. Cleanup — 로컬 이미지 정리

배포 서버에서 최신 이미지를 반영하려면:

docker compose pull && docker compose up -d

---

테스트

pytest tests/ -v

---

환경변수 레퍼런스

변수	기본값	설명
BINANCE_API_KEY	—	Binance API 키
BINANCE_API_SECRET	—	Binance API 시크릿
SYMBOL	XRPUSDT	거래 심볼
LEVERAGE	10	레버리지 배수
RISK_PER_TRADE	0.02	트레이드당 리스크 비율 (2%)
DISCORD_WEBHOOK_URL	—	Discord 웹훅 URL

---

주의사항

이 봇은 실제 자산을 거래합니다. 운영 전 반드시 Binance Testnet에서 충분히 검증하세요.
과거 수익이 미래 수익을 보장하지 않습니다. 투자 손실에 대한 책임은 사용자 본인에게 있습니다. 성투기원합니다.