3분봉 자동매매

키움 REST API와 Node.js로 시작하는 3분봉 자동매매

로

키움 Open API와 파이썬을 사용하여 3분봉 자동매매가 가능한지 살펴보았습니다. 이번에는 키움증권에서 제공하는 키움 REST API와 Node.js를 가지고 3분봉 자동매매 개발을 시작하는 방법에 대해서 확인해 보겠습니다.

1. 서론: 3분봉 자동매매 시스템의 도입 배경

주식 시장이 빠르게 변화함에 따라, 트레이더들은 수동적인 투자 방식에서 벗어나 자동화된 시스템을 활용한 전략적 매매로 전환하고 있다. 자동매매 시스템은 정해진 규칙에 따라 매수·매도를 실행함으로써 인간의 감정을 배제하고 일관된 성과를 도모할 수 있다는 점에서 큰 장점을 갖는다.

국내 증권사 중 하나인 키움증권은 오랜 기간 개인 투자자에게 오픈 API를 제공해 왔으며, 최근에는 REST 기반의 API를 통해 보다 현대적인 자동매매 구현 환경을 지원하고 있다. Node.js는 비동기 I/O 처리에 최적화된 자바스크립트 런타임으로, REST API와의 궁합이 뛰어나 자동매매 시스템 개발에 적합한 플랫폼으로 평가받고 있다.

이 글에서는 키움증권의 REST API와 Node.js를 활용해 3분봉 기반의 자동매매 시스템을 구현하는 과정을 단계별로 살펴본다. 특히 REST API의 구조, Node.js 개발 환경 구성, 3분봉 전략 설계, 실제 매매 실행 로직까지 실무에 필요한 내용을 중심으로 설명한다.

2. 키움 REST API 이해하기

2.1 키움 Open API의 개요

키움증권은 오랜 기간 HTS 기반의 COM 방식 API(Kiwoom OpenAPI+)를 통해 자동매매 환경을 제공해 왔다. 그러나 COM 기반 API는 윈도우 플랫폼에 종속되며, 비동기 처리나 외부 시스템 연동에 제한이 있었다. 이를 보완하기 위해 키움증권은 REST API 기반의 새로운 인터페이스를 도입했다.

공식 문서: https://openapi.kiwoom.com/main/home

2.2 REST API의 주요 기능

  • 실시간 시세 조회
  • 분/일/틱 차트 데이터 제공
  • 주문 실행 (시장가, 지정가)
  • 잔고 및 체결 내역 조회
  • 계좌 정보 확인

2.3 제한 사항 및 유의점

  • 인증 절차: 토큰 기반 인증 필요 (OAuth 2.0 유사 구조), 토큰의 유효기간은 24시간이며, 매 24시간마다 재발급이 필요
  • 호출 제한: 초당 요청 횟수 제한이 있으며, 이를 초과할 경우 일정 시간 동안 블록될 수 있다.

3. Node.js로 3분봉 자동매매 개발 환경 구축

3.1 Node.js의 장점

Node.js는 이벤트 기반의 비동기 처리 모델을 채택하고 있어, REST API와 같은 네트워크 중심의 작업에 적합하다. 특히 다수의 종목에 대해 반복적인 요청을 수행하거나, 실시간 데이터에 기반한 매매 판단을 내려야 하는 자동매매 시스템에서 높은 처리 효율을 제공한다.

3.2 개발 환경 구성

# Node.js 설치 (v18 이상 권장)
$ brew install node

# 프로젝트 디렉토리 생성 및 초기화
$ mkdir kiwoom-tradebot && cd kiwoom-tradebot
$ npm init -y

# 필수 모듈 설치
$ npm install axios dotenv momen

3.3 API 호출 예제 (시세 조회)

// getPrice.js
require('dotenv').config();
const axios = require('axios');

const accessToken = process.env.ACCESS_TOKEN; // 사전에 발급받은 토큰
const baseURL = 'https://openapi.koreainvestment.com:9443';

async function getCurrentPrice(stockCode) {
  const response = await axios.get(`${baseURL}/uapi/domestic-stock/v1/quotations/inquire-price`, {
    headers: {
      'authorization': `Bearer ${accessToken}`,
      'appkey': process.env.APP_KEY,
      'appsecret': process.env.APP_SECRET,
      'tr_id': 'FHKST01010100',
    },
    params: {
      fid_cond_mrkt_div_code: 'J',
      fid_input_iscd: stockCode,
    },
  });
  console.log(response.data);
}

