Bithumb/README.md

# DeepCoin

빗썸 KRW 마켓 암호화폐 캔들 데이터 수집 및 선물 매매 전략 파이프라인.

## 주요 기능

- 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집
- SQLite(`coins.db`) 저장 — 테이블명 `{SYMBOL}_{인터벌코드}` (예: `BTC_60`, `BTC_10080`)
- 2017-01-01~ 역방향 페이지네이션 수집 (기본 3447일)
- Ground Truth 기반 선물 롱·숏 벤치마크 및 인과 전략 시뮬레이션

## 요구사항

- 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` | 수집·차트 일수 (2017~) | `3447` |
| `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 키 없이도 동작합니다.

---

## 파이프라인 (0~4단계)

| 단계 | 목적 | 산출물 (v3 기준) | 스크립트 |
|------|------|------------------|----------|
| **사전** | 캔들 데이터 수집 | `coins.db` | `01_download.py` |
| **0단계** | GT 매수/매도 **기본 데이터**(타점) 생성 | `docs/0_ground_truth/{spot,futures}/` | `02_ground_truth.py`, `02_ground_truth_futures.py` |
| **1단계** | 0단계 데이터로 **최근 3년 sim** | `docs/1_simulation/{spot,futures}/` | `02_ground_truth_sim.py`, `02_ground_truth_futures_sim.py` |
| **2단계** | 인과 기법 **GT 정합·MTF 분석** | `docs/2_analysis/spot/` | `03_run_techniques.py`, `03_run_signal_type_align.py`, `03_run_mtf_analysis.py` |
| **3단계** | 인과 전략 sim → **1단계와 비교** | `docs/3_causal/futures/` | `04_run_causal_futures.py` |
| **4단계** | 시뮬 코드 기반 **실거래** | (예정) | (예정) |

### 실행 순서

0단계(GT 타점)를 먼저 만든 뒤, 1단계 sim을 돌립니다.

```bash
# 사전: 데이터 수집
python scripts/01_download.py

# 0단계: Ground Truth 타점 생성 (v1/v2/v3)
python scripts/02_ground_truth.py

# 0단계: 선물 GT 타점 차트 (롱·숏 4색, 타점만)
python scripts/02_ground_truth_futures.py

# 1단계: GT 기반 sim (최근 3년 · 40만원)
python scripts/02_ground_truth_sim.py --tier all
python scripts/02_ground_truth_futures_sim.py --tier v3

# 2단계: 인과 기법 GT 정합 비교
python scripts/03_run_techniques.py

# 2단계: v3 신호 유형별 정합 (B/B*/B^/Bd/S/Sd)
python scripts/03_run_signal_type_align.py

# 2단계: GT v3 · 멀티 TF 피처 상관 분석
python scripts/03_run_mtf_analysis.py

# 3단계: 인과 전략 sim + 1단계 sim 비교
python scripts/04_run_causal_futures.py
python scripts/04_run_causal_futures.py --mtf
python scripts/04_run_causal_futures.py --walkforward
```

### 0단계 — GT 타점 (`docs/0_ground_truth/`)

- `spot/ground_truth_chart_v3.html` — 현물 GT 매수/매도 타점
- `futures/ground_truth_chart_v3.html` — 선물 L↑/L↓/S↓/S↑ 4색 마커

### 1단계 — GT sim (`docs/1_simulation/`)

`docs/1_simulation/futures/ground_truth_chart_sim_v3.html` (비교 기준)

- 0단계 GT 타점 그대로 최근 3년 선물/현물 sim
- sim 초기 자본 **40만 원**, 매수(L↑·S↓)는 총평가 구간별 현금 비율 상한: 1억↑ 10% · 10억↑ 5% · 100억↑ 1%

### 2단계 — 인과 기법 (`docs/2_analysis/spot/`)

