# DeepCoin

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

## 주요 기능

- 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집
- SQLite(`coins.db`) 저장 — 테이블명 `{SYMBOL}_{인터벌코드}` (예: `BTC_60`, `BTC_10080`)
- 2017-01-01~ 역방향 페이지네이션 수집 (기본 3650일·10년, **1분봉 포함**)
- 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` | 전체 수집·차트 일수 (10년) | `3650` |
| `DOWNLOAD_INTERVALS` | 인터벌 코드 목록 (`1`=1분봉 포함) | `1,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단계**는 현물·선물 공통입니다. 이후 현물·선물은 각각 1~3단계로 독립 진행합니다.

| 구분 | 단계 | 내용 | 산출물 | 스크립트 |
|------|------|------|--------|----------|
| 사전 | — | 캔들 수집 | `coins.db` | `00_download.py` |

### 0단계 — GT 타점 (현물·선물 공통)

| 시장 | 산출물 | 스크립트 |
|------|--------|----------|
| 현물 | `docs/0_ground_truth/spot/` | `0_ground_truth.py` |
| 선물 | `docs/0_ground_truth/futures/` | `0_ground_truth_futures.py` |

### 현물 단계

| 단계 | 내용 | 산출물 | 스크립트 |
|------|------|--------|----------|
| **현물 1단계** | GT sim (벤치마크) 현물 | `docs/spot/1_simulation/` | `1_ground_truth_sim.py` |
| **현물 2단계** | 인과 기법 분석 (현물) | `docs/spot/2_analysis/` | `2_run_techniques.py` 등 |
| **현물 3단계** | 현물 실거래 운영 | (예정) | (예정) |

### 선물 단계

| 단계 | 내용 | 산출물 | 스크립트 |
|------|------|--------|----------|
| **선물 1단계** | GT sim (벤치마크) 선물 | (예정) | (예정) |
| **선물 2단계** | 인과 기법 분석 (선물) | (예정) | (예정) |
| **선물 3단계** | 선물 실거래 운영 | (예정) | (예정) |

### 단계별 상세 설명

#### 사전 — 캔들 수집

빗썸 Public API로 분·일·주·월봉(1분봉 포함) OHLCV를 수집해 `coins.db`에 저장합니다. 이후 모든 단계는 이 DB만 참조하며, 현물·선물이 DB를 공유합니다.

- 기본 동작: DB 최신 시각 이후 **증분 갱신** (`00_download.py`)
- 전체 재수집: `--full` 옵션 (최초 1회·DB 재구축 시)
- 테이블명: `{SYMBOL}_{인터벌코드}` (예: `BTC_3`, `BTC_1440`)

#### 0단계 — GT 타점 (현물·선물 공통)

**Ground Truth(GT)** 는 사후적으로 “이상적인 매매 타점”을 정의한 기준 데이터입니다. 미래 캔들을 참조해 ZigZag 스윙·눌림목·돌파·다이버전스 타점을 찾으므로 **실거래에 직접 쓸 수 없고**, 이후 단계(벤치마크·기법 분석)의 **정답지(기준선)** 역할을 합니다.

| 티어 | 포함 신호 | 설명 |
|------|-----------|------|
| **v1** | 스윙 B/S | ZigZag 스윙 저점 매수·고점 매도만 |
| **v2** | + 눌림목 B* | v1 + 상승 레그 중 눌림목 매수 |
| **v3** | + 돌파 B^ + 다이버전스 Bd/Sd | v2 + 돌파 매수 + RSI 다이버전스 매수·매도 |

v3 신호 유형 6종:

| `signal_type` | 라벨 | 의미 |
|---------------|------|------|
| `swing_low` | B | ZigZag 스윙 저점 매수 |
| `pullback` | B* | 상승 추세 눌림목 매수 |
| `breakout` | B^ | 횡보·레인지 상단 돌파 매수 |
| `div_bull` | Bd | RSI 상승 다이버전스 매수 |
| `swing_high` | S | ZigZag 스윙 고점 매도 |
| `div_bear` | Sd | RSI 하락 다이버전스 매도 |

