mang_issu_cls_code — 봇에서 관리종목 거르기

이 글은 KIS 주식현재가 시세 FHKST01010100 글에서 위험 플래그 한 갈래만 떼어 낸 글입니다. 현재가 응답 전체 필드와 호가·체결 구조는 그쪽을 보시고, 여기서는 “이 종목을 사도 되는가” 만 다룹니다.

1. 왜 이걸 안 거르면 백테스트가 무너지나

주문이 거부되는 것은 아닙니다. 체결되는 방식이 달라집니다. 한국거래소는 코스닥 관리종목의 매매방식을 연속적 경쟁매매에서 30분 단위의 주기적 단일가매매로 바꿔 운영하고 있고, 정리매매 종목은 가격제한폭 확대 적용의 예외로 분류돼 있습니다. 지정가를 냈는데 즉시 체결되지 않고 다음 단일가 시점까지 기다리게 되는 상태가 됩니다.

이게 왜 문제냐면, 백테스트는 거의 예외 없이 “분봉 종가에 체결된다” 를 가정하기 때문입니다. 실제로는 30분 뒤 단일가에 체결되고, 그 사이 호가가 크게 벌어져 있습니다. 전략이 틀린 것이 아니라 체결 가정이 틀린 것인데, 결과는 “백테스트는 좋았는데 실전은 다르다” 로 나타납니다. 백테스트와 실전이 갈리는 지점에서 다룬 괴리의 흔한 원인 하나가 정확히 이것입니다.

2. 경로 두 개 — 종목당 1콜 vs 전 종목 한 번에

한국투자증권 KIS API 로 “이 종목이 관리종목인가” 를 아는 길은 두 개고, 쓰임새가 완전히 다릅니다.

대부분의 사고는 이 둘을 바꿔 쓰는 데서 납니다. 유니버스 2,900종목을 현재가로 훑으면 시세 조회와 주문이 써야 할 초당 한도까지 같이 태우고, 반대로 마스터파일만 믿으면 장중에 새로 걸린 임시 정지를 놓칩니다.

3. REST 경로: 현재가 응답의 플래그 8개

한국투자증권 공식 저장소 koreainvestment/open-trading-api 의 예제 chk_inquire_price.py 와 MCP 용 data.csv 컬럼 매핑에 적힌 이름 그대로입니다.

시장경고 코드 값

값의 뜻은 공식 저장소의 구조체 헤더 종목마스터정보(코스피).h 주석에 그대로 적혀 있습니다.

/* 종목마스터정보(코스피).h — 한국투자증권 공식 저장소 발췌 */
char    short_over_cls_code[1];      /* 단기과열종목구분코드 0:해당없음 */
char    trht_yn[1];                  /* 거래정지 여부 */
char    sltr_yn[1];                  /* 정리매매 여부 */
char    mang_issu_yn[1];             /* 관리 종목 여부 */
char    mrkt_alrm_cls_code[2];       /* 시장 경고 구분 코드 (00:해당없음 01:투자주의 */
                                     /* 02:투자경고 03:투자위험 */
char    mrkt_alrm_risk_adnt_yn[1];   /* 시장 경고위험 예고 여부 */
char    insn_pbnt_yn[1];             /* 불성실 공시 여부 */
char    byps_lstn_yn[1];             /* 우회 상장 여부 */
char    ssts_hot_yn[1];              /* 공매도과열종목여부 */
char    stange_runup_yn[1];          /* 이상급등종목여부 */

실제 응답에서 꺼내기

import requests

BASE = "https://openapi.koreainvestment.com:9443"

def price_flags(token, appkey, appsecret, code):
    r = requests.get(
        f"{BASE}/uapi/domestic-stock/v1/quotations/inquire-price",
        headers={
            "authorization": f"Bearer {token}",
            "appkey": appkey,
            "appsecret": appsecret,
            "tr_id": "FHKST01010100",   # 모의투자는 별도 확인
            "custtype": "P",
        },
        params={"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": code},
        timeout=5,
    )
    o = r.json()["output"]
    return {
        "price":      int(o["stck_prpr"]),
        "managed":    o["mang_issu_cls_code"],   # 관리종목여부
        "warn":       o["mrkt_warn_cls_code"],   # 00/01/02/03
        "caution":    o["invt_caful_yn"],        # 투자유의여부
        "liquidation":o["sltr_yn"],              # 정리매매여부
        "overheat":   o["short_over_yn"],        # 단기과열여부
        "halted":     o["temp_stop_yn"],         # 임시 정지 여부
    }

def tradable(f, allow_caution=False):
    if f["halted"] == "Y":           return False, "임시 정지"
    if f["liquidation"] == "Y":      return False, "정리매매"
    if f["managed"] not in ("", "N", "0"): return False, "관리종목"
    if f["warn"] != "00":
        if not (allow_caution and f["warn"] == "01"):
            return False, f"시장경고 {f['warn']}"
    if f["overheat"] == "Y":         return False, "단기과열"
    return True, "ok"

4. 마스터파일 경로: 전 종목을 한 번에

한국투자증권은 종목 마스터파일을 공개 URL 로 배포합니다. 공식 저장소의 kis_kospi_code_mst.py 가 내려받기와 파싱을 그대로 보여 줍니다.

https://new.real.download.dws.co.kr/common/master/kospi_code.mst.zip
https://new.real.download.dws.co.kr/common/master/kosdaq_code.mst.zip

