주식자동매매: 키움증권 RestAPI 이용

글쓴이 /

최근 개인 투자자들 사이에서도 정해진 규칙에 따라 체계적으로 매매하는 주식자동매매에 대한 관심이 빠르게 커지고 있습니다. 이 글에서는 국내 대표 증권사 중 하나인 키움증권이 제공하는 RestAPI를 기준으로, 자동매매 시스템을 구축하기 위해 알아야 할 핵심 개념부터 API 신청, 토큰 발급, 기본 주문 코드, 그리고 실전 적용 시 유의해야 할 사항까지 단계별로 정리합니다.

1. 주식자동매매란?

주식자동매매(알고리즘매매, 시스템트레이딩)는 사람이 매 순간 호가창을 보며 직접 주문을 내는 대신, 사전에 정의된 매매 전략과 조건을 컴퓨터 프로그램이 대신 실행하도록 만든 투자 방식입니다. 투자자는 진입·청산·손절 조건을 코드로 작성해 두고, 프로그램은 실시간 시세와 계좌 정보를 받아 조건이 충족되는 즉시 증권사 서버로 주문을 전송합니다.

수동매매와 비교했을 때 가장 큰 차이는 일관성입니다. 감정이나 피로에 영향을 받지 않고 정해진 규칙을 그대로 실행하기 때문에, 전략의 성과를 과거 데이터로 검증(백테스트)한 뒤 그 결과를 실제 매매에서도 유사하게 재현할 수 있다는 장점이 있습니다. 다만 이는 전략 자체가 타당하고 API 연동과 주문 로직이 안정적으로 구현되어 있을 때의 이야기이며, 시스템 오류나 API 제약을 제대로 이해하지 못하면 오히려 손실을 키우는 원인이 될 수 있습니다.

2. 키움증권 RestAPI

키움증권은 오랫동안 윈도우 전용 OCX 방식의 Open API+를 제공해 왔습니다. 이 방식은 반드시 윈도우 환경에서 영업점 프로그램을 설치하고 로그인 상태를 유지해야 한다는 제약이 있었습니다. 이에 비해 최근 제공되는 키움 RestAPI는 HTTP/HTTPS 기반의 표준 REST 방식으로 동작하기 때문에, 운영체제에 관계없이 파이썬, 자바, Node.js 등 HTTP 요청을 보낼 수 있는 어떤 언어에서도 사용할 수 있다는 점이 가장 큰 변화입니다.

  • JSON 기반의 요청/응답 구조
  • OAuth2 client_credentials 방식의 접근토큰(access token) 인증
  • 기능별로 고유한 TR ID(api-id)를 헤더에 담아 요청 종류를 구분
  • 실전투자 서버(api.kiwoom.com)와 모의투자 서버(mockapi.kiwoom.com)를 분리 제공

3. API 신청 방법

RestAPI를 사용하려면 먼저 키움증권 계좌와 API 이용 신청이 선행되어야 합니다. 일반적인 절차는 다음과 같습니다.

  1. 키움증권 계좌 개설 — 비대면 계좌개설 또는 영업점을 통해 증권계좌를 먼저 준비합니다.
  2. 키움 Open API 포털 접속 — openapi.kiwoom.com에 로그인합니다.
  3. API 서비스 이용 신청 — 포털 내 REST API 신청 메뉴에서 이용 약관에 동의하고 서비스를 신청합니다.
  4. appkey / secretkey 발급 — 신청이 승인되면 애플리케이션 등록 화면에서 고유한 appkey와 secretkey가 발급됩니다. 이 값들은 토큰 발급의 핵심 인증 정보이므로 외부에 노출되지 않도록 관리해야 합니다.
  5. 모의투자 서비스 신청(선택) — 실전 자금을 사용하기 전에 모의투자 서버에서 동일한 방식으로 테스트할 수 있도록 모의투자 계좌도 함께 신청해 두는 것을 권장합니다.

4. 토큰 발급 방법

키움 RestAPI는 OAuth2의 client_credentials 방식을 사용해 접근토큰을 발급합니다. appkey와 secretkey를 이용해 토큰 발급 엔드포인트에 POST 요청을 보내면, 이후 모든 API 호출 시 Authorization 헤더에 담아 사용할 Bearer 토큰을 받을 수 있습니다.

  • 요청 URL(실전): https://api.kiwoom.com/oauth2/token
  • 요청 URL(모의투자): https://mockapi.kiwoom.com/oauth2/token
  • Method: POST
  • Header: Content-Type: application/json;charset=UTF-8
  • Body: grant_type(client_credentials), appkey, secretkey
import requests

def get_access_token(app_key: str, app_secret: str, is_mock: bool = True) -> str:
    base_url = "https://mockapi.kiwoom.com" if is_mock else "https://api.kiwoom.com"
    url = f"{base_url}/oauth2/token"
    headers = {"Content-Type": "application/json;charset=UTF-8"}
    body = {
        "grant_type": "client_credentials",
        "appkey": app_key,
        "secretkey": app_secret,
    }
    res = requests.post(url, headers=headers, json=body)
    res.raise_for_status()
    data = res.json()
    return data["token"]  # Bearer 토큰 문자열

응답에는 접근토큰(token), 토큰 유형(token_type, bearer), 만료 일시를 나타내는 expires_dt 등이 포함됩니다. 토큰은 무기한 유효한 것이 아니라 일정 시간이 지나면 만료되므로, 자동매매 프로그램에서는 토큰의 만료 시각을 기록해 두었다가 만료 전에 자동으로 재발급하는 로직을 반드시 포함해야 합니다.

