VI 발동되면 봇 주문은 어떻게 되나 — 정적·동적 VI 대응

키움 REST API든 한국투자증권 KIS API든, 처음 만든 봇이 실전에서 가장 먼저 이상해지는 순간은 대체로 똑같습니다. 급등이나 급락이 나온 종목에서 손절 주문을 시장가로 던졌는데 2분 가까이 아무 일도 일어나지 않습니다. 체결 통보도 없고 에러도 없습니다.

KIS 에러코드 목록을 뒤져도 답이 없습니다. 에러가 아니기 때문입니다. 그 종목에 VI(변동성완화장치, Volatility Interruption)가 걸린 것이고, 그 구간에는 접속매매가 아니라 단일가매매가 돌아갑니다. 이 글은 그 2분 동안 봇이 무엇을 하면 안 되고, 무엇을 읽어야 하는지만 다룹니다.

1. VI가 걸리면 정확히 무엇이 바뀌나

평소 국내주식은 접속매매로 돌아갑니다. 매수 호가와 매도 호가가 맞으면 그 자리에서 체결됩니다. VI가 발동되면 그 종목만 단일가매매로 전환됩니다. 들어오는 주문을 일정 시간 모아 두었다가 한 번에 하나의 가격으로 체결시키는 방식입니다. 한국거래소는 이 냉각 구간을 2분으로 운영합니다(현재 기준은 아래 캐치 참고).

봇 입장에서 핵심은 "거부"가 아니라 "보류"라는 점입니다. 정리하면 이렇습니다.

2. 정적VI와 동적VI — 봇이 구분해야 하는 이유

VI는 하나가 아니라 두 종류이고, 기준가격이 다릅니다.

"동적+정적"은 제가 만든 말이 아니라 실제로 API 응답에 오는 값입니다. 키움 ka10054 응답의 viaplc_tp(VI적용구분) 필드에는 "동적", "정적", "동적+정적"이 들어옵니다. 실시간 항목 1h에서는 같은 값이 필드번호 1225로 옵니다.

3. 봇에서 실제로 터지는 사고 3가지

① 시장가 손절이 2분간 멈춘다

손절 로직을 "손실 -3%면 시장가 매도"로 짰다고 합시다. 그런데 -3%가 찍히는 순간은 대개 급락 중이고, 급락은 동적VI 발동 조건과 겹칩니다. 즉 손절이 가장 필요한 순간에 단일가로 전환되는 구조입니다. 시장가는 이 구간에서 즉시 체결되지 않으므로, "시장가니까 무조건 나간다"는 가정이 깨집니다.

② 미체결 → 재주문 루프가 중복 주문을 만든다

많은 봇이 while 루프에서 체결을 확인하고, 일정 시간 미체결이면 취소 후 재주문합니다. VI 구간에서는 이 로직이 2분 동안 여러 번 돕니다. 취소·정정이 접수돼도 체결 타이밍은 단일가 기준이라 취소와 신규 주문이 뒤엉킬 수 있습니다.

③ 백테스트 가정이 통째로 무너진다

백테스트에서는 "신호가 뜬 봉의 종가에 체결"로 잡는 경우가 많습니다. VI가 걸린 종목은 그 시간에 체결 자체가 없습니다. 거래비용을 반영한 백테스트를 돌렸더라도 VI 구간을 무시했다면 급등락 종목의 성과는 실제보다 좋게 나옵니다.

4. 발동을 읽는 API — 조회와 실시간

키움 REST API — ka10054 변동성완화장치발동종목요청

현재 발동 중인 종목 목록을 통째로 받는 조회입니다.

공식 문서의 응답 예시입니다. 필드명을 그대로 옮깁니다.

