Files

xavis 58802bdc5f feat(spot): 3단계 운영 파이프라인 — composite_v3 + MTF paper/live

MTF 필터 백테스트, paper/live 체결, 빗썸 Private API 연동 및 운영 스크립트·설계 문서를 추가해 2단계 전략을 실거래 단계에 연결한다.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-12 18:27:34 +09:00

12 KiB

Raw Blame History

DeepCoin

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

기본 전략 축: 3분봉 현물, 최근 10년 데이터. data/·docs/는 공통(common) · 현물(spot) · 선물(futures) 세 유형으로 구분합니다.

주요 기능

빗썸 Public API(v1) 기반 분·일·주·월봉 캔들 수집 (1분봉 포함)
SQLite 캔들 DB — 현물·선물 공통 (data/common/coins.db)
Ground Truth(GT) 기반 현물·선물 벤치마크·인과 기법 분석·(예정) 실거래 운영

요구사항

Python 3.10+
Conda 환경 ncue 또는 xavis

설치

cd DeepCoin
conda activate ncue   # 또는 xavis
pip install -r requirements.txt
cp .env.example .env

.env 권장값 (현물 3분봉·10년):

SYMBOL=BTC
DB_PATH=data/common/coins.db
DOWNLOAD_DAYS=3650
GT_INTERVAL_MIN=3
GT_LOOKBACK_DAYS=3650

폴더 구조 (공통 · 현물 · 선물)

data/와 docs/ 최상위는 동일하게 common / spot / futures 세 갈래입니다.

DeepCoin/
├── src/deepcoin/              # 소스 코드
├── scripts/                   # 파이프라인 스크립트
│
├── data/
│   ├── common/                # 공통 — 현물·선물 공유 리소스
│   │   └── coins.db           # 캔들 OHLCV (유일한 공유 DB)
│   ├── spot/                  # 현물 전용 데이터
│   │   ├── ground_truth/      # 0단계 GT JSON
│   │   ├── techniques/        # 2단계 기법 결과
│   │   └── mtf/               # 2단계 MTF 규칙
│   └── futures/               # 선물 전용 데이터
│       ├── ground_truth/      # 0단계 선물 GT JSON
│       ├── techniques/        # (예정) 2단계
│       └── mtf/               # (예정) 2단계
│
└── docs/
    ├── common/                # 공통 문서 (예정)
    ├── spot/                  # 현물 리포트·차트
    │   ├── 0_ground_truth/    # 0단계 GT 차트
    │   ├── 1_simulation/      # 1단계 sim 차트
    │   ├── 2_analysis/        # 2단계 분석 리포트
    │   └── 3_operations/      # 3단계 운영 (예정)
    └── futures/               # 선물 리포트·차트
        ├── 0_ground_truth/    # 0단계 선물 GT 차트
        ├── 1_simulation/      # (예정) 1단계
        ├── 2_analysis/        # (예정) 2단계
        └── 3_operations/      # (예정) 3단계

유형별 역할

유형	`data/`	`docs/`	설명
common	`coins.db`	(예정)	현물·선물이 공유하는 캔들 DB
spot	GT·기법·MTF JSON	단계별 HTML·리포트	현물 파이프라인 산출물
futures	선물 GT JSON	단계별 HTML·리포트	선물 파이프라인 산출물

테이블명: {SYMBOL}_{인터벌} (예: BTC_3, BTC_1440)

현물 파이프라인 전체 순서

flowchart TD
    A[common: 캔들 수집] --> B[spot 0단계: GT 타점]
    B --> C[spot 1단계: GT sim]
    C --> D[spot 2단계: 인과 기법]
    D --> E[spot 3단계: 실거래 운영]
    B --> F[futures 0단계: 선물 GT]

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

권장 실행 명령 (현물 + 선물 0단계)

conda activate ncue
export PYTHONPATH=src

# ── common: 캔들 수집 ─────────────────────────────────────────
python scripts/00_download.py              # 증분 갱신
python scripts/00_download.py --full       # 최초 1회·재구축

# ── spot 0단계: GT 타점 (3분봉·10년) ──────────────────────────
python scripts/0_ground_truth.py --interval 3 --days 3650 --tier all

# ── spot 1단계: GT sim (최근 3년) ───────────────────────────
python scripts/1_ground_truth_sim.py --tier all

# ── spot 2단계: 인과 기법 (일괄) ──────────────────────────────
bash scripts/2_run_stage2_all.sh

# ── futures 0단계: 선물 GT (현물 GT 기반) ───────────────────
python scripts/0_ground_truth_futures.py --tier all

# ── spot 3단계: 운영 (기본 paper) ─────────────────────────────
bash scripts/3_run_stage3_all.sh
# python scripts/3_run_operations.py --mode paper
# python scripts/3_run_operations.py --mode live   # API 키 필요

단계별 상세

common — 캔들 수집 (사전)