getCurrentPrice('005930'); // 삼성전자

4. 3분봉 자동매매 데이터를 활용한 전략 설계

4.1 3분봉의 의미

3분봉은 3분 단위로 시세 데이터를 분할한 것으로, 단타 전략에서 특히 유용하다. 짧은 시간 안에 급변하는 시장 흐름을 포착할 수 있어 초단기 트레이딩에 적합하다.

4.2 분봉 데이터 요청

const getMinuteChart = async (stockCode) => {
  const response = await axios.get(`${baseURL}/uapi/domestic-stock/v1/quotations/inquire-time-itemchartprice`, {
    headers: {
      'authorization': `Bearer ${accessToken}`,
      'appkey': process.env.APP_KEY,
      'appsecret': process.env.APP_SECRET,
      'tr_id': 'FHKST03010200',
    },
    params: {
      fid_cond_mrkt_div_code: 'J',
      fid_input_iscd: stockCode,
      fid_input_timecnt: 100,
      fid_input_timeminunit: 3, // 3분봉
    },
  });
  return response.data.output2;
};

4.3 이동평균 기반 신호 감지

단기 이동평균선이 장기 이동평균선을 상향 돌파할 경우 매수 신호로 간주할 수 있다. 아래는 간단한 예시이다.

const detectGoldenCross = (data) => {
  const closePrices = data.map(d => parseFloat(d.stck_prpr));
  const ma3 = average(closePrices.slice(-3));
  const ma9 = average(closePrices.slice(-9));
  return ma3 > ma9;
};

const average = arr => arr.reduce((sum, val) => sum + val, 0) / arr.length;

5. 3분봉 자동매매 실행 로직 구성

5.1 주문 실행

const sendOrder = async (stockCode, quantity, price, buy = true) => {
  const response = await axios.post(`${baseURL}/uapi/domestic-stock/v1/trading/order-cash`, {
    headers: {
      'authorization': `Bearer ${accessToken}`,
      'appkey': process.env.APP_KEY,
      'appsecret': process.env.APP_SECRET,
      'tr_id': buy ? 'TTTC0802U' : 'TTTC0801U',
    },
    data: {
      CANO: process.env.ACCOUNT_NO,
      ACNT_PRDT_CD: '01',
      PDNO: stockCode,
      ORD_DVSN: '01', // 시장가
      ORD_QTY: quantity,
      ORD_UNPR: price,
    },
  });
  console.log(response.data);
};

5.2 자동화 흐름

  1. 3분마다 분봉 데이터 조회
  2. 전략에 따라 매수/매도 신호 판별
  3. 주문 실행
  4. 체결 여부 확인 및 로깅
  5. 잔고 및 손익 실시간 반영

6. Node.js + REST API 조합의 실용성과 확장성

Node.js는 REST API를 기반으로 한 서버 구성에 특화되어 있으며, 다음과 같은 확장성을 갖는다.

  • 다종 전략 병렬 운영: 비동기 처리 구조를 통해 다수의 종목을 동시에 분석 및 거래 가능
  • 외부 시스템 연동 용이: Telegram, Slack, Notion 등의 알림 시스템 연동
  • 클라우드 호스팅 최적화: AWS Lambda, GCP Cloud Functions 등과의 연동을 통한 서버리스 아키텍처 가능
  • 전략 변경 유연성: 전략 모듈화 및 스케줄링 가능 (ex. node-cron)

7. 결론

키움 REST API와 Node.js는 자동매매 시스템을 빠르고 효율적으로 구축할 수 있는 강력한 조합이다. 특히 3분봉과 같은 초단기 데이터를 활용한 전략을 구현할 경우, REST API의 실시간성, Node.js의 비동기 구조는 큰 이점을 제공한다.

다만, 실제 매매에 적용하기 전에는 충분한 백테스트와 로직 검증이 선행되어야 하며, API 호출 제한과 보안 이슈도 철저히 관리해야 한다. 향후에는 다양한 전략 모듈, 상태 저장 로직, 클라우드 기반 운영 등으로 시스템을 확장해 나갈 수 있다.

관련 글 더보기

댓글 남기기