**
skfolio_Catton**은 오픈소스 포트폴리오 최적화 라이브러리인skfolio를 기반으로, 암호화폐(Crypto) 시장과 Freqtrade 자동매매 봇에 맞춤 연계할 수 있도록 실전 퀀트 파이프라인과 한국어 튜토리얼을 결합한 독립 프로젝트입니다.
- 🌟 핵심 기능
- 📊 지원하는 주요 최적화 모델
- 🚀 빠른 시작 (Windows)
- 💡 실전 활용 가이드
- 1. 거래소 실시간 시세 수집 (업비트 / 바이낸스)
- 2. HRP 머신러닝 군집화 및 상관계수 분석
- 3. Freqtrade 연계 및 설정 파일(config.json) 자동 주입
- 4. 파이썬 코드로 직접 실행하기
- 5. 한국어 주피터 노트북 실습
- 6. 인터랙티브 퀀트 웹 대시보드 (Streamlit)
- 7. 주기적 포트폴리오 리밸런싱 롤링 백테스트
- 8. 인터랙티브 HTML 퀀트 분석 보고서 생성
- 9. 변동성 기반 동적 손절/익절 리스크 계산기
- 10. 최적 자산배분 비중 엑셀(CSV) 내보내기
- 11. 블랙-리터만 베이지안 자산배분
- 12. 역사적 크립토 블랙스완 스트레스 테스트
- 13. 김치 프리미엄 & 환율 차익 분석기
- 14. Freqtrade 멀티 전략 자금 배분 최적화기
- 15. 몬테카를로 미래 자산 경로 및 VaR 리스크 시뮬레이터
- 16. 공포·탐욕 지수 기반 거시 국면 동적 현금 비중 조절기
- 17. 퀀트 멀티 팩터 분석 및 스마트 베타 유니버스 스크리너
- 18. Freqtrade 완전체 실전 전략 샘플
- 19. 상관계수 붕괴 & 디커플링 감지기
- 20. 가상자산 세후 순수익률 & 세금 시뮬레이터
- 21. 업비트 원화(KRW) 마켓 전용 캔들 수집기
- 22. 한국 거래소 수수료 및 포트폴리오 수익률 잠식 계산기
- 23. 김치 프리미엄 기반 동적 자산배분 레짐 시그널러
- 24. 한국 특금법 트래블룰 준수 & 100만원 안전 분할 전송 어드바이저
- 25. 유동성 리스크 필터 및 Amihud/Corwin-Schultz 측정기
- 26. 켈리 공식 및 하프 켈리 포지션 사이징 계산기
- 27. 빗썸(Bithumb) 원화 마켓 전용 캔들 수집기
- 28. 3각 차익거래 기회 탐색 및 수수료 잠식 분석기
- 29. 김치 프리미엄 델타 중립 펀딩비 차익 시뮬레이터
- 30. 점프 디퓨전(Merton Jump) 기반 플래시 크래시 가상 시세 생성기
- 31. Freqtrade 선물 펀딩비 차익 화이트리스트 & 설정 생성기
- 32. 코인베이스(Coinbase) 기관용 USD 벤치마크 시세 수집기
- 33. 오메가 비율(Omega) 및 손익통증비율(Gain-to-Pain) 산출기
- 34. 목표 변동성 타겟팅(Vol-Targeting) 및 동적 현금 배분기
- 35. 가상자산 꼬리 의존성(Tail Dependence) 및 동반 급락 분석기
- 📁 프로젝트 구조
- 🧪 단위 테스트 및 CI/CD
- 📜 라이선스 및 크레딧
- scikit-learn 완벽 호환:
fit(),predict(),GridSearchCV등 scikit-learn 표준 API를 그대로 사용하여 친숙하고 간결한 코드 작성이 가능합니다.
- Freqtrade 트레이딩 봇 자동 연계 (
scripts/crypto_portfolio_optimizer.py):- Freqtrade가 수집한 과거 시세 데이터(
.feather)를 자동 탐색하여 최적 배분 비중을 계산합니다. - 계산된 비중을 Freqtrade
config.json의pair_whitelist및pair_stake_amounts로 즉시 반영합니다.
- Freqtrade가 수집한 과거 시세 데이터(
- 계층적 리스크 패리티 (HRP) & 머신러닝 군집화 (
scripts/crypto_hrp_clustering.py):- 공분산 행렬의 역행렬을 계산하지 않아, 노이즈와 다중공선성이 심한 코인 시장에서 극도로 안정적인 위험 균등 배분을 구현합니다.
- 실시간 시세 수집기 (
scripts/fetch_live_crypto.py):- API 키 없이도 바이낸스(USDT) 및 업비트(KRW 원화 마켓) 시세를 1초 만에 다운로드하여 최적화에 투입합니다.
- 한국어 인터랙티브 주피터 노트북 (
notebooks/):- 퀀트 자산배분 기초부터 암호화폐 리스크 패리티 실습까지 한국어로 단계별 학습을 지원합니다.
- Windows 원클릭 실행 환경 (
setup.ps1):- 복잡한 빌드 과정 없이 PowerShell 스크립트 한 번으로 가상환경 구축 및 필수 패키지 설치를 완료합니다.
| 모델명 | 설명 | 특징 및 추천 대상 |
|---|---|---|
| Max Sharpe Ratio | 샤프 지수(수익/위험 비율)를 극대화 | 기대 수익 대비 변동성이 가장 우수한 포트폴리오 |
| Min Variance | 전체 포트폴리오의 변동성을 극소화 | 급격한 변동성을 피하고 안정적인 자산 보존을 원할 때 |
| Risk Parity (ERC) | 각 자산이 전체 위험에 기여하는 비중을 동일하게 배분 | 특정 고변동성 알트코인에 위험이 집중되는 현상 방지 |
| Min Semi-Variance | 하방 변동성(낙폭 위험)만을 최소화 | 상승 변동성은 제한하지 않고 급락 위험만 회피 |
| Min CVaR | 조건부 가치평가(Expected Shortfall) 극소화 | 극단적 꼬리 위험(Fat-Tail)과 급락 손실 집중 방어 |
| HRP (Hierarchical Risk Parity) | 머신러닝 계층적 트리 군집화 기반 위험 배분 | 공분산 역행렬을 구하지 않아 다중공선성에 가장 강인함 |
| Schur Complementary (Cotton) | Peter Cotton 슈어 보수 기반 계층적 배분 | 상위 클러스터 간 위험 전이 차단 및 독립적 위험 가중 |
PowerShell 터미널에서 다음 명령어를 순서대로 실행합니다:
# 1. 저장소 폴더 이동
cd "D:\private project\skfolio_Catton"
# 2. Windows 원클릭 가상환경 구축 스크립트 실행
.\setup.ps1
# 3. 가상환경 활성화
.\.venv\Scripts\Activate.ps1
# 4. 환경 설치 검증
python scripts/verify_environment.py별도의 API 키 발급 없이 공개 시세를 즉시 다운로드하여 data/live/에 저장합니다:
# 업비트 원화(KRW) 마켓 1시간봉 수집
python scripts/fetch_live_crypto.py --exchange upbit --pairs BTC/KRW ETH/KRW SOL/KRW XRP/KRW --timeframe 1h
# 바이낸스 USDT 마켓 15분봉 수집
python scripts/fetch_live_crypto.py --exchange binance --pairs BTC/USDT ETH/USDT SOL/USDT --timeframe 15m코인 간의 상관관계 행렬을 계산하고 계층적 트리 군집화(Dendrogram)를 통해 최적 분산 비중을 계산합니다:
python scripts/crypto_hrp_clustering.py --timeframe 1h
# HRP 모델 최적 비중 및 상관계수 행렬을 JSON 파일로 내보내기
python scripts/crypto_hrp_clustering.py --use-synthetic --export-json reports/hrp_allocation.jsonskfolio가 계산한 최적 자산 비중을 Freqtrade 설정 파일로 자동 내보내어, 봇이 해당 비중대로 주문을 넣도록 연동합니다:
python scripts/crypto_portfolio_optimizer.py `
--timeframe 15m `
--export-freqtrade ../freqtrade/user_data/config.json `
--export-model "Risk Parity (ERC)" `
--wallet-size 10000결과:
config.json의pair_whitelist가 최적 코인들로 자동 갱신되며, 총 투자금(10,000 USDT)에 따른 코인별pair_stake_amounts가 자동으로 계산되어 저장됩니다. 기존 JSON은 검증 후 원자적으로 갱신되며, 손상된 설정 파일은 덮어쓰지 않습니다.
계산된 비중을 실제 주문금액에 반영하려면 freqtrade_integration/skfolio_callbacks.py를 Freqtrade 프로젝트에서 import할 수 있는 위치에 두고 기존 전략에 믹스인을 추가합니다:
from freqtrade.strategy import IStrategy
from freqtrade_integration import SkfolioFreqtradeMixin
class MyStrategy(SkfolioFreqtradeMixin, IStrategy):
# 기존 전략 설정과 populate_* 메서드
passSkfolioFreqtradeMixin.custom_stake_amount()는 pair_stake_amounts를 우선 사용하고, 해당 값이 없으면 사용 가능한 지갑 금액에 pair_weights를 적용합니다. 설정이 잘못되었거나 목록에 없는 페어는 기본적으로 주문금액 0을 반환하여 신규 진입을 차단합니다. 합성데이터 결과는 Freqtrade 설정으로 내보낼 수 없습니다.
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanVariance, ObjectiveFunction, RiskBudgeting
from skfolio.preprocessing import prices_to_returns
# 1. 가격 데이터 로드 및 수익률 변환
prices = load_sp500_dataset()[["AAPL", "MSFT", "AMZN", "JNJ"]]
returns = prices_to_returns(prices)
# 2. 리스크 패리티(위험 균등 배분) 모델 학습
model = RiskBudgeting()
model.fit(returns)
# 3. 최적 자산 비중 출력
for asset, weight in zip(returns.columns, model.weights_):
print(f"{asset}: {weight * 100:.2f}%")브라우저에서 대화형으로 실습할 수 있는 튜토리얼 노트북을 제공합니다:
jupyter lab- notebooks/01_quickstart_portfolio_optimization.ipynb: 포트폴리오 최적화 기본 개념 및 모델 비교
- notebooks/02_crypto_risk_parity_allocation.ipynb: 변동성 큰 암호화폐를 위한 리스크 패리티 자산배분
마우스 클릭만으로 포트폴리오 최적화부터 미래 시뮬레이션, 스트레스 테스트까지 한 번에 수행하는 웹 대시보드를 제공합니다:
streamlit run app_dashboard.py- 📊 포트폴리오 최적화 & 자산배분: 리스크 패리티, HRP, 최대 샤프 모델 선택 및 Freqtrade
config.json원클릭 주입 - 🇰🇷 업비트(Upbit) KRW 마켓 실시간 데이터 소스: 사이드바에서 업비트 공개 REST API를 직접 연동하여 실시간 원화마켓 캔들 데이터 기반 포트폴리오 최적화(HRP / Markowitz / ERC) 구동
- 🔄 주기적 리밸런싱 백테스트: 롤링 윈도우 워크포워드 백테스트 및 Buy & Hold 대비 초과수익률/MDD 측정
- 🎲 몬테카를로 미래 시뮬레이션: 1,000회 GBM 자산 경로 투영, 95% 신뢰구간 콘 차트, 95% VaR / CVaR 계산
- 💥 역사적 블랙스완 스트레스 테스트: 코로나 쇼크, 루나 폭락, FTX 파산 등 극단적 위기 시나리오별 잔여 자산 진단
- 😨 공포·탐욕 매크로 현금 조절: 실시간 Fear & Greed 지수 수집 및 고평가 국면 안전자산(USDT) 버퍼 계산
- ⚡ 김치 프리미엄 차익거래 & 전술적 자산배분 레짐: 실시간 원/달러 환율 반영 업비트-바이낸스 격차 분석 및 김프 과열도에 따른 현금(KRW) 동적 비중 조절
- 💰 세후 순수익률 & 세금 시뮬레이터: 대한민국 가상자산 소득세법(기본공제 250만 원, 22% 분리과세) 기반 실질 순수익 계산
- 💸 국내 거래소 수수료 & Fee Drag 시뮬레이터: 업비트/빗썸/코인원/코빗 5대 프리셋 및 리밸런싱 회전율에 따른 연간 수익률 잠식률 비교 분석
- 🛡️ 특금법 트래블룰 안전 분할 전송: 100만 원 법정 기준 초과 시 해외거래소/개인지갑 입출금 동결 방지를 위한 95만 원 버퍼 분할 전송 플래너
일정 주기(예: 50개 캔들 또는 7일)마다 자산 비중을 재조정(Rebalancing)할 때, 단순 보유(Buy & Hold) 대비 수익률과 낙폭(MDD)이 어떻게 개선되는지 워크포워드 시뮬레이션을 수행합니다:
# 리스크 패리티 모델 기반 롤링 리밸런싱 백테스트 실행 (거래 수수료 0.1% 반영 및 15% 낙폭 시 현금 방어 보호)
python scripts/crypto_rebalancing_backtest.py --model "Risk Parity" --timeframe 15m --fee 0.001 --drawdown-guard 0.15 --export-nav-csv reports/rebal_nav.csv
# 합성 데이터로 빠른 검증 실행 및 결과 JSON / CSV 파일 내보내기
python scripts/crypto_rebalancing_backtest.py --use-synthetic --model "Equal Weight" --export-json reports/rebalancing_results.json --export-csv reports/rebal_metrics.csv- 산출 지표: 누적 수익률(Total Return), 최대 낙폭(MDD), 버크 비율(Burke Ratio), RoMaD(Return over MDD), 수중 시간 비율(Time Underwater %), 연환산 샤프/소르티노 지수, 회전율(Turnover Rate), 스털링 비율(Sterling Ratio), 페인 지수(Pain Index) 및 페인 비율(Pain Ratio) 비교 요약표 출력
- NAV 시계열 추적:
--export-nav-csv옵션으로 포트폴리오, 동일비중 벤치마크, Buy&Hold 벤치마크의 일별/캔들별 순자산가치 및 드로다운 궤적을 CSV로 내보내기 지원
오프라인 브라우저에서도 열어볼 수 있는 프리미엄 다크 테마 기반 단일 HTML 보고서 파일(reports/crypto_portfolio_report.html)을 생성합니다:
python scripts/export_html_report.py --output reports/crypto_portfolio_report.html --model "Risk Parity (ERC)"- 포함 내용: 다크 핀테크 테마(#0E1117) 디자인, KPI 성과 카드(샤프 지수, 연환산 수익률, MDD), 기관 하방 리스크 카드(궤양지수 Ulcer Index, 마틴 비율 Martin Ratio, 스털링 비율 Sterling Ratio), 최적 자산 배분 도넛 차트, 코인 간 상관관계 히트맵, 누적 수익률 시뮬레이션 인터랙티브 차트, Freqtrade 설정 코드
각 코인의 하방 변동성(Semi-Deviation)과 위험-보상 비율(RR Ratio)을 분석하여 개별 코인별 권장 손절폭(Stoploss)과 익절폭(Take-Profit)을 자동 산출합니다:
# 분석용 리스크 JSON 및 CSV 파일 내보내기
python scripts/crypto_risk_budget_calculator.py `
--risk-mult 2.0 `
--rr-ratio 2.0 `
--export-json user_data/risk_params.json `
--export-csv user_data/risk_params.csv
# 기존 Freqtrade config.json에 콜백용 종목별 SL/TP를 안전하게 주입
python scripts/crypto_risk_budget_calculator.py `
--risk-mult 2.0 `
--rr-ratio 2.0 `
--freqtrade-config ../freqtrade/user_data/config.json-
실시간 시세 수집 후 즉시 최적화 실행 (
--optimize):# 바이낸스 최신 캔들을 받아와서 즉시 포트폴리오 최적화 실행 python scripts/fetch_live_crypto.py --exchange binance --optimize
-
Freqtrade 실전 전략 주문 금액 동적 할당 (
scripts/freqtrade_stake_allocator.py): skfolio가 산출한 비중을 Freqtrade 전략(custom_stake_amount)에서 단 한 줄로 불러와 실제 매수 주문 금액을 코인별 비중대로 자동 집행합니다:from scripts.freqtrade_stake_allocator import get_custom_stake_amount def custom_stake_amount(self, pair: str, current_time, current_rate: float, proposed_stake: float, min_stake: float | None, max_stake: float | None, entry_tag: str | None, side: str, **kwargs) -> float: return get_custom_stake_amount( pair=pair, proposed_stake=proposed_stake, total_wallet=self.wallets.get_total_stake_amount(), min_stake=min_stake, max_stake=max_stake, config_path="user_data/config.json", )
시장 균형 수익률(Prior)과 트레이더의 주관적 시장 전망(Views)을 베이지안 통계로 결합하여 안정적이고 극단값 없는 최적 비중을 계산합니다:
# 상대적 뷰(BTC가 ETH보다 +2% 초과 상승)와 절대적 뷰(SOL +5% 상승) 반영 및 최적 비중 JSON/CSV 내보내기
python scripts/crypto_black_litterman.py `
--views "BTC/USDT>ETH/USDT:0.02" "SOL/USDT:0.05" `
--risk-aversion 2.5 `
--export-json reports/black_litterman.json `
--export-csv reports/black_litterman.csv2020 코로나 쇼크, 2018 크립토 윈터, 2022 루나/UST 붕괴, FTX 파산, 2021 중국 채굴 금지 및 역대 브릿지 해킹 등 크립토 역사상 최악의 쇼크 시나리오(총 11개 역사적 시나리오)를 포트폴리오에 가상 주입하여 자산 방어력, 스트레스 VaR(sVaR 95%), 스트레스 기대 숏폴(sES 95%), 주요 리스크 유발 자산(Primary Driver) 및 스테이블코인 헤징 버퍼 효과를 정밀 평가합니다:
# 포트폴리오 자본금 $10,000, 20% 현금/스테이블 헤징 버퍼 시뮬레이션 및 자산별 기여도 출력
python scripts/crypto_stress_tester.py `
--wallet-size 10000 `
--cash-buffer 0.20 `
--show-assets `
--export-json reports/stress_test.json `
--export-csv reports/stress_test.csv `
--export-asset-csv reports/stress_asset_breakdown.csv국내 거래소(업비트 KRW)와 해외 거래소(바이낸스 USDT)의 실시간 시세를 환율(USD/KRW)로 정밀 환산하여 코인별 김치 프리미엄(%)과 차익 스프레드를 계산합니다:
python scripts/crypto_kimchi_premium.py --usdt-krw 1350.0 --export-json reports/kimchi_premium.json여러 Freqtrade 매매 전략(추세추종, 역추세, 볼린저 밴드 돌파 등)의 백테스트 손익 곡선을 바탕으로, 전체 계좌의 낙폭(MDD)을 최소화하는 전략별 최적 자금 배분 비율을 도출합니다:
# 백테스트 결과 기반 전략 간 리스크 패리티 가중치 산출
python scripts/freqtrade_strategy_optimizer.py --capital 10000 --model "Risk Parity"기하 브라운 운동(GBM)을 기반으로 향후 90일간 발생 가능한 1,000개의 가상 가격 경로를 시뮬레이션하여 95% 신뢰구간 콘 차트와 최대 손실액(VaR, CVaR), 원금 손실 확률을 계산합니다:
# 향후 90일 1,000개 경로 시뮬레이션 및 VaR/CVaR 신뢰구간 JSON/CSV 내보내기
python scripts/crypto_monte_carlo.py --days 90 --sims 1000 --capital 10000 --export-json reports/monte_carlo.json --export-csv reports/monte_carlo.csvAlternative.me 실시간 공포·탐욕 지수를 읽어와 시장 과열(Extreme Greed) 시 최대 40%의 현금 버퍼를 강제 확보하여 자산을 보호하고, 공포 국면에서는 적극 투자로 스위칭하며 정형 JSON 및 CSV로 내보냅니다:
python scripts/crypto_macro_regime.py --wallet-size 10000 --export-json reports/macro_regime.json --export-csv reports/macro_regime.csv모멘텀(Momentum), 저변동성(Low Volatility), 추세 강도(Trend Strength) 팩터를 Z-score로 정규화 합산하여 상위 우량 코인을 자동 선별(Smart Beta Universe)하고 정형 JSON 및 CSV 보고서로 내보냅니다:
python scripts/crypto_factor_analyzer.py --lookback 60 --top-n 3 --export-json reports/factor_ranking.json --export-csv reports/factor_ranking.csvfreqtrade-vibe-strategies에 바로 투입할 수 있는 완전체 전략 파일입니다.
- 동적 주문 금액:
custom_stake_amount()에서 skfolio 최적 비중을 읽어와 코인별 매수 주문액을 자동 차등 집행 - 동적 손절/익절:
custom_stoploss()에서 코인별 하방 변동성 맞춤 손절폭 적용 및 수익 발생 시 브레이크이븐 트레일링
비트코인(BTC)과 알트코인 간의 롤링 상관계수를 실시간 모니터링하여, 동조화가 깨지는 이상 현상(역상관, 상관계수 급락), 포트폴리오 분산 비율(DR) 및 분산 투자 강화 기회를 감지하고 JSON 및 CSV로 내보냅니다:
python scripts/crypto_correlation_breakdown.py --window 30 --threshold 1.8 --export-json reports/corr_breakdown.json --export-csv reports/corr_breakdown.csv한국 가상자산 소득세(연간 기본공제 250만 원, 22% 분리과세) 규정을 반영하여, 포트폴리오 운용 및 리밸런싱에 따른 실현 손익 통산과 세금 잠식률(Tax Drag), 최종 세후 순수익률을 계산합니다:
python scripts/crypto_tax_calculator.py --profit 12000000 --capital 50000000업비트 공개 REST API를 통해 API 키 없이도 KRW 마켓의 OHLCV 캔들 및 실시간 시세를 직접 수집하고, skfolio 포트폴리오 최적화에 즉시 투입 가능한 DatetimeIndex 피벗 DataFrame을 생성합니다:
# 업비트 KRW 마켓 일봉 100개 수집 및 CSV 내보내기
python scripts/fetch_upbit_crypto.py --markets KRW-BTC KRW-ETH KRW-SOL KRW-XRP --count 100 --output-csv data/live/upbit_prices.csv업비트(0.05%), 빗썸(0.04% 쿠폰 / 0.25%), 코인원(0.20%), 코빗 등 국내 주요 거래소의 수수료 체계와 원화 출금 수수료(건당 1,000원), 연간 포트폴리오 회전율(Turnover)을 반영하여 실질 연간 수수료 잠식률(Fee Drag %)과 손익분기 최소 요구수익률을 산출하고 JSON 및 CSV로 내보냅니다:
# 업비트 KRW 마켓 기준 5,000만원 자본금, 연간 회전율 6배수 수수료 시뮬레이션 및 JSON/CSV 내보내기
python scripts/crypto_krw_fee_calculator.py --exchange upbit --capital 50000000 --turnover 6.0 --export-json reports/krw_fee.json --export-csv reports/krw_fee.csv
# 국내 전체 거래소 수수료 잠식 비교 매트릭스 CSV 내보내기
python scripts/crypto_krw_fee_calculator.py --compare --capital 50000000 --export-csv reports/exchange_fee_compare.csv실시간 김치 프리미엄 수준을 바탕으로 시장의 과열/할인 레짐(EXTREME_OVERHEATED, MODERATE_OVERHEATED, FAIR_EQUILIBRIUM, NEGATIVE_DISCOUNT)을 진단하고, 포트폴리오의 안전자산(KRW 현금)과 위험자산(크립토) 비중을 동적으로 리스케일링하며 정형 JSON 및 CSV로 내보냅니다:
# 김치 프리미엄 실시간 또는 지정값(+6.5%) 기준 전술적 자산배분 실행 및 JSON/CSV 내보내기
python scripts/crypto_kimchi_regime.py --premium 6.5 --export-json reports/kimchi_regime.json --export-csv reports/kimchi_regime.csv대한민국 특정 금융거래정보법(특금법)에 따른 100만원 이상 가상자산 전송 시의 VASP 트래블룰 규제 적용 여부를 판별하고, 미지원 해외 거래소나 개인 지갑 송금 시 입출금 정지를 방지하기 위한 1회 안전 전송선(KRW 950,000 안전 버퍼) 기준 최적 분할 전송 횟수, 총 소요 시간 및 수수료 누적액을 계산합니다:
# 3,000 XRP 전송 시 100만원 임계점 대비 안전 분할 전송 계획 도출
python scripts/crypto_travel_rule_advisor.py --coin XRP --amount 3000 --price-krw 1900 --export-json reports/travel_rule.jsonAmihud 비유동성 비율, Corwin-Schultz 고저가 실효 스프레드, 주문 규모별 시장 충격 슬리피지를 복합 평가하여 호가가 얇은 알트코인을 포트폴리오 유니버스에서 안전하게 필터링합니다:
# 최소 거래대금 $50k, Amihud 2.0 이하, $10,000 주문 기준 최대 슬리피지 1.5% 이하 스크리닝
python scripts/crypto_liquidity_filter.py --min-volume 50000 --max-amihud 2.0 --trade-size 10000 --max-slippage 1.5 --export-json reports/liquidity_report.json과거 백테스트 승률과 손익비(Payoff Ratio)를 바탕으로 기하급수적 계좌 성장을 달성하는 이산/연속 켈리 비중(f*) 및 암호화폐 변동성 하방 리스크를 50% 완화한 하프 켈리(Half-Kelly) 투자 비중을 계산하고, 자본금 기준 달러 주문 금액을 정형 JSON 및 CSV로 내보냅니다:
python scripts/crypto_kelly_sizer.py --win-rate 0.58 --payoff 1.75 --capital 20000 --export-json reports/kelly_sizing.json --export-csv reports/kelly_sizing.csv빗썸 공개 REST API를 통해 API 키 없이도 KRW 마켓의 OHLCV 캔들 데이터, 실시간 호가 스프레드, 상위 오더북 호가 사다리(Ladder) 및 대량 주문 체결 시의 기관 수준 VWAP 체결가와 슬리피지(bps)를 시뮬레이션하고 CSV로 내보냅니다:
# 빗썸 KRW 마켓 일봉 30개 수집 및 CSV 내보내기
python scripts/fetch_bithumb_crypto.py --symbols BTC ETH SOL XRP --count 30 --export-csv data/live/bithumb_prices.csv
# 실시간 호가창 스프레드 및 상위 5단계 호가 사다리 조회
python scripts/fetch_bithumb_crypto.py --symbols BTC ETH --orderbook --depth-levels 5
# 5,000만원 대량 매수 주문에 대한 기관 VWAP 체결 슬리피지 시뮬레이션 및 CSV 내보내기
python scripts/fetch_bithumb_crypto.py --symbols BTC ETH --orderbook --order-size 50000000 --side buy --export-csv reports/bithumb_impact.csv3개 레그(Quote -> A -> B -> Quote) 환율 경로의 순환 불일치를 탐색하고 거래소 수수료(Fee Drag)와 슬리피지 버퍼를 감안한 무위험 차익 기회를 정형 JSON 및 CSV 데이터로 내보냅니다:
python scripts/crypto_triangular_arbitrage.py --p-btc-usdt 65000 --p-eth-usdt 3500 --p-eth-btc 0.0545 --export-json reports/triangular_arb.json --export-csv reports/triangular_arb.csv국내 거래소(업비트/빗썸)와 해외 거래소(바이낸스/바이비트) 간의 김치 프리미엄 스프레드 수렴 및 무기한 선물 8시간 펀딩비 수익을 결합한 델타 중립 캐리 트레이드(Basis Trading)의 순수익, 거래소 수수료 잠식, 연환산 APR 및 손익분기 스프레드를 정밀 시뮬레이션하고 정형 JSON 및 CSV 보고서로 내보냅니다:
python scripts/crypto_kimchi_hedging.py --capital 50000000 --entry-kp 1.0 --exit-kp 4.0 --days 30 --export-json reports/kimchi_hedging.json --export-csv reports/kimchi_hedging.csv거래소 선물 무기한 계약의 실시간 펀딩비(Funding Rate)를 분석하여 연환산 APR 기준 고수익 페어 목록을 선별하고, Freqtrade 선물 봇 설정(config.json)을 자동으로 생성 및 JSON으로 내보냅니다:
python scripts/freqtrade_funding_arbitrage.py --min-apr 15.0 --stake 1000 --export-json config/funding_arbitrage.json키팅-샤드윅 오메가 비율(Omega Ratio), 게인투페인 비율(Gain-to-Pain), 테일 비율(Tail Ratio), 상식 비율(Common Sense Ratio), 케스트너 K-비율(K-Ratio), 궤양지수(Ulcer Index), 마틴 비율(Martin Ratio), 페인 지수(Pain Index), 버크 비율(Burke Ratio), 스털링 비율(Sterling Ratio), 최대 침체 기간(Duration) 등 기관 수준의 하방 리스크를 종합 계산하고 정형 JSON 및 CSV 보고서로 내보냅니다:
python scripts/crypto_drawdown_metrics.py --rf 2.0 --export-json reports/drawdown_metrics.json --export-csv reports/drawdown_metrics.csv포트폴리오의 실현 변동성(Realized Volatility)을 실시간 추적하여, 목표 변동성(Target Volatility, 예: 25%)에 맞추어 포트폴리오의 총 익스포저를 동적으로 스케일링하고 안전자산(USDT 현금) 비중을 조절합니다. 고변동 장세에서는 디리스킹(De-risking)을 실행하고 샤프 지수 및 칼마 비율(Calmar Ratio)을 극대화하며, 워크포워드 롤링 시뮬레이션(--simulate) 및 JSON/CSV/NAV 시계열 내보내기를 지원합니다:
# 목표 변동성 단일 시점 비중 사이징 및 결과 내보내기
python scripts/crypto_vol_target_allocator.py --target-vol 0.25 --realized-vol 0.50 --export-json reports/vol_target.json --export-csv reports/vol_target.csv
# 정적(Unhedged) vs 변동성 타겟팅 동적 배분 워크포워드 시뮬레이션 비교 및 NAV 시계열 내보내기
python scripts/crypto_vol_target_allocator.py --simulate --target-vol 0.25 --lookback 30 --days 180 --export-csv reports/vol_target_sim.csv --export-nav-csv reports/vol_target_nav.csv비선형 극단 상황(하위 5% 폭락 또는 상위 5% 급등)에서의 자산 간 동조화 계수(Tail Dependence Coefficient)를 추정하여, 일반 선형 상관계수로는 포착할 수 없는 시장 붕괴 시의 동반 급락 위험 및 시스템적 취약도(Systemic Crash Vulnerability)를 계산하고 정형 JSON 및 CSV 보고서로 내보냅니다:
python scripts/crypto_tail_dependence.py --quantile 0.05 --export-json reports/tail_dependence.json --export-csv reports/tail_dependence.csv빗썸 공개 REST API를 통해 실시간 호가창(Order Book) 데이터를 수집하고, 최우선 매수/매도호가, 중간 가격(Mid Price), 원화 스프레드 및 베이시스 포인트(bps) 스프레드, 매수/매도 호가 깊이(Market Depth in KRW)를 계산하여 비교 요약표 및 CSV로 내보냅니다:
# 실시간 호가 스프레드 및 호가창 깊이 분석 (기본 30단계 호가)
python scripts/fetch_bithumb_crypto.py --symbols BTC ETH SOL XRP --orderbook --orderbook-count 30 --export-csv reports/bithumb_orderbook.csv
# 캔들 데이터 수집 및 CSV 내보내기
python scripts/fetch_bithumb_crypto.py --symbols BTC ETH --interval 24h --count 100 --export-csv reports/bithumb_prices.csv글로벌 USD 기준 거래소인 코인베이스(Coinbase Exchange) 공개 REST API를 통해 실시간 오더북 호가 깊이를 탐색하고, 상위 호가 사다리(Top Depth Ladder) 시각화 및 대규모 주문 금액($50,000~$1,000,000)에 따른 VWAP 체결가, 호가 스프레드, 슬리피지(Slippage in bps), 가격 충격도(Price Impact), 체결률(Fill %) 및 총 누적 호가 깊이를 정밀 산출하여 CSV로 내보냅니다:
# 실시간 오더북 시장 충격 및 호가 사다리 탐색 ($50,000 매수 주문, 상위 5단계 사다리 기준)
python scripts/fetch_coinbase_crypto.py --symbols BTC ETH SOL --orderbook --order-size 50000 --side buy --book-level 2 --depth-levels 5 --export-csv reports/coinbase_slippage.csv
# 캔들 데이터 수집 및 CSV 내보내기
python scripts/fetch_coinbase_crypto.py --symbols BTC ETH SOL --timeframe 1d --limit 100 --export-csv reports/coinbase_prices.csv국내 1위 거래소인 업비트(Upbit) 공개 REST API를 활용하여 실시간 오더북(호가창)의 상위 매수/매도 호가 사다리(Ladder Depth)를 10단계 이상 상세 탐색하고, 대규모 주문 금액(예: 5천만 원~10억 원) 집행 시 발생하는 VWAP 체결 단가, 호가 스프레드, 슬리피지(Slippage in bps), 가격 충격도(Market Impact bps) 및 체결률(Fill %)을 정밀 시뮬레이션하여 CSV로 내보냅니다:
# 업비트 KRW-BTC 5천만 원 매수 주문 시뮬레이션 및 호가 사다리 탐색
python scripts/fetch_upbit_crypto.py --orderbook BTC --order-size 50000000 --side buy --depth-levels 10 --export-orderbook-csv reports/upbit_orderbook.csv
# 1억 원 매도 주문에 대한 호가 스프레드 및 체결 충격도 분석
python scripts/fetch_upbit_crypto.py --orderbook ETH --order-size 100000000 --side sellskfolio_Catton/
├── .github/workflows/
│ └── crypto_ci.yml # GitHub Actions 자동 테스트 CI 워크플로우
├── .streamlit/
│ └── config.toml # 핀테크 다크 테마 대시보드 환경설정
├── notebooks/ # 한국어 대화형 주피터 노트북
│ ├── 01_quickstart_portfolio_optimization.ipynb
│ └── 02_crypto_risk_parity_allocation.ipynb
├── scripts/ # 실전 자동화 스크립트 모음
│ ├── crypto_portfolio_optimizer.py # Freqtrade 연계 크립토 최적화 파이프라인 (제약조건 지원)
│ ├── crypto_hrp_clustering.py # HRP 계층적 트리 군집화 및 상관계수 분석
│ ├── crypto_rebalancing_backtest.py # 주기적 포트폴리오 롤링 리밸런싱 백테스트
│ ├── export_html_report.py # 인터랙티브 HTML 퀀트 보고서 생성기
│ ├── crypto_risk_budget_calculator.py # 변동성 기반 동적 SL/TP 리스크 계산기
│ ├── crypto_black_litterman.py # 블랙-리터만 베이지안 포트폴리오 최적화기
│ ├── crypto_stress_tester.py # 역사적 블랙스완 스트레스 테스터
│ ├── crypto_kimchi_premium.py # 김치 프리미엄 & 환율 차익 분석기
│ ├── crypto_kimchi_regime.py # 김치 프리미엄 기반 동적 자산배분 레짐 시그널러
│ ├── crypto_krw_fee_calculator.py # 한국 거래소 수수료 및 Fee Drag 시뮬레이터
│ ├── crypto_travel_rule_advisor.py # 한국 특금법 트래블룰 준수 안전 분할 전송기
│ ├── fetch_upbit_crypto.py # 업비트 원화(KRW) 마켓 캔들 및 호가 사다리/체결 슬리피지 분석기
│ ├── fetch_bithumb_crypto.py # 빗썸 원화(KRW) 마켓 캔들 및 호가창/스프레드 분석기
│ ├── fetch_coinbase_crypto.py # 코인베이스 USD 마켓 캔들 및 시장충격 슬리피지 분석기
│ ├── freqtrade_strategy_optimizer.py # 멀티 전략 간 자금 배분 최적화기
│ ├── crypto_monte_carlo.py # 몬테카를로 미래 자산 경로 및 VaR 시뮬레이터
│ ├── crypto_macro_regime.py # 공포·탐욕 지수 기반 동적 현금 비중 조절기
│ ├── crypto_factor_analyzer.py # 퀀트 멀티 팩터 분석 및 스마트 베타 스크리너
│ ├── crypto_correlation_breakdown.py # 상관계수 붕괴 & 디커플링 감지기
│ ├── crypto_tax_calculator.py # 가상자산 세후 순수익률 & 세금 시뮬레이터
│ ├── crypto_vol_target_allocator.py # 목표 변동성 타겟팅 및 현금 동적 배분기
│ ├── crypto_tail_dependence.py # 극단 꼬리 의존성 및 동반 급락 분석기
│ ├── freqtrade_stake_allocator.py # Freqtrade 전략 동적 주문금액 연동 브릿지
│ ├── fetch_live_crypto.py # 거래소(바이낸스/업비트) 실시간 시세 수집기
│ └── verify_environment.py # 환경 검증 스크립트
├── strategies/ # Freqtrade 실전 전략 모음
│ └── SkfolioEnhancedAtrStrategy.py # skfolio 동적 비중/리스크 완전 연동 실전 전략
├── src/skfolio/ # skfolio 핵심 최적화 알고리즘 엔진
├── tests/ # 단위 테스트 모음
│ ├── test_crypto_suite.py # 통합 테스트 스위트 러너 (Python 3.10~3.14 호환)
│ ├── test_upbit_fetcher.py # 업비트 캔들 수집기 검증
│ ├── test_krw_fee_calculator.py # 한국 거래소 수수료 계산기 검증
│ ├── test_kimchi_regime.py # 김치 프리미엄 레짐 시그널러 검증
│ ├── test_travel_rule_advisor.py # 트래블룰 안전 분할 전송기 검증
│ ├── test_crypto_optimizer.py
│ ├── test_hrp_clustering.py
│ ├── test_live_fetcher.py
│ ├── test_dashboard.py
│ ├── test_rebalancing.py
│ ├── test_html_report.py
│ ├── test_risk_calculator.py
│ ├── test_freqtrade_integration.py
│ ├── test_stake_allocator.py
│ ├── test_black_litterman.py
│ ├── test_stress_tester.py
│ ├── test_kimchi_premium.py
│ ├── test_strategy_optimizer.py
│ ├── test_monte_carlo.py
│ ├── test_macro_regime.py
│ ├── test_factor_analyzer.py
│ ├── test_enhanced_strategy.py
│ ├── test_correlation_breakdown.py
│ ├── test_tax_calculator.py
│ ├── test_upbit_fetcher.py
│ ├── test_krw_fee_calculator.py
│ ├── test_kimchi_regime.py
│ └── test_travel_rule_advisor.py
├── requirements-local.txt # 로컬 개발 및 퀀트 연구용 패키지 목록
├── setup.ps1 # Windows PowerShell 원클릭 설치 스크립트
├── app_dashboard.py # Streamlit 인터랙티브 웹 대시보드 (다크 테마 & 캐싱)
├── README.md # 프로젝트 메인 한국어 안내 문서
└── LICENSE # BSD 3-Clause 라이선스 전문
프로젝트의 모든 핵심 모듈은 통합 테스트 스위트를 통해 검증됩니다:
python tests/test_crypto_suite.pyRan 265 tests in 7.502s -> OK
코드가 main 브랜치에 푸시될 때마다 GitHub Actions가 클라우드에서 위 테스트를 자동으로 수행하여 코드 무결성을 보장합니다.
- 본 프로젝트는 skfolio developers가 개발한 오픈소스
skfolio라이브러리를 기반으로 합니다. - 원본 소프트웨어는 BSD 3-Clause License를 따르며, 라이선스 전문은 LICENSE 파일에서 확인하실 수 있습니다.
- Copyright (c) 2023-2026 The skfolio developers. All rights reserved.