Files
Bithumb/README.md
dsyoon 741c949470 refactor: Git에서 데이터 제거, 설정·코드만 유지
파이프라인 산출물(data/, docs/)을 Git 추적에서 제외하고
히스토리를 단일 커밋으로 재구성해 저장소 용량을 경량화한다.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-12 10:01:43 +09:00

315 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: 캔들 수집 모듈 초기 구현