- `comparison_report.html` — 기법별 GT 정합 recall·score
- `signal_type_report.html` — B/B*/B^/Bd/S/Sd 유형별 recall
- `mtf_correlation_report.html` — GT v3 × 10 TF 피처 (Cohen's d)

`src/deepcoin/techniques/` — 9종 인과 기법 (미래 데이터 미사용).

| ID | 기법 | 유형 | 설명 |
|----|------|------|------|
| `zigzag_causal` | 인과 ZigZag | swing | GT ZigZag 5%의 인과 버전 |
| `minor_swing` | 소형 스윙 하이브리드 | hybrid | ZigZag 2.5% + 국소 극값 |
| `local_extrema` | 국소 극값 | swing | 눌림목·반등 고점 |
| `bb_reversal` | 볼린저 역추세 | indicator | BB 하단 매수·상단 매도 |
| `ma_cross` | EMA 크로스 | indicator | EMA(20/60) 골든·데드 크로스 |
| `rsi_swing` | RSI 스윙 | indicator | RSI 과매도·과매수 복귀 |
| `macd_cross` | MACD 크로스 | indicator | MACD 시그널선 크로스 |
| `donchian` | 돈치안 채널 | swing | 채널 상·하단 돌파 |
| `composite_v3` | v3 통합 스코어링 | composite | 4종 신호 가중 투표 + EMA(60) 필터 |

### 3단계 — 인과 sim (`docs/3_causal/futures/`)

- `causal_chart_sim_v3.html` — composite_v3 인과 sim
- `causal_mtf_chart_sim_v3.html` — composite + MTF 필터
- `walkforward_mtf_chart_sim_v3.html` — bar-by-bar 워크포워드 MTF
- `causal_futures_report.html` — 1단계 sim 대비 composite_v3
- `causal_mtf_futures_report.html` — 1단계 sim 대비 composite+MTF
- `walkforward_mtf_report.html` — 1단계 sim 대비 워크포워드

---

## 디렉터리 구조

```text
DeepCoin/
├── src/deepcoin/
│   ├── data/               # 캔들 수집·로드
│   ├── ground_truth/       # 1단계 GT 생성·차트·선물 sim 엔진
│   ├── techniques/         # 1단계 기법 커먼
│   ├── evaluation/         # 2단계 GT 정합 평가
│   └── strategy/           # 3단계 인과 전략
├── scripts/
│   ├── 01_download.py              # 사전
│   ├── 02_ground_truth.py          # 0단계 GT
│   ├── 02_ground_truth_futures.py  # 0단계 선물 GT 차트
│   ├── 02_ground_truth_sim.py      # 1단계 현물 sim
│   ├── 02_ground_truth_futures_sim.py  # 1단계 선물 sim
│   ├── 03_run_techniques.py        # 2단계
│   ├── 03_run_signal_type_align.py # 2단계
│   └── 04_run_causal_futures.py    # 3단계
├── data/
│   ├── ground_truth/spot/  # GT JSON v1~v3
│   ├── techniques/         # 2단계 기법 실행 결과
│   └── causal/             # 3단계 인과 신호 JSON
├── docs/
│   ├── 0_ground_truth/     # 0단계 GT 타점 차트
│   │   ├── spot/
│   │   └── futures/
│   ├── 1_simulation/       # 1단계 GT sim 차트
│   │   ├── spot/
│   │   └── futures/
│   ├── 2_analysis/         # 2단계 정합·MTF 리포트
│   │   ├── spot/
│   │   └── futures/
│   └── 3_causal/           # 3단계 인과 sim·리포트
│       ├── spot/
│       └── futures/
└── coins.db
```

## 변경 이력

- 2026-06-10: docs를 단계별 폴더(`0_ground_truth`~`3_causal`)로 재구성, 단계 정의 정렬 (0=GT 타점, 1=sim)
- 2026-06-09: 파이프라인 번호를 0~4단계 체계로 통일 (0=벤치마크, 1=GT+기법, 2=인과분석, 3=시뮬, 4=실거래)
- 2026-06-09: 3단계 인과 선물 전략 (composite_v3 + ATR) + 0단계 벤치마크 비교
- 2026-06-09: v3 신호 유형별 GT 정합 리포트 + composite_v3 통합 기법
- 2026-06-09: 선물 GT 차트 futures/gt/ 정리, 마커 UI 개선
- 2026-06-08: Ground Truth v1/v2/v3 + 매매 기법 8종
- 2026-06-07: 캔들 수집 모듈 초기 구현