**현물 0단계** (`0_ground_truth.py`): 3분봉·2017년~ 구간에서 GT를 생성하고, 매수/매도 마커가 표시된 인터랙티브 차트를 만듭니다.

- 데이터: `data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json`
- 차트: `docs/0_ground_truth/spot/ground_truth_chart_v{1,2,3}.html`

**선물 0단계** (`0_ground_truth_futures.py`): 동일한 현물 GT 신호를 선물 롱·숏 4색 마커로 변환합니다. 가격·시각은 현물 GT와 동일하며, 해석만 선물 관점으로 매핑합니다.

| 현물 GT | 선물 마커 | 의미 |
|---------|-----------|------|
| buy (B·B*·B^·Bd) | **L↑** | 롱 진입 (상방 매수) |
| buy | **S↑** | 숏 청산 (하방 매도) |
| sell (S·Sd) | **L↓** | 롱 청산 (상방 매도) |
| sell | **S↓** | 숏 진입 (하방 매수) |

- 데이터: `data/futures/ground_truth/ground_truth_trades_v{1,2,3}.json`
- 차트: `docs/0_ground_truth/futures/ground_truth_chart_v{1,2,3}.html`

#### 현물 1단계 — GT sim (벤치마크) 현물

0단계 GT 타점을 **그대로** 따라 매매했을 때의 수익을 재현하는 **현물 벤치마크**입니다. “GT를 완벽히 따랐다면 얼마를 벌 수 있었는가”를 측정하며, 이후 인과 기법·실거래 전략이 비교해야 할 **상한선(천장)** 입니다.

- 기간: 최근 **3년** (`GT_SIM_LOOKBACK_DAYS=1095`)
- 초기 자본: **20만 원**
- 매수 규칙: 총평가 구간별 현금 비율 상한 — 1억↑ 10% · 10억↑ 5% · 100억↑ 1%
- 수수료: 편도 0.05% (`GT_TRADING_FEE_RATE`)
- 산출물: `docs/spot/1_simulation/ground_truth_chart_sim_v{1,2,3}.html` (누적 수익 곡선·체결 마커 포함)

#### 현물 2단계 — 인과 기법 분석 (현물)

0단계 GT v3 타점을 **미래 데이터 없이** 재현할 수 있는 인과(causal) 매매 기법 39종을 실행하고, GT와 얼마나 맞는지 정량 평가합니다. 목표는 “실시간으로 쓸 수 있는 기법 조합이 GT 타점을 얼마나 포착하는가”를 파악하는 것입니다.

