국내 주식 전체 종목코드 받기 — kospi_code.mst 파싱

자동매매 봇을 만들 때 의외로 첫날 막히는 지점이 "살 종목 후보 목록을 어디서 받나"입니다. KIS API 키를 발급받고 첫 주문까지 성공했더라도, 그 주문에는 종목코드를 이미 알고 있다는 전제가 깔려 있습니다. 삼성전자 하나를 사는 봇이면 005930을 하드코딩하면 그만이지만, "코스피 전 종목 중 조건에 맞는 것"을 찾는 순간 목록 자체가 필요해집니다.

그런데 증권사 REST API의 조회 계열은 대부분 종목코드를 입력으로 받는 구조라 전 종목을 훑어 주지 않습니다. 그래서 종목 목록은 API가 아니라 파일로 배포됩니다.

1. 파일은 어디에 있나 — 내려받기와 압축 해제

한국투자증권은 종목정보 마스터 파일을 공개 다운로드 서버에 .zip으로 올려 둡니다. 개발자센터의 인증(appkey·appsecret·access_token)이 필요 없고, 그냥 HTTP로 받으면 됩니다. 호출 제한과도 무관합니다.

# 코스피
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

파이썬으로 받아서 푸는 것까지는 열 줄이 안 됩니다.

import ssl, urllib.request, zipfile, os

BASE = "https://new.real.download.dws.co.kr/common/master/"

def download_mst(market: str, out_dir: str = ".") -> str:
    """market: 'kospi' | 'kosdaq'  ->  압축 푼 .mst 파일 경로"""
    name = f"{market}_code.mst"
    zip_path = os.path.join(out_dir, name + ".zip")

    # 일부 환경에서 인증서 검증 옵션 때문에 막히는 경우가 있어 컨텍스트를 명시
    ctx = ssl.create_default_context()
    with urllib.request.urlopen(BASE + name + ".zip", context=ctx) as r, \
         open(zip_path, "wb") as f:
        f.write(r.read())

    with zipfile.ZipFile(zip_path, "r") as z:
        z.extractall(out_dir)
    os.remove(zip_path)
    return os.path.join(out_dir, name)

path = download_mst("kospi")
print(path, os.path.getsize(path), "bytes")

2. 한 줄이 어떻게 생겼나 — 가변 + 고정폭 구조

이 파일이 초보자를 잡는 이유는 CSV가 아니기 때문입니다. 쉼표도 탭도 없습니다. 한 줄이 한 종목인데, 그 줄이 두 구간으로 나뉩니다.

핵심은 "뒤에서부터 자른다"는 점입니다. 종목명 길이가 제각각이라 앞에서부터는 끝을 알 수 없지만, 뒤쪽 고정폭 구간의 길이는 항상 같기 때문에 뒤에서 228자(코스닥은 222자)를 떼어 내면 남는 것이 앞쪽 구간이 됩니다. 그러고 나면 앞쪽은 자리수가 정해져 있습니다.

3. 파싱 코드 전문 (코스피·코스닥)

앞쪽 세 필드만 있으면 종목 유니버스는 완성됩니다. 뒤쪽 60여 개 필드는 필요할 때 pandas의 read_fwf로 붙이면 되고, 대부분의 자동매매 봇은 코드·이름·시장 구분 세 개면 충분합니다.

import pandas as pd

TAIL_LEN = {"kospi": 228, "kosdaq": 222}   # ← 시장마다 다르다

def parse_mst(path: str, market: str) -> pd.DataFrame:
    n = TAIL_LEN[market]
    rows = []
    # 인코딩 고정: cp949 (UTF-8로 열면 UnicodeDecodeError)
    with open(path, mode="r", encoding="cp949") as f:
        for line in f:
            row = line.rstrip("\n")
            if len(row) <= n:          # 빈 줄·꼬리 방어
                continue
            head = row[0:len(row) - n]  # 앞쪽 가변 구간
            rows.append({
                "code"  : head[0:9].strip(),    # 단축코드 → 공백 제거 필수
                "isin"  : head[9:21].strip(),   # 표준코드
                "name"  : head[21:].strip(),    # 한글 종목명
                "market": market.upper(),
            })
    return pd.DataFrame(rows)

kospi  = parse_mst(download_mst("kospi"),  "kospi")
kosdaq = parse_mst(download_mst("kosdaq"), "kosdaq")
universe = pd.concat([kospi, kosdaq], ignore_index=True)

print(len(universe))
print(universe[universe["name"] == "삼성전자"])

결과는 이렇게 나옵니다.

       code          isin    name market
