Bithumb/README.md

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

설치

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단계 완료 후 구현 예정입니다.

# 사전: 전체 인터벌 증분 갱신 (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 추세 필터

---

디렉터리 구조

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