b4c775563c
- hydra/main.py: auth_guard 미들웨어에 실제 API 키 검증 로직 추가 - hydra/main.py: lifespan 초기화 블록 try-except 감싸기, finally에서 ohlcv_store None 체크 추가 - Dockerfile: --host 127.0.0.1 → 0.0.0.0 (컨테이너 간 통신 가능하도록) - hydra/config/settings.py: 기본 API 키 사용 시 경고 validator 추가 - README.md: 첫 사용자를 위한 상세 가이드로 전면 재작성 - docs/QUICKSTART_KO.md: 단계별 시작 가이드 개선 - docs/API_REFERENCE_KO.md: 전체 엔드포인트 응답 예시 및 파라미터 설명 추가 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
426 lines
11 KiB
Markdown
426 lines
11 KiB
Markdown
# HYDRA Engine
|
|
|
|
HYDRA Engine은 **로컬 우선(Local-first)** 철학으로 설계된 자동매매 엔진입니다.
|
|
데이터 수집 → 지표 계산 → 레짐 분류 → 시그널 생성 → 백테스트 → 실거래까지 하나의 저장소에서 관리합니다.
|
|
|
|
> **이 프로젝트는 교육·연구·실험용입니다.**
|
|
> 실거래 수익을 보장하지 않으며, 사용에 따른 모든 책임은 사용자 본인에게 있습니다.
|
|
> 반드시 [DISCLAIMER.md](DISCLAIMER.md)를 먼저 읽으세요.
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [포함된 기능](#1-포함된-기능)
|
|
2. [사용 철학 — 어떻게 접근할 것인가](#2-사용-철학--어떻게-접근할-것인가)
|
|
3. [준비물 설치](#3-준비물-설치)
|
|
4. [처음 시작하기 (5단계)](#4-처음-시작하기-5단계)
|
|
5. [테스트 실행](#5-테스트-실행)
|
|
6. [Docker로 전체 파이프라인 실행](#6-docker로-전체-파이프라인-실행)
|
|
7. [API 사용법](#7-api-사용법)
|
|
8. [CLI 사용법](#8-cli-사용법)
|
|
9. [Docker 프로필 선택](#9-docker-프로필-선택)
|
|
10. [자주 발생하는 문제 (FAQ)](#10-자주-발생하는-문제-faq)
|
|
11. [문서](#11-문서)
|
|
12. [라이선스](#12-라이선스)
|
|
|
|
---
|
|
|
|
## 1. 포함된 기능
|
|
|
|
| 모듈 | 설명 |
|
|
|------|------|
|
|
| FastAPI 서버 | REST API로 모든 기능 제어 |
|
|
| OHLCV 수집기 | 거래소에서 캔들 데이터 수집, SQLite/TimescaleDB 저장 |
|
|
| 지표 계산 엔진 | RSI, MACD, Bollinger Band 등 자동 계산 |
|
|
| 레짐 분류 엔진 | 시장 상태(추세/횡보/변동성) 분류 |
|
|
| 전략 시그널 엔진 | 매수/매도 시그널 생성 |
|
|
| 보조 데이터 수집 | 오더북, 이벤트 일정, 감성 점수 |
|
|
| 인메모리 백테스트 | 수집된 데이터로 전략 성과 검증 |
|
|
| Kill Switch | 긴급 전 포지션 청산 |
|
|
| 주문 큐 | 안전한 주문 처리 파이프라인 |
|
|
| 리스크 엔진 | 포지션 및 리스크 관리 |
|
|
| CLI 도구 | 터미널에서 모든 기능 제어 |
|
|
| Telegram 알림 | 주요 이벤트 실시간 알림 |
|
|
|
|
---
|
|
|
|
## 2. 사용 철학 — 어떻게 접근할 것인가
|
|
|
|
HYDRA는 **한 번에 모든 기능을 켜는 프로젝트가 아닙니다.**
|
|
|
|
```
|
|
1단계: 테스트 실행으로 코드 정상 확인
|
|
2단계: 데이터 수집 (거래소 API 키 없어도 공개 데이터 가능)
|
|
3단계: 지표·레짐·시그널 계산 확인
|
|
4단계: API/CLI로 상태 관찰
|
|
5단계: 백테스트로 전략 검증
|
|
6단계: (충분한 검증 후) 실거래 연결
|
|
```
|
|
|
|
처음 사용하는 분은 **1~4단계**부터 시작하는 것을 강력히 권장합니다.
|
|
|
|
---
|
|
|
|
## 3. 준비물 설치
|
|
|
|
### 필수 소프트웨어
|
|
|
|
| 소프트웨어 | 버전 | 설치 링크 |
|
|
|-----------|------|----------|
|
|
| Python | 3.11 이상 | https://www.python.org/downloads/ |
|
|
| Git | 최신 | https://git-scm.com/ |
|
|
| Docker Desktop | 최신 | https://www.docker.com/products/docker-desktop |
|
|
|
|
> Docker Desktop을 설치하면 Docker와 Docker Compose가 함께 설치됩니다.
|
|
|
|
### 설치 확인
|
|
|
|
터미널(명령 프롬프트 / PowerShell / Terminal)에서 아래 명령을 실행해 버전을 확인합니다.
|
|
|
|
```bash
|
|
python --version # Python 3.11.x 이상이어야 함
|
|
git --version
|
|
docker --version
|
|
docker compose version
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 처음 시작하기 (5단계)
|
|
|
|
### 4.1 저장소 다운로드
|
|
|
|
```bash
|
|
git clone https://github.com/sinmb79/Hydra-Engine.git
|
|
cd Hydra-Engine
|
|
```
|
|
|
|
### 4.2 Python 가상환경 생성 및 활성화
|
|
|
|
가상환경은 이 프로젝트 전용 Python 환경을 만들어 다른 프로젝트와 충돌하지 않게 합니다.
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
```
|
|
|
|
**Windows (PowerShell):**
|
|
```powershell
|
|
.venv\Scripts\Activate.ps1
|
|
```
|
|
|
|
> PowerShell에서 실행 오류가 발생하면 먼저 아래 명령을 실행하세요:
|
|
> ```powershell
|
|
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
|
> ```
|
|
|
|
**macOS / Linux:**
|
|
```bash
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
활성화되면 터미널 앞에 `(.venv)`가 표시됩니다.
|
|
|
|
### 4.3 패키지 설치
|
|
|
|
```bash
|
|
pip install -e .[dev]
|
|
```
|
|
|
|
> 처음 설치 시 수분이 걸릴 수 있습니다.
|
|
|
|
### 4.4 환경 변수 설정
|
|
|
|
`.env.example` 파일을 복사해 `.env`를 만듭니다.
|
|
|
|
**macOS / Linux:**
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
**Windows (PowerShell):**
|
|
```powershell
|
|
Copy-Item .env.example .env
|
|
```
|
|
|
|
생성된 `.env` 파일을 텍스트 에디터로 열어 아래 항목을 수정합니다.
|
|
|
|
```env
|
|
# 반드시 변경하세요 — 이 값이 API 접근 비밀번호입니다
|
|
HYDRA_API_KEY=여기에-랜덤-문자열-입력
|
|
|
|
# 프로필: lite(입문) / pro(중급) / expert(고급)
|
|
HYDRA_PROFILE=lite
|
|
|
|
# Redis 주소 (Docker 사용 시 기본값 유지)
|
|
REDIS_URL=redis://localhost:6379
|
|
```
|
|
|
|
> **HYDRA_API_KEY**는 API 호출 시 인증에 사용됩니다.
|
|
> 아무 문자열이나 사용할 수 있습니다. 예: `my-hydra-secret-2024`
|
|
|
|
### 4.5 테스트 실행으로 정상 확인
|
|
|
|
```bash
|
|
pytest -q
|
|
```
|
|
|
|
모든 테스트가 통과하면 준비 완료입니다.
|
|
|
|
---
|
|
|
|
## 5. 테스트 실행
|
|
|
|
```bash
|
|
# 전체 테스트
|
|
pytest -q
|
|
|
|
# 특정 파일만
|
|
pytest tests/test_backtest_runner.py -v
|
|
|
|
# 상세 출력
|
|
pytest -v
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Docker로 전체 파이프라인 실행
|
|
|
|
Docker Desktop이 실행 중인지 확인한 후 아래 명령을 실행합니다.
|
|
|
|
```bash
|
|
docker compose -f docker-compose.lite.yml up --build
|
|
```
|
|
|
|
> 첫 실행 시 이미지 빌드로 수분이 걸립니다.
|
|
|
|
### 실행 확인
|
|
|
|
새 터미널을 열고 헬스체크를 합니다.
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/health
|
|
```
|
|
|
|
아래와 같은 응답이 오면 정상입니다.
|
|
|
|
```json
|
|
{"status": "ok"}
|
|
```
|
|
|
|
### 종료
|
|
|
|
```bash
|
|
# Ctrl+C 로 중지 후
|
|
docker compose -f docker-compose.lite.yml down
|
|
```
|
|
|
|
---
|
|
|
|
## 7. API 사용법
|
|
|
|
모든 API 호출은 `/health`를 제외하고 `X-HYDRA-KEY` 헤더를 포함해야 합니다.
|
|
|
|
```bash
|
|
curl -H "X-HYDRA-KEY: 여기에-API-키" http://127.0.0.1:8000/엔드포인트
|
|
```
|
|
|
|
### 7.1 헬스체크 (인증 불필요)
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8000/health
|
|
```
|
|
|
|
### 7.2 활성 시장 확인
|
|
|
|
```bash
|
|
curl -H "X-HYDRA-KEY: my-hydra-secret-2024" \
|
|
http://127.0.0.1:8000/markets
|
|
```
|
|
|
|
### 7.3 수집 중인 심볼 확인
|
|
|
|
```bash
|
|
curl -H "X-HYDRA-KEY: my-hydra-secret-2024" \
|
|
http://127.0.0.1:8000/data/symbols
|
|
```
|
|
|
|
### 7.4 캔들(OHLCV) 데이터 조회
|
|
|
|
```bash
|
|
curl -G http://127.0.0.1:8000/data/candles \
|
|
-H "X-HYDRA-KEY: my-hydra-secret-2024" \
|
|
--data-urlencode "market=binance" \
|
|
--data-urlencode "symbol=BTC/USDT" \
|
|
--data-urlencode "timeframe=1h" \
|
|
--data-urlencode "limit=100"
|
|
```
|
|
|
|
### 7.5 백테스트 실행
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8000/backtest/run \
|
|
-H "Content-Type: application/json" \
|
|
-H "X-HYDRA-KEY: my-hydra-secret-2024" \
|
|
-d '{
|
|
"market": "binance",
|
|
"symbol": "BTC/USDT",
|
|
"timeframe": "1h",
|
|
"since": 1704067200000,
|
|
"until": 1706745600000,
|
|
"initial_capital": 10000,
|
|
"trade_amount_usd": 100,
|
|
"commission_pct": 0.001
|
|
}'
|
|
```
|
|
|
|
> `since`와 `until`은 Unix timestamp (밀리초) 입니다.
|
|
> 위 예시는 2024년 1월 1일 ~ 2024년 2월 1일 구간입니다.
|
|
|
|
### 7.6 포지션 / 손익 확인
|
|
|
|
```bash
|
|
curl -H "X-HYDRA-KEY: my-hydra-secret-2024" http://127.0.0.1:8000/positions
|
|
curl -H "X-HYDRA-KEY: my-hydra-secret-2024" http://127.0.0.1:8000/pnl
|
|
```
|
|
|
|
### 7.7 Kill Switch (주의: 전 포지션 청산)
|
|
|
|
```bash
|
|
curl -X POST "http://127.0.0.1:8000/killswitch?reason=manual_test" \
|
|
-H "X-HYDRA-KEY: my-hydra-secret-2024"
|
|
```
|
|
|
|
> Kill Switch는 실거래 중 긴급 상황에서만 사용하세요.
|
|
|
|
전체 API 목록은 [docs/API_REFERENCE_KO.md](docs/API_REFERENCE_KO.md)를 참고하세요.
|
|
|
|
---
|
|
|
|
## 8. CLI 사용법
|
|
|
|
```bash
|
|
# 도움말
|
|
python -m hydra.cli.app --help
|
|
|
|
# 초기 설정 마법사
|
|
python -m hydra.cli.app setup
|
|
|
|
# 현재 상태 확인
|
|
python -m hydra.cli.app status
|
|
|
|
# 시장 목록 확인
|
|
python -m hydra.cli.app market list-markets
|
|
|
|
# 시장 활성화 (paper = 모의거래)
|
|
python -m hydra.cli.app market enable binance --mode paper
|
|
|
|
# Kill Switch (긴급 청산)
|
|
python -m hydra.cli.app kill
|
|
```
|
|
|
|
> `trade`, `strategy`, `module` 명령 일부는 현재 개발 예정 상태입니다.
|
|
|
|
---
|
|
|
|
## 9. Docker 프로필 선택
|
|
|
|
| 프로필 | 파일 | 데이터베이스 | 권장 대상 |
|
|
|--------|------|------------|----------|
|
|
| **lite** | `docker-compose.lite.yml` | SQLite | 처음 시작하는 분, 개인 PC |
|
|
| **pro** | `docker-compose.pro.yml` | TimescaleDB + Redis | 중간 규모 수집·분석 |
|
|
| **expert** | `docker-compose.expert.yml` | 고사양 확장 구성 | 대용량 데이터, 고성능 서버 |
|
|
|
|
처음 사용자는 **lite**부터 시작하세요.
|
|
|
|
```bash
|
|
# lite
|
|
docker compose -f docker-compose.lite.yml up --build
|
|
|
|
# pro (DB_PASSWORD 설정 필요)
|
|
docker compose -f docker-compose.pro.yml up --build
|
|
|
|
# expert
|
|
docker compose -f docker-compose.expert.yml up --build
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 자주 발생하는 문제 (FAQ)
|
|
|
|
### Q: `pytest` 실행 시 ModuleNotFoundError가 발생해요
|
|
|
|
가상환경이 활성화되어 있는지 확인하세요.
|
|
|
|
```bash
|
|
# 가상환경 활성화 확인
|
|
# 터미널 앞에 (.venv)가 보여야 함
|
|
|
|
# 다시 설치
|
|
pip install -e .[dev]
|
|
```
|
|
|
|
### Q: Docker 실행 시 Redis 연결 오류가 발생해요
|
|
|
|
Docker Desktop이 실행 중인지 확인하세요. 그 다음 `.env` 파일의 `REDIS_URL`을 확인합니다.
|
|
|
|
Docker Compose 환경에서는 Redis가 컨테이너로 자동 실행되므로 기본값을 유지하세요.
|
|
|
|
```env
|
|
REDIS_URL=redis://redis:6379 # Docker Compose 내부
|
|
REDIS_URL=redis://localhost:6379 # 로컬 직접 실행
|
|
```
|
|
|
|
### Q: API 호출 시 403 오류가 발생해요
|
|
|
|
`X-HYDRA-KEY` 헤더가 `.env`의 `HYDRA_API_KEY`와 일치하는지 확인하세요.
|
|
|
|
```bash
|
|
curl -H "X-HYDRA-KEY: 설정한-키-값" http://127.0.0.1:8000/markets
|
|
```
|
|
|
|
### Q: `HYDRA_API_KEY가 기본값` 경고가 뜨는데 괜찮나요?
|
|
|
|
로컬 테스트 목적이면 무시할 수 있지만, 외부에 서버를 노출할 경우 반드시 변경하세요.
|
|
`.env` 파일에서 `HYDRA_API_KEY=change-me`를 다른 값으로 바꾸면 경고가 사라집니다.
|
|
|
|
### Q: Windows에서 PowerShell 실행 정책 오류가 발생해요
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
|
```
|
|
|
|
### Q: Docker 빌드가 너무 느려요
|
|
|
|
처음 빌드는 수분이 걸립니다. 두 번째 실행부터는 캐시를 사용해 빠릅니다.
|
|
빌드 없이 실행하려면 `--build` 옵션을 제거하세요.
|
|
|
|
```bash
|
|
docker compose -f docker-compose.lite.yml up
|
|
```
|
|
|
|
---
|
|
|
|
## 11. 문서
|
|
|
|
| 문서 | 설명 |
|
|
|------|------|
|
|
| [docs/QUICKSTART_KO.md](docs/QUICKSTART_KO.md) | 10분 빠른 시작 가이드 |
|
|
| [docs/API_REFERENCE_KO.md](docs/API_REFERENCE_KO.md) | 전체 API 엔드포인트 레퍼런스 |
|
|
| [DISCLAIMER.md](DISCLAIMER.md) | 법적 고지 및 책임 한계 |
|
|
|
|
---
|
|
|
|
## 12. 안전 안내
|
|
|
|
- `.env` 파일과 API 키는 절대 Git에 올리지 마세요. (`.gitignore`에 이미 포함되어 있습니다)
|
|
- 실거래 전에는 반드시 paper 모드와 백테스트로 전략을 충분히 검증하세요.
|
|
- 기본적으로 로컬/사설 네트워크에서만 운용하는 것을 권장합니다.
|
|
- 거래소 API 키는 필요한 최소 권한만 부여하세요.
|
|
|
|
---
|
|
|
|
## 13. 라이선스
|
|
|
|
[MIT License](LICENSE)
|