API로 만드는 주식 프로그램

증권사 API를 사용하면 HTS 화면을 사람이 직접 누르지 않아도 프로그램이 시세를 조회하고, 차트를 그리고, 조건을 감시하고, 모의 또는 실전 주문 흐름을 만들 수 있다. 한국투자증권의 KIS Developers는 이런 기능을 Open API 형태로 제공한다. 공식 포털은 API 설명, 예제 코드, 개발자 지원 자료를 제공하며, 프로젝트의 코드는 이 흐름을 Python 프로그램으로 옮긴 것이다.

여기서 중요한 점은 자동매매 자체가 목적이 아니라 데이터 흐름을 이해하는 것이다. 토큰을 발급받고, 종목코드로 시세를 조회하고, 캔들 데이터를 표준 형태로 바꾸고, 조건을 만족하는 이벤트를 탐지하고, 그 결과를 사람이 이해할 수 있는 화면과 로그로 보여 주는 과정이 핵심이다.

공식 API 흐름

client = KISClient()
client.issue_access_token()
body = client.inquire_daily_itemchart(
    fid_input_iscd="005930",
    period="D",
)
df = candles_to_dataframe(body)

프로젝트 구성

응용 프로그램 1: 현재가 조회

가장 작은 프로그램은 종목코드 하나를 넣고 현재가를 조회하는 것이다. 이 단계에서 독자는 API 키, 토큰, 헤더, 파라미터, 응답 JSON의 의미를 익힌다. 책에서는 삼성전자 005930처럼 익숙한 종목을 예시로 쓰면 흐름이 좋다.

python hankook/moei/main.py

# 흐름
# 1) .env.local에서 APP_KEY / APP_SECRET 읽기
# 2) /oauth2/tokenP로 접근 토큰 발급
# 3) /uapi/domestic-stock/v1/quotations/inquire-price 호출
# 4) output JSON 출력

응용 프로그램 2: 차트 대시보드

차트 프로그램은 일봉, 주봉, 월봉 데이터를 가져와 캔들, 이동평균, RSI, 거래량을 한 화면에 보여 준다. 오른쪽에는 LLM 판단, 판단 이유, 이력 영역이 이미 준비되어 있다. 현재 코드에서는 placeholder에 가깝지만, 이 빈자리가 바로 LLM을 붙이기 좋은 자리다.

응용 프로그램 3: 뉴스 기반 후보 선정

fetch_positive_news.py는 네이버 금융 뉴스를 수집하고, 호재와 악재 키워드 사전으로 점수를 계산한 뒤 종목명과 매칭한다. 현재 positive_news.csv에는 호재성 기사에서 추출한 종목별 행이 저장되어 있다. 이 구조는 초보자에게 매우 좋다. 왜냐하면 처음부터 LLM에게 모든 판단을 맡기지 않고, 키워드 규칙으로 작동하는 기준선을 먼저 만들기 때문이다.

뉴스 제목 + 요약
  -> 종목명 매칭
  -> 호재/악재 키워드 점수
  -> 후보 종목 CSV
  -> LLM 요약과 리스크 설명 추가

응용 프로그램 4: 급등락 실시간 감시

surge_monitor.py는 KIS 1분봉을 일정 주기로 조회하고, 최근 N분 수익률, 거래량 급증, 캔들 폭 조건을 동시에 만족할 때 이벤트를 출력한다. watchlist를 직접 지정할 수도 있고, 거래대금 상위 종목이나 호재 후보 종목으로 자동 구성할 수도 있다.

LLM은 이 이벤트의 원인을 추정하는 보조자로 쓸 수 있다. 예를 들어 방금 발생한 급등 이벤트에 대해 최근 뉴스, 공시, 업종 흐름, 과거 이벤트 이력을 모아 '왜 알림이 발생했는지' 설명하게 할 수 있다. 단, LLM의 설명은 사실 확인 전의 가설로 표시해야 한다.

응용 프로그램 5: 모의매매 스케줄러

paper_trade.py는 실거래가 아니라 모의 실험이다. 매일 아침 호재 후보를 고르고, 장 마감 후 당일 OHLC 데이터로 익절 +5%, 손절 -3%, 미도달 시 종가 청산 규칙을 적용한다. 결과는 날짜별 CSV로 저장된다. 프로젝트에는 2026년 4월 29일, 4월 30일, 5월 4일, 5월 6일의 모의매매 결과 파일이 있다.

