Bithumb/README.md

DeepCoin

빗썸 KRW 마켓 암호화폐 캔들 데이터 수집 프로젝트.

주요 기능

• 빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집
• SQLite(coins.db) 저장 — 테이블명 {SYMBOL}_{인터벌코드} (예: BTC_60, BTC_10080)
• 최대 2년(기본 730일) 역방향 페이지네이션 수집

요구사항

• 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	수집 일수 (최대 2년)	730
DOWNLOAD_INTERVALS	인터벌 코드 목록	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 키 없이도 동작합니다.

5단계 파이프라인

단계	목적	스크립트
0	데이터 수집	01_download.py
1	Ground Truth (사후 벤치마크 타점)	02_ground_truth.py
2	매매 기법 개발·GT 정합 비교	03_run_techniques.py
3	인과 신호 (과거 데이터만)	(예정)
4	시뮬레이션 백테스트	(예정)
5	실거래 운영	(예정)

# 0. 데이터 수집
python scripts/01_download.py

# 1. Ground Truth (매수·매도 벤치마크 타점)
python scripts/02_ground_truth.py

# 1-b. 선물 GT 차트 (현물 GT → 롱·숏 4색)
python scripts/02_ground_truth_futures.py

# 2. 매매 기법 실행 및 GT 정합 비교
python scripts/03_run_techniques.py

2단계 매매 기법 (8종)

Ground Truth 타점에 맞출 수 있는 후보 기법. 모두 인과 신호 (미래 데이터 미사용).

ID	기법	유형	설명
zigzag_causal	인과 ZigZag	swing	GT ZigZag 5%의 인과 버전
minor_swing	소형 스윙 하이브리드	hybrid	ZigZag 2.5% + 국소 극값
local_extrema	국소 극값	swing	눌림목·반등 고점 (9/27 유형)
bb_reversal	볼린저 역추세	indicator	BB 하단 매수·상단 매도
ma_cross	EMA 크로스	indicator	EMA(20/60) 골든·데드 크로스
rsi_swing	RSI 스윙	indicator	RSI 과매도·과매수 복귀
macd_cross	MACD 크로스	indicator	MACD 시그널선 크로스
donchian	돈치안 채널	swing	채널 하단·상단 반전

GT 정합 평가: 매수/매도 recall, 레그 recall, 수익 포착률, 종합 score.

실행 (데이터 수집)

# 전체 인터벌, 최대 2년
python scripts/download_candles.py

# 일·주·월봉만 빠르게
python scripts/download_candles.py --intervals 1440,10080,43200

# 최근 90일, 60분봉만
python scripts/download_candles.py --days 90 --intervals 60

디렉터리 구조

DeepCoin/
├── src/deepcoin/
│   ├── api/bithumb.py
│   ├── data/
│   ├── ground_truth/       # 1단계
│   ├── techniques/         # 2단계 매매 기법
│   └── evaluation/         # GT 정합 평가
├── scripts/
│   ├── 01_download.py
│   ├── 02_ground_truth.py
│   └── 03_run_techniques.py
├── data/
│   ├── ground_truth/
│   │   ├── spot/           # 현물 GT JSON
│   │   └── futures/        # 선물 GT JSON (예정)
│   └── techniques/
├── docs/
│   ├── 02_ground_truth/
│   │   ├── gt/             # 1단계 GT 타점 차트 (v1~v3)
│   │   ├── spot/           # 2단계 현물 sim 차트
│   │   └── futures/        # 선물 GT 차트 (롱·숏 4색, v1~v3)
│   └── 03_analysis/
└── coins.db

변경 이력

• 2026-06-09: 선물 GT 차트 v1~v3 추가 (현물 GT → 롱·숏 4색 마커)
• 2026-06-09: docs/02_ground_truth를 gt(타점)·spot(sim)·futures 3폴더로 분리
• 2026-06-09: Ground Truth 산출물 현물(spot)/선물(futures) 폴더 분리
• 2026-06-08: 2단계 매매 기법 8종 + GT 정합 비교 리포트 추가
• 2026-06-08: 1단계 Ground Truth (ZigZag 스윙 매수·매도 타점) 추가
• 2026-06-07: BTC 최대 2년 분·일·주·월봉 수집 지원
• 2026-06-07: 캔들 수집 모듈 초기 구현