1234  005930  KR7005930003  삼성전자  KOSPI

4. 함정 3가지 — cp949 · 자리수 · 코드 두 종류

함정 ① 인코딩이 cp949다

open(path)를 그냥 부르면 파이썬은 환경 기본 인코딩(요즘은 대개 UTF-8)으로 읽으려 하고, 곧바로 이런 예외가 납니다.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xbb in position 21:
invalid start byte

encoding="cp949"를 명시하면 해결됩니다. 같은 함정이 저장할 때도 반복됩니다 — 파싱 결과를 to_csv()로 저장한 뒤 엑셀에서 열면 한글이 깨집니다. 저장은 encoding="utf-8-sig"로 하면 엑셀과 파이썬 양쪽에서 안전합니다.

universe.to_csv("universe.csv", index=False, encoding="utf-8-sig")

함정 ② 코스피 코드를 코스닥에 그대로 쓴다

가장 흔한 실수입니다. 코스피용으로 만든 파싱 함수를 그대로 코스닥에 돌리면 228과 222의 차이인 6자만큼 모든 필드가 밀립니다. 그런데 예외가 나지 않습니다. 종목명 끝에 숫자 몇 개가 붙거나 코드 앞이 잘리는 식으로 조용히 틀리기 때문에, 며칠 뒤 "왜 이 종목만 주문이 거부되지?"로 발견됩니다.

그래서 위 코드에서는 길이를 TAIL_LEN 딕셔너리 상수로 분리했습니다. 숫자를 함수 안에 박아 두면 언젠가 반드시 복사·붙여넣기 사고가 납니다. 주문 단계에서 나는 에러의 상당수가 사실은 이런 데이터 준비 단계의 오염에서 시작됩니다.

함정 ③ 코드가 두 종류다 — 단축코드 vs 표준코드

마스터 파일에는 코드가 두 개 들어 있습니다.

증권사 REST API에 실제로 넣는 것은 여섯 자리 단축코드입니다. 필드명은 증권사마다 다르므로(한국투자증권과 키움 REST API의 파라미터 이름이 서로 다릅니다) 정확한 이름은 각사 공식 개발자 문서에서 확인하십시오. 공백이 붙은 채로 보내면 대개 "해당 종목 없음" 계열 응답이 돌아오는데, 눈으로는 코드가 맞아 보여서 원인을 찾는 데 시간이 오래 걸립니다.

5. 목록을 그대로 쓰면 안 되는 이유 — 걸러야 할 것들

파싱에 성공하면 수천 줄짜리 표가 생깁니다. 그런데 여기 있는 게 전부 "우리가 생각하는 주식"은 아닙니다. 마스터 파일에는 보통주 외에도 ETF·리츠·스팩·우선주·투자회사 등이 함께 들어 있습니다. 전략이 "코스피 전 종목 모멘텀"인데 유니버스에 ETF가 섞여 있으면, 백테스트 결과는 사실상 다른 전략의 결과가 됩니다.

구분에 쓰는 것이 뒤쪽 고정폭 구간의 그룹코드 필드입니다. 다만 코드 값을 여기서 외우려 하지 마십시오 — 값 체계는 시장·시기에 따라 달라질 수 있습니다. 대신 직접 세어 보는 것이 가장 확실합니다.

# 뒤쪽 고정폭 구간에서 앞 2자리(그룹코드)만 떼어 분포를 본다
def group_code(path: str, market: str) -> pd.Series:
    n = TAIL_LEN[market]
    codes = []
    with open(path, encoding="cp949") as f:
        for line in f:
            row = line.rstrip("\n")
            if len(row) > n:
                codes.append(row[len(row) - n : len(row) - n + 2])
    return pd.Series(codes).value_counts()

print(group_code("kospi_code.mst", "kospi"))
# 값별 건수를 보고, 대표 종목 몇 개를 눈으로 확인해
# "이 값이 보통주" "이 값이 ETF"를 직접 대응시킨다

그리고 이 파일은 고정된 목록이 아닙니다. 신규 상장·상장폐지·종목명 변경이 계속 반영됩니다. 한 번 받아 두고 몇 달 쓰면 이미 없는 종목에 주문을 넣거나, 새로 상장한 종목을 영원히 못 보게 됩니다. 종목을 이름이 아니라 코드로 매칭하는 것도 같은 이유입니다 — 이름은 바뀝니다.

6. pykrx·FinanceDataReader와 무엇이 다른가

"이걸 왜 직접 파싱하나, pykrx 쓰면 한 줄인데"라고 생각하실 수 있습니다. 맞습니다. 목적이 다를 뿐입니다.

