AutoCoinTrader/docs/user_guide.md

AutoCoinTrader 사용 가이드

개요

AutoCoinTrader는 Upbit 시세 데이터를 기반으로 MACD, SMA, ADX 지표를 활용해 매수/매도 신호를 분석하고(dry_run 모드), 설정에 따라 자동 주문까지 수행할 수 있는 트레이딩 보조/자동화 도구입니다. 모든 주요 상태 파일(holdings.json, trades.json, pending_orders.json)은 data/ 디렉터리 하위에서 관리됩니다.

1. 사전 준비

1.1 필수 요구사항

1. Python 3.11 이상
2. 가상환경 권장 (venv, pyenv, Conda 등)
3. Upbit API 키 (자동매매 사용 시)
4. Telegram Bot Token & Chat ID (알림 사용 시)

1.2 설치

python -m venv .venv; .\.venv\Scripts\activate
pip install -r requirements.txt

1.3 환경변수 설정 (.env)

.env 파일에 아래 항목을 필요 시 추가:

TELEGRAM_BOT_TOKEN=123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TELEGRAM_CHAT_ID=123456789
UPBIT_ACCESS_KEY=YOUR_UPBIT_ACCESS
UPBIT_SECRET_KEY=YOUR_UPBIT_SECRET

# 선택 기능
AGGREGATE_ALERTS=false
TELEGRAM_TEST=0
AUTO_TRADE_ENABLED=0   # require_env_confirm 활성화 시 1로 설정해야 자동매매 진행
ORDER_MONITOR_TIMEOUT=120
ORDER_POLL_INTERVAL=3
ORDER_MAX_RETRIES=1
ORDER_MAX_CONSECUTIVE_ERRORS=5

UPBIT_* 키는 실거래(dry_run=False) + 자동매매(trading_mode=auto_trade/mixed)에서 필수. .env는 반드시 .gitignore에 포함시키십시오.

2. 설정 파일 (config/config.json)

미존재 시 기본값이 내부 로직에서 자동 로드됩니다. 핵심 항목:

키	설명	기본값
candle_count	각 심볼 지표 계산에 사용하는 캔들 개수	200
buy_check_interval_minutes	매수 조건 검사 주기	240
stop_loss_check_interval_minutes	손절 검사 주기	60
profit_taking_check_interval_minutes	익절 검사 주기	240
loop	True면 주기적 루프 실행	True
dry_run	True면 시뮬레이션 기록만	True
max_threads	병렬 스레드 수	3
trading_mode	signal_only / auto_trade / mixed	signal_only
auto_trade.buy_enabled	자동 매수 허용 여부	False
auto_trade.buy_amount_krw	1회 매수 금액	10000
auto_trade.min_order_value_krw	최소 주문 허용 KRW	5000
auto_trade.loss_threshold	손절 기준(%)	-5.0
auto_trade.profit_threshold_1	부분 익절 시작 수익률(%)	10.0
auto_trade.profit_threshold_2	전량 익절 고수익 기준(%)	30.0
auto_trade.drawdown_1	중간 구간 트레일링 하락률(%)	5.0
auto_trade.drawdown_2	고수익 구간 트레일링 하락률(%)	15.0

3. 주요 데이터 파일 (data/)

파일	용도
holdings.json	현재 보유 코인 상태 (매수 평균가, 수량, max_price 등)
trades.json	매수/매도 기록 (원자적 저장)
pending_orders.json	사용자 확인 대기 중인 주문 토큰 목록

모든 경로는 코드 내부에서 src.common의 상수를 통해 관리되므로 재배치 시 해당 상수만 수정하면 됩니다.

4. 실행 방법

4.1 기본 실행 (드라이런)

python main.py

루프 모드, 설정 주기에 따라 매수/손절/익절 검사 수행. data/ 하위에 기록 생성.

4.2 벤치마크 실행

python main.py --benchmark

순차/병렬 처리 시간 비교 후 로그 출력.

4.3 실거래 모드 전환

1. config.json에서 dry_run을 false, trading_mode를 auto_trade 또는 mixed로 설정.
2. .env에 UPBIT_ACCESS_KEY, UPBIT_SECRET_KEY 추가.
3. (선택) AUTO_TRADE_ENABLED=1 설정 (require_env_confirm일 경우 필수).
4. 소액으로 먼저 검증 후 확장.

4.4 Telegram 알림 테스트

.env에 TELEGRAM_TEST=1 설정 후 최초 실행 시 시작 메시지 전송.

5. 매수/매도 로직 개요

1. 매수 조건: MACD 교차, SMA 단기>장기, ADX 임계 초과 조합 (3가지 패턴)
2. 매도 조건: 손절(초기 하락), 부분 익절 후 수익 보호, 트레일링 익절 (구간별 다른 하락률 적용)
3. 부분 익절 1회 후 partial_sell_done 플래그로 중복 익절 방지.

6. 수동 확인 기반 주문 흐름

자동매매 모드에서 주문은 pending_orders.json에 기록 → 사용자가 confirm_<토큰> 파일 생성 → 타임아웃 내 확인되면 주문 실행.

7. 로그

logs/AutoCoinTrader.log 회전 로그(최대 10MB, 백업 7개). LOG_DIR, LOG_LEVEL 환경변수로 조정 가능.

8. Troubleshooting

증상	원인	해결
실거래 안 됨	API 키 미설정	.env 키 추가 및 dry_run False
텔레그램 알림 없음	토큰/채팅ID 누락	.env 값 확인
부분 체결 후 holdings 미반영	네트워크 지연	로그에서 monitor 결과 확인 후 수동 조정
trades.json 손상	비정상 종료	자동 백업(.corrupted.<ts>) 후 재생성됨

9. 성능 & 안정성 팁

1. 스레드 수(max_threads)를 심볼 수 대비 과도하게 늘리지 말 것 (IO 포화 발생 가능).
2. 캔들 개수(candle_count)는 필요 이상 크게 하면 지표 계산 비용 증가.
3. 네트워크 오류 다발 시 ORDER_MAX_CONSECUTIVE_ERRORS 조정.

10. 백테스트 확장 (향후 계획)

data/ 구조 유지 + 별도 backtest/ 모듈에서 동일 지표 계산 후 결과 비교, trades.json 포맷 재사용. (구현 예정)

11. FAQ

Q: dry_run과 auto_trade 차이?
A: dry_run은 모든 거래를 기록만 하고 실제 주문을 보내지 않음. auto_trade는 조건 충족 시 주문 API 호출.

Q: 부분 익절 후 재매도는 어떻게?
A: partial_sell_done 플래그 True 후 트레일링 조건 또는 수익 보호 조건 충족 시 전량 매도.

Q: trades.json 손상 시?
A: 자동으로 .corrupted.<timestamp> 백업 후 새로 시작. 백업 파일 검토 가능.

Q: 설정 변경 반영 시점?
A: 프로세스 재시작 필요. 장기 실행 중에는 실시간 반영 안 함.

Q: 최소 주문 금액 미만 상황?
A: 매도/매수 모두 안전하게 건너뛰고 로그와 텔레그램 알림(선택)으로 통지.