국내주식 거래상태 조회 API 5분 정리 (관리종목·거래정지 확인)
보유 종목이 어느 날 갑자기 관리종목으로 지정되거나 거래정지에 걸린다면, 그 사실을 가장 먼저 아는 사람이 되고 싶지 않으신가요? 다행히 이 정보는 개발자라면 API로 직접 확인할 수 있습니다. 이 글에서는 목적에 따라 어떤 API를 선택해야 하는지 실무 기준으로 정리했습니다.
왜 거래상태를 API로 확인해야 할까
주식 투자를 하다 보면 정상 거래, 관리종목, 거래정지, 정리매매처럼 종목의 상태가 수시로 바뀝니다. 특히 자동매매 프로그램이나 포트폴리오 관리 툴을 직접 만드는 경우, 이 상태 값을 실시간 혹은 최소 하루 단위로 반영하지 않으면 큰 손실로 이어질 수 있습니다.
수동으로 매번 거래소 공시를 확인하는 방식은 확장성이 없습니다. 종목이 몇 개 되지 않는다면 괜찮지만, 스크리닝 대상 종목이 수백 개를 넘어가는 순간부터는 API 연동이 사실상 필수가 됩니다. 아래에서는 목적별로 활용 가능한 세 가지 축의 API를 소개합니다.
1. 한국거래소(KRX) Open API — 가장 공식적인 출처
한국거래소 정보데이터시스템에서 제공하는 API는 전 종목의 지정 내역과 시장 조치 상태를 확인할 수 있는 가장 신뢰도 높은 소스입니다.
- 제공 정보: 투자주의·투자경고 지정, 관리종목 지정, 거래정지, 상장폐지 우려 종목 등 시장 경보 및 조치 내역
- 특징: 종목별 기본 정보와 함께 조회 가능하며 정확도가 가장 높음
- 제약: 비상업적 목적(개인 연구, 개인 투자)에 한해 무료 이용 가능하므로, 상업 서비스에 활용하려면 별도 협의가 필요합니다.
투자 판단의 최종 근거로 삼아야 할 만큼 정확성이 중요하다면, 다른 API로 얻은 데이터를 KRX 정보와 교차 검증하는 것도 좋은 방법입니다.
2. 증권사 Open API — 실전 자동매매에 유리한 선택
실시간 매매 프로그램이나 시세 조회 서비스를 만든다면, 증권사가 제공하는 API가 개발 편의성과 응답 속도 면에서 가장 효율적입니다.
키움증권 Open API+
GetMasterStockState(종목코드) 함수를 호출하면 정상, 증거금 100%, 거래정지, 관리종목, 정리매매 등의 상태값이 텍스트나 코드 형태로 반환됩니다. 별도의 파일 다운로드 없이 함수 호출 한 번으로 상태를 즉시 확인할 수 있다는 점이 장점입니다.
한국투자증권 (KIS Developers)
국내 주식 종목 정보를 일괄로 내려받을 수 있는 종목 마스터(Master) 파일을 제공합니다. 이 파일의 데이터 필드에는 관리종목 여부, 거래정지 여부 등을 나타내는 상태 코드(플래그)가 포함되어 있어, 매일 아침 마스터 파일을 다운로드해 전체 종목 상태를 일괄 업데이트하는 방식으로 널리 활용됩니다. 종목 수가 많은 스크리닝 시스템을 운영한다면 이 방식이 API 호출 횟수를 크게 줄여줍니다.
3. 공공데이터포털 — 진입장벽이 가장 낮은 선택지
공공데이터포털(data.go.kr)에서 ‘금융위원회_주식시세정보’ API를 무료로 신청해 사용할 수 있습니다.
- 제공 정보: 기본 시세와 함께 일부 종목 상태 정보 제공
- 특징: 증권사 계좌 개설이나 별도 프로그램 설치 없이 REST API 형태로 웹에서 바로 테스트하고 연동 가능
빠르게 프로토타입을 만들어보고 싶거나, 아직 어떤 증권사 API를 쓸지 결정하지 못한 초기 단계라면 이 API로 먼저 구조를 잡아보는 것을 추천합니다.
목적별 API 선택 가이드
| 목적 | 추천 API |
|---|---|
| 가장 정확한 시장 조치 이력 확인 | KRX Open API |
| 자동매매/실시간 시세 연동 | 키움증권 Open API+ |
| 대량 종목 일괄 상태 업데이트 | 한국투자증권 종목 마스터 파일 |
| 빠른 프로토타이핑, 무료 REST 연동 | 공공데이터포털 |
결국 선택 기준은 하나입니다. 정확성이 최우선이면 KRX, 개발 편의성과 자동화가 최우선이면 증권사 API, 진입장벽 최소화가 목표라면 공공데이터포털입니다.
자주 묻는 질문 (FAQ)
Q. 개인 투자자도 이 API들을 쓸 수 있나요?
네, 위에서 소개한 API 대부분은 개인 개발자·투자자도 신청 후 이용할 수 있습니다. 다만 KRX API는 비상업적 목적으로 이용 범위가 제한되어 있으므로 상업적 활용 시에는 별도 확인이 필요합니다.
Q. 증권사 API를 쓰려면 꼭 그 증권사 계좌가 있어야 하나요?
대부분의 증권사 Open API는 해당 증권사 계좌 개설과 API 신청 절차를 거쳐야 이용할 수 있습니다. 계좌 개설 없이 테스트해보고 싶다면 공공데이터포털 쪽이 진입장벽이 낮습니다.
Q. 관리종목 지정 여부를 실시간으로 알림받을 수 있나요?
API 자체가 실시간 푸시를 제공하지는 않는 경우가 많아, 일정 주기로 상태를 폴링(polling)하거나 마스터 파일을 정기적으로 갱신해 변경 여부를 직접 비교하는 방식으로 구현하는 경우가 일반적입니다.
마무리 정리
- 정확성이 가장 중요하다면 KRX Open API를 기준점으로 삼으세요.
- 자동매매·실시간 연동이 목적이라면 증권사 Open API(키움증권, 한국투자증권 등)가 효율적입니다.
- 빠르게 시작하고 싶다면 공공데이터포털로 먼저 구조를 검증해보세요.
투자 자동화 도구를 직접 만들고 계신다면, 종목 상태 API와 함께 시세 조회·주문 실행 API를 어떻게 조합해서 설계할지도 함께 고민해볼 만한 주제입니다.