# DeepCoin

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

- **기본 축:** 3분봉 현물 BTC, 최근 **10년** 캔들 (`DOWNLOAD_DAYS=3650`)
- **데이터·문서 분류:** `common` (공유) · `spot` (현물) · `futures` (선물)
- **현재 운영 전략:** `fractal_swing` + MTF off — paper/live tick 운영 구현 완료

## 주요 기능

- 빗썸 Public API(v1) 분·일·주·월봉 캔들 수집 (11개 TF, 1분봉 포함)
- SQLite 공유 DB (`data/common/coins.db`) — 현물·선물·MTF 공용
- Ground Truth(GT) 벤치마크 → 39종 인과 기법 분석 → **실거래 운영(paper/live)**
- 운영 tick: 캔들 증분 sync, 신호 tail 갱신, 슬리피지·일 체결 상한, 텔레그램 체결 알림

## 요구사항

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

## 설치

```bash
cd DeepCoin
conda activate ncue   # 또는 xavis
pip install -r requirements.txt
cp .env.example .env   # API 키·텔레그램 등 로컬 설정
```

`.env` 핵심값 (현물 3분봉·10년·fractal 운영):

```env
SYMBOL=BTC
DB_PATH=data/common/coins.db
DOWNLOAD_DAYS=3650
GT_INTERVAL_MIN=3
GT_LOOKBACK_DAYS=3650
GT_INITIAL_CASH_KRW=200000
GT_SIM_LOOKBACK_DAYS=1095
OPS_TECHNIQUE_ID=fractal_swing
OPS_MTF_ENABLED=false
OPS_SLIPPAGE_RATE=0.0005
OPS_DAILY_MAX_TRADES=100
```

---

## 설계 개요

### 파이프라인 단계

| 단계 | 목적 | 미래 데이터 | 실거래 |
|------|------|-------------|--------|
| **common** | 캔들 DB 구축 | — | — |
| **spot 0단계** | GT v3 사후 최적 타점 (정답지) | 사용 (연구용) | 불가 |
| **spot 1단계** | GT 타점 완벽 추종 sim 상한선 | GT 자체가 사후 | 불가 |
| **spot 2단계** | 39종 인과 기법 평가·MTF 규칙 | 미사용 | 불가 |
| **spot 3단계** | paper/live tick 운영 | 미사용 | **가능** |
| **futures 0단계** | 현물 GT → 선물 롱·숏 마커 | — | — |

### 현물 3단계 운영 아키텍처 (fractal_swing)

```mermaid
flowchart TD
    subgraph tick["3_run_operations.py tick (권장 180초)"]
        A[sync_ops_candles<br/>전 TF 증분 INSERT] --> B[generate_raw_signals<br/>캐시 + tail 800봉 갱신]
        B --> C[filter_signals_for_ops<br/>MTF·TrendGate 선택]
        C --> D[OperationsRunner<br/>bar 단위 클러스터 체결]
        D --> E{paper / live}
        E -->|paper| F[PaperExecutor<br/>모델 슬리피지 체결]
        E -->|live| G[LiveExecutor<br/>빗썸 시장가]
        F --> H[TelegramNotifier<br/>체결 알림]
        G --> H
        H --> I[state.json + ops_report.json]
    end
    J[3_run_filtered_backtest.py] --> K[simulate_gt_signals_pnl<br/>동일 체결 규칙 3년 sim]
```

**백테스트 vs live 정합:** 슬리피지·수수료·일 체결 상한·매수 상한(`max_buy_from_cash`)·클러스터 분할이 `pnl.py` ↔ `trade_engine` ↔ `executor`에서 동일 규칙을 사용합니다.

### 운영 전략 비교 (2단계 결론 반영)

| 전략 | 3년 sim (운영 조건) | 체결 빈도 | 현재 `.env` |
|------|---------------------|-----------|-------------|
| **fractal_swing** (MTF off) | **+1,873,140%** (슬리피지 0.05%, 일 100회) | 일 ~50회 매수 | **기본값** |
| fractal_swing ideal (2단계) | +7,560,826% (슬리피지 0, 상한 없음) | 일 ~52회 | 연구용 |
| composite_v3 + MTF on | +3.37% | 낮음 | `.env.example` 주석 참고 |

상세 해석: [`docs/spot/2_analysis/stage2_final_summary.md`](docs/spot/2_analysis/stage2_final_summary.md)

---

## 폴더 구조

