Hydra-Engine/docs/API_REFERENCE_KO.md

HYDRA Engine API 레퍼런스

인증

/health를 제외한 모든 엔드포인트는 아래 헤더를 요구합니다.

X-HYDRA-KEY: <HYDRA_API_KEY>

.env에 설정한 HYDRA_API_KEY 값을 사용합니다.

인증 실패 시 응답:

HTTP 403
{"detail": "Invalid or missing API key. Set X-HYDRA-KEY header."}

---

엔드포인트 목록

1. 헬스체크

GET /health

서버 상태를 확인합니다. 인증 불필요.

curl http://127.0.0.1:8000/health

응답:

{"status": "ok"}

---

2. 시스템

GET /status

서버 프로필, 가동 시간 등 시스템 상태를 조회합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/status

GET /modules

각 모듈(수집기, 지표 엔진 등)의 활성 상태를 조회합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/modules

---

3. 시장 관리

GET /markets

현재 설정된 시장 목록과 활성 상태를 반환합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/markets

응답 예시:

[
  {"market_id": "binance", "active": true, "mode": "paper"},
  {"market_id": "upbit", "active": false, "mode": "paper"}
]

POST /markets/{market_id}/enable

시장을 활성화합니다.

curl -X POST \
  -H "X-HYDRA-KEY: my-key" \
  http://127.0.0.1:8000/markets/binance/enable

POST /markets/{market_id}/disable

시장을 비활성화합니다.

curl -X POST \
  -H "X-HYDRA-KEY: my-key" \
  http://127.0.0.1:8000/markets/binance/disable

---

4. 데이터

GET /data/symbols

수집 중이거나 저장된 시장/심볼/타임프레임 목록을 반환합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/data/symbols

응답 예시:

[
  {"market": "binance", "symbol": "BTC/USDT", "timeframe": "1h"},
  {"market": "binance", "symbol": "ETH/USDT", "timeframe": "1h"}
]

GET /data/candles

OHLCV 캔들 데이터를 조회합니다.

쿼리 파라미터:

파라미터	필수	설명	예시
market	필수	거래소 ID	binance
symbol	필수	심볼	BTC/USDT
timeframe	필수	타임프레임	1h, 4h, 1d
limit	선택	캔들 수 (기본 200, 최대 1000)	100
since	선택	시작 시간 (Unix ms)	1704067200000

curl -G http://127.0.0.1:8000/data/candles \
  -H "X-HYDRA-KEY: my-key" \
  --data-urlencode "market=binance" \
  --data-urlencode "symbol=BTC/USDT" \
  --data-urlencode "timeframe=1h" \
  --data-urlencode "limit=100"

응답 예시:

[
  {
    "timestamp": 1704067200000,
    "open": 42000.0,
    "high": 42500.0,
    "low": 41800.0,
    "close": 42300.0,
    "volume": 1234.56
  }
]

---

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

시그널 히스토리 목록을 반환합니다.

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

현재 보유 포지션 목록을 반환합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/positions

응답 예시:

[
  {
    "symbol": "BTC/USDT",
    "side": "long",
    "size": 0.01,
    "entry_price": 42000.0,
    "unrealized_pnl": 30.0
  }
]

GET /pnl

누적 손익 정보를 반환합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/pnl

POST /pnl/reset-daily

일일 손익을 초기화합니다.

curl -X POST -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/pnl/reset-daily

---

7. 리스크 엔진

GET /risk

현재 리스크 상태(포지션 한도, 사용률 등)를 반환합니다.

curl -H "X-HYDRA-KEY: my-key" http://127.0.0.1:8000/risk

POST /killswitch

경고: 이 엔드포인트는 모든 포지션을 즉시 청산을 시도합니다. 신중하게 사용하세요.

긴급 상황에서 전 포지션 청산을 트리거합니다.

curl -X POST "http://127.0.0.1:8000/killswitch?reason=emergency" \
  -H "X-HYDRA-KEY: my-key"

파라미터:

• reason (선택): 청산 사유 메모 (로그에 기록됨)

---

8. 백테스트

POST /backtest/run

수집된 캔들 데이터를 기반으로 전략을 백테스트합니다.

요청 본문:

{
  "market": "binance",
  "symbol": "BTC/USDT",
  "timeframe": "1h",
  "since": 1704067200000,
  "until": 1706745600000,
  "initial_capital": 10000,
  "trade_amount_usd": 100,
  "commission_pct": 0.001
}

필드	필수	설명
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%)

curl -X POST http://127.0.0.1:8000/backtest/run \
  -H "Content-Type: application/json" \
  -H "X-HYDRA-KEY: my-key" \
  -d '{
    "market": "binance",
    "symbol": "BTC/USDT",
    "timeframe": "1h",
    "since": 1704067200000,
    "until": 1706745600000,
    "initial_capital": 10000,
    "trade_amount_usd": 100,
    "commission_pct": 0.001
  }'

응답 예시:

{
  "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": [...]
}

Unix timestamp 변환 팁:

• 2024-01-01 00:00:00 UTC → 1704067200000
• 2024-02-01 00:00:00 UTC → 1706745600000

---

9. 보조 데이터

GET /orderbook

최근 수집된 오더북 스냅샷을 반환합니다.

GET /events

수집된 크립토 이벤트 일정(상장, 하드포크 등)을 반환합니다.

GET /sentiment

감성 분석 점수를 반환합니다. (-1.0 = 매우 부정, +1.0 = 매우 긍정)

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 모드) 이후에만 진행하세요.