{
  "motn_stk": [
    {
      "stk_cd": "005930",
      "stk_nm": "삼성전자",
      "acc_trde_qty": "1105968",
      "motn_pric": "67000",          // 발동가격
      "dynm_dispty_rt": "+9.30",     // 동적괴리율(%)
      "trde_cntr_proc_time": "172311", // 매매체결처리시각 HHmmss
      "virelis_time": "172511",        // VI해제시각 HHmmss
      "viaplc_tp": "동적",             // 정적 / 동적 / 동적+정적
      "dynm_stdpc": "61300",         // 동적기준가격
      "static_stdpc": "0",           // 정적기준가격
      "static_dispty_rt": "0.00",
      "open_pric_pre_flu_rt": "+16.93",
      "vimotn_cnt": "23",            // VI발동횟수
      "stex_tp": "NXT"
    }
  ],
  "return_code": 0,
  "return_msg": "정상적으로 처리되었습니다"
}

봇이 실제로 쓰는 필드는 셋입니다 — viaplc_tp(무슨 VI인가), virelis_time(언제 풀리나), vimotn_cnt(오늘 몇 번째인가). 특히 vimotn_cnt가 두 자리로 올라간 종목은 하루 종일 널뛰는 중이라는 뜻이라 진입 자체를 막는 필터로 쓸 만합니다. 위 예시의 삼성전자 건이 "vimotn_cnt": "23"인 것은 공식 문서의 형식 예시일 뿐 실제 시장 기록이 아니라는 점만 감안하시면 됩니다.

키움 WebSocket — 실시간 항목 1h (VI발동/해제)

보유 종목이 많으면 조회를 반복하는 쪽이 요청 제한에 먼저 걸립니다. 실시간 등록이 정석입니다. 조건검색 WebSocket과 같은 채널에 type을 1h로 등록하면 됩니다.

# 등록 (WebSocket, wss://api.kiwoom.com:10000)
{"trnm": "REG", "grp_no": "1", "refresh": "1",
 "data": [{"item": [""], "type": ["1h"]}]}

# 수신
{"trnm": "REAL", "data": [{
  "type": "1h", "name": "VI발동/해제", "item": "005930",
  "values": {
    "9001": "005930",   # 종목코드
    "302":  "삼성전자",  # 종목명
    "9068": "1",        # VI발동구분
    "1221": "4125",     # VI발동가격
    "1223": "111454",   # 매매체결처리시각
    "1224": "111703",   # VI해제시각
    "1225": "정적",      # VI적용구분
    "1236": "3750",     # 기준가격 정적
    "1238": "+10.00",   # 괴리율 정적
    "1490": "1",        # VI발동횟수
    "9069": "1"         # 발동방향구분
  }}]}

한국투자증권 KIS — 변동성완화장치 현황

KIS 쪽은 조회형만 있습니다. 키움과 KIS를 같이 쓰는 구성이라면 양쪽 필드명이 다르므로 어댑터를 하나 두는 편이 낫습니다.

FID_INPUT_DATE_1에 영업일을 넣어야 하므로, 휴장일 판별이 스케줄러에 붙어 있어야 공휴일에 빈 응답을 받고 헤매지 않습니다.

5. 2분을 하드코딩하면 안 되는 이유

많은 글이 "VI는 2분"이라고 씁니다. 제도 설명으로는 맞습니다. 그런데 봇의 타이머로 쓰기에는 틀립니다. 앞서 인용한 키움 공식 문서의 ka10054 응답 예시를 그대로 검산해 보면 이렇습니다.

같은 문서, 같은 응답 안에서 간격이 갈립니다. 단일가 종료에는 임의 종료 요소가 들어가기 때문입니다. 그래서 발동시각 + 120으로 게이트를 열면 아직 단일가인데 주문을 던지는 경우가 생깁니다.

6. VI 게이트 구현 — 파이썬 스켈레톤

구조는 단순합니다. 종목코드 → 해제시각 맵을 하나 두고, 주문 직전에 물어보는 것입니다.

import time
from datetime import datetime, timedelta