```text
DeepCoin/
├── src/deepcoin/
│   ├── api/                   # 빗썸 Public·Private REST
│   ├── data/                  # 캔들 수집·DB·로더
│   ├── ground_truth/          # GT 타점·sim·차트
│   ├── techniques/            # 39종 인과 기법
│   ├── mtf/                   # MTF 피처·필터·규칙
│   ├── evaluation/            # 2단계 리포트·인과 sim
│   ├── operations/            # 3단계 운영 (runner·executor·sync·backtest)
│   └── notifications/         # 텔레그램 체결 알림
├── scripts/                   # 단계별 CLI
│
├── data/
│   ├── common/coins.db        # 공유 캔들 OHLCV
│   ├── spot/
│   │   ├── ground_truth/      # 0단계 GT JSON
│   │   ├── techniques/        # 2단계 기법 결과 (fractal_swing.json 등)
│   │   ├── mtf/               # mtf_rules_v3.json
│   │   └── operations/        # fractal_ops_state.json
│   └── futures/ground_truth/  # 선물 GT JSON
│
└── docs/
    ├── live/                  # 운영 백테스트 매매 차트 (index.html)
    ├── spot/
    │   ├── 0_ground_truth/    # GT 차트 HTML
    │   ├── 1_simulation/      # 1단계 sim 차트
    │   ├── 2_analysis/        # 2단계 리포트·설계 가이드
    │   └── 3_operations/      # 운영·백테스트 JSON 리포트
    └── futures/0_ground_truth/  # 선물 GT 차트
```

테이블명: `{SYMBOL}_{인터벌분}` (예: `BTC_3`, `BTC_1440`). 인터벌: 분봉=분 숫자, 일=`1440`, 주=`10080`, 월=`43200`.

---

## 파이프라인 실행 순서

```mermaid
flowchart LR
    A[00_download] --> B[0_ground_truth]
    B --> C[1_ground_truth_sim]
    C --> D[2_run_stage2_all]
    D --> E[3_run_operations]
    B --> F[0_ground_truth_futures]
```

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

### 권장 명령

```bash
conda activate ncue
export PYTHONPATH=src

# common
python scripts/00_download.py              # 증분 갱신
python scripts/00_download.py --full         # 최초·재구축

# spot 0~2단계 (분석·기법 캐시 생성)
python scripts/0_ground_truth.py --interval 3 --days 3650 --tier all
python scripts/1_ground_truth_sim.py --tier all
bash scripts/2_run_stage2_all.sh

# futures 0단계
python scripts/0_ground_truth_futures.py --tier all

# spot 3단계 — fractal_swing 운영
python scripts/3_run_filtered_backtest.py       # 운영 조건 3년 sim 검증
python scripts/3_render_live_chart.py           # docs/live 매매 차트
python scripts/3_run_fractal_realistic_backtest.py  # 슬리피지 시나리오
bash scripts/3_run_fractal_ops.sh                 # 백테스트 + paper 180초 loop
python scripts/3_run_operations.py --loop 180 --mode live  # live (API 키 필요)
```

---

## 단계별 상세

### common — 캔들 수집

| 항목 | 내용 |
|------|------|
| DB | `data/common/coins.db` (`DB_PATH`) |
| 증분 갱신 | DB 최신 시각 이후만 API 조회·INSERT |
| 전체 재수집 | `--full` |
| TF | `DOWNLOAD_INTERVALS` (기본 11개) |

운영 tick에서는 `sync_ops_candles()`가 subprocess 대신 **in-process** 증분 sync를 수행합니다 (`OPS_SYNC_CANDLES=true`).

### spot 0단계 — GT 타점

사후 최적 매매 타점. 실거래 불가, 이후 단계의 벤치마크.

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

산출: `data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json`, `docs/spot/0_ground_truth/ground_truth_chart_v*.html`

### spot 1단계 — GT sim

GT 타점 완벽 추종 시 3년 수익 상한선. 초기 20만 원, `GT_SIM_LOOKBACK_DAYS=1095`.

산출: `docs/spot/1_simulation/ground_truth_chart_sim_v*.html`

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

39종 기법의 GT 정합·3년 sim·신호 유형·MTF 상관 분석.

| 스크립트 | 산출물 |
|----------|--------|
| `2_run_techniques.py` | `data/spot/techniques/`, `comparison_report.html` |
| `2_run_causal_sim.py` | `causal_sim_report.html`, `technique_chart_sim_*.html` |
| `2_run_signal_type_align.py` | `signal_type_report.html` |
| `2_run_mtf_analysis.py` | `mtf_rules_v3.json`, `mtf_correlation_report.html` |

설계: [`docs/spot/2_analysis/stage2_design_guide.md`](docs/spot/2_analysis/stage2_design_guide.md)  
결과 정리: [`docs/spot/2_analysis/stage2_final_summary.md`](docs/spot/2_analysis/stage2_final_summary.md)

