# DeepCoin

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

기본 전략 축: **3분봉 현물**, 최근 **10년** 데이터. `data/`·`docs/`는 **공통(common)** · **현물(spot)** · **선물(futures)** 세 유형으로 구분합니다.

## 주요 기능

- 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집 (1분봉 포함)
- SQLite 캔들 DB — 현물·선물 **공통** (`data/common/coins.db`)
- Ground Truth(GT) 기반 현물·선물 벤치마크·인과 기법 분석·(예정) 실거래 운영

## 요구사항

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

## 설치

```bash
cd DeepCoin
conda activate ncue   # 또는 xavis
pip install -r requirements.txt
cp .env.example .env
```

`.env` 권장값 (현물 3분봉·10년):

```env
SYMBOL=BTC
DB_PATH=data/common/coins.db
DOWNLOAD_DAYS=3650
GT_INTERVAL_MIN=3
GT_LOOKBACK_DAYS=3650
```

---

## 폴더 구조 (공통 · 현물 · 선물)

`data/`와 `docs/` 최상위는 동일하게 **common / spot / futures** 세 갈래입니다.

```text
DeepCoin/
├── src/deepcoin/              # 소스 코드
├── scripts/                   # 파이프라인 스크립트
│
├── data/
│   ├── common/                # 공통 — 현물·선물 공유 리소스
│   │   └── coins.db           # 캔들 OHLCV (유일한 공유 DB)
│   ├── spot/                  # 현물 전용 데이터
│   │   ├── ground_truth/      # 0단계 GT JSON
│   │   ├── techniques/        # 2단계 기법 결과
│   │   └── mtf/               # 2단계 MTF 규칙
│   └── futures/               # 선물 전용 데이터
│       ├── ground_truth/      # 0단계 선물 GT JSON
│       ├── techniques/        # (예정) 2단계
│       └── mtf/               # (예정) 2단계
│
└── docs/
    ├── common/                # 공통 문서 (예정)
    ├── spot/                  # 현물 리포트·차트
    │   ├── 0_ground_truth/    # 0단계 GT 차트
    │   ├── 1_simulation/      # 1단계 sim 차트
    │   ├── 2_analysis/        # 2단계 분석 리포트
    │   └── 3_operations/      # 3단계 운영 (예정)
    └── futures/               # 선물 리포트·차트
        ├── 0_ground_truth/    # 0단계 선물 GT 차트
        ├── 1_simulation/      # (예정) 1단계
        ├── 2_analysis/        # (예정) 2단계
        └── 3_operations/      # (예정) 3단계
```

### 유형별 역할

| 유형 | `data/` | `docs/` | 설명 |
|------|---------|---------|------|
| **common** | `coins.db` | (예정) | 현물·선물이 공유하는 캔들 DB |
| **spot** | GT·기법·MTF JSON | 단계별 HTML·리포트 | 현물 파이프라인 산출물 |
| **futures** | 선물 GT JSON | 단계별 HTML·리포트 | 선물 파이프라인 산출물 |

테이블명: `{SYMBOL}_{인터벌}` (예: `BTC_3`, `BTC_1440`)

---

## 현물 파이프라인 전체 순서

```mermaid
flowchart TD
    A[common: 캔들 수집] --> B[spot 0단계: GT 타점]
    B --> C[spot 1단계: GT sim]
    C --> D[spot 2단계: 인과 기법]
    D --> E[spot 3단계: 실거래 운영]
    B --> F[futures 0단계: 선물 GT]
```

| 순서 | 단계 | 유형 | 스크립트 | 산출물 |
|------|------|------|----------|--------|
| 0 | **사전** | common | `00_download.py` | `data/common/coins.db` |
| 1 | **0단계** | spot | `0_ground_truth.py` | `data/spot/ground_truth/`, `docs/spot/0_ground_truth/` |
| 2 | **1단계** | spot | `1_ground_truth_sim.py` | `docs/spot/1_simulation/` |
| 3 | **2단계** | spot | `2_run_*.py`, `2_run_stage2_all.sh` | `data/spot/techniques/`, `docs/spot/2_analysis/` |
| 4 | **3단계** | spot | `3_run_*.py`, `3_run_stage3_all.sh` | `data/spot/operations/`, `docs/spot/3_operations/` |
| — | **0단계** | futures | `0_ground_truth_futures.py` | `data/futures/ground_truth/`, `docs/futures/0_ground_truth/` |

### 권장 실행 명령 (현물 + 선물 0단계)