LLM을 넣기 좋은 부분

LLM을 주식 프로그램에 넣을 때 가장 좋은 위치는 '사람이 읽고 판단해야 하는 정보의 압축'이다. 숫자 계산, 주문 전송, 손절 조건 같은 부분은 결정적 코드와 규칙으로 처리하고, LLM은 설명, 요약, 분류, 질의응답, 리포트 작성에 배치하는 것이 안전하다.

LLM에게 맡기면 위험한 부분

• 실전 주문 버튼을 LLM 판단만으로 누르게 하지 않는다.
• 손절, 익절, 포지션 크기 같은 위험 관리 규칙을 자연어 출력에 의존하지 않는다.
• API 키, 앱시크릿, 계좌번호 같은 민감 정보를 프롬프트에 넣지 않는다.
• 뉴스 요약만으로 사실 여부가 확인된 것처럼 표시하지 않는다.
• 백테스트 결과가 좋다는 이유로 미래 수익이 보장된다고 쓰지 않는다.

추천 아키텍처

KIS Open API
  -> KISClient: 인증, 토큰 재발급, REST 호출
  -> DataFrame: OHLCV, 1분봉, 현재가 정규화
  -> Rule Engine: 급등락, 손절/익절, 후보 필터
  -> Storage: CSV 로그, 이벤트 기록, 모의매매 결과
  -> LLM Layer: 뉴스 요약, 차트 설명, 이벤트 해설, 회고 리포트
  -> UI: PyQt 대시보드, 알림, 사용자 질문

이 구조에서 LLM은 마지막 판단자가 아니라 해설자와 분석 보조자다. 수치 계산은 코드가 하고, LLM은 그 숫자가 무엇을 의미하는지 독자와 사용자에게 설명한다. 이 역할 분담을 지키면 프로그램은 훨씬 안정적이고 책의 메시지도 명확해진다.

실습 순서

• 1단계: KIS Developers에서 API 키를 발급받고 .env.local에 APP_KEY와 APP_SECRET을 설정한다.
• 2단계: hankook/moei/main.py로 현재가 조회가 되는지 확인한다.
• 3단계: chart/main.py로 일봉 차트를 그리고 종목코드를 바꿔 본다.
• 4단계: build_stock_list.py로 투자 유의 종목을 제외한 종목 목록을 만든다.
• 5단계: fetch_positive_news.py로 뉴스 기반 후보 CSV를 만든다.
• 6단계: paper_trade.py --runonce로 모의매매 결과를 저장한다.
• 7단계: surge_monitor.py로 1분봉 급등락 감시 조건을 실험한다.
• 8단계: LLM에게 CSV 결과와 이벤트 로그를 요약하게 해 대시보드 우측 패널에 넣는다.

안전 장치

주식 API 프로그램은 재미있는 장난감처럼 보이지만, 실전 계좌와 연결되면 곧바로 돈이 움직인다. 따라서 책에서는 모의투자와 페이퍼 트레이딩을 기본값으로 두고, 실전 주문은 별도 장에서 위험 고지, 권한 분리, 주문 전 확인, 최대 손실 제한, 로그 보존까지 다룬 뒤에야 언급하는 편이 좋다.

마무리

한국투자증권 API를 사용하면 개인 개발자도 시세 조회, 차트 대시보드, 이벤트 감시, 모의매매 같은 실전적인 프로그램을 만들 수 있다. 여기에 LLM을 붙이면 숫자와 로그가 사람의 언어로 바뀐다. 좋은 구조는 명확하다. API는 데이터를 가져오고, 규칙 엔진은 조건을 판정하고, LLM은 그 결과를 설명한다. 이 분업이 지켜질 때 주식 프로그램은 더 똑똑해지면서도 더 안전해진다.

참고 자료

• KIS Developers 공식 포털: https://apiportal.koreainvestment.com/
• 한국투자증권 공식 GitHub: https://github.com/koreainvestment/open-trading-api
• KIS Developers 공식 GitHub 조직: https://github.com/koreainvestment