### spot 3단계 — fractal_swing live 운영

설계 가이드: [`docs/spot/3_operations/stage3_design_guide.md`](docs/spot/3_operations/stage3_design_guide.md)  
(가이드 초版은 composite_v3 중심 — **현재 운영 기본값은 fractal_swing**)

#### 백테스트 실적 (BTC, 3년, 초기 20만원)

| 조건 | 수익률 | 매수 체결 | 비고 |
|------|--------|-----------|------|
| 운영 백테스트 | **+1,873,140%** | ~53,500 | 슬리피지 0.05%, 일 100회, MTF off |
| 2단계 ideal | +7,560,826% | ~56,893 | 슬리피지 0, 상한 없음 |

#### 스크립트·산출물

| 스크립트 | 산출물 |
|----------|--------|
| `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` | `fractal_ops_report.json`, `fractal_ops_state.json` |
| `3_run_fractal_ops.sh` | 백테스트 + paper 180초 loop |

#### 운영 tick 동작

1. **캔들 sync** — `OPS_SYNC_INTERVALS` 비우면 `DOWNLOAD_INTERVALS` 전체 TF, `db_max` 이후만 INSERT
2. **신호** — 2단계 캐시 JSON 로드; DB 최신 봉 > 캐시 max bar 시 **tail 800봉** fractal 재계산·병합 (`OPS_SIGNAL_TAIL_BARS`)
3. **필터** — tick당 **최신 봉** 신호만 MTF 평가 (`OPS_MTF_ENABLED=false` 시 스킵)
4. **체결** — bar 단위 클러스터 분할, 일 `OPS_DAILY_MAX_TRADES` 상한
5. **알림** — 체결 성공 시 텔레그램; live 실패 시 사유 포함 알림
6. **저장** — `OPS_STATE_JSON`, `OPS_REPORT_JSON`

#### live 전환 체크리스트

1. `python scripts/3_run_filtered_backtest.py` → **약 +1,873,140%** 확인
2. `.env`: `OPS_MODE=live`, `BITHUMB_ACCESS_KEY` / `BITHUMB_SECRET_KEY`
3. `python scripts/3_run_operations.py --loop 180` (paper 1~2일 모니터링 권장)
4. `fractal_ops_report.json` — `candle_sync`, `signal_refresh`, 체결 건수 확인
5. 텔레그램 체결 알림 동작 확인 (`COIN_TELEGRAM_*`)

**주의:** 백테스트는 3년 **일괄 재생** sim, live는 **tick 누적**. 실거래 체결가는 모델 슬리피지보다 불리할 수 있습니다.

#### composite_v3 + MTF (대안 운영 프로필)

`.env.example` 주석 참고:

```env
OPS_TECHNIQUE_ID=composite_v3
OPS_MIN_SCORE=2.5
OPS_MTF_ENABLED=true
OPS_TREND_GATE_ENABLED=true
OPS_DAILY_MAX_TRADES=20
```

### futures 0단계 — 선물 GT

현물 GT buy/sell → 롱·숏 4색 마커 (L↑/L↓/S↑/S↓).  
산출: `data/futures/ground_truth/`, `docs/futures/0_ground_truth/`  
선물 1~3단계는 예정.

---

## 환경 변수

전체 목록: `.env.example`. 주요 항목만 정리합니다.

### 공통·GT

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `SYMBOL` | 코인 심볼 | `BTC` |
| `DB_PATH` | 캔들 DB | `data/common/coins.db` |
| `DOWNLOAD_DAYS` | 수집·GT 기간(일) | `3650` |
| `DOWNLOAD_INTERVALS` | 수집 TF 목록 | 11개 TF |
| `GT_INTERVAL_MIN` | GT·기법·운영 기준 봉(분) | `3` |
| `GT_LOOKBACK_DAYS` | GT·기법 lookback | `3650` |
| `GT_SIM_LOOKBACK_DAYS` | sim·백테스트 기간 | `1095` (3년) |
| `GT_INITIAL_CASH_KRW` | sim·paper 초기 자본 | `200000` |
| `GT_TRADING_FEE_RATE` | 편도 수수료 | `0.0005` |