```bash
conda activate ncue
export PYTHONPATH=src

# ── common: 캔들 수집 ─────────────────────────────────────────
python scripts/00_download.py              # 증분 갱신
python scripts/00_download.py --full       # 최초 1회·재구축

# ── spot 0단계: GT 타점 (3분봉·10년) ──────────────────────────
python scripts/0_ground_truth.py --interval 3 --days 3650 --tier all

# ── spot 1단계: GT sim (최근 3년) ───────────────────────────
python scripts/1_ground_truth_sim.py --tier all

# ── spot 2단계: 인과 기법 (일괄) ──────────────────────────────
bash scripts/2_run_stage2_all.sh

# ── futures 0단계: 선물 GT (현물 GT 기반) ───────────────────
python scripts/0_ground_truth_futures.py --tier all

# ── spot 3단계: 운영 (기본 paper) ─────────────────────────────
bash scripts/3_run_stage3_all.sh
# python scripts/3_run_operations.py --mode paper
# python scripts/3_run_operations.py --mode live   # API 키 필요
```

---

## 단계별 상세

### common — 캔들 수집 (사전)

| 항목 | 내용 |
|------|------|
| DB 경로 | `data/common/coins.db` (`DB_PATH`) |
| 기본 동작 | DB 최신 시각 이후 증분 갱신 |
| 전체 재수집 | `--full` |
| 1분봉만 풀 다운 | `00_download_candles.py --full --days 3650 --intervals 1` |

### spot 0단계 — GT 타점

사후 최적 매매 타점. **실거래 불가**, 이후 단계의 정답지(기준선).

| 티어 | 포함 신호 |
|------|-----------|
| v1 | 스윙 B/S |
| v2 | + 눌림목 B* |
| v3 | + 돌파 B^ + 다이버전스 Bd/Sd |

| 산출물 | 경로 |
|--------|------|
| JSON | `data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json` |
| 차트 | `docs/spot/0_ground_truth/ground_truth_chart_v{1,2,3}.html` |

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

GT 타점 완벽 추종 시 수익 상한선. 최근 3년·초기 20만 원.

| 산출물 | 경로 |
|--------|------|
| sim 차트 | `docs/spot/1_simulation/ground_truth_chart_sim_v{1,2,3}.html` |

### spot 2단계 — 인과 기법 분석

설계·목적·MTF 역할 등 상세: [`docs/spot/2_analysis/stage2_design_guide.md`](docs/spot/2_analysis/stage2_design_guide.md)

| 순서 | 스크립트 | 산출물 |
|------|----------|--------|
| 2-1 | `2_run_techniques.py` | `data/spot/techniques/`, `docs/spot/2_analysis/comparison_report.html` |
| 2-2 | `2_run_causal_sim.py` | `docs/spot/2_analysis/causal_sim_report.html` |
| 2-3 | `2_run_signal_type_align.py` | `docs/spot/2_analysis/signal_type_report.html` |
| 2-4 | `2_run_mtf_analysis.py` | `data/spot/mtf/mtf_rules_v3.json`, `docs/spot/2_analysis/mtf_correlation_report.html` |

### spot 3단계 — 실거래 운영

설계·운영 가이드: [`docs/spot/3_operations/stage3_design_guide.md`](docs/spot/3_operations/stage3_design_guide.md)

`composite_v3` + MTF 필터 + 고TF 게이트. **기본 `OPS_MODE=paper`**.

| 순서 | 스크립트 | 산출물 |
|------|----------|--------|
| 3-1 | `3_run_filtered_backtest.py` | `filtered_backtest_report.json` |
| 3-2 | `3_run_operations.py` | `ops_report.json`, `ops_state.json` |
| 일괄 | `3_run_stage3_all.sh` | 위 전체 |

| 모드 | 설명 |
|------|------|
| `paper` | 모의 체결 (권장) |
| `live` | 빗썸 시장가 주문 (`BITHUMB_ACCESS_KEY` 필요) |

### futures 0단계 — 선물 GT

현물 GT를 롱·숏 4색 마커로 변환.

| 현물 GT | 선물 마커 | 의미 |
|---------|-----------|------|
| buy | L↑ / S↑ | 롱 진입 / 숏 청산 |
| sell | L↓ / S↓ | 롱 청산 / 숏 진입 |

| 산출물 | 경로 |
|--------|------|
| JSON | `data/futures/ground_truth/ground_truth_trades_v{1,2,3}.json` |
| 차트 | `docs/futures/0_ground_truth/ground_truth_chart_v{1,2,3}.html` |

선물 1~3단계는 `docs/futures/{1_simulation,2_analysis,3_operations}/` (예정).

---

## 환경 변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `DB_PATH` | 공통 캔들 DB | `data/common/coins.db` |
| `SYMBOL` | 코인 심볼 | `BTC` |
| `DOWNLOAD_DAYS` | 수집·차트 일수 | `3650` |
| `GT_INTERVAL_MIN` | GT·기법 기준 인터벌(분) | `3` |
| `GT_LOOKBACK_DAYS` | GT 타점 기간(일) | `3650` |
| `GT_SIM_LOOKBACK_DAYS` | sim 거래 기간(일) | `1095` |
| `GT_INITIAL_CASH_KRW` | sim 초기 자본(원) | `200000` |