파일은 cp949 인코딩의 고정폭 구조고, 뒤쪽 228바이트가 속성 영역입니다. 파싱 자체는 kospi_code.mst 파싱 — cp949·228자 고정폭에 코드 전문이 있으니 여기서는 반복하지 않고, 파싱 결과에서 어떤 컬럼을 보는지 만 봅니다. 공식 파서가 붙이는 컬럼 이름은 한글입니다.

# kis_kospi_code_mst.py 의 part2_columns 중 위험 플래그 구간
'기준가', '매매수량단위', '시간외수량단위',
'거래정지', '정리매매', '관리종목', '시장경고', '경고예고',
'불성실공시', '우회상장', '락구분', '액면변경', '증자구분', '증거금비율',
...
'우선주', '공매도과열', '이상급등', 'KRX300', 'KOSPI', ...

import pandas as pd

def build_universe(df):
    """마스터파일 DataFrame -> 거래 가능 유니버스"""
    ok = df[
        (df['거래정지']   != 'Y') &
        (df['정리매매']   != 'Y') &
        (df['관리종목']   != 'Y') &
        (df['시장경고'].astype(str).str.zfill(2) == '00') &
        (df['경고예고']   != 'Y') &
        (df['불성실공시'] != 'Y') &
        (df['단기과열']   != 'Y') &
        (df['공매도과열'] != 'Y') &
        (df['이상급등']   != 'Y') &
        (df['SPAC']       != 'Y')      # 코스닥은 '기업인수목적회사여부'
    ].copy()
    return ok[['단축코드', '한글명', '시가총액']]

# 하루 한 번만 돌린다. 장중에 다시 내려받지 않는다.
kospi = get_kospi_master_dataframe(BASE_DIR)
universe = build_universe(kospi)
print(len(kospi), "->", len(universe))

5. 함정 — 같은 뜻, 다른 이름

이 글에서 가장 많이 실수가 나는 지점입니다. REST 응답과 마스터파일 구조체는 같은 개념에 다른 필드명을 씁니다.

정리하면 세 가지입니다.

• 이름이 다르다 — mang_issu_cls_code 로 만든 파서를 마스터파일에 쓰면 키가 없습니다. 예외가 나면 다행이고, dict.get() 을 썼다면 None 이 되어 필터가 조용히 꺼집니다.
• 있고 없고가 다르다 — 공매도과열·이상급등·경고예고·불성실공시·우회상장은 마스터파일에만 있습니다. 실시간 현재가만 보면 이 다섯은 영영 못 봅니다.
• 거래정지가 같은 말이 아니다 — REST 의 temp_stop_yn 은 임시 정지, 마스터파일의 trht_yn 은 거래정지 여부로 별도 필드입니다. 장중 변동은 REST 쪽에서만 잡힙니다.

6. 봇에 붙이는 2단 구조

정리하면 이렇게 됩니다.

1. 장 시작 전 1회 — kospi_code.mst·kosdaq_code.mst 를 받아 유니버스를 만든다. 2,900종목이 보통 수백 종목 단위로 줄어든다.
2. 장중 — 신호 계산은 이 유니버스 안에서만 한다. 관리종목·정리매매는 여기서 이미 없다.
3. 주문 직전 1콜 — 실제로 낼 종목에만 inquire-price 를 부르고 temp_stop_yn·mrkt_warn_cls_code 를 재확인한다. 어차피 현재가가 필요하므로 추가 호출이 아니다.

3번이 핵심입니다. 어차피 지정가를 정하려면 현재가를 불러야 하고, 그 응답에 위험 플래그가 같이 들어 있으므로 필터 비용이 사실상 0 입니다. 이 구조면 유니버스 스캔이 계정 초당 한도를 잡아먹지 않아 EGW00201 위험도 없습니다 — 호출 한도 설계는 API 호출 제한 설계에 정리해 두었습니다.

7. 남는 한계

• 마스터파일은 과거를 주지 않습니다. 오늘 받은 파일은 오늘 상태입니다. 6개월 전 어떤 종목이 관리종목이었는지는 매일 스냅샷을 저장해 두지 않았다면 복원할 수 없습니다.
• 장중 신규 지정은 마스터파일에 없습니다. 그래서 주문 직전 재확인이 필요합니다.
• 상장폐지 직전의 정리매매는 며칠뿐입니다. 일 1회 갱신이면 그 구간을 놓칠 수 있으므로, 보유 종목은 보유 중에도 플래그를 주기적으로 확인하는 편이 안전합니다.
• 필드명과 코드 체계는 바뀔 수 있습니다. 위 내용은 발행 시점의 한국투자증권 공식 저장소 기준입니다. KIS Developers 공식 문서와 저장소에서 현재 스펙을 확인하십시오.
• 이 필터는 손실을 막지 못합니다. 체결 가정이 무너지는 구간을 피하는 위생 장치일 뿐이고, 전략의 성과와는 별개 문제입니다.

알고랩(퀀트웍스)은 투자자문업·투자일임업을 영위하지 않으며, 본 글은 특정 종목의 매매를 권유하지 않습니다. 소프트웨어 제작·기술 정보 제공 목적의 글이며, 투자 판단과 그 결과에 대한 책임은 투자자 본인에게 있습니다. API 스펙·거래소 제도는 발행 시점 기준이며 변경될 수 있으므로 한국투자증권 KIS Developers 및 한국거래소 공식 자료를 확인하십시오.