Bithumb/README.md

Bithumb

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

• 기본 축: 3분봉 현물 BTC, 최근 10년 캔들 (DOWNLOAD_DAYS=3650)
• 데이터·문서 분류: common (공유) · spot (현물)
• 현재 운영 전략: 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

설치

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

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

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 운영	미사용	가능

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

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

---

폴더 구조

Bithumb/
├── src/bithumb/
│   ├── 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
│
└── docs/
    ├── live/                  # 운영 백테스트 매매 차트 (index.html)
    └── spot/
        ├── 0_ground_truth/    # GT 차트 HTML
        ├── 1_simulation/      # 1단계 sim 차트
        ├── 2_analysis/        # 2단계 리포트·설계 가이드
        └── 3_operations/      # 운영·백테스트 JSON 리포트

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

---

파이프라인 실행 순서

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]

순서	단계	스크립트	산출물
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/

권장 명령

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

# 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_final_summary.md

spot 3단계 — fractal_swing live 운영

설계 가이드: 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 주석 참고:

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

---

환경 변수

전체 목록: .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/bithumb/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·백테스트·텔레그램)	구현됨

---

변경 이력

• 2026-06-13: 프로젝트명 Bithumb으로 변경, 선물(futures) 파이프라인 제거
• 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 구조 재편
• 2026-06-12: 3단계 운영 파이프라인 초기 구현 (composite_v3 + MTF paper/live)
• 2026-06-12: 2단계 인과 기법 분석 파이프라인 완료
• 2026-06-08: Ground Truth v1/v2/v3
• 2026-06-07: 캔들 수집 모듈 초기 구현