Initial public release
This commit is contained in:
sinmb79
@@ -0,0 +1,154 @@
|
||||
# HYDRA Engine API 레퍼런스
|
||||
|
||||
모든 보호된 엔드포인트는 아래 헤더를 요구합니다.
|
||||
|
||||
```http
|
||||
X-HYDRA-KEY: <HYDRA_API_KEY>
|
||||
```
|
||||
|
||||
## 1. 헬스체크
|
||||
|
||||
### `GET /health`
|
||||
|
||||
인증 없이 호출할 수 있습니다.
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/health
|
||||
```
|
||||
|
||||
## 2. 시스템
|
||||
|
||||
### `GET /status`
|
||||
|
||||
서버 프로필과 상태를 조회합니다.
|
||||
|
||||
### `GET /modules`
|
||||
|
||||
활성 모듈 상태를 조회합니다.
|
||||
|
||||
## 3. 시장 관리
|
||||
|
||||
### `GET /markets`
|
||||
|
||||
현재 활성 시장 목록을 반환합니다.
|
||||
|
||||
### `POST /markets/{market_id}/enable`
|
||||
|
||||
시장 활성화
|
||||
|
||||
예시:
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "X-HYDRA-KEY: my-local-demo-key" \
|
||||
http://127.0.0.1:8000/markets/binance/enable
|
||||
```
|
||||
|
||||
### `POST /markets/{market_id}/disable`
|
||||
|
||||
시장 비활성화
|
||||
|
||||
## 4. 데이터
|
||||
|
||||
### `GET /data/symbols`
|
||||
|
||||
수집 중이거나 저장된 시장/심볼/타임프레임 목록을 반환합니다.
|
||||
|
||||
### `GET /data/candles`
|
||||
|
||||
쿼리 파라미터:
|
||||
|
||||
- `market`
|
||||
- `symbol`
|
||||
- `timeframe`
|
||||
- `limit` (기본 200, 최대 1000)
|
||||
- `since` (선택)
|
||||
|
||||
예시:
|
||||
|
||||
```bash
|
||||
curl -G http://127.0.0.1:8000/data/candles \
|
||||
-H "X-HYDRA-KEY: my-local-demo-key" \
|
||||
--data-urlencode "market=binance" \
|
||||
--data-urlencode "symbol=BTC/USDT" \
|
||||
--data-urlencode "timeframe=1h" \
|
||||
--data-urlencode "limit=100"
|
||||
```
|
||||
|
||||
## 5. 지표 / 레짐 / 시그널
|
||||
|
||||
### `GET /indicators`
|
||||
### `GET /indicators/list`
|
||||
### `GET /regime`
|
||||
### `GET /regime/list`
|
||||
### `GET /signal`
|
||||
### `GET /signal/list`
|
||||
|
||||
이 엔드포인트들은 최신 계산 결과를 확인할 때 사용합니다.
|
||||
|
||||
## 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`
|
||||
|
||||
요청 본문:
|
||||
|
||||
```json
|
||||
{
|
||||
"market": "binance",
|
||||
"symbol": "BTC/USDT",
|
||||
"timeframe": "1h",
|
||||
"since": 1704067200000,
|
||||
"until": 1706745600000,
|
||||
"initial_capital": 10000,
|
||||
"trade_amount_usd": 100,
|
||||
"commission_pct": 0.001
|
||||
}
|
||||
```
|
||||
|
||||
응답에는 아래 항목이 포함됩니다.
|
||||
|
||||
- 시장 / 심볼 / 타임프레임
|
||||
- 초기 자본 / 최종 자본
|
||||
- 체결 트레이드 목록
|
||||
- equity curve
|
||||
- 성과 지표(`total_return_pct`, `total_trades`, `win_rate`, `max_drawdown_pct`, `sharpe_ratio`, `avg_pnl_usd`)
|
||||
|
||||
## 8. 보조 데이터
|
||||
|
||||
### `GET /orderbook`
|
||||
### `GET /events`
|
||||
### `GET /sentiment`
|
||||
|
||||
각 엔드포인트는 최근 오더북, 이벤트 일정, 감성 점수를 조회하는 데 사용합니다.
|
||||
|
||||
## 9. 인증 실패 시
|
||||
|
||||
- 잘못된 API 키: `403 Invalid API key`
|
||||
- 내부 초기화 전 호출: `503 Store not initialized` 등
|
||||
|
||||
## 10. 권장 호출 순서
|
||||
|
||||
1. `/health`
|
||||
2. `/markets`
|
||||
3. `/data/symbols`
|
||||
4. `/data/candles`
|
||||
5. `/backtest/run`
|
||||
|
||||
실거래 관련 동작은 충분한 검증 이후에만 진행하세요.
|
||||
@@ -0,0 +1,116 @@
|
||||
# HYDRA Engine 빠른 시작 가이드
|
||||
|
||||
이 문서는 "처음 받은 사람이 10분 안에 테스트와 기본 실행까지 해보는 것"을 목표로 합니다.
|
||||
|
||||
## 1. 준비물
|
||||
|
||||
- Python 3.11 이상
|
||||
- Git
|
||||
- Docker / Docker Compose
|
||||
|
||||
## 2. 설치
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sinmb79/Hydra-Engine.git
|
||||
cd Hydra-Engine
|
||||
python -m venv .venv
|
||||
```
|
||||
|
||||
Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\Activate.ps1
|
||||
```
|
||||
|
||||
패키지 설치:
|
||||
|
||||
```bash
|
||||
pip install -e .[dev]
|
||||
```
|
||||
|
||||
## 3. 환경 변수
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
최소 예시:
|
||||
|
||||
```env
|
||||
HYDRA_API_KEY=my-local-demo-key
|
||||
HYDRA_PROFILE=lite
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
## 4. 정상 동작 확인
|
||||
|
||||
```bash
|
||||
pytest -q
|
||||
```
|
||||
|
||||
테스트가 모두 통과하면 기본 코드 상태는 정상입니다.
|
||||
|
||||
## 5. Lite 프로필 실행
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.lite.yml up --build
|
||||
```
|
||||
|
||||
다른 터미널에서 헬스체크:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/health
|
||||
```
|
||||
|
||||
## 6. 필수 API 예제
|
||||
|
||||
### 6.1 활성 시장 확인
|
||||
|
||||
```bash
|
||||
curl -H "X-HYDRA-KEY: my-local-demo-key" http://127.0.0.1:8000/markets
|
||||
```
|
||||
|
||||
### 6.2 저장된 심볼 목록 확인
|
||||
|
||||
```bash
|
||||
curl -H "X-HYDRA-KEY: my-local-demo-key" http://127.0.0.1:8000/data/symbols
|
||||
```
|
||||
|
||||
### 6.3 백테스트 실행
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/backtest/run \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-HYDRA-KEY: my-local-demo-key" \
|
||||
-d '{
|
||||
"market": "binance",
|
||||
"symbol": "BTC/USDT",
|
||||
"timeframe": "1h",
|
||||
"since": 1704067200000,
|
||||
"until": 1706745600000
|
||||
}'
|
||||
```
|
||||
|
||||
## 7. CLI 예제
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## 8. 추천 사용 순서
|
||||
|
||||
1. 테스트 통과 확인
|
||||
2. Lite 프로필 실행
|
||||
3. 시장 설정 확인
|
||||
4. 데이터 조회
|
||||
5. 백테스트 실행
|
||||
6. 전략/실거래 확장 여부 판단
|
||||
|
||||
## 9. 주의사항
|
||||
|
||||
- 실거래 키를 넣기 전에 먼저 paper 모드로 확인하세요.
|
||||
- API 키, 계정번호, 개인 설정은 `.env` 또는 로컬 전용 파일에만 저장하세요.
|
||||
- FastAPI Swagger UI는 기본 비활성화 상태입니다. API 사용법은 `docs/API_REFERENCE_KO.md`를 참고하세요.
|
||||
Reference in New Issue
Block a user