class ViGate:
    """VI 발동 종목의 주문을 해제 시각까지 보류한다."""
    def __init__(self, buffer_sec=3):
        self._until = {}          # {'005930': datetime}
        self.buffer = buffer_sec

    def on_event(self, stk_cd, virelis_time, viaplc_tp):
        """ka10054 응답 또는 실시간 1h 수신 시 호출. virelis_time = 'HHmmss'"""
        today = datetime.now().date()
        h, m, s = int(virelis_time[:2]), int(virelis_time[2:4]), int(virelis_time[4:6])
        until = datetime.combine(today, datetime.min.time()) \
                + timedelta(hours=h, minutes=m, seconds=s)
        self._until[stk_cd] = until + timedelta(seconds=self.buffer)
        print(f"[VI] {stk_cd} {viaplc_tp} → {self._until[stk_cd]:%H:%M:%S}까지 보류")

    def blocked(self, stk_cd):
        until = self._until.get(stk_cd)
        if until is None:
            return False
        if datetime.now() >= until:
            self._until.pop(stk_cd, None)
            return False
        return True

gate = ViGate()

def send_order(stk_cd, qty, side):
    if gate.blocked(stk_cd):
        # 재주문 루프를 여기서 끊는다 — 큐에 넣고 해제 후 재평가
        pending.append((stk_cd, qty, side))
        return None
    return broker.order(stk_cd, qty, side)

7. KRX와 NXT — stex_tp가 갈리는 구간

앞의 응답 예시를 다시 보면 같은 005930인데 stex_tp가 "KRX"인 건과 "NXT"인 건이 따로 옵니다. 넥스트레이드(NXT) 주문 라우팅을 쓰고 있다면 거래소별로 발동 상태를 따로 관리해야 한다는 뜻입니다.

키움 ka10054의 종목코드 표기도 갈립니다 — 문서 설명에 따르면 KRX는 039490, NXT는 039490_NX, SOR은 039490_AL 형식입니다. 봇 내부에서 종목코드를 문자열로 비교한다면 접미사를 정규화하지 않으면 매칭이 통째로 실패합니다.

8. 서킷브레이커·사이드카와 뭐가 다른가

봇 설계에서 셋을 한 덩어리로 묶으면 안 되는 이유는 복구 로직이 다르기 때문입니다. VI는 종목 단위라 나머지 포지션은 정상 운용해야 하고, 시장 단위 조치는 전체를 멈추고 재개 후 상태를 다시 읽어야 합니다. 각 장치의 발동 요건·지속 시간은 제도 변경이 있으므로 한국거래소 공식 안내로 현재 값을 확인하십시오.

자주 묻는 것

VI가 발동되면 이미 걸어 둔 지정가 주문은 사라지나요?

사라지지 않습니다. 호가에 남아 단일가 체결 대상이 됩니다. 그래서 VI 직전에 걸어 둔 지정가가 단일가에서 예상보다 불리하게 체결되는 경우가 생깁니다. 급변 구간에 지정가를 촘촘히 깔아 두는 전략이라면 이 점을 감안해야 합니다.

조회와 실시간 중 뭘 먼저 붙이나요?

보유·감시 종목이 열 개 안쪽이면 ka10054 주기 조회로 충분합니다. 수십 개를 다루거나 연속조회까지 돌고 있다면 실시간 1h가 맞습니다. 다만 실시간은 연결이 끊기면 그 사이 이벤트를 놓치므로, 재접속 직후 ka10054를 한 번 불러 현재 발동 목록을 다시 채우는 복구 경로를 같이 두세요.

이 값들을 그대로 믿어도 되나요?

이 글의 API ID·URL·파라미터·응답 필드명은 2026-08-16 시점 키움증권 REST API 공식 가이드와 한국투자증권 공개 예제 코드에서 확인한 값입니다. 다만 제도 수치(발동 비율·단일가 지속 시간·거래소별 적용 범위)는 변경 이력이 있어 이 글에서 의도적으로 특정 퍼센트를 단정하지 않았습니다. 운영 전 각 증권사 개발자 포털과 한국거래소 공식 안내로 대조하시기 바랍니다.