airkjw/Hydra-Engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: 인증 미들웨어 활성화, lifespan 예외처리, Docker 네트워크 바인딩 수정 및 문서 전면 개선

Browse Source 
- 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>
This commit is contained in:
sinmb79
2026-03-30 16:02:04 +09:00
parent 92a692b63c
commit b4c775563c
6 changed files with 785 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Dockerfile
View File

@@ -18,4 +18,4 @@ RUN useradd -m hydra && chown -R hydra:hydra /app
USER hydra USER hydra
EXPOSE 8000 EXPOSE 8000
CMD ["uvicorn", "hydra.main:app", "--host", "127.0.0.1", "--port", "8000"] CMD ["uvicorn", "hydra.main:app", "--host", "0.0.0.0", "--port", "8000"]

382
README.md
View File

@@ -1,154 +1,267 @@
# HYDRA Engine # HYDRA Engine
HYDRA Engine은 로컬 우선(Local-first) 철학으로 설계된 자동매매 엔진 프로젝트입니다. HYDRA Engine은 **로컬 우선(Local-first)** 철학으로 설계된 자동매매 엔진입니다.
데이터 수집, 지표 계산, 레짐 분류, 시그널 생성, 보조 데이터 수집, 백테스트, FastAPI API, Typer CLI를 하나의 저장소에서 관리합니다. 데이터 수집 → 지표 계산 → 레짐 분류 → 시그널 생성 → 백테스트 → 실거래까지 하나의 저장소에서 관리합니다.
이 저장소는 "실거래 수익 보장"을 목표로 하지 않습니다. 먼저 안전하게 실행하고, 충분히 검증하고, 필요할 때만 확장하는 것을 목표로 합니다. > **이 프로젝트는 교육·연구·실험용입니다.**
> 실거래 수익을 보장하지 않으며, 사용에 따른 모든 책임은 사용자 본인에게 있습니다.
> 반드시 [DISCLAIMER.md](DISCLAIMER.md)를 먼저 읽으세요.
## 1. 현재 포함된 기능 ---
- FastAPI 기반 제어/API 서버 ## 목차
- Redis 기반 상태 공유
- OHLCV 수집기와 SQLite/TimescaleDB 저장소
- 지표 계산 엔진
- 레짐(Regime) 분류 엔진
- 전략 시그널 엔진
- 오더북 / 이벤트 / 감성 보조 데이터 수집
- 인메모리 백테스트 엔진
- Kill Switch, 주문 큐, 리스크 엔진, 설정 검증
- CLI 도구와 Docker Compose 프로필(lite / pro / expert)
## 2. 이 프로젝트를 어떻게 이해하면 좋은가 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-라이선스)
HYDRA는 한 번에 모든 기능을 다 켜는 프로젝트가 아닙니다. ---
1. 먼저 데이터를 수집합니다. ## 1. 포함된 기능
2. 지표와 레짐, 시그널을 계산합니다.
3. API나 CLI로 상태를 확인합니다.
4. 백테스트로 전략을 검증합니다.
5. 실거래는 마지막 단계에서 매우 조심스럽게 붙입니다.
현재 저장소에는 실거래로 연결되는 기반 코드가 일부 포함되어 있지만, 여러 CLI 명령은 아직 "예정" 상태의 placeholder를 포함합니다. 공개 배포용으로는 안전하게 시험, 학습, 백테스트, 데이터 파이프라인 검증부터 시작하는 것을 권장합니다. | 모듈 | 설명 |
|------|------|
| FastAPI 서버 | REST API로 모든 기능 제어 |
| OHLCV 수집기 | 거래소에서 캔들 데이터 수집, SQLite/TimescaleDB 저장 |
| 지표 계산 엔진 | RSI, MACD, Bollinger Band 등 자동 계산 |
| 레짐 분류 엔진 | 시장 상태(추세/횡보/변동성) 분류 |
| 전략 시그널 엔진 | 매수/매도 시그널 생성 |
| 보조 데이터 수집 | 오더북, 이벤트 일정, 감성 점수 |
| 인메모리 백테스트 | 수집된 데이터로 전략 성과 검증 |
| Kill Switch | 긴급 전 포지션 청산 |
| 주문 큐 | 안전한 주문 처리 파이프라인 |
| 리스크 엔진 | 포지션 및 리스크 관리 |
| CLI 도구 | 터미널에서 모든 기능 제어 |
| Telegram 알림 | 주요 이벤트 실시간 알림 |
## 3. 빠른 시작 ---
가장 쉬운 시작 방법은 아래 두 가지입니다. ## 2. 사용 철학 — 어떻게 접근할 것인가
- 로컬 Python 환경에서 테스트부터 실행 HYDRA는 **한 번에 모든 기능을 켜는 프로젝트가 아닙니다.**
- Docker Compose Lite 프로필로 전체 파이프라인 기동
### 3.1 요구 사항 ```
1단계: 테스트 실행으로 코드 정상 확인
2단계: 데이터 수집 (거래소 API 키 없어도 공개 데이터 가능)
3단계: 지표·레짐·시그널 계산 확인
4단계: API/CLI로 상태 관찰
5단계: 백테스트로 전략 검증
6단계: (충분한 검증 후) 실거래 연결
```
- Python 3.11 이상 처음 사용하는 분은 **1~4단계**부터 시작하는 것을 강력히 권장합니다.
- Docker / Docker Compose
- Redis
- Git
### 3.2 저장소 준비 ---
## 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 ```bash
git clone https://github.com/sinmb79/Hydra-Engine.git git clone https://github.com/sinmb79/Hydra-Engine.git
cd Hydra-Engine cd Hydra-Engine
```
### 4.2 Python 가상환경 생성 및 활성화
가상환경은 이 프로젝트 전용 Python 환경을 만들어 다른 프로젝트와 충돌하지 않게 합니다.
```bash
python -m venv .venv python -m venv .venv
``` ```
Windows PowerShell: **Windows (PowerShell):**
```powershell ```powershell
.venv\Scripts\Activate.ps1 .venv\Scripts\Activate.ps1
``` ```
macOS / Linux: > PowerShell에서 실행 오류가 발생하면 먼저 아래 명령을 실행하세요:
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```
**macOS / Linux:**
```bash ```bash
source .venv/bin/activate source .venv/bin/activate
``` ```
패키지 설치: 활성화되면 터미널 앞에 `(.venv)`가 표시됩니다.
### 4.3 패키지 설치
```bash ```bash
pip install -e .[dev] pip install -e .[dev]
``` ```
### 3.3 환경 변수 설정 > 처음 설치 시 수분이 걸릴 수 있습니다.
`.env.example`를 복사해서 `.env`를 만드세요. ### 4.4 환경 변수 설정
`.env.example` 파일을 복사해 `.env`를 만듭니다.
**macOS / Linux:**
```bash ```bash
cp .env.example .env cp .env.example .env
``` ```
Windows PowerShell: **Windows (PowerShell):**
```powershell ```powershell
Copy-Item .env.example .env Copy-Item .env.example .env
``` ```
최소 필수 항목: 생성된 `.env` 파일을 텍스트 에디터로 열어 아래 항목을 수정합니다.
```env ```env
HYDRA_API_KEY=change-me-to-a-random-secret # 반드시 변경하세요 — 이 값이 API 접근 비밀번호입니다
HYDRA_API_KEY=여기에-랜덤-문자열-입력
# 프로필: lite(입문) / pro(중급) / expert(고급)
HYDRA_PROFILE=lite HYDRA_PROFILE=lite
# Redis 주소 (Docker 사용 시 기본값 유지)
REDIS_URL=redis://localhost:6379 REDIS_URL=redis://localhost:6379
``` ```
`pro` 또는 `expert` 프로필에서는 `DB_PASSWORD`가 필요합니다. > **HYDRA_API_KEY**는 API 호출 시 인증에 사용됩니다.
> 아무 문자열이나 사용할 수 있습니다. 예: `my-hydra-secret-2024`
## 4. 가장 먼저 해볼 것 ### 4.5 테스트 실행으로 정상 확인
### 4.1 테스트 실행
```bash ```bash
pytest -q pytest -q
``` ```
정상이라면 전체 테스트가 통과해야 합니다. 모든 테스트가 통과하면 준비 완료입니다.
### 4.2 Lite 프로필로 실행 ---
## 5. 테스트 실행
```bash
# 전체 테스트
pytest -q
# 특정 파일만
pytest tests/test_backtest_runner.py -v
# 상세 출력
pytest -v
```
---
## 6. Docker로 전체 파이프라인 실행
Docker Desktop이 실행 중인지 확인한 후 아래 명령을 실행합니다.
```bash ```bash
docker compose -f docker-compose.lite.yml up --build docker compose -f docker-compose.lite.yml up --build
``` ```
서버 헬스체크: > 첫 실행 시 이미지 빌드로 수분이 걸립니다.
### 실행 확인
새 터미널을 열고 헬스체크를 합니다.
```bash ```bash
curl http://127.0.0.1:8000/health curl http://127.0.0.1:8000/health
``` ```
## 5. 주요 사용 흐름 아래와 같은 응답이 오면 정상입니다.
### 5.1 활성 시장 확인 ```json
{"status": "ok"}
```
### 종료
```bash ```bash
curl -H "X-HYDRA-KEY: change-me-to-a-random-secret" \ # 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 http://127.0.0.1:8000/markets
``` ```
### 5.2 수집 중인 심볼 확인 ### 7.3 수집 중인 심볼 확인
```bash ```bash
curl -H "X-HYDRA-KEY: change-me-to-a-random-secret" \ curl -H "X-HYDRA-KEY: my-hydra-secret-2024" \
http://127.0.0.1:8000/data/symbols http://127.0.0.1:8000/data/symbols
``` ```
### 5.3 캔들 조회 ### 7.4 캔들(OHLCV) 데이터 조회
```bash ```bash
curl -G http://127.0.0.1:8000/data/candles \ curl -G http://127.0.0.1:8000/data/candles \
-H "X-HYDRA-KEY: change-me-to-a-random-secret" \ -H "X-HYDRA-KEY: my-hydra-secret-2024" \
--data-urlencode "market=binance" \ --data-urlencode "market=binance" \
--data-urlencode "symbol=BTC/USDT" \ --data-urlencode "symbol=BTC/USDT" \
--data-urlencode "timeframe=1h" \ --data-urlencode "timeframe=1h" \
--data-urlencode "limit=200" --data-urlencode "limit=100"
``` ```
### 5.4 백테스트 실행 ### 7.5 백테스트 실행
```bash ```bash
curl -X POST http://127.0.0.1:8000/backtest/run \ curl -X POST http://127.0.0.1:8000/backtest/run \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "X-HYDRA-KEY: change-me-to-a-random-secret" \ -H "X-HYDRA-KEY: my-hydra-secret-2024" \
-d '{ -d '{
"market": "binance", "market": "binance",
"symbol": "BTC/USDT", "symbol": "BTC/USDT",
@@ -161,63 +274,152 @@ curl -X POST http://127.0.0.1:8000/backtest/run \
}' }'
``` ```
### 5.5 Kill Switch > `since`와 `until`은 Unix timestamp (밀리초) 입니다.
> 위 예시는 2024년 1월 1일 ~ 2024년 2월 1일 구간입니다.
Kill Switch는 전 포지션 청산을 시도하는 고위험 명령입니다. 테스트 목적이 아니라면 함부로 사용하지 마세요. ### 7.6 포지션 / 손익 확인
CLI:
```bash ```bash
python -m hydra.cli.app kill 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
``` ```
API: ### 7.7 Kill Switch (주의: 전 포지션 청산)
```bash ```bash
curl -X POST "http://127.0.0.1:8000/killswitch?reason=manual_test" \ curl -X POST "http://127.0.0.1:8000/killswitch?reason=manual_test" \
-H "X-HYDRA-KEY: change-me-to-a-random-secret" -H "X-HYDRA-KEY: my-hydra-secret-2024"
``` ```
## 6. CLI 예시 > Kill Switch는 실거래 중 긴급 상황에서만 사용하세요.
전체 API 목록은 [docs/API_REFERENCE_KO.md](docs/API_REFERENCE_KO.md)를 참고하세요.
---
## 8. CLI 사용법
```bash ```bash
# 도움말
python -m hydra.cli.app --help python -m hydra.cli.app --help
# 초기 설정 마법사
python -m hydra.cli.app setup python -m hydra.cli.app setup
# 현재 상태 확인
python -m hydra.cli.app status python -m hydra.cli.app status
# 시장 목록 확인
python -m hydra.cli.app market list-markets python -m hydra.cli.app market list-markets
# 시장 활성화 (paper = 모의거래)
python -m hydra.cli.app market enable binance --mode paper python -m hydra.cli.app market enable binance --mode paper
python -m hydra.cli.app trade crypto binance BTC/USDT buy 0.01
# Kill Switch (긴급 청산)
python -m hydra.cli.app kill
``` ```
주의: > `trade`, `strategy`, `module` 명령 일부는 현재 개발 예정 상태입니다.
- `trade`, `strategy`, `module` 일부 명령은 아직 placeholder 메시지를 출력합니다. ---
- 공개 버전 기준으로는 데이터 수집, 관찰, 백테스트 중심으로 사용하는 것이 안전합니다.
## 7. Docker 프로필 ## 9. Docker 프로필 선택
- `docker-compose.lite.yml` | 프로필 | 파일 | 데이터베이스 | 권장 대상 |
- SQLite 사용 |--------|------|------------|----------|
- 개인 PC / 테스트 / 입문용 | **lite** | `docker-compose.lite.yml` | SQLite | 처음 시작하는 분, 개인 PC |
- `docker-compose.pro.yml` | **pro** | `docker-compose.pro.yml` | TimescaleDB + Redis | 중간 규모 수집·분석 |
- TimescaleDB + Redis | **expert** | `docker-compose.expert.yml` | 고사양 확장 구성 | 대용량 데이터, 고성능 서버 |
- 중간 규모 수집/분석용
- `docker-compose.expert.yml`
- 고사양 장비 / 확장 시나리오용
## 8. 문서 처음 사용자는 **lite**부터 시작하세요.
- 자세한 시작 가이드: [docs/QUICKSTART_KO.md](docs/QUICKSTART_KO.md) ```bash
- API 레퍼런스: [docs/API_REFERENCE_KO.md](docs/API_REFERENCE_KO.md) # lite
- 법적 고지: [DISCLAIMER.md](DISCLAIMER.md) docker compose -f docker-compose.lite.yml up --build
## 9. 안전 안내 # pro (DB_PASSWORD 설정 필요)
docker compose -f docker-compose.pro.yml up --build
- 이 저장소는 교육, 연구, 실험용입니다. # expert
- 실거래 전에는 반드시 paper 모드와 백테스트로 먼저 검증하세요. docker compose -f docker-compose.expert.yml up --build
- `.env`, API 키, 계정 정보는 절대 Git에 올리지 마세요. ```
---
## 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 키는 필요한 최소 권한만 부여하세요.
## 10. 라이선스 ---
이 저장소는 [MIT License](LICENSE)를 따릅니다. ## 13. 라이선스
[MIT License](LICENSE)

386
docs/API_REFERENCE_KO.md
View File

@@ -1,113 +1,271 @@
# HYDRA Engine API 레퍼런스 # HYDRA Engine API 레퍼런스
모든 보호된 엔드포인트는 아래 헤더를 요구합니다. ## 인증
`/health`를 제외한 모든 엔드포인트는 아래 헤더를 요구합니다.
```http ```http
X-HYDRA-KEY: <HYDRA_API_KEY> X-HYDRA-KEY: <HYDRA_API_KEY>
``` ```
## 1. 헬스체크 `.env`에 설정한 `HYDRA_API_KEY` 값을 사용합니다.
### `GET /health` **인증 실패 시 응답:**
```json
HTTP 403
{"detail": "Invalid or missing API key. Set X-HYDRA-KEY header."}
```
인증 없이 호출할 수 있습니다. ---
## 엔드포인트 목록
### 1. 헬스체크
#### `GET /health`
서버 상태를 확인합니다. **인증 불필요.**
```bash ```bash
curl http://127.0.0.1:8000/health curl http://127.0.0.1:8000/health
``` ```
## 2. 시스템 **응답:**
```json
{"status": "ok"}
```
### `GET /status` ---
서버 프로필과 상태를 조회합니다. ### 2. 시스템
### `GET /modules` #### `GET /status`
활성 모듈 상태를 조회합니다. 서버 프로필, 가동 시간 등 시스템 상태를 조회합니다.
## 3. 시장 관리 ```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/status
```
### `GET /markets` #### `GET /modules`
현재 활성 시장 목록을 반환합니다. 각 모듈(수집기, 지표 엔진 등)의 활성 상태를 조회합니다.
### `POST /markets/{market_id}/enable` ```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/modules
```
시장 활성화 ---
예시: ### 3. 시장 관리
#### `GET /markets`
현재 설정된 시장 목록과 활성 상태를 반환합니다.
```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/markets
```
**응답 예시:**
```json
[
{"market_id": "binance", "active": true, "mode": "paper"},
{"market_id": "upbit", "active": false, "mode": "paper"}
]
```
#### `POST /markets/{market_id}/enable`
시장을 활성화합니다.
```bash ```bash
curl -X POST \ curl -X POST \
-H "X-HYDRA-KEY: my-local-demo-key" \ -H "X-HYDRA-KEY: my-key" \
http://127.0.0.1:8000/markets/binance/enable http://127.0.0.1:8000/markets/binance/enable
``` ```
### `POST /markets/{market_id}/disable` #### `POST /markets/{market_id}/disable`
시장 비활성화 시장을 비활성화합니다.
## 4. 데이터 ```bash
curl -X POST \
-H "X-HYDRA-KEY: my-key" \
http://127.0.0.1:8000/markets/binance/disable
```
### `GET /data/symbols` ---
### 4. 데이터
#### `GET /data/symbols`
수집 중이거나 저장된 시장/심볼/타임프레임 목록을 반환합니다. 수집 중이거나 저장된 시장/심볼/타임프레임 목록을 반환합니다.
### `GET /data/candles` ```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/data/symbols
```
쿼리 파라미터: **응답 예시:**
```json
[
{"market": "binance", "symbol": "BTC/USDT", "timeframe": "1h"},
{"market": "binance", "symbol": "ETH/USDT", "timeframe": "1h"}
]
```
- `market` #### `GET /data/candles`
- `symbol`
- `timeframe`
- `limit` (기본 200, 최대 1000)
- `since` (선택)
예시: OHLCV 캔들 데이터를 조회합니다.
**쿼리 파라미터:**
| 파라미터 | 필수 | 설명 | 예시 |
|---------|------|------|------|
| `market` | 필수 | 거래소 ID | `binance` |
| `symbol` | 필수 | 심볼 | `BTC/USDT` |
| `timeframe` | 필수 | 타임프레임 | `1h`, `4h`, `1d` |
| `limit` | 선택 | 캔들 수 (기본 200, 최대 1000) | `100` |
| `since` | 선택 | 시작 시간 (Unix ms) | `1704067200000` |
```bash ```bash
curl -G http://127.0.0.1:8000/data/candles \ curl -G http://127.0.0.1:8000/data/candles \
-H "X-HYDRA-KEY: my-local-demo-key" \ -H "X-HYDRA-KEY: my-key" \
--data-urlencode "market=binance" \ --data-urlencode "market=binance" \
--data-urlencode "symbol=BTC/USDT" \ --data-urlencode "symbol=BTC/USDT" \
--data-urlencode "timeframe=1h" \ --data-urlencode "timeframe=1h" \
--data-urlencode "limit=100" --data-urlencode "limit=100"
``` ```
## 5. 지표 / 레짐 / 시그널 **응답 예시:**
```json
### `GET /indicators` [
### `GET /indicators/list` {
### `GET /regime` "timestamp": 1704067200000,
### `GET /regime/list` "open": 42000.0,
### `GET /signal` "high": 42500.0,
### `GET /signal/list` "low": 41800.0,
"close": 42300.0,
이 엔드포인트들은 최신 계산 결과를 확인할 때 사용합니다. "volume": 1234.56
}
## 6. 포지션 / 손익 / 리스크 ]
### `GET /positions`
### `GET /pnl`
### `POST /pnl/reset-daily`
### `GET /risk`
### `POST /killswitch`
`POST /killswitch`는 매우 위험한 명령이므로 테스트 목적이 아니라면 호출하지 마세요.
예시:
```bash
curl -X POST "http://127.0.0.1:8000/killswitch?reason=manual_test" \
-H "X-HYDRA-KEY: my-local-demo-key"
``` ```
## 7. 백테스트 ---
### `POST /backtest/run` ### 5. 지표 / 레짐 / 시그널
요청 본문: #### `GET /indicators`
가장 최근 계산된 지표 값을 반환합니다.
#### `GET /indicators/list`
계산 가능한 지표 목록을 반환합니다.
#### `GET /regime`
현재 시장 레짐(상태) 분류 결과를 반환합니다.
> 레짐 예시: `trending_up`, `trending_down`, `sideways`, `high_volatility`
#### `GET /regime/list`
레짐 히스토리 목록을 반환합니다.
#### `GET /signal`
가장 최근 전략 시그널을 반환합니다.
> 시그널 예시: `{"signal": "buy", "confidence": 0.72}`
#### `GET /signal/list`
시그널 히스토리 목록을 반환합니다.
```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/indicators
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/regime
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/signal
```
---
### 6. 포지션 / 손익
#### `GET /positions`
현재 보유 포지션 목록을 반환합니다.
```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/positions
```
**응답 예시:**
```json
[
{
"symbol": "BTC/USDT",
"side": "long",
"size": 0.01,
"entry_price": 42000.0,
"unrealized_pnl": 30.0
}
]
```
#### `GET /pnl`
누적 손익 정보를 반환합니다.
```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/pnl
```
#### `POST /pnl/reset-daily`
일일 손익을 초기화합니다.
```bash
curl -X POST -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/pnl/reset-daily
```
---
### 7. 리스크 엔진
#### `GET /risk`
현재 리스크 상태(포지션 한도, 사용률 등)를 반환합니다.
```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/risk
```
#### `POST /killswitch`
> **경고: 이 엔드포인트는 모든 포지션을 즉시 청산을 시도합니다. 신중하게 사용하세요.**
긴급 상황에서 전 포지션 청산을 트리거합니다.
```bash
curl -X POST "http://127.0.0.1:8000/killswitch?reason=emergency" \
-H "X-HYDRA-KEY: my-key"
```
**파라미터:**
- `reason` (선택): 청산 사유 메모 (로그에 기록됨)
---
### 8. 백테스트
#### `POST /backtest/run`
수집된 캔들 데이터를 기반으로 전략을 백테스트합니다.
**요청 본문:**
```json ```json
{ {
@@ -122,33 +280,103 @@ curl -X POST "http://127.0.0.1:8000/killswitch?reason=manual_test" \
} }
``` ```
응답에는 아래 항목이 포함됩니다. | 필드 | 필수 | 설명 |
|------|------|------|
| `market` | 필수 | 거래소 ID |
| `symbol` | 필수 | 심볼 |
| `timeframe` | 필수 | 타임프레임 |
| `since` | 필수 | 시작 시간 (Unix ms) |
| `until` | 필수 | 종료 시간 (Unix ms) |
| `initial_capital` | 선택 | 초기 자본 (기본 10000 USD) |
| `trade_amount_usd` | 선택 | 1회 거래 금액 (기본 100 USD) |
| `commission_pct` | 선택 | 수수료율 (기본 0.001 = 0.1%) |
- 시장 / 심볼 / 타임프레임 ```bash
- 초기 자본 / 최종 자본 curl -X POST http://127.0.0.1:8000/backtest/run \
- 체결 트레이드 목록 -H "Content-Type: application/json" \
- equity curve -H "X-HYDRA-KEY: my-key" \
- 성과 지표(`total_return_pct`, `total_trades`, `win_rate`, `max_drawdown_pct`, `sharpe_ratio`, `avg_pnl_usd`) -d '{
"market": "binance",
"symbol": "BTC/USDT",
"timeframe": "1h",
"since": 1704067200000,
"until": 1706745600000,
"initial_capital": 10000,
"trade_amount_usd": 100,
"commission_pct": 0.001
}'
```
## 8. 보조 데이터 **응답 예시:**
```json
{
"market": "binance",
"symbol": "BTC/USDT",
"timeframe": "1h",
"initial_capital": 10000,
"final_capital": 10850.0,
"total_return_pct": 8.5,
"total_trades": 24,
"win_rate": 0.583,
"max_drawdown_pct": -4.2,
"sharpe_ratio": 1.35,
"avg_pnl_usd": 35.4,
"trades": [...],
"equity_curve": [...]
}
```
### `GET /orderbook` > **Unix timestamp 변환 팁:**
### `GET /events` > - 2024-01-01 00:00:00 UTC → `1704067200000`
### `GET /sentiment` > - 2024-02-01 00:00:00 UTC → `1706745600000`
각 엔드포인트는 최근 오더북, 이벤트 일정, 감성 점수를 조회하는 데 사용합니다. ---
## 9. 인증 실패 시 ### 9. 보조 데이터
- 잘못된 API 키: `403 Invalid API key` #### `GET /orderbook`
- 내부 초기화 전 호출: `503 Store not initialized` 등
## 10. 권장 호출 순서 최근 수집된 오더북 스냅샷을 반환합니다.
1. `/health` #### `GET /events`
2. `/markets`
3. `/data/symbols`
4. `/data/candles`
5. `/backtest/run`
실거래 관련 동작은 충분한 검증 이후에만 진행하세요. 수집된 크립토 이벤트 일정(상장, 하드포크 등)을 반환합니다.
#### `GET /sentiment`
감성 분석 점수를 반환합니다. (-1.0 = 매우 부정, +1.0 = 매우 긍정)
```bash
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/orderbook
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/events
curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/sentiment
```
---
## 주요 HTTP 오류 코드
| 코드 | 의미 | 원인 |
|------|------|------|
| `403` | 인증 실패 | API 키 누락 또는 불일치 |
| `503` | 서비스 초기화 중 | 서버 기동 직후, 잠시 후 재시도 |
| `422` | 요청 형식 오류 | 필수 파라미터 누락 또는 타입 오류 |
| `500` | 서버 내부 오류 | 로그 확인 필요 |
---
## 권장 호출 순서
처음 사용할 때는 아래 순서로 호출해 각 단계가 정상인지 확인합니다.
```
1. GET /health → 서버 정상 확인
2. GET /markets → 시장 설정 확인
3. GET /data/symbols → 수집 데이터 확인
4. GET /data/candles → 캔들 데이터 조회
5. POST /backtest/run → 백테스트 실행
6. GET /positions → 포지션 확인
7. GET /pnl → 손익 확인
```
실거래 관련 동작은 충분한 검증(백테스트, paper 모드) 이후에만 진행하세요.

164
docs/QUICKSTART_KO.md
View File

@@ -1,116 +1,190 @@
# HYDRA Engine 빠른 시작 가이드 # HYDRA Engine 빠른 시작 가이드
이 문서는 "처음 받은 사람이 10분 안에 테스트와 기본 실행까지 해보는 것"을 목표로 합니다. **목표:** 이 문서를 따라하면 10~15분 안에 테스트 통과 및 서버 기동까지 완료할 수 있습니다.
## 1. 준비물 ---
- Python 3.11 이상 ## 1단계: 저장소 다운로드
- Git
- Docker / Docker Compose
## 2. 설치
```bash ```bash
git clone https://github.com/sinmb79/Hydra-Engine.git git clone https://github.com/sinmb79/Hydra-Engine.git
cd Hydra-Engine cd Hydra-Engine
```
---
## 2단계: Python 가상환경 설정
```bash
python -m venv .venv python -m venv .venv
``` ```
Windows PowerShell: **Windows (PowerShell):**
```powershell ```powershell
.venv\Scripts\Activate.ps1 .venv\Scripts\Activate.ps1
``` ```
패키지 설치: **macOS / Linux:**
```bash
source .venv/bin/activate
```
터미널 앞에 `(.venv)` 가 표시되면 활성화 성공입니다.
```bash ```bash
pip install -e .[dev] pip install -e .[dev]
``` ```
## 3. 환경 변수 ---
## 3단계: 환경 변수 설정
**macOS / Linux:**
```bash ```bash
cp .env.example .env cp .env.example .env
``` ```
최소 예시: **Windows (PowerShell):**
```powershell
Copy-Item .env.example .env
```
`.env` 파일을 열고 `HYDRA_API_KEY` 를 변경합니다:
```env ```env
HYDRA_API_KEY=my-local-demo-key HYDRA_API_KEY=my-secret-key-2024
HYDRA_PROFILE=lite HYDRA_PROFILE=lite
REDIS_URL=redis://localhost:6379 REDIS_URL=redis://localhost:6379
``` ```
## 4. 정상 동작 확인 > `HYDRA_API_KEY` 는 API 호출 시 사용하는 비밀번호입니다. 아무 문자열이나 가능합니다.
---
## 4단계: 테스트 실행
```bash ```bash
pytest -q pytest -q
``` ```
테스트가 모두 통과하면 기본 코드 상태는 정상입니다. 전체 테스트가 통과하면 코드 상태가 정상입니다.
## 5. Lite 프로필 실행 실패하는 테스트가 있으면:
- 가상환경이 활성화되어 있는지 확인
- `pip install -e .[dev]` 를 다시 실행
---
## 5단계: Docker로 서버 실행
Docker Desktop이 실행 중인지 먼저 확인합니다.
```bash ```bash
docker compose -f docker-compose.lite.yml up --build docker compose -f docker-compose.lite.yml up --build
``` ```
다른 터미널에서 헬스체크: 새 터미널 창을 열고 헬스체크:
```bash ```bash
curl http://127.0.0.1:8000/health curl http://127.0.0.1:8000/health
``` ```
## 6. 필수 API 예제 ```json
{"status": "ok"}
### 6.1 활성 시장 확인
```bash
curl -H "X-HYDRA-KEY: my-local-demo-key" http://127.0.0.1:8000/markets
``` ```
### 6.2 저장된 심볼 목록 확인 이 응답이 오면 서버가 정상 실행 중입니다.
---
## 6단계: 기본 API 호출 테스트
이후 모든 API 호출에는 `X-HYDRA-KEY` 헤더를 붙입니다.
### 시장 확인
```bash ```bash
curl -H "X-HYDRA-KEY: my-local-demo-key" http://127.0.0.1:8000/data/symbols curl -H "X-HYDRA-KEY: my-secret-key-2024" \
http://127.0.0.1:8000/markets
``` ```
### 6.3 백테스트 실행 ### 저장된 심볼 목록
```bash
curl -H "X-HYDRA-KEY: my-secret-key-2024" \
http://127.0.0.1:8000/data/symbols
```
### 캔들 데이터 조회
```bash
curl -G http://127.0.0.1:8000/data/candles \
-H "X-HYDRA-KEY: my-secret-key-2024" \
--data-urlencode "market=binance" \
--data-urlencode "symbol=BTC/USDT" \
--data-urlencode "timeframe=1h" \
--data-urlencode "limit=50"
```
### 백테스트 실행
```bash ```bash
curl -X POST http://127.0.0.1:8000/backtest/run \ curl -X POST http://127.0.0.1:8000/backtest/run \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "X-HYDRA-KEY: my-local-demo-key" \ -H "X-HYDRA-KEY: my-secret-key-2024" \
-d '{ -d '{
"market": "binance", "market": "binance",
"symbol": "BTC/USDT", "symbol": "BTC/USDT",
"timeframe": "1h", "timeframe": "1h",
"since": 1704067200000, "since": 1704067200000,
"until": 1706745600000 "until": 1706745600000,
"initial_capital": 10000,
"trade_amount_usd": 100,
"commission_pct": 0.001
}' }'
``` ```
## 7. CLI 예제 ---
```bash ## 7단계: 권장 사용 순서
python -m hydra.cli.app status
python -m hydra.cli.app market list-markets ```
python -m hydra.cli.app market enable binance --mode paper 테스트 통과 확인
python -m hydra.cli.app kill ↓
시장 설정 확인 (GET /markets)
↓
데이터 수집 상태 확인 (GET /data/symbols)
↓
캔들 데이터 조회 (GET /data/candles)
↓
백테스트 실행 (POST /backtest/run)
↓
전략 성과 분석
↓
(충분한 검증 후) 실거래 연결
``` ```
## 8. 추천 사용 순서 ---
1. 테스트 통과 확인 ## CLI 빠른 참조
2. Lite 프로필 실행
3. 시장 설정 확인
4. 데이터 조회
5. 백테스트 실행
6. 전략/실거래 확장 여부 판단
## 9. 주의사항 ```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 # 시장 목록
python -m hydra.cli.app market enable binance --mode paper # 모의거래 활성화
```
- 실거래 키를 넣기 전에 먼저 paper 모드로 확인하세요. ---
- API 키, 계정번호, 개인 설정은 `.env` 또는 로컬 전용 파일에만 저장하세요.
- FastAPI Swagger UI는 기본 비활성화 상태입니다. API 사용법은 `docs/API_REFERENCE_KO.md`를 참고하세요. ## 문제가 생겼을 때
| 증상 | 확인할 것 |
|------|----------|
| `ModuleNotFoundError` | 가상환경 활성화 여부, `pip install -e .[dev]` 재실행 |
| `403 Invalid API key` | `.env`의 `HYDRA_API_KEY`와 헤더 값 일치 여부 |
| Redis 연결 오류 | Docker Desktop 실행 여부, `REDIS_URL` 설정 |
| 포트 8000 이미 사용 중 | 다른 프로세스 확인 후 종료 |
더 자세한 내용은 [README.md](../README.md) 의 FAQ 섹션을 참고하세요.

13
hydra/config/settings.py
View File

@@ -1,4 +1,6 @@
import warnings
from functools import lru_cache from functools import lru_cache
from pydantic import field_validator
from pydantic_settings import BaseSettings from pydantic_settings import BaseSettings
@@ -13,6 +15,17 @@ class Settings(BaseSettings):
model_config = {"env_file": ".env", "env_file_encoding": "utf-8"} model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
@field_validator("hydra_api_key")
@classmethod
def api_key_must_not_be_default(cls, v: str) -> str:
if v == "change-me":
warnings.warn(
"[HYDRA] HYDRA_API_KEY가 기본값 'change-me'로 설정되어 있습니다. "
".env 파일에서 안전한 값으로 변경하세요.",
stacklevel=2,
)
return v
@lru_cache @lru_cache
def get_settings() -> Settings: def get_settings() -> Settings:

14
hydra/main.py
View File

@@ -48,6 +48,8 @@ async def lifespan(app: FastAPI):
configure_logging(settings.log_level) configure_logging(settings.log_level)
logger.info("hydra_starting", profile=settings.hydra_profile) logger.info("hydra_starting", profile=settings.hydra_profile)
ohlcv_store = None
try:
r = redis_lib.Redis.from_url(settings.redis_url, decode_responses=True) r = redis_lib.Redis.from_url(settings.redis_url, decode_responses=True)
set_redis(r) set_redis(r)
@@ -90,10 +92,15 @@ async def lifespan(app: FastAPI):
set_store_for_backtest(ohlcv_store) set_store_for_backtest(ohlcv_store)
logger.info("hydra_started") logger.info("hydra_started")
except Exception as exc:
logger.error("hydra_startup_failed", error=str(exc))
raise
try: try:
yield yield
finally: finally:
logger.info("hydra_stopping") logger.info("hydra_stopping")
if ohlcv_store is not None:
await ohlcv_store.close() await ohlcv_store.close()
@@ -104,6 +111,13 @@ def create_app() -> FastAPI:
async def auth_guard(request: Request, call_next): async def auth_guard(request: Request, call_next):
if request.url.path == "/health": if request.url.path == "/health":
return await call_next(request) return await call_next(request)
from fastapi.responses import JSONResponse
api_key = request.headers.get("X-HYDRA-KEY", "")
if not api_key or api_key != get_settings().hydra_api_key:
return JSONResponse(
status_code=403,
content={"detail": "Invalid or missing API key. Set X-HYDRA-KEY header."},
)
return await call_next(request) return await call_next(request)
app.include_router(health.router) app.include_router(health.router)