### spot 3단계 운영 (fractal 기본)

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `OPS_MODE` | `paper` / `live` | `paper` |
| `OPS_TECHNIQUE_ID` | 운영 기법 | `fractal_swing` |
| `OPS_MTF_ENABLED` | MTF 필터 | `false` |
| `OPS_TREND_GATE_ENABLED` | 고TF trend gate | `false` |
| `OPS_DAILY_MAX_TRADES` | 일일 체결 상한 | `100` |
| `OPS_MIN_ORDER_KRW` | 최소 주문(원) | `5000` |
| `OPS_SLIPPAGE_RATE` | 편도 슬리피지 | `0.0005` (0.05%) |
| `OPS_ORDER_INTERVAL_SEC` | live 주문 간격(초) | `0.35` |
| `OPS_SYNC_CANDLES` | tick 캔들 증분 sync | `true` |
| `OPS_SYNC_INTERVALS` | sync TF (비우면 전체) | 전체 |
| `OPS_SIGNAL_TAIL_BARS` | 신호 tail 재계산 봉 | `800` |
| `OPS_PERSIST_SIGNAL_CACHE` | tail 후 JSON 저장 | `false` |
| `OPS_STATE_JSON` | 운영 상태 | `fractal_ops_state.json` |
| `OPS_REPORT_JSON` | tick 리포트 | `fractal_ops_report.json` |
| `OPS_FILTERED_BACKTEST_JSON` | 백테스트 리포트 | `fractal_filtered_backtest_report.json` |
| `COIN_TELEGRAM_BOT_TOKEN` | 텔레그램 Bot | (비우면 알림 off) |
| `COIN_TELEGRAM_CHAT_ID` | 텔레그램 chat ID | |
| `OPS_TELEGRAM_ENABLED` | 체결 알림 | 토큰·chat_id 있으면 자동 on |
| `BITHUMB_ACCESS_KEY` | live API | — |
| `BITHUMB_SECRET_KEY` | live API | — |

### 경로 변수 요약

| 용도 | 변수 | 기본 경로 |
|------|------|-----------|
| spot GT | `GROUND_TRUTH_FILE` | `data/spot/ground_truth/...` |
| spot 기법 | `TECHNIQUES_DIR` | `data/spot/techniques/` |
| spot MTF | `MTF_RULES_JSON` | `data/spot/mtf/mtf_rules_v3.json` |
| spot 운영 상태 | `OPS_STATE_JSON` | `data/spot/operations/fractal_ops_state.json` |
| spot 운영 리포트 | `OPS_REPORT_JSON` | `docs/spot/3_operations/fractal_ops_report.json` |
| live 차트 | `3_render_live_chart.py` | `docs/live/` |

---

## 소스 모듈 (spot 3단계)

| 모듈 | 역할 |
|------|------|
| `operations/runner.py` | tick 오케스트레이션 |
| `operations/candle_sync.py` | 전 TF 증분 캔들 sync |
| `operations/signal_pipeline.py` | 신호 생성·캐시·tail 갱신·MTF 필터 |
| `operations/executor.py` | paper/live 체결 |
| `operations/execution.py` | 슬리피지 `fill_price` |
| `operations/trade_engine.py` | 매수·매도 사이징·포트폴리오 |
| `operations/backtest.py` | 운영 조건 3년 sim |
| `operations/chart.py` | `docs/live` 백테스트 차트 |
| `operations/state_store.py` | 운영 상태 JSON |
| `ground_truth/pnl.py` | sim 엔진 (백테스트·2단계 공용) |
| `api/bithumb_private.py` | live 잔고·시장가 주문 |
| `notifications/telegram.py` | 체결 텔레그램 알림 |

---

## 현물 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 | 캔들 수집·증분 sync | 구현됨 |
| spot | 0~2단계 (GT·기법·MTF) | 구현됨 |
| spot | 3단계 (fractal paper/live·백테스트·텔레그램) | **구현됨** |
| futures | 0단계 GT | 구현됨 |
| futures | 1~3단계 | 예정 |

---

## 변경 이력

- 2026-06-13: 텔레그램 매수·매도 체결 알림 (`notifications/telegram.py`)
- 2026-06-13: `docs/live/` 운영 백테스트 매매 차트 (`3_render_live_chart.py`)
- 2026-06-13: fractal_swing live 운영 — 슬리피지·일 체결 상한·전 TF 증분 sync·신호 tail 갱신
- 2026-06-13: 운영 백테스트 **+1,873,140%** (3년, 슬리피지 0.05%, 일 100회) 검증
- 2026-06-12: `data/`·`docs/` common/spot/futures 3유형 구조 재편
- 2026-06-12: 3단계 운영 파이프라인 초기 구현 (composite_v3 + MTF paper/live)
- 2026-06-12: 2단계 인과 기법 분석 파이프라인 완료
- 2026-06-08: Ground Truth v1/v2/v3
- 2026-06-07: 캔들 수집 모듈 초기 구현