108 lines
4.0 KiB
Markdown
108 lines
4.0 KiB
Markdown
# AssetMonitor 주식·코인 모니터링 시스템
|
||
|
||
## 개요
|
||
`AssetMonitor`는 주식‧ETF 및 암호화폐 시장을 실시간으로 감시하여 Bollinger Band, RSI, MACD, 이동평균(Golden-Cross), 거래량 등을 종합 분석한 **매수 후보(signals)**를 텔레그램으로 통보하는 자동화 봇입니다.
|
||
|
||
---
|
||
|
||
## 주요 구성 파일
|
||
| 파일 | 설명 |
|
||
|------|------|
|
||
| `config.py` | ✅ API 토큰, 텔레그램 채널 ID, 볼린저 밴드/임계값, 모니터링 자산 목록(KR_COINS, US_STOCKS, KR_ETFS) 등 전역 설정을 보관합니다. |
|
||
| `stock_monitor.py` | 시스템의 핵심 로직이 담긴 실행 스크립트입니다. <br/>• 데이터 수집 ⇒ 기술적 지표 계산 ⇒ 매수 신호 판단 ⇒ 메시지 포맷팅/발송 <br/>• `schedule` 라이브러리로 정해진 시간마다 작업을 자동 실행합니다. |
|
||
| `requirements.txt` | 프로젝트 의존 패키지를 명시합니다. |
|
||
|
||
---
|
||
|
||
## 데이터 흐름
|
||
1. **스케줄 트리거** (`run_schedule`)
|
||
지정된 시각에 각 모니터링 함수가 호출됩니다.
|
||
2. **데이터 획득**
|
||
*주식 / ETF*: `FinanceDataReader`
|
||
*암호화폐*: 빗썸 **240분 봉** Open API
|
||
3. **기술적 지표 계산** (`calculate_technical_indicators`)
|
||
- Bollinger Band (기간 20, ±2σ)
|
||
- RSI(14)
|
||
- MACD(12-26-9)
|
||
- 단/중/장기 이동평균선(MA5/20/60)
|
||
- 거래량 MA5
|
||
4. **매수 후보 판정** (`check_buy_signals`)
|
||
- 볼린저 하단 근접도 < `BOLLINGER_THRESHOLD` (기본 0.10)
|
||
- RSI < 30 (과매도)
|
||
- MACD 골든크로스
|
||
- MA5가 MA20 상향 돌파
|
||
- 거래량 급증(현재 > MA5 × 1.5)
|
||
위 조건 중 ① Bollinger & RSI 동시 충족 **또는** ② 최소 2개 이상(+Bollinger 또는 RSI 포함) 만족 시 `buy=True`.
|
||
5. **알림 발송** (`send_*_telegram_message`)
|
||
multiprocessing Pool을 이용해 다중 메시지를 병렬로 전송합니다.
|
||
|
||
---
|
||
|
||
## 스케줄 테이블 (기본값)
|
||
| 대상 | 실행 시각(서버 기준) | 호출 함수 |
|
||
|------|----------------------|-----------|
|
||
| KRW 코인 | 매시간 04, 34분 | `monitor_coins()` |
|
||
| 미국 주식 / ETF | 05:10, 16:30, 23:30 | `monitor_us_stocks()` |
|
||
| 한국 ETF / 주식 | 07:10, 18:20 | `monitor_kr_stocks()` |
|
||
|
||
> 시간은 `config.py`가 아닌 `stock_monitor.py`의 `run_schedule()` 내부에 하드코딩되어 있습니다. 필요 시 직접 수정하세요.
|
||
|
||
---
|
||
|
||
## 설치 방법
|
||
1. Python ≥ 3.9 환경을 준비합니다.
|
||
2. 저장소를 클론하고 디렉터리로 이동:
|
||
```bash
|
||
$ git clone <repo-url>
|
||
$ cd AssetMonitor
|
||
```
|
||
3. 패키지 설치:
|
||
```bash
|
||
$ pip install -r requirements.txt
|
||
```
|
||
4. **보안 키 등록**
|
||
민감 정보는 코드에 직접 기록하지 말고 *환경 변수*로 주입하기를 권장합니다.
|
||
```bash
|
||
# zsh 예시
|
||
export COIN_TELEGRAM_BOT_TOKEN="<TOKEN>"
|
||
export STOCK_TELEGRAM_BOT_TOKEN="<TOKEN>"
|
||
export COIN_TELEGRAM_CHAT_ID="<CHAT_ID>"
|
||
export STOCK_TELEGRAM_CHAT_ID="<CHAT_ID>"
|
||
```
|
||
또는 `config.py` 내부 상수를 직접 수정할 수 있습니다.
|
||
|
||
---
|
||
|
||
## 사용 방법
|
||
```bash
|
||
$ python stock_monitor.py
|
||
```
|
||
스크립트가 백그라운드에서 무한 루프로 동작하며 지정된 시간마다 텔레그램 알림을 전송합니다.
|
||
|
||
### Docker(선택)
|
||
컨테이너 실행 예시:
|
||
```dockerfile
|
||
FROM python:3.11-slim
|
||
WORKDIR /app
|
||
COPY . .
|
||
RUN pip install -r requirements.txt
|
||
CMD ["python", "stock_monitor.py"]
|
||
```
|
||
|
||
---
|
||
|
||
## 커스터마이징
|
||
- **자산 목록 추가/삭제**: `config.py`의 `KR_COINS`, `US_STOCKS`, `KR_ETFS` 사전을 편집합니다.
|
||
- **임계값·기간 조정**: `BOLLINGER_PERIOD`, `BOLLINGER_STD`, `BOLLINGER_THRESHOLD`, `BUY_THRESHOLD` 등 변경.
|
||
|
||
---
|
||
|
||
## 한계 및 면책 조항
|
||
본 프로젝트는 교육·연구 목적의 오픈소스 예제로, 투자 손실에 대해 어떠한 책임도 지지 않습니다. 실거래에 사용하려면 충분한 검증과 백테스트를 진행하십시오.
|
||
|
||
---
|
||
|
||
## 라이선스
|
||
MIT (프로젝트 루트의 `LICENSE` 파일 참조, 미존재 시 필요에 따라 추가하세요.)
|
||
|