# KBX v20 — Official Market/Data Provider Adapters

## 목적
KRX OPEN API, OPENDART, KIS를 KBX/Domain에서 직접 호출하지 않고 Provider Adapter 뒤에 격리한다. 공식 문서에서 확인되지 않은 URL·호출한도·오류코드는 계약에 추정하여 넣지 않는다.

## KRX
- 이용 순서: 인증키 신청 → API 서비스 탐색 → 개별 서비스 활용 신청 → 승인 후 이용.
- 인증키는 Request Header의 `AUTH_KEY`로 전달한다.
- 개별 데이터 서비스 URL/메서드는 승인된 KRX 서비스 명세를 운영 설정으로 등록한다. v20 저장소는 확인되지 않은 공통 URL을 만들지 않는다.
- 숫자형 공통 호출한도는 이번 공식 자료에서 확인되지 않아 `null`로 유지한다.

## OPENDART
- Base: `https://opendart.fss.or.kr/api/`
- 인증: query `crtfc_key`, 40자리.
- Reference operations: `list.json`, `company.json`, `corpCode.xml`.
- 응답 `status`: 000 정상, 013 데이터 없음, 020 요청 제한, 800 점검, 900 정의되지 않은 오류 등.
- 020은 공식 가이드에서 일반적으로 20,000건 이상의 요청에서 발생할 수 있다고 설명하지만 서비스별 제한이 다를 수 있으므로 KBX가 20,000을 보편적 quota로 고정하지 않는다.

## KIS
- REST 실전: `https://openapi.koreainvestment.com:9443`
- REST 모의: `https://openapivts.koreainvestment.com:29443`
- OAuth token: `POST /oauth2/tokenP`, `grant_type=client_credentials`, appkey/appsecret.
- Access token 유효기간 24시간, 공식 문서는 6시간 갱신발급주기를 안내한다.
- 2026-04-20 공식 공지: 실전 REST 18 req/s, 모의 1 req/s, token 발급 1 req/s. 동시 호출은 100~150ms 간격 권장.
- v20의 KIS Adapter는 시세 조회 GET만 지원한다. 주문/정정취소 POST는 별도 Trading Integration 계약 없이는 추가하지 않는다.
- 현재가 Reference: `/uapi/domestic-stock/v1/quotations/inquire-price`, TR `FHKST01010100`.

## Secret 정책
`AUTH_KEY`, `crtfc_key`, appkey, appsecret, access_token은 UI·Telemetry·Audit diff·로그에 저장하지 않는다. Adapter는 `IKbxProviderSecretStore`에서만 읽는다.

## 캐시/실패
Provider 데이터는 업무 원장이 아니다. Provider 장애 시 기존 Domain Write를 되돌리거나 외부 응답을 Business Truth로 승격하지 않는다. 데이터 신선도와 원천 시각을 별도 보존한다.