355 lines
11 KiB
Markdown
355 lines
11 KiB
Markdown
# 자동매매 활성화 가이드 (Deployment & Safety)
|
|
|
|
## 개요
|
|
이 문서는 MACD 알림 봇의 **자동매매 기능(auto_trade)**을 안전하게 활성화하고 운영하는 방법을 설명합니다.
|
|
|
|
---
|
|
|
|
## 1. 사전 준비 (필수)
|
|
|
|
### 1.1 Upbit API 키 생성
|
|
1. [Upbit 홈페이지](https://upbit.com) 로그인
|
|
2. 계정 설정 → API 관리 → "Open API" 클릭
|
|
3. "오픈 API 키 생성" 버튼 클릭
|
|
4. 접근 권한:
|
|
- ✅ **조회**: 계좌, 자산, 주문내역 (필수)
|
|
- ✅ **매매**: 매도 주문 (필수)
|
|
- ✅ **출금**: 해제 권장 (자동매매에 불필요)
|
|
5. IP 화이트리스트: 봇이 실행되는 서버 IP 추가 (선택, 권장)
|
|
6. Access Key / Secret Key 메모 (비밀 유지!)
|
|
|
|
### 1.2 Telegram Bot 토큰 & Chat ID 확인
|
|
- 기존에 설정했다면 그대로 사용 가능
|
|
- 없다면 [BotFather로 새 봇 생성](https://core.telegram.org/bots#botfather) 후 Chat ID 확인
|
|
|
|
### 1.3 환경변수 설정 (`.env` 파일)
|
|
```bash
|
|
# Telegram 알림
|
|
TELEGRAM_BOT_TOKEN=your_bot_token
|
|
TELEGRAM_CHAT_ID=your_chat_id
|
|
|
|
# Upbit API (자동매매 시 필수)
|
|
UPBIT_ACCESS_KEY=your_access_key
|
|
UPBIT_SECRET_KEY=your_secret_key
|
|
|
|
# 선택: 자동매매 활성화 확인 (require_env_confirm=true일 때)
|
|
AUTO_TRADE_ENABLED=1
|
|
|
|
# 선택: 주문 모니터링 타임아웃 (초, 기본 120)
|
|
ORDER_MONITOR_TIMEOUT=120
|
|
|
|
# 선택: 주문 폴링 간격 (초, 기본 3)
|
|
ORDER_POLL_INTERVAL=3
|
|
|
|
# 선택: 재시도 횟수 (기본 1)
|
|
ORDER_MAX_RETRIES=1
|
|
```
|
|
|
|
⚠️ `.env` 파일을 `.gitignore`에 추가하여 비밀 정보를 저장소에 커밋하지 마세요.
|
|
|
|
---
|
|
|
|
## 2. config.json 설정
|
|
|
|
### 2.1 기본 설정 (신중하게)
|
|
```json
|
|
{
|
|
"trading_mode": "signal_only",
|
|
"auto_trade": {
|
|
"enabled": false,
|
|
"max_trade_krw": 1000000,
|
|
"allowed_symbols": [],
|
|
"require_env_confirm": true
|
|
},
|
|
"confirm": {
|
|
"confirm_via_file": true,
|
|
"confirm_timeout": 300
|
|
},
|
|
"monitor": {
|
|
"enabled": true,
|
|
"timeout": 120,
|
|
"poll_interval": 3,
|
|
"max_retries": 1
|
|
},
|
|
"notify": {
|
|
"order_filled": true,
|
|
"order_partial": true,
|
|
"order_cancelled": true,
|
|
"order_error": true
|
|
},
|
|
"dry_run": true
|
|
}
|
|
```
|
|
|
|
### 2.2 각 항목 설명
|
|
|
|
#### `trading_mode`
|
|
- `"signal_only"` (기본): Telegram 알림만 전송
|
|
- `"auto_trade"`: 자동매매 시도 (수동 확인 필수)
|
|
- `"mixed"`: 알림 + 거래 기록
|
|
|
|
#### `auto_trade`
|
|
- `enabled`: `false`로 유지 (기본값). 실제 자동매도 활성화하려면 명시적으로 `true`로 변경
|
|
- `buy_enabled`: `false`로 유지 (기본값). 실제 자동매수 활성화하려면 명시적으로 `true`로 변경
|
|
- `buy_amount_krw`: 매수 시 사용할 KRW 금액 (예: 10,000)
|
|
- `max_trade_krw`: 한 번에 매도할 최대 KRW 금액 (예: 1,000,000)
|
|
- `allowed_symbols`: 자동매매 허용 심볼 목록. 빈 배열이면 모든 심볼 허용
|
|
- 예: `["KRW-BTC", "KRW-ETH"]` (이 심볼들만 자동매매)
|
|
- `require_env_confirm`: `true`이면 환경변수 `AUTO_TRADE_ENABLED=1` 필요 (권장)
|
|
|
|
#### `confirm`
|
|
- `confirm_via_file`: 파일 기반 확인 활성화 여부
|
|
- `confirm_timeout`: 확인 대기 시간(초). 이 시간 내에 확인이 없으면 주문 취소
|
|
|
|
#### `monitor`
|
|
- `enabled`: 주문 모니터링 활성화
|
|
- `timeout`: 주문 폴링 타임아웃(초)
|
|
- `poll_interval`: 주문 상태 확인 간격(초)
|
|
- `max_retries`: 타임아웃 시 재시도 횟수
|
|
|
|
#### `notify`
|
|
- `order_filled`: 완전체결 시 알림
|
|
- `order_partial`: 부분체결/타임아웃 시 알림
|
|
- `order_cancelled`: 주문 취소 시 알림
|
|
- `order_error`: 오류 발생 시 알림
|
|
|
|
---
|
|
|
|
## 3. 안전 체크리스트 (자동매매 활성화 전)
|
|
|
|
### ✅ 필수 확인 항목
|
|
- [ ] Upbit API 키가 올바르게 발급되었나? (테스트 계좌에서 실제 키 사용하기)
|
|
- [ ] `.env` 파일이 `.gitignore`에 있나?
|
|
- [ ] `config.json`의 `dry_run`이 `true`로 설정되어 있나? (테스트 단계)
|
|
- [ ] `auto_trade.enabled`가 `false`로 설정되어 있나? (테스트 단계)
|
|
- [ ] 로그 파일(`logs/macd_alarm.log`)을 확인할 수 있는 환경인가?
|
|
|
|
### ✅ 단계적 활성화 (점진적 위험 증가)
|
|
|
|
#### 3.1 단계 1: Signal-Only 모드 (알림만)
|
|
```json
|
|
{
|
|
"trading_mode": "signal_only",
|
|
"dry_run": true
|
|
}
|
|
```
|
|
- 실행: `python main.py`
|
|
- 기대 결과: 매도/매수 신호 감지 시 Telegram 알림 수신
|
|
- 확인: 로그에 오류 없고, Telegram 메시지가 제대로 도착하는가?
|
|
|
|
#### 3.2 단계 2: Mixed 모드 (알림 + 기록, dry-run)
|
|
```json
|
|
{
|
|
"trading_mode": "mixed",
|
|
"auto_trade": {
|
|
"enabled": false,
|
|
"buy_enabled": false
|
|
},
|
|
"dry_run": true
|
|
}
|
|
```
|
|
- 실행: `python main.py`
|
|
- 기대 결과: 매도 신호 시 Telegram + `trades.json` 기록
|
|
- 매수 신호는 `auto_trade.buy_enabled`가 true일 때만 `trades.json`에 기록됨
|
|
- 확인: `trades.json`에 매도 기록이 제대로 저장되는가? (매수 기록은 buy_enabled가 true일 때만 저장됨)
|
|
|
|
#### 3.3 단계 3: Auto-Trade 시뮬레이션 (dry-run, 실제 주문 아님)
|
|
```json
|
|
{
|
|
"trading_mode": "auto_trade",
|
|
"auto_trade": {
|
|
"enabled": true,
|
|
"max_trade_krw": 100000,
|
|
"allowed_symbols": [],
|
|
"require_env_confirm": true
|
|
},
|
|
"dry_run": true
|
|
}
|
|
```
|
|
- 환경변수 설정:
|
|
```bash
|
|
$env:AUTO_TRADE_ENABLED = "1"
|
|
```
|
|
- 실행: `python main.py`
|
|
- 기대 결과:
|
|
- 매도 신호 감지 시 Telegram으로 확인 토큰 수신
|
|
- 토큰으로 파일 생성 후 주문 진행 (시뮬레이션)
|
|
- `pending_orders.json` 및 `trades.json`에 기록
|
|
- 확인:
|
|
- Telegram 확인 메시지 형식이 명확한가?
|
|
- 파일 생성으로 확인 메커니즘이 동작하는가?
|
|
- 거래 기록이 제대로 저장되는가?
|
|
|
|
#### 3.4 단계 4: **실제 자동매도 활성화** (최종 단계, 신중!)
|
|
```json
|
|
{
|
|
"trading_mode": "auto_trade",
|
|
"auto_trade": {
|
|
"enabled": true,
|
|
"buy_enabled": false,
|
|
"max_trade_krw": 100000,
|
|
"allowed_symbols": ["KRW-BTC"],
|
|
"require_env_confirm": true
|
|
},
|
|
"dry_run": false
|
|
}
|
|
```
|
|
- 환경변수 설정:
|
|
```bash
|
|
$env:AUTO_TRADE_ENABLED = "1"
|
|
```
|
|
- Upbit 테스트 계좌 또는 소액 계좌 사용 권장
|
|
- 실행: `python main.py`
|
|
- 확인:
|
|
- Telegram에서 실제 매도 주문 확인 메시지 수신
|
|
- 파일 생성으로 주문 실행
|
|
- Upbit 계정에서 주문 이력 확인
|
|
- 모니터링 후 체결 알림 수신
|
|
|
|
#### 3.5 단계 5: **실제 자동매수 활성화** (최종 단계, 매우 신중!)
|
|
```json
|
|
{
|
|
"trading_mode": "auto_trade",
|
|
"auto_trade": {
|
|
"enabled": true,
|
|
"buy_enabled": true,
|
|
"buy_amount_krw": 10000,
|
|
"max_trade_krw": 100000,
|
|
"allowed_symbols": ["KRW-BTC"],
|
|
"require_env_confirm": true
|
|
},
|
|
"dry_run": false
|
|
}
|
|
```
|
|
- 환경변수 설정:
|
|
```bash
|
|
$env:AUTO_TRADE_ENABLED = "1"
|
|
```
|
|
- ⚠️ **중요**: 자동매수는 자본 손실 위험이 높습니다. 반드시 소액으로 시작하세요.
|
|
- Upbit 테스트 계좌 또는 소액 계좌 사용 필수
|
|
- 실행: `python main.py`
|
|
- 확인:
|
|
- 매수 신호 감지 시 Telegram에서 매수 주문 확인 메시지 수신
|
|
- 파일 생성으로 주문 실행
|
|
- Upbit 계정에서 매수 주문 이력 확인
|
|
- 모니터링 후 체결 알림 수신
|
|
- `holdings.json`에 새로운 보유 정보 자동 기록
|
|
|
|
---
|
|
|
|
## 4. 주문 확인 프로세스
|
|
|
|
### 4.1 Telegram 기반 확인 (현재 구현)
|
|
1. 자동매매 신호 감지 → Telegram 알림 수신
|
|
```
|
|
[확인필요] 자동매매 주문 대기
|
|
토큰: a1b2c3d4
|
|
심볼: KRW-BTC
|
|
주문량: 0.00010000
|
|
```
|
|
|
|
2. 프로젝트 루트에서 파일 생성 (PowerShell 예):
|
|
```powershell
|
|
New-Item "confirm_a1b2c3d4" -ItemType File
|
|
```
|
|
또는 `confirmed_tokens.txt` 파일에 토큰 추가:
|
|
```
|
|
a1b2c3d4
|
|
```
|
|
|
|
3. 코드가 자동으로 파일/토큰 감지 → 주문 실행
|
|
|
|
### 4.2 타임아웃
|
|
- 기본 300초(5분) 내에 확인이 없으면 자동 취소
|
|
- `config.json`의 `confirm.confirm_timeout`으로 조정 가능
|
|
|
|
---
|
|
|
|
## 5. 운영 (Troubleshooting)
|
|
|
|
### 주문이 실행되지 않는 경우
|
|
1. **환경변수 확인**:
|
|
```bash
|
|
echo $env:AUTO_TRADE_ENABLED
|
|
# 결과: 1이어야 함
|
|
```
|
|
|
|
2. **API 키 확인**:
|
|
```bash
|
|
echo $env:UPBIT_ACCESS_KEY
|
|
# 결과: 실제 키가 설정되어 있어야 함
|
|
```
|
|
|
|
3. **로그 파일 확인**:
|
|
```bash
|
|
Get-Content "logs/macd_alarm.log" -Tail 20
|
|
# "자동매매 비활성화" 또는 "Upbit API 키 없음" 오류 찾기
|
|
```
|
|
|
|
4. **config.json 문법 확인**:
|
|
```bash
|
|
python -c "import json; json.load(open('config.json'))"
|
|
# JSON 파싱 오류 있으면 출력됨
|
|
```
|
|
|
|
### 부분체결 처리
|
|
- 주문량이 크거나 시장 유동성이 낮으면 부분체결 발생 가능
|
|
- `ORDER_MAX_RETRIES` 환경변수로 재시도 횟수 조정 (기본 1회)
|
|
- 모니터링은 `ORDER_MONITOR_TIMEOUT` 시간(기본 120초) 동안 진행
|
|
|
|
### 긴급 중지
|
|
- 파일 생성하지 않으면 `confirm_timeout` 후 자동 취소
|
|
- 또는 `dry_run: true`로 되돌려서 봇 재시작
|
|
|
|
---
|
|
|
|
## 6. 성능/안정성 팁
|
|
|
|
1. **작은 규모로 시작**:
|
|
- `max_trade_krw`: 처음엔 10만~100만 KRW 범위
|
|
- `allowed_symbols`: 확실한 심볼 몇 개만 선택
|
|
|
|
2. **로그 모니터링**:
|
|
- 실시간: `Get-Content "logs/macd_alarm.log" -Tail 10 -Wait`
|
|
- 또는 별도 터미널에서: `tail -f logs/macd_alarm.log`
|
|
|
|
3. **야간/주말 고려**:
|
|
- Upbit는 24/7 운영이지만, 유동성이 낮은 시간대 존재
|
|
- 백테스트 후 적절한 시간대에만 매매 권장
|
|
|
|
4. **백업**:
|
|
- `trades.json` 주기적 백업
|
|
- 또는 SQLite로 마이그레이션 고려
|
|
|
|
---
|
|
|
|
## 7. FAQ
|
|
|
|
**Q: 실제로 주문이 체결되면 어떻게 되나?**
|
|
A: Upbit 계정에서 직접 체결되며, `trades.json` + Telegram 알림으로 기록됩니다.
|
|
|
|
**Q: 파일 생성을 깜빡하면?**
|
|
A: `confirm_timeout` 후 자동 취소되고, `trades.json`에 `user_not_confirmed` 기록됩니다.
|
|
|
|
**Q: 여러 심볼이 동시에 신호 나면?**
|
|
A: 각 심볼마다 독립적인 토큰으로 확인 요청. 병렬 처리 가능.
|
|
|
|
**Q: 테스트 중 실제 주문을 방지하려면?**
|
|
A: `dry_run: true` 또는 `auto_trade.enabled: false`, `auto_trade.buy_enabled: false` 유지.
|
|
|
|
**Q: 자동매수와 자동매도를 독립적으로 제어할 수 있나?**
|
|
A: 네. `auto_trade.enabled`는 매도만, `auto_trade.buy_enabled`는 매수만 제어합니다. 각각 독립적으로 활성화/비활성화 가능합니다.
|
|
|
|
**Q: 매수 후 holdings.json은 자동으로 업데이트되나?**
|
|
A: 네. 매수 체결 완료 시 자동으로 `holdings.json`에 매수가, 수량, 최고가, 매수시간이 기록됩니다.
|
|
|
|
**Q: 자동매수 금액을 어떻게 설정하나?**
|
|
A: `config.json`의 `auto_trade.buy_amount_krw`에 매수할 KRW 금액을 설정하세요. (예: 10000 = 1만원)
|
|
|
|
---
|
|
|
|
## 8. 법적 공지
|
|
|
|
⚠️ **면책**: 이 봇은 교육 목적으로 제작되었습니다. 실제 투자/자동매매 시 발생하는 손실에 대해 개발자는 책임을 지지 않습니다. 충분한 테스트 후 자신의 책임 하에 사용하세요.
|
|
|