# 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/02_ground_truth/futures/ground_truth_chart_sim_v3.html` | `02_ground_truth_futures_sim.py` |
| **1단계** | Ground Truth 타점 + 매매 **기법 커먼** 모듈 | GT JSON, `techniques/`, 선물 GT 차트 | `02_ground_truth.py`, `02_ground_truth_futures.py` |
| **2단계** | 0단계 시점에서 **과거 데이터만** 쓰는 인과 타점 판별·정합 분석 | `docs/03_analysis/` | `03_run_techniques.py`, `03_run_signal_type_align.py` |
| **3단계** | 개발 로직으로 시뮬 → **0단계와 수익률 비교** | `docs/02_ground_truth/futures/causal_chart_sim_v3.html`, `docs/03_simulation/` | `04_run_causal_futures.py` |
| **4단계** | 시뮬 코드 기반 **실거래** 운영 | (예정) | (예정) |

### 실행 순서

1단계(GT·기법)를 먼저 만든 뒤, 0단계 벤치마크 sim을 돌립니다.

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

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

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

# 0단계: 선물 벤치마크 수익 sim (GT 사후 타점 · 최근 3년 · 40만원)
#   → ground_truth_chart_sim_v3.html 이 상한 기준
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

# 3단계: 인과 전략 시뮬 + 0단계 벤치마크 비교
python scripts/04_run_causal_futures.py
```

### 0단계 벤치마크 (기준 차트)

`docs/02_ground_truth/futures/ground_truth_chart_sim_v3.html`

- 현물 v3 GT 매수/매도 1타점 → 선물 **L↑/L↓/S↓/S↑** 동시 체결
- **사후 최적 타점** 기준이므로 실전 상한선(천장)으로 사용
- 매수(B 계열): L↑ 롱 진입 + S↑ 숏 청산
- 매도(S 계열): L↓ 롱 청산 + S↓ 숏 진입

### 1단계 기법 커먼 (9종)

`src/deepcoin/techniques/` — 모두 **인과 신호** (미래 데이터 미사용).

| 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) 필터 |

### 2단계 정합 분석

- `docs/03_analysis/comparison_report.html` — 기법별 recall·score
- `docs/03_analysis/signal_type_report.html` — B/B*/B^/Bd/S/Sd 유형별 recall

### 3단계 인과 시뮬

- `docs/02_ground_truth/futures/causal_chart_sim_v3.html` — 0단계와 동일 UI, 인과 신호 체결
- `docs/03_simulation/causal_futures_report.html` — 0단계 대비 수익률·정합 요약

---

## 디렉터리 구조

```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          # 1단계 GT
│   ├── 02_ground_truth_futures.py  # 1단계 선물 GT 차트
│   ├── 02_ground_truth_futures_sim.py  # 0단계 벤치마크 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/
│   ├── 02_ground_truth/
│   │   ├── spot/
│   │   │   ├── gt/         # 현물 GT 타점 차트 (sim 없음)
│   │   │   └── ground_truth_chart_sim_v*.html  # 현물 sim
│   │   └── futures/
│   │       ├── gt/         # 선물 GT 타점 차트 (sim 없음)
│   │       ├── ground_truth_chart_sim_v3.html   # 0단계 벤치마크
│   │       └── causal_chart_sim_v3.html         # 3단계 인과 sim
│   ├── 03_analysis/        # 2단계 정합 리포트
│   └── 03_simulation/      # 3단계 시뮬 비교 리포트
└── coins.db
```

## 변경 이력

- 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: 캔들 수집 모듈 초기 구현