# DeepCoin

빗썸 KRW 마켓 암호화폐 캔들 데이터 수집 프로젝트.

## 주요 기능

- 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집
- SQLite(`coins.db`) 저장 — 테이블명 `{SYMBOL}_{인터벌코드}` (예: `BTC_60`, `BTC_10080`)
- 최대 2년(기본 730일) 역방향 페이지네이션 수집

## 요구사항

- Python 3.10+
- Conda 환경 `ncue` 또는 `xavis`

## 설치

```bash
cd DeepCoin
conda activate ncue
pip install -r requirements.txt
cp .env.example .env   # API 키 등 입력
```

## 환경 변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `SYMBOL` | 코인 심볼 | `BTC` |
| `COIN_NAME` | 코인 이름 | `비트코인` |
| `DB_PATH` | SQLite 경로 | `coins.db` |
| `DOWNLOAD_DAYS` | 수집 일수 (최대 2년) | `730` |
| `DOWNLOAD_INTERVALS` | 인터벌 코드 목록 | `3,5,10,15,30,60,240,1440,10080,43200` |
| `BITHUMB_API_CANDLE_COUNT` | 요청당 캔들 수 (최대 200) | `200` |
| `API_REQUEST_SLEEP_SEC` | API 호출 간격(초) | `0.35` |

인터벌 코드: 분봉은 분 단위 숫자, 일봉=`1440`, 주봉=`10080`, 월봉=`43200`

캔들 조회는 Public API이므로 API 키 없이도 동작합니다.

## 5단계 파이프라인

| 단계 | 목적 | 스크립트 |
|------|------|----------|
| 0 | 데이터 수집 | `01_download.py` |
| 1 | Ground Truth (사후 벤치마크 타점) | `02_ground_truth.py` |
| 2 | 매매 기법 개발·GT 정합 비교 | `03_run_techniques.py` |
| 3 | 인과 신호 (과거 데이터만) | (예정) |
| 4 | 시뮬레이션 백테스트 | (예정) |
| 5 | 실거래 운영 | (예정) |

```bash
# 0. 데이터 수집
python scripts/01_download.py

# 1. Ground Truth (매수·매도 벤치마크 타점)
python scripts/02_ground_truth.py

# 1-b. 선물 GT 차트 (현물 GT → 롱·숏 4색)
python scripts/02_ground_truth_futures.py

# 1-c. 선물 1년 sim 차트 (40만원 · 롱·숏 4색)
python scripts/02_ground_truth_futures_sim.py

# 2. 매매 기법 실행 및 GT 정합 비교
python scripts/03_run_techniques.py
```

## 2단계 매매 기법 (8종)

Ground Truth 타점에 맞출 수 있는 후보 기법. 모두 **인과 신호** (미래 데이터 미사용).

| ID | 기법 | 유형 | 설명 |
|----|------|------|------|
| `zigzag_causal` | 인과 ZigZag | swing | GT ZigZag 5%의 인과 버전 |
| `minor_swing` | 소형 스윙 하이브리드 | hybrid | ZigZag 2.5% + 국소 극값 |
| `local_extrema` | 국소 극값 | swing | 눌림목·반등 고점 (9/27 유형) |
| `bb_reversal` | 볼린저 역추세 | indicator | BB 하단 매수·상단 매도 |
| `ma_cross` | EMA 크로스 | indicator | EMA(20/60) 골든·데드 크로스 |
| `rsi_swing` | RSI 스윙 | indicator | RSI 과매도·과매수 복귀 |
| `macd_cross` | MACD 크로스 | indicator | MACD 시그널선 크로스 |
| `donchian` | 돈치안 채널 | swing | 채널 하단·상단 반전 |

GT 정합 평가: 매수/매도 recall, 레그 recall, 수익 포착률, 종합 score.

## 실행 (데이터 수집)

```bash
# 전체 인터벌, 최대 2년
python scripts/download_candles.py

# 일·주·월봉만 빠르게
python scripts/download_candles.py --intervals 1440,10080,43200

# 최근 90일, 60분봉만
python scripts/download_candles.py --days 90 --intervals 60
```

## 디렉터리 구조

```text
DeepCoin/
├── src/deepcoin/
│   ├── api/bithumb.py
│   ├── data/
│   ├── ground_truth/       # 1단계
│   ├── techniques/         # 2단계 매매 기법
│   └── evaluation/         # GT 정합 평가
├── scripts/
│   ├── 01_download.py
│   ├── 02_ground_truth.py
│   └── 03_run_techniques.py
├── data/
│   ├── ground_truth/
│   │   ├── spot/           # 현물 GT JSON
│   │   └── futures/        # 선물 GT JSON (예정)
│   └── techniques/
├── docs/
│   ├── 02_ground_truth/
│   │   ├── gt/             # 현물 1단계 GT 타점 차트 (v1~v3)
│   │   ├── spot/           # 현물 2단계 sim 차트 (v1~v3)
│   │   └── futures/        # 선물 GT(gt/)·sim 차트 (롱·숏 4색, v1~v3)
│   └── 03_analysis/
└── coins.db
```

## 변경 이력

- 2026-06-09: 선물 GT 차트를 futures/gt/로 정리, 마커 UI 개선(2배·세로스택·Y축뒤집기)
- 2026-06-09: 선물 GT 차트 v1~v3 추가 (현물 GT → 롱·숏 4색 마커)
- 2026-06-09: docs/02_ground_truth를 gt(타점)·spot(sim)·futures 3폴더로 분리
- 2026-06-09: Ground Truth 산출물 현물(spot)/선물(futures) 폴더 분리
- 2026-06-08: 2단계 매매 기법 8종 + GT 정합 비교 리포트 추가
- 2026-06-08: 1단계 Ground Truth (ZigZag 스윙 매수·매도 타점) 추가
- 2026-06-07: BTC 최대 2년 분·일·주·월봉 수집 지원
- 2026-06-07: 캔들 수집 모듈 초기 구현