AI가 '안 된다'고 했다 — 상식 한마디로 뒤집힌 키움 미국주식 API 조사기

단순한 질문에서 시작했다

시작은 단순한 질문이었다. "키움증권 REST API로 미국주식 계좌 상황(잔고·예수금)을 내 프로그램과 연동할 수 있을까?" 자동매매 시스템을 만들다 보면 결국 "지금 내 계좌에 뭐가 얼마나 있나"를 코드로 읽어와야 하는데, 국내주식이 아니라 미국주식이 되는지가 관건이었다.

이런 "지금 되는지"류 질문은 AI에게 맡기기 좋다. 방대한 문서를 빠르게 뒤지는 건 사람보다 훨씬 낫기 때문이다. 그래서 조사를 맡겼다. 그리고 그 결과가, 이 글을 쓰게 만든 사건이 됐다.

AI의 첫 결론: "미국주식 잔고 조회는 없습니다"

터미널에서 돌아가는 Claude Code에게 조사를 맡겼다. Claude Code는 키움의 공식 GitHub 저장소에 올라온 API 명세 파일(JSON)을 내려받아, 그 안의 200개가 넘는 API를 전수조사했다. 결과는 명확해 보였다 — 카테고리가 국내주식과 인증(OAuth)뿐이라, "미국주식 종목별 잔고 조회는 지원하지 않는다"는 결론이었다. 근거(공식 저장소의 스펙 파일)가 구체적이었기 때문에, 꽤 확신에 찬 답이었다.

솔직히 그 답을 그대로 믿고 다른 증권사 API로 갈아탈 뻔했다.

그런데 상식이 걸렸다

한 가지가 마음에 걸렸다. 그래서 되물었다.

> "해외주식 거래를 오픈했으면서, 잔고 조회를 안 열었다고?"

이게 방향을 튼 지점이었다. 주문을 넣을 수 있게 API를 열어놓고 정작 내 잔고는 못 보게 막아둔다는 건, 상식적으로 앞뒤가 안 맞았다. 증권사 입장에서도, 개발자 입장에서도 그럴 이유가 없다. AI는 "공식 GitHub이니 최신이겠지"라고 넘겨짚었던 것이고, 나는 그 전제 자체를 의심한 것이다.

돌이켜보면 이건 데이터로 반박한 게 아니라 상식으로 반박한 것이다. 그리고 그런 종류의 의심은, 아직 AI보다 사람이 잘한다.

진짜는 원본에 있었다

그래서 저장소가 아니라 실제 포털을 직접 봐야 했다. 그런데 여기서 도구를 바꿔야 했다. 터미널에서 도는 Claude Code는 명세 파일 같은 텍스트는 잘 다루지만, 렌더링된 웹페이지를 사람처럼 눈으로 볼 수는 없기 때문이다. 그래서 브라우저에 직접 붙어 화면을 보는 Claude in Chrome으로 전환했다.

Claude in Chrome으로 키움 API 공식 사이트를 열자, 헤드라인부터가 "키움 미국주식 REST API"였다. 공지사항에는 "REST API 미국주식 신규 지원 안내"가 있었고, 날짜는 불과 2주 전이었다. 공식 GitHub 저장소가 아직 이 업데이트를 반영하지 못하고 있었던 것이다.

가이드를 열어보니 국내주식과 나란히 미국주식 카테고리가 있었고, 그 아래 계좌·주문·환전·시세가 전부 있었다. 원장 잔고 확인, 예수금 상세 같은 — 내가 처음부터 찾던 바로 그 기능들이 실제로 존재했다. 잔고 응답에는 종목별 보유수량·평가금액·손익이 원화 환산까지 포함돼 나온다는 것도 확인할 수 있었다.

AI가 "없다"고 단언했던 기능이, 사실은 2주 전에 열려 있었다.

왜 AI가 틀렸나 — 스테일 소스의 함정

AI가 무능해서 틀린 게 아니다. AI는 "구체적인 근거가 있는 소스"(공식 저장소의 스펙 파일)를 신뢰했는데, 하필 그 소스가 최신이 아니었다. 공식이라는 라벨이 최신을 보장하지는 않는다. GitHub 저장소는 사람이 수동으로 업데이트하는 경우가 많아서, 포털의 실제 서비스보다 늦을 수 있다.

이건 자동매매를 만들 때 계속 마주치는 문제와 같은 종류다. "그럴듯한 근거가 있는 틀린 답"은 "근거 없는 틀린 답"보다 오히려 위험하다. 확신을 주기 때문이다. 그래서 결정적인 사실은 항상 1차 원본(여기서는 실제 서비스 포털과 공식 문서)에서 다시 확인해야 한다.

정찰과 코딩은 다른 도구로

한 가지 더 배운 게 있다. 이 조사에서 도구를 두 종류로 나눠 쓴 게 유효했다. 로그인 화면이나 자바스크립트로 그려지는 페이지 뒤를 봐야 할 때는 브라우저에 붙는 Claude in Chrome이 필요했다 — 실제 렌더링된 화면과 캡처, 페이지가 어떻게 동작하는지를 직접 볼 수 있었다. 반대로 한번 구조를 파악한 뒤 그 내용을 정리하고 코드로 굳히는 일은 터미널의 Claude Code가 맞았다. "눈으로 확인하는 일"과 "텍스트·코드를 다루는 일"을 각각 잘하는 쪽에 맡긴 셈이다. 하나의 만능 도구를 찾기보다, 일의 성격에 맞는 도구로 갈아타는 게 더 빨랐다.

확보한 뒤엔, 다시 쓸 수 있게

한 번 확인하고 끝내지 않았다. 앞으로 이 API를 코드로 다룰 때마다 매번 문서를 뒤지지 않도록, 확인한 내용을 체계적으로 정리해 재사용 가능한 형태로 묶어뒀다. 특히 주문 관련 기능에는 안전장치를 넣었다 — 예를 들어 주문 유형(시장가·지정가)에 따라 주문 단가를 넣어야 하는지 말아야 하는지가 갈리는 함정이 있어서, 이런 조건을 규칙으로 명시하고 실행 전 사람 확인·모의투자 기본값·드라이런(실제 주문 없이 시험) 같은 장치를 함께 걸어뒀다. 이 부분은 이전 글들에서 다룬 리스크 관리·안전장치 원칙과 그대로 이어진다.

오늘의 정리

AI가 "안 된다"고 단언할 때, 그게 상식과 어긋나면 전제를 의심해봐야 한다. 이번엔 그 의심 하나가 방향을 완전히 바꿨다.
공식 저장소조차 최신이 아닐 수 있다. 결정적인 사실은 1차 원본에서 다시 확인한다.
빠른 조사·전수 확인은 AI가, "이게 말이 되나?"라는 판단은 사람이 — 이 분업이 이번 조사의 핵심이었다.

AI에게 일을 맡긴다는 건 판단까지 통째로 넘긴다는 뜻이 아니다. AI가 캐 온 사실을 사람이 상식으로 검증하고 방향을 트는, 그 왕복이 실제로 작동하는 방식이다.

이 글은 익명의 1인 운영자가 AI 도구를 활용해 공개된 API 문서를 조사한 경험을 정리한 것으로, 실제 계좌번호·API 키·개인 정보나 운영 중인 시스템의 내부 상세는 담고 있지 않습니다. API의 구체적인 사용법과 최신 사양은 반드시 해당 증권사의 공식 개발자 문서를 기준으로 확인하시기 바랍니다. 이 글은 투자 조언이 아니며 특정 종목이나 매매기법을 추천하지 않습니다. 투자 손실에 대한 책임은 투자자 본인에게 있습니다.