### 경로 변수 요약

| 용도 | 변수 예시 | 기본 경로 |
|------|-----------|-----------|
| spot GT JSON | `GROUND_TRUTH_FILE` | `data/spot/ground_truth/...` |
| spot GT 차트 | `GROUND_TRUTH_CHART_V3_FILE` | `docs/spot/0_ground_truth/...` |
| spot sim 차트 | `GROUND_TRUTH_CHART_SIM_V3_FILE` | `docs/spot/1_simulation/...` |
| spot 2단계 | `TECHNIQUES_DIR` | `data/spot/techniques/` |
| futures GT JSON | `GROUND_TRUTH_FUTURES_FILE` | `data/futures/ground_truth/...` |
| futures GT 차트 | `GROUND_TRUTH_FUTURES_CHART_V3_FILE` | `docs/futures/0_ground_truth/...` |

전체 목록: `.env.example`

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

---

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

`src/deepcoin/techniques/` — 단일 33 + 복합 6, 미래 데이터 미사용.

| ID | 기법 | 유형 |
|----|------|------|
| `zigzag_causal` | 인과 ZigZag | 스윙 B/S |
| `minor_swing` | 소형 스윙 하이브리드 | 하이브리드 |
| `local_extrema` | 국소 극값 | 스윙 B/S |
| `pivot_swing` | 피벗 스윙 | 스윙 B/S |
| `fractal_swing` | 프랙탈 스윙 | 스윙 B/S |
| `swing_failure` | 스윙 실패 | 스윙 B/S |
| `donchian` | 돈치안 채널 | 스윙 B/S |
| `ema_pullback` | EMA 눌림목 | 눌림목 B* |
| `fib_pullback` | 피보나치 눌림목 | 눌림목 B* |
| `support_bounce` | 지지·저항 반등 | 눌림목 B* |
| `keltner_breakout` | Keltner 돌파 | 돌파 B^ |
| `range_breakout` | 레인지 돌파 | 돌파 B^ |
| `volume_breakout` | 거래량 돌파 | 돌파 B^ |
| `bb_squeeze_breakout` | BB 스퀴즈 돌파 | 돌파 B^ |
| `rsi_divergence` | RSI 다이버전스 | Bd/Sd |
| `macd_divergence` | MACD 다이버전스 | Bd/Sd |
| `obv_divergence` | OBV 다이버전스 | Bd/Sd |
| `bb_reversal` | 볼린저 역추세 | 지표 |
| `ma_cross` | EMA 크로스 | 지표 |
| `rsi_swing` | RSI 스윙 | 지표 |
| `macd_cross` | MACD 크로스 | 지표 |
| `supertrend` | Supertrend | 추세 |
| `adx_trend` | ADX 추세 | 추세 |
| `ichimoku_trend` | 일목 추세 | 추세 |
| `parabolic_sar` | Parabolic SAR | 추세 |
| `stochastic_cross` | Stochastic 크로스 | 모멘텀 |
| `cci_extreme` | CCI 극값 | 모멘텀 |
| `roc_reversal` | ROC 반전 | 모멘텀 |
| `keltner_reversal` | Keltner 역추세 | 변동성 |
| `atr_channel` | ATR 채널 | 변동성 |
| `pivot_points` | 피벗 포인트 | 구조 |
| `support_resistance` | 구조적 지지·저항 | 구조 |
| `volume_spike` | 거래량 스파이크 | 거래량 |
| `composite_swing` | 스윙 복합 | 복합 |
| `composite_pullback` | 눌림목 복합 | 복합 |
| `composite_breakout` | 돌파 복합 | 복합 |
| `composite_divergence` | 다이버전스 복합 | 복합 |
| `composite_v3` | v3 통합 스코어링 | 복합 |
| `composite_full` | 전체 통합 복합 | 복합 |

---

## 구현 현황

| 유형 | 단계 | 상태 |
|------|------|------|
| common | 사전 (캔들) | 구현됨 |
| spot | 0~3단계 | 구현됨 (3단계 기본 paper) |
| futures | 0단계 | 구현됨 |
| futures | 1~3단계 | 예정 |

---

## 변경 이력

- 2026-06-12: `data/`·`docs/`를 **common / spot / futures** 3유형 구조로 재편, `coins.db` → `data/common/`, 0단계 차트 → `docs/{spot,futures}/0_ground_truth/`
- 2026-06-12: `0_ground_truth_futures.py` — 현물 GT → 선물 JSON·차트 변환 로직 보완
- 2026-06-12: README 현물 파이프라인 전체 순서 갱신
- 2026-06-12: `src/deepcoin/data/` 모듈 복원
- 2026-06-11: 파이프라인 단계별 상세 설명 추가
- 2026-06-08: Ground Truth v1/v2/v3
- 2026-06-07: 캔들 수집 모듈 초기 구현