Bithumb/README.md

# 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 규칙
│   │   └── operations/        # 3단계 운영 상태
│   └── futures/               # 선물 전용 데이터
│       ├── ground_truth/      # 0단계 선물 GT JSON
│       ├── techniques/        # (예정) 2단계
│       └── mtf/               # (예정) 2단계
│
└── docs/
    ├── live/                  # live 운영 백테스트 매매 차트
    ├── 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단계: fractal_swing 운영 ───────────────────────────
bash scripts/3_run_fractal_ops.sh          # 백테스트 + paper loop
python scripts/3_run_fractal_realistic_backtest.py
python scripts/3_run_filtered_backtest.py  # 운영 조건 3년 sim
python scripts/3_run_operations.py --loop 180 --mode live  # 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단계 — fractal_swing live 운영

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

**운영 전략:** `fractal_swing` + MTF off. 백테스트(운영 조건) **3년 +1,873,140%** (초기 20만원 → 약 37.5억, 슬리피지 0.05%·일 100회 상한 반영).

| 순서 | 스크립트 | 산출물 |
|------|----------|--------|
| 백테스트 | `3_run_filtered_backtest.py` | `fractal_filtered_backtest_report.json` |
| **매매 차트** | `3_render_live_chart.py` | `docs/live/index.html`, `fractal_swing_ops_chart.html` |
| 시나리오 | `3_run_fractal_realistic_backtest.py` | `fractal_realistic_backtest.json` |
| 운영 | `3_run_operations.py --loop 180` | `fractal_ops_report.json`, `fractal_ops_state.json` |
| 일괄 | `3_run_fractal_ops.sh` | 백테스트 + paper loop |

#### 백테스트 vs live 코드 정합 (라이브 직전 확인)

| 항목 | 백테스트 | live/paper 코드 | 상태 |
|------|----------|-----------------|------|
| 기법 | `fractal_swing` | `OPS_TECHNIQUE_ID` | 일치 |
| MTF | off | `OPS_MTF_ENABLED=false` | 일치 |
| 슬리피지 0.05% | `simulate_gt_signals_pnl` | `fill_price` → `executor` | 일치 |
| 수수료 0.05% | `GT_TRADING_FEE_RATE` | 동일 | 일치 |
| 최소 주문 5,000원 | `OPS_MIN_ORDER_KRW` | `trade_engine` | 일치 |
| 일 체결 100회 | `daily_max_trades` in sim | `runner` `trades_today_count` | 일치 |
| 매수 상한 | `max_buy_from_cash` | `compute_buy_order` | 일치 |
| 신호 | 캐시 JSON 전기간 | tail 800봉 갱신 + tick 체결 | 일치 (갱신 로직 추가) |
| 캔들 DB | 로컬 DB | `sync_ops_candles` 전 TF 증분 INSERT | 일치 |

**live 전환 전 체크**

1. `.env`: `OPS_MODE=live`, API 키 설정
2. `python scripts/3_run_filtered_backtest.py` → 필터 sim **약 +1,873,140%** 확인
3. `python scripts/3_run_operations.py --loop 180` (paper로 1~2일 모니터링 권장)
4. `fractal_ops_report.json`에서 `candle_sync`, `signal_refresh`, 체결 건수 확인

**주의:** 백테스트는 **3년 전기간 재생** sim이고, live는 **시간에 따라 누적**합니다. 2단계 ideal **+7,560,826%**(슬리피지 0)와는 다릅니다. 실거래 체결가는 모델 슬리피지보다 불리할 수 있습니다.

#### 운영 환경 변수 (fractal 기본)

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `OPS_MODE` | `paper` / `live` | `paper` |
| `OPS_TECHNIQUE_ID` | 운영 기법 | `fractal_swing` |
| `OPS_MTF_ENABLED` | MTF 필터 | `false` |
| `OPS_DAILY_MAX_TRADES` | 일일 체결 상한 | `100` |
| `OPS_SLIPPAGE_RATE` | 편도 슬리피지 | `0.0005` (0.05%) |
| `OPS_MIN_ORDER_KRW` | 최소 주문 | `5000` |
| `OPS_ORDER_INTERVAL_SEC` | live 주문 간격(초) | `0.35` |
| `OPS_SYNC_CANDLES` | tick마다 캔들 증분 sync | `true` |
| `OPS_SYNC_INTERVALS` | sync TF (비우면 `DOWNLOAD_INTERVALS` 전체) | 전체 |
| `OPS_SIGNAL_TAIL_BARS` | 신호 tail 재계산 봉 수 | `800` |
| `OPS_PERSIST_SIGNAL_CACHE` | tail 갱신 후 JSON 저장 | `false` |
| `OPS_STATE_JSON` | 운영 상태 | `fractal_ops_state.json` |
| `OPS_REPORT_JSON` | 운영 리포트 | `fractal_ops_report.json` |

`composite_v3` + MTF 운영은 `.env.example` 주석 참고.

### 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` |
| `OPS_MODE` | 운영 모드 | `paper` |
| `OPS_TECHNIQUE_ID` | 운영 기법 | `fractal_swing` |
| `OPS_SLIPPAGE_RATE` | 편도 슬리피지 | `0.0005` |
| `OPS_DAILY_MAX_TRADES` | 일일 체결 상한 | `100` |
| `OPS_SYNC_CANDLES` | tick 캔들 sync | `true` |

### 경로 변수 요약

| 용도 | 변수 예시 | 기본 경로 |
|------|-----------|-----------|
| 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/` |
| spot 3단계 운영 | `OPS_STATE_JSON` | `data/spot/operations/fractal_ops_state.json` |
| spot 3단계 리포트 | `OPS_REPORT_JSON` | `docs/spot/3_operations/fractal_ops_report.json` |
| 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단계 fractal_swing live 준비) |
| futures | 0단계 | 구현됨 |
| futures | 1~3단계 | 예정 |

---

## 변경 이력

- 2026-06-13: `docs/live/` — 운영 백테스트 매수·매도 타점 HTML 차트 (`3_render_live_chart.py`)
- 2026-06-13: 운영 백테스트 **+1,873,140%** (3년, 슬리피지 0.05%, 일 100회) 검증
- 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: 캔들 수집 모듈 초기 구현