| 스크립트 | 분석 내용 | 산출물 |
|----------|-----------|--------|
| `2_run_techniques.py` | 39종 기법 전체 실행 + GT 정합 비교 | `comparison_report.html`, `data/spot/techniques/*.json` |
| `2_run_signal_type_align.py` | B/B*/B^/Bd/S/Sd 유형별 recall | `signal_type_report.html` |
| `2_run_mtf_analysis.py` | GT v3 × 10개 TF 피처 상관 (Cohen's d) | `mtf_correlation_report.html`, `data/spot/mtf/mtf_rules_v3.json` |

평가 지표:

- **recall**: GT 신호 대비 기법 신호가 허용 오차(`GT_ALIGN_TOLERANCE_BARS`) 내에 맞춘 비율
- **score**: recall·정밀도·타점 거리를 종합한 정합 점수
- **MTF 상관**: 일·주·월 등 상위 TF 지표가 GT 유형별로 어떤 패턴을 보이는지 통계 분석

#### 현물 3단계 — 현물 실거래 운영 (예정)

현물 2단계에서 검증된 인과 기법(또는 `composite_v3` 등 통합 기법)을 빗썸 현물 API에 연결해 **실제 주문·체결·리스크 관리**를 수행하는 단계입니다.

- 실시간 캔들 수신 및 인과 신호 생성
- 주문 실행·포지션(보유 코인)·손절/익절 규칙
- 1단계 GT sim 벤치마크 대비 실거래 성과 모니터링
- 텔레그램 등 알림·로그·장애 복구

#### 선물 1단계 — GT sim (벤치마크) 선물 (예정)

선물 0단계 GT 타점(L↑/L↓/S↓/S↑)을 그대로 따라 롱·숏 포지션을 운용했을 때의 수익을 재현하는 **선물 벤치마크**입니다. 현물 1단계와 동일한 개념이나, 롱·숏 양방향·레버리지·청산 규칙 등 선물 고유 파라미터를 반영합니다.

- 0단계 선물 GT 4색 마커 기준 체결 시뮬레이션
- 현물 1단계와 동일한 초기 자본·기간·수수료 체계 (선물 수수료·슬리피지 별도 정의 예정)
- 산출물 예정: `docs/futures/1_simulation/`

#### 선물 2단계 — 인과 기법 분석 (선물) (예정)

현물 2단계와 동일한 인과 기법 39종(또는 선물 특화 변형)을 선물 GT v3 타점과 정합 평가합니다. 롱·숏 각각의 recall, MTF 필터, 신호 유형별 성능을 선물 관점에서 분석합니다.

- 선물 GT 6종 신호 ↔ 인과 기법 정합 리포트
- 선물 MTF 상관 분석 및 규칙 추출
- 산출물 예정: `docs/futures/2_analysis/`, `data/futures/techniques/`, `data/futures/mtf/`

#### 선물 3단계 — 선물 실거래 운영 (예정)

선물 2단계에서 검증된 전략을 실제 선물 거래 API에 연결해 롱·숏 포지션을 자동 운용하는 단계입니다.

- 실시간 인과 신호 → 롱/숏 진입·청산
- 레버리지·증거금·청산가 모니터링
- 선물 1단계 sim 벤치마크 대비 실거래 성과 추적

### 실행 순서

0단계(GT 타점)를 먼저 만든 뒤, 현물 1단계 sim → 현물 2단계 인과 분석 순으로 진행합니다. 선물·현물 3단계는 각 시장의 1·2단계 완료 후 구현 예정입니다.

```bash
# 사전: 전체 인터벌 증분 갱신 (1분~월봉, DB 최신 이후만)
python scripts/00_download.py

# 사전: 전체 인터벌 풀 다운 (최초 1회 또는 DB 재구축)
python scripts/00_download.py --full

# 1분봉만 풀 다운 (수 시간 소요)
python scripts/00_download_candles.py --full --days 3650 --intervals 1

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

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

# 현물 1단계: GT sim (최근 3년 · 20만원)
python scripts/1_ground_truth_sim.py --tier all

# 현물 2단계: 인과 기법 GT 정합 비교
python scripts/2_run_techniques.py
python scripts/2_run_signal_type_align.py --from-cache
python scripts/2_run_mtf_analysis.py
```

### 현물 2단계 인과 기법 목록 (39종)

`src/deepcoin/techniques/` — 단일 33 + 복합 6, **미래 데이터 미사용**. 카탈로그: `data/spot/techniques_catalog.json`

| ID | 기법 | 유형 | 설명 |
|----|------|------|------|
| `zigzag_causal` | 인과 ZigZag | 스윙 B/S | 되돌림 % 확정 시 스윙 저점 매수·고점 매도 (GT ZigZag 인과 버전) |
| `minor_swing` | 소형 스윙 하이브리드 | 하이브리드 | 소형 ZigZag(2.5%) + 국소 극값 — GT 중간 눌림목 보완 |
| `local_extrema` | 국소 극값 | 스윙 B/S | 국소 저점 매수·고점 매도 (눌림목 유형 포착) |
| `pivot_swing` | 피벗 스윙 | 스윙 B/S | 피벗 저점 매수·고점 매도 (스윙 B/S) |
| `fractal_swing` | 프랙탈 스윙 | 스윙 B/S | Williams 프랙탈 스윙 저점 매수·고점 매도 |
| `swing_failure` | 스윙 실패 | 스윙 B/S | 스윙 고저점 돌파 실패(페일드 브레이크아웃) 반전 신호 |
| `donchian` | 돈치안 채널 | 스윙 B/S | 돈치안(40) 채널 하단 매수·상단 매도 |
| `ema_pullback` | EMA 눌림목 | 눌림목 B* | EMA(20/60) 눌림목 반등 매수·되돌림 매도 (B*) |
| `fib_pullback` | 피보나치 눌림목 | 눌림목 B* | 피보나치 38.2~61.8% 되돌림 구간 매수·매도 (B*) |
| `support_bounce` | 지지·저항 반등 | 눌림목 B* | N봉 지지·저항 터치 후 반전 (B*) |
| `keltner_breakout` | Keltner 돌파 | 돌파 B^ | Keltner 채널 상·하단 돌파 (B^) |
| `range_breakout` | 레인지 돌파 | 돌파 B^ | N봉 레인지 상·하단 돌파 (B^) |
| `volume_breakout` | 거래량 돌파 | 돌파 B^ | 거래량 스파이크 + 레인지 돌파 (B^) |
| `bb_squeeze_breakout` | BB 스퀴즈 돌파 | 돌파 B^ | 볼린저 밴드 스퀴즈 후 돌파 (B^) |
| `rsi_divergence` | RSI 다이버전스 | 다이버전스 Bd/Sd | RSI 상승(Bd)·하락(Sd) 다이버전스 |
| `macd_divergence` | MACD 다이버전스 | 다이버전스 Bd/Sd | MACD 히스토그램 상승(Bd)·하락(Sd) 다이버전스 |
| `obv_divergence` | OBV 다이버전스 | 다이버전스 Bd/Sd | OBV 상승(Bd)·하락(Sd) 다이버전스 |
| `bb_reversal` | 볼린저 역추세 | 지표 | BB(20,2) 하단 매수·상단 매도 + EMA 추세 필터 |
| `ma_cross` | EMA 크로스 | 지표 | EMA(20/60) 골든크로스 매수·데드크로스 매도 |
| `rsi_swing` | RSI 스윙 | 지표 | RSI(14) 과매도 반등 매수·과매수 하락 매도 |
| `macd_cross` | MACD 크로스 | 지표 | MACD(12,26,9) 시그널선 골든·데드 크로스 |
| `supertrend` | Supertrend | 추세 | Supertrend 상승·하락 전환 신호 |
| `adx_trend` | ADX 추세 | 추세 | ADX(14) 강세 + DI 크로스 추세 신호 |
| `ichimoku_trend` | 일목 추세 | 추세 | 일목 전환선·기준선 크로스 추세 신호 |
| `parabolic_sar` | Parabolic SAR | 추세 | Parabolic SAR 추세 전환 신호 |
| `stochastic_cross` | Stochastic 크로스 | 모멘텀 | Stochastic(14,3) %K/%D 크로스 |
| `cci_extreme` | CCI 극값 | 모멘텀 | CCI(20) 과매도·과매수 반전 |
| `roc_reversal` | ROC 반전 | 모멘텀 | ROC(12) 극값 반전 신호 |
| `keltner_reversal` | Keltner 역추세 | 변동성 | Keltner 채널 하단 매수·상단 매도 |
| `atr_channel` | ATR 채널 | 변동성 | EMA(20) ± ATR(14)×2 채널 반전 |
| `pivot_points` | 피벗 포인트 | 구조 | 롤링 피벗 S1/R1 반전 |
| `support_resistance` | 구조적 지지·저항 | 구조 | 스윙 피벗 기반 S/R 반전 |
| `volume_spike` | 거래량 스파이크 | 거래량 | 거래량 스파이크 후 반전 (클라이맥스) |
| `composite_swing` | 스윙 복합 | 복합 | 스윙 저점·고점 전담 기법 가중 투표 (B/S) |
| `composite_pullback` | 눌림목 복합 | 복합 | 눌림목·역추세 기법 가중 투표 (B*) |
| `composite_breakout` | 돌파 복합 | 복합 | 돌파·모멘텀 기법 가중 투표 (B^) |
| `composite_divergence` | 다이버전스 복합 | 복합 | RSI/MACD/OBV 다이버전스 가중 투표 (Bd/Sd) |
| `composite_v3` | v3 통합 스코어링 | 복합 | v3 GT 6종 신호 유형별 핵심 기법 가중 투표 + EMA(60) 추세 필터 |
| `composite_full` | 전체 통합 복합 | 복합 | 전체 인과 기법 가중 투표 + EMA 추세 필터 |

---

## 디렉터리 구조

```text
DeepCoin/
├── src/deepcoin/
│   ├── data/               # 캔들 수집·로드
│   ├── ground_truth/       # 0·1단계 GT·차트
│   ├── techniques/         # 현물 2단계 인과 기법 (39종)
│   ├── evaluation/         # 현물 2단계 GT 정합 평가
│   └── mtf/                # 현물 2단계 MTF 분석
├── scripts/                        # 접두사: 00=사전, 0=0단계, 1=현물1, 2=현물2
│   ├── 00_download.py              # 사전 (증분/풀다운 래퍼)
│   ├── 00_download_candles.py      # 사전 (캔들 수집 본체)
│   ├── 0_ground_truth.py          # 0단계 현물 GT
│   ├── 0_ground_truth_futures.py  # 0단계 선물 GT 차트
│   ├── 1_ground_truth_sim.py      # 현물 1단계 sim
│   ├── 2_run_techniques.py        # 현물 2단계
│   ├── 2_run_signal_type_align.py
│   └── 2_run_mtf_analysis.py
├── coins.db                # 공유 캔들 DB (현물·선물 유일한 공유 리소스)
├── data/
│   ├── spot/               # 현물 전용
│   │   ├── ground_truth/   # GT JSON v1~v3
│   │   ├── techniques/     # 2단계 기법 실행 결과
│   │   └── mtf/            # MTF 규칙
│   └── futures/            # 선물 (0단계 GT만, 1~3단계 추후)
│       └── ground_truth/
├── docs/
│   ├── 0_ground_truth/       # 0단계 (현물·선물 공통)
│   │   ├── spot/
│   │   └── futures/
│   └── spot/               # 현물 1~2단계
│       ├── 1_simulation/
│       └── 2_analysis/
```

현물·선물은 `coins.db`만 공유합니다. 현재 구현 범위는 **0단계(공통) + 현물 1·2단계**이며, 선물 1~3단계·현물 3단계는 추후 구현 예정입니다.

## 변경 이력

- 2026-06-11: `docs/0_ground_truth/{spot,futures}/`로 0단계 차트를 docs 직하로 이동
- 2026-06-11: `scripts/` 접두사를 파이프라인 단계와 일치 (`00_` 사전, `0_` 0단계, `1_` 현물1, `2_` 현물2)
- 2026-06-11: README 파이프라인 단계별 상세 설명 추가 (0단계 공통 + 현물·선물 1~3단계)
- 2026-06-11: README 파이프라인을 0단계(공통) + 현물·선물 각 1~3단계 체계로 정리
- 2026-06-11: 선물 1~3단계·`04_run_causal_futures` 제거, 현물 0·1·2단계만 유지
- 2026-06-11: `docs/spot/`·`docs/futures/` 상위 분리 (`data/`와 동일 구조)
- 2026-06-11: `data/spot/`·`data/futures/` 완전 분리 (`coins.db`만 공유), 선물 GT·MTF·causal 독립 경로
- 2026-06-11: 2단계 38종 기법 리포트 재생성, 3단계 causal/MTF/walkforward 재검증, README 39종 표 반영
- 2026-06-11: 캔들 수집 기본 동작을 DB 최신 이후 증분 갱신으로 변경 (`--full`로 전체 재수집)
- 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: 캔들 수집 모듈 초기 구현