실무 권장은 둘 다 쓰되 역할을 나누는 것입니다. 주문을 보낼 증권사가 배포한 마스터 파일을 "정본"으로 삼고, pykrx·FinanceDataReader는 보조·교차검증에 씁니다. 두 목록의 종목 수가 크게 어긋나면 어느 한쪽이 깨진 것이므로, 그 자체가 좋은 알람이 됩니다. 가격 데이터 쪽 선택은 파이썬 주식 데이터 소스 비교에서 따로 다뤘습니다.

7. 봇에 붙이는 구조 — 하루 한 번 갱신 캐시

실제 봇에서는 전략이 돌 때마다 파일을 받으면 안 됩니다. 파일이 수 MB이고 내용은 하루 단위로만 바뀌므로, 장 시작 전 1회 갱신 → 로컬 캐시 → 전략은 캐시만 조회가 정석입니다.

import datetime as dt, pathlib

CACHE = pathlib.Path("cache")

def load_universe(market: str) -> pd.DataFrame:
    CACHE.mkdir(exist_ok=True)
    today = dt.date.today().isoformat()
    cached = CACHE / f"{market}_{today}.parquet"

    if cached.exists():                       # 오늘 것이 있으면 재사용
        return pd.read_parquet(cached)

    df = parse_mst(download_mst(market, str(CACHE)), market)

    # ── 최소 검증: 통과 못 하면 어제 캐시를 계속 쓴다 ──
    assert df["code"].str.len().eq(6).all(),  "단축코드 자리수 이상"
    assert len(df) > 500,                     "종목 수가 비정상적으로 적다"

    df.to_parquet(cached)
    return df

조건에 맞는 종목을 증권사 쪽에서 골라 주는 방법도 있습니다. 키움은 HTS에서 만든 검색식을 API로 불러와 편입 종목을 실시간으로 받을 수 있는데, 이 경우 유니버스를 직접 관리할 필요가 줄어듭니다. 자세한 절차는 키움 REST API 조건검색에 정리해 두었습니다.

자주 묻는 질문

KIS API에 전체 종목코드를 내려주는 엔드포인트가 있나요?

한국투자증권 KIS REST API의 조회 계열은 대부분 종목코드를 입력으로 받는 구조라, 전 종목을 훑어 주는 용도가 아닙니다. 그래서 전 종목 목록은 마스터 파일로 받습니다. 배포 주소와 파일 레이아웃은 공식 개발자센터와 공식 깃허브 저장소의 샘플 코드를 기준으로 확인하시기 바랍니다.

kospi_code.mst 파일을 열었더니 한글이 깨집니다.

인코딩이 cp949이기 때문입니다. open(path, encoding="cp949")로 읽으십시오. 저장할 때는 utf-8-sig를 쓰면 엑셀에서도 깨지지 않습니다.

단축코드와 표준코드 중 주문 API에는 무엇을 넣나요?

여섯 자리 단축코드(005930)입니다. 표준코드(KR7005930003)는 함께 들어 있지만 주문 파라미터로는 쓰지 않는 것이 일반적입니다. 파일에서 읽은 뒤 strip()으로 공백을 제거하는 것을 잊지 마십시오.

코스피 파싱 코드를 코스닥에 그대로 쓰면 되나요?

안 됩니다. 뒤쪽 고정폭 길이가 코스피 228자, 코스닥 222자로 다릅니다. 예외 없이 조용히 값이 밀리므로, 길이를 시장별 상수로 분리하고 파싱 직후 검증을 넣으십시오.

pykrx를 쓰면 마스터 파일은 안 써도 되나요?

리서치·백테스트라면 pykrx가 훨씬 간편합니다. 다만 실제 주문을 넣는 봇이라면 주문을 받을 증권사가 배포하는 목록을 기준으로 삼고, 라이브러리는 교차검증용으로 두는 조합을 권합니다.

마무리

정리하면 세 줄입니다. 전 종목 코드는 API가 아니라 kospi_code.mst.zip·kosdaq_code.mst.zip 파일로 받는다. 인코딩은 cp949, 파싱은 뒤에서 228자(코스닥 222자)를 떼고 앞쪽을 자리수로 자른다. 주문에는 공백을 지운 여섯 자리 단축코드를 넣는다.

나머지는 운영의 문제입니다 — 언제 갱신할지, 무엇을 걸러 낼지, 실패했을 때 어떻게 멈출지. 종목 목록 하나가 틀어지면 그 위에 올린 전략·주문이 전부 함께 틀어집니다.