항목	내용
DB 경로	`data/common/coins.db` (`DB_PATH`)
기본 동작	DB 최신 시각 이후 증분 갱신
전체 재수집	`--full`
1분봉만 풀 다운	`00_download_candles.py --full --days 3650 --intervals 1`

spot 0단계 — GT 타점

사후 최적 매매 타점. 실거래 불가, 이후 단계의 정답지(기준선).

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

산출물	경로
JSON	`data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json`
차트	`docs/spot/0_ground_truth/ground_truth_chart_v{1,2,3}.html`

spot 1단계 — GT sim (벤치마크)

GT 타점 완벽 추종 시 수익 상한선. 최근 3년·초기 20만 원.

산출물	경로
sim 차트	`docs/spot/1_simulation/ground_truth_chart_sim_v{1,2,3}.html`

spot 2단계 — 인과 기법 분석

설계·목적·MTF 역할 등 상세: docs/spot/2_analysis/stage2_design_guide.md

순서	스크립트	산출물
2-1	`2_run_techniques.py`	`data/spot/techniques/`, `docs/spot/2_analysis/comparison_report.html`
2-2	`2_run_causal_sim.py`	`docs/spot/2_analysis/causal_sim_report.html`
2-3	`2_run_signal_type_align.py`	`docs/spot/2_analysis/signal_type_report.html`
2-4	`2_run_mtf_analysis.py`	`data/spot/mtf/mtf_rules_v3.json`, `docs/spot/2_analysis/mtf_correlation_report.html`

spot 3단계 — 실거래 운영

설계·운영 가이드: docs/spot/3_operations/stage3_design_guide.md

composite_v3 + MTF 필터 + 고TF 게이트. 기본 OPS_MODE=paper.

순서	스크립트	산출물
3-1	`3_run_filtered_backtest.py`	`filtered_backtest_report.json`
3-2	`3_run_operations.py`	`ops_report.json`, `ops_state.json`
일괄	`3_run_stage3_all.sh`	위 전체

모드	설명
`paper`	모의 체결 (권장)
`live`	빗썸 시장가 주문 (`BITHUMB_ACCESS_KEY` 필요)

futures 0단계 — 선물 GT

현물 GT를 롱·숏 4색 마커로 변환.

현물 GT	선물 마커	의미
buy	L↑ / S↑	롱 진입 / 숏 청산
sell	L↓ / S↓	롱 청산 / 숏 진입

산출물	경로
JSON	`data/futures/ground_truth/ground_truth_trades_v{1,2,3}.json`
차트	`docs/futures/0_ground_truth/ground_truth_chart_v{1,2,3}.html`

선물 1~3단계는 docs/futures/{1_simulation,2_analysis,3_operations}/ (예정).

환경 변수

변수	설명	기본값
`DB_PATH`	공통 캔들 DB	`data/common/coins.db`
`SYMBOL`	코인 심볼	`BTC`
`DOWNLOAD_DAYS`	수집·차트 일수	`3650`
`GT_INTERVAL_MIN`	GT·기법 기준 인터벌(분)	`3`
`GT_LOOKBACK_DAYS`	GT 타점 기간(일)	`3650`
`GT_SIM_LOOKBACK_DAYS`	sim 거래 기간(일)	`1095`
`GT_INITIAL_CASH_KRW`	sim 초기 자본(원)	`200000`

경로 변수 요약

용도	변수 예시	기본 경로
spot GT JSON	`GROUND_TRUTH_FILE`	`data/spot/ground_truth/...`
spot GT 차트	`GROUND_TRUTH_CHART_V3_FILE`	`docs/spot/0_ground_truth/...`
spot sim 차트	`GROUND_TRUTH_CHART_SIM_V3_FILE`	`docs/spot/1_simulation/...`
spot 2단계	`TECHNIQUES_DIR`	`data/spot/techniques/`
futures GT JSON	`GROUND_TRUTH_FUTURES_FILE`	`data/futures/ground_truth/...`
futures GT 차트	`GROUND_TRUTH_FUTURES_CHART_V3_FILE`	`docs/futures/0_ground_truth/...`

전체 목록: .env.example

인터벌 코드: 분봉=분 단위 숫자, 일봉=1440, 주봉=10080, 월봉=43200

현물 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	사전 (캔들)	구현됨
spot	0~3단계	구현됨 (3단계 기본 paper)
futures	0단계	구현됨
futures	1~3단계	예정

변경 이력

2026-06-12: data/·docs/를 common / spot / futures 3유형 구조로 재편, coins.db → data/common/, 0단계 차트 → docs/{spot,futures}/0_ground_truth/
2026-06-12: 0_ground_truth_futures.py — 현물 GT → 선물 JSON·차트 변환 로직 보완
2026-06-12: README 현물 파이프라인 전체 순서 갱신
2026-06-12: src/deepcoin/data/ 모듈 복원
2026-06-11: 파이프라인 단계별 상세 설명 추가
2026-06-08: Ground Truth v1/v2/v3
2026-06-07: 캔들 수집 모듈 초기 구현

12 KiB Raw Blame History