5. 기본 주문 코드 예시

토큰을 발급받았다면 이를 이용해 실제 주문 API를 호출할 수 있습니다. 아래는 국내주식 매수 주문을 전송하는 간단한 파이썬 예시입니다. 주문 API는 TR ID 역할을 하는 api-id 헤더(예: 매수주문 kt10000)로 요청 종류를 구분하며, 종목코드·수량·가격·거래소구분 등을 바디에 담아 전송합니다.

import requests

def buy_order(
    access_token: str,
    stock_code: str,
    quantity: int,
    price: int,
    is_mock: bool = True,
) -> dict:
    base_url = "https://mockapi.kiwoom.com" if is_mock else "https://api.kiwoom.com"
    url = f"{base_url}/api/dostk/ordr"

    headers = {
        "Content-Type": "application/json;charset=UTF-8",
        "Authorization": f"Bearer {access_token}",
        "api-id": "kt10000",  # 주식 매수주문 TR
    }

    body = {
        "dmst_stex_tp": "KRX",     # 국내거래소구분
        "stk_cd": stock_code,      # 종목코드 (예: "005930")
        "ord_qty": str(quantity),  # 주문수량
        "trde_tp": "0",            # 매매구분 (지정가 등, 코드표 참조)
        "ord_uv": str(price),      # 주문단가
    }

    res = requests.post(url, headers=headers, json=body)
    res.raise_for_status()
    return res.json()


if __name__ == "__main__":
    token = get_access_token(app_key="발급받은 appkey", app_secret="발급받은 secretkey")
    result = buy_order(token, stock_code="005930", quantity=1, price=70000)
    print(result)

실제 운영 환경에서는 매매구분(trde_tp) 코드, 거래소구분 값 등 세부 파라미터가 공식 문서 업데이트에 따라 달라질 수 있으므로, 운영 전 반드시 키움증권 Open API 포털의 최신 개발 가이드와 비교해 필드명과 값을 확인하시기 바랍니다.

6. 자동매매 구현 흐름

실제 자동매매 시스템은 단순히 주문 함수 하나로 끝나지 않습니다. 일반적으로 다음과 같은 흐름으로 구성됩니다.

  1. 전략 신호 생성 — 퀀트 전략(이동평균, 추세추종, 변동성 돌파 등)과 백테스트로 검증된 로직이 실시간 시세를 바탕으로 매수·매도 신호를 만듭니다.
  2. 인증 및 토큰 관리 — 프로그램 시작 시 토큰을 발급받고, 만료 전 자동 재발급되도록 별도의 토큰 관리 모듈을 둡니다.
  3. 주문 실행 — 신호가 발생하면 종목코드·수량·가격·주문유형을 계산해 주문 API를 호출합니다.
  4. 체결 및 잔고 확인 — 주문 접수 이후에는 체결내역·미체결·잔고 조회 API로 실제 체결 여부를 지속적으로 확인합니다.
  5. 리스크 관리 — 손절가·익절가, 최대 보유 종목 수, 1회 주문 한도 등 리스크 규칙을 매 루프마다 점검합니다.
  6. 로깅 및 알림 — 매매 내역과 오류를 로그로 남기고, 텔레그램 봇 등으로 실시간 알림을 전송해 시스템 상태를 상시 모니터링합니다.
  7. 스케줄링 — 장 시작부터 장 마감까지 일정 주기로 위 과정을 반복 실행하는 스케줄러(예: cron, APScheduler)를 구성합니다.

7. 주의사항

  • 모의투자 선행 테스트 — 실전 자금을 투입하기 전, 모의투자 서버에서 충분한 기간 동안 전략과 주문 로직을 검증해야 합니다.
  • API 호출 제한 준수 — 증권사별로 초당·분당 호출 횟수 제한이 있으므로, 과도한 반복 호출로 인한 차단을 방지하도록 호출 빈도를 조절해야 합니다.
  • 인증정보 보안 관리 — appkey, secretkey, 접근토큰은 절대 코드에 하드코딩하거나 공개 저장소에 올리지 말고, 환경변수나 별도의 비밀 관리 도구를 사용해야 합니다.
  • 네트워크·서버 점검 대비 — 증권사 서버 점검, 네트워크 단절 등 예외 상황에 대비한 재시도·예외처리 로직이 필요합니다.
  • 과최적화 경계 — 과거 데이터에 지나치게 맞춘 전략은 실제 시장에서 기대와 다른 성과를 낼 수 있으므로, 표본 외 검증(워크포워드 테스트 등)을 거치는 것이 좋습니다.
  • 법적·세무적 책임 — 자동매매로 발생하는 모든 손익과 세금, 수수료에 대한 책임은 투자자 본인에게 있으며, 관련 법규와 증권사 약관을 반드시 숙지해야 합니다.
  • 공식 문서 변경 확인 — API 명세는 증권사 정책에 따라 변경될 수 있으므로, 운영 중인 시스템은 주기적으로 공식 개발자 포털의 공지사항과 가이드를 확인해야 합니다.

키움증권 RestAPI는 기존 OCX 방식보다 훨씬 가볍고 유연하게 자동매매 시스템을 구축할 수 있게 해주지만, 그만큼 인증·보안·예외처리를 스스로 꼼꼼히 챙겨야 하는 책임도 함께 따릅니다. 이번 글에서 다룬 흐름을 바탕으로 모의투자 환경에서 충분히 검증한 뒤, 단계적으로 실전 자동매매에 적용해 보시기 바랍니다.

댓글 달기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

위로 스크롤