한국투자증권 API 첫 연동: 환경·토큰 만료·업무 오류 검사 OnTech Insight

TECH INSIGHT / EXPLAINED

첫 연동의 목표는 의도한 환경에서 유효한 시세 응답을 받는 것입니다. 앱 인증 정보·접근 토큰·시장 선택·응답 검증을 네 단계로 나눠 확인하세요.

AI로 제작한 설명용 일러스트. 세 사람이 모의·실전 인증 정보를 분리하고 시세 응답을 검증합니다.

실제 프로젝트의 로컬 실행 화면

기존 프로젝트의 화면 또는 함수를 로컬에서 실행해 촬영했습니다. 개인정보 없는 샘플 입력을 사용했으며, 실행한 범위는 각 이미지 아래에 설명했습니다.

LLMStockTrading의 원본 KISClient._parse를 가상 Response 객체로 직접 실행한 결과. HTTP 오류·업무 오류·JSON 해석 오류가 서로 다른 예외로 관측됐다. 실제 KIS 요청이나 토큰 갱신·주문을 실행한 기록은 아니다.

인증 정보를 환경에 묶기

공식 KIS 포털과 예제 저장소에서 신청 절차, 계좌와 모의투자 지원 기능을 확인합니다. 모의와 실전 키는 별도 설정으로 관리합니다. 모의 주소는 https://openapivts.koreainvestment.com:29443, 실전은 https://openapi.koreainvestment.com:9443입니다. 한쪽 실패를 다른 환경으로 자동 전환하지 않습니다.

지원 중인 Python 버전·독립 실행 환경·고정한 Requests 의존성을 사용하세요. 인증 정보와 캐시 토큰은 보호된 저장소에 두고 소스나 커밋된 JSON에 넣지 않습니다. 토큰 앞부분도 출력할 필요가 없습니다.

자정이 아니라 만료 시각으로 캐시

tokenP 요청에는 client_credentials와 appkey·appsecret을 사용합니다. 토큰과 함께 발급 응답의 만료 정보, 해당 환경을 저장합니다. 유효한 동안 재사용하고 명시적인 갱신 여유를 두세요. 오늘 받은 토큰인지 여부만으로 유효성을 판단하지 않습니다. 여러 작업자가 동시에 같은 토큰을 갱신하지 않도록 조율해야 합니다.

시세 조회 실패가 곧 만료는 아닙니다. HTTP 상태와 업무 오류 필드를 나누고 문서화된 인증 오류일 때만 갱신합니다. 추측한 하루 발급 횟수 대신 현재 문서의 발급 제한을 따릅니다.

시장과 종목 하나를 지정해 조회

국내 주식 inquire-price의 공식 예제는 실전과 모의 모두 FHKST01010100을 사용합니다. 다른 기능은 다를 수 있습니다. 현재 예제의 FID_COND_MRKT_DIV_CODE=J는 KRX이며 시장 코드를 서로 바꿔 써서는 안 됩니다. 005930 같은 여섯 자리 코드는 문자열로 보존합니다.

Bearer 인증과 appkey/appsecret 헤더, 타임아웃을 넣어 요청한 후 HTTP 성공과 rt_cd를 모두 확인하고 output을 읽습니다. 아래 파서는 가상 응답을 쓰며 계좌에 연결하지 않습니다.

from decimal import Decimal
def parse_kis_quote(payload):
    if not isinstance(payload, dict):
        raise ValueError('expected response object')
    if payload.get('rt_cd') != '0':
        raise RuntimeError('KIS business request failed')
    out = payload.get('output')
    if not isinstance(out, dict):
        raise ValueError('missing output object')
    price = Decimal(str(out['stck_prpr']))
    change = Decimal(str(out['prdy_ctrt']))
    if not price.is_finite() or price <= 0 or not change.is_finite():
        raise ValueError('invalid quote values')
    return {'price': price, 'change_pct': change}
sample = {'rt_cd': '0', 'output': {'stck_prpr': '71000', 'prdy_ctrt': '0.85'}}
assert parse_kis_quote(sample)['price'] == Decimal('71000')

확인되지 않은 이름 필드에 의존하지 않기

선택한 엔드포인트가 보장하는 필드만 사용합니다. 모든 시세에 hts_kor_isnm이 있다고 가정하는 대신, 종목명은 문서의 종목 마스터나 적절한 기준정보 조회에서 얻습니다. 누락과 잘못된 값을 명시적으로 처리하세요.

다음으로 시각을 포함한 조회 데이터를 저장하고, 주문 없이 판단만 기록해 전략을 시험합니다. 모의 주문 상태 전이는 별도로 검증합니다. 모의 체결은 소프트웨어 시험에는 유용하지만 실전 체결 품질을 입증하지는 않습니다.

공식 자료와 함께 읽기

KIS official repository · Current-price official example · KIS authentication example

내용·예제 검토: 2026-09-29

한국투자증권 API 첫 연동: 환경·토큰 만료·업무 오류 검사