키움증권
트레이딩뷰 얼러트로 키움증권 계좌의 국내 주식(코스피·코스닥)과 미국 주식(나스닥·뉴욕·아멕스)을 자동매매하는 방법. 키움 REST API 신청, 계좌번호·App Key 등록, 모의투자 연습, 주식 주문메시지 예시와 주의사항을 정리했습니다.
트레이딩뷰 얼러트가 울리면 TVExtBot이 키움증권 계좌로 주문을 보냅니다. API키 연결 → 주문메시지 작성 → 얼러트 설정 순서로 진행하세요.
바로 찾기: 지원 범위 · 설정 순서 · 장외 거래 · 시장가·지정가 · 자동 취소 · 문제 해결
지원 범위
| 거래 대상 | 주문 방식 | 장외 거래 |
|---|---|---|
| 국내 주식: 코스피·코스닥 | 시장가·지정가 | 실전 계좌의 NXT 지원 종목만 가능 |
| 미국 주식: 나스닥·뉴욕·아멕스 | 시장가·지정가 | TVExtBot의 장외 거래 옵션 미지원 |
모의투자: kiwoom-testnet | 국내 주식 시장가·지정가 | NXT·미국 주식 미지원 |
주문수량은 주식 수, 주문가능 잔액·수량 대비 %, 총자산 대비 % 중에서 고릅니다.
amount: 1은 1주입니다. 매도할 때 다른 주문에 묶인 수량은 주문가능수량에서 빠질 수 있습니다. → 수량 입력 방법
설정 순서
API키 발급·등록
거래소 API 발급 방법의 키움증권 항목을 펼칩니다. 신청 → IP·계좌 등록 → 키 발급 → 확장프로그램 등록 순서로 진행합니다. 모의투자 연결 방법도 같은 항목에 있습니다.
트레이딩뷰 연결·결과 확인
만든 메시지와 웹훅 URL을 얼러트에 넣습니다. → 얼러트 설정 순서 실행 후 TVExtBot 주문내역·에러 메시지와 증권사 체결내역을 확인합니다.
장외 거래 (정규장 밖 주문)
「메시지 작성」 → 실행 조건 → 장외 거래를 켭니다. 주문메시지에 "extended_hours":true가 들어갑니다.
아래 시간은 모두 한국시간입니다.
| 시장 | 주문 시간 | 알아둘 점 |
|---|---|---|
| 국내 NXT 프리마켓 | 08:00–08:50 | 실전 계좌·NXT 지원 종목만 |
| 국내 NXT 애프터마켓 | 15:30–20:00 | 주문은 15:30부터, 체결은 15:40부터 |
미국 주식에는 적용하지 않습니다. 키움의 「장외 거래」 체크는 실전 국내 주문에서만 사용할 수 있습니다. 키움 미국 주문은 기존 주문 경로로 처리합니다.
- 정규장에는 기존 주문 방식으로 처리합니다.
- 모의투자에서는 장외 거래를 사용할 수 없습니다.
- NXT 미지원 종목은 주문하지 않으며, KRX 장외시장으로 자동 전환하지 않습니다.
- 휴장·거래정지·증권사 운영 조건 때문에 주문이 거부될 수 있습니다.
시장가와 지정가
| 주문할 때 선택 | 실제 처리 |
|---|---|
| 국내 정규장 시장가 | 기존 시장가 주문 |
| 국내 NXT 시장가 | 1호가 기준 시장성 지정가로 제출 |
| 미국 시장가 | 키움 미국 시장가 주문으로 제출 |
| 지정가 | 지정한 가격 또는 LAST·BID·ASK 기준 가격으로 제출 |
시장성 지정가는 바로 체결되도록 매수는 조금 높게, 매도는 조금 낮게 가격을 정하는 방식입니다. 그래도 가격이 범위를 벗어나면 미체결로 남을 수 있습니다.
- 허용 폭: 0–5%, 비워 두면 0.5%. 매수는 매도 1호가에 더하고, 매도는 매수 1호가에서 뺍니다.
- 주문을 보내지 않는 경우: 1호가 미수신, 매수·매도 호가 차이 2% 초과. 국내 시장성 지정가는 상·하한가를 못 받아도 주문하지 않습니다.
- 국내 가격 제한: 시장성 지정가는 호가 단위와 상·하한가에 맞춰 조정합니다.
예를 들어 매수 지정가가 16,530원이어도 더 유리한 호가에 체결되면 실제 체결가는 16,440원일 수 있습니다. 지정가는 매수 때 낼 가격의 상한이지, 꼭 그 가격에 체결된다는 뜻이 아닙니다.
기록된 체결가
- 체결가를 조회하면 실제 체결가를 기록하고, 지정가와 다르면 알림에 나눠 보여 줍니다.
- 조회하지 못하면 지정가로 기록합니다. 기록된 가격만 보고 체결을 확정하지 마세요.
- 체결가는 주문 직후 한 번만 조회합니다. 그 뒤에 체결되거나 나머지가 체결되면 최종 체결가와 다를 수 있습니다.
- 최종 확인은 증권사 체결내역에서 하세요.
미체결 자동 취소
「실행 조건 → 미체결 자동 취소」에 1–600초의 정수를 넣습니다. 60초로 정하면 주문 접수 60초 뒤에 남은 수량을 취소합니다. 실제 취소는 처리 상황에 따라 조금 늦을 수 있습니다.
실전·모의 일반 지정가(조건주문 제외)와 실전 국내 NXT 시장성 지정가가 대상입니다. 키움 미국 시장가에는 적용하지 않습니다.
| 상황 | 처리 |
|---|---|
| 전부 미체결 | 남은 주문 전량 취소 |
| 일부 체결 | 체결분 유지, 미체결분만 취소 |
| 바로 주문·퀵주문 | 자동 취소 옵션 적용 안 됨 |
| 취소 실패·상태 확인 실패 | 증권사 앱에서 미체결 확인 및 직접 취소 필요 |
정상 취소는 텔레그램 안내(ℹ️)로만 알립니다. 에러 메시지 목록에는 남지 않습니다. 취소 실패·상태 확인 실패는 텔레그램과 에러 메시지 목록 모두에 남습니다.
「미체결 먼저 취소」와 다릅니다
- 미체결 먼저 취소: 새 주문을 내기 전에 기존 주문을 취소합니다.
- 미체결 자동 취소: 이번 새 주문의 미체결을 나중에 취소합니다.
「미체결 먼저 취소」를 시장가(시장성 지정가)와 함께 쓰면, 기존 주문을 취소하기 전에 호가부터 확인합니다. 호가 때문에 주문할 수 없으면 기존 주문을 그대로 둡니다.
그래도 취소 뒤에 호가가 바뀌거나 다른 이유로 새 주문이 거부되면 기존 주문만 취소되고 새 주문은 없을 수 있습니다.
- 호가 때문에 거부되면 오류 안내에 「기존 미체결 주문은 이미 취소됐습니다」가 붙습니다.
- 수량 부족·증권사 거부 같은 다른 이유에는 붙지 않습니다.
「미체결 먼저 취소」를 쓴 주문이 실패하면 증권사 앱에서 기존 주문이 남았는지 확인하세요.
주문메시지 예시
삼성전자 10주 시장가 매수
TVM:{"exchange":"kiwoom","account":"계좌번호","symbol":"005930/KOSPI","type":"market","side":"buy","amount":10,"token":"인증키"}:MVT테슬라 보유 수량의 50%를 시장가 매도 (미국 주식)
TVM:{"exchange":"kiwoom","account":"계좌번호","symbol":"TSLA/NASD","type":"market","side":"sell","bal_pct":50,"token":"인증키"}:MVT모의투자 계좌에서 카카오 5주 지정가 매수 (마지막 체결가)
TVM:{"exchange":"kiwoom-testnet","account":"계좌번호","symbol":"035720/KOSPI","type":"limit","side":"buy","amount":5,"price":"last","token":"인증키"}:MVT예시는 형식만 보여 줍니다
종목은 종목코드/시장 형식입니다.
실제 메시지는 확장프로그램 「메시지 작성」에서 만드세요.
항목의 뜻은 주문메시지 항목 설명에 있습니다.
주문이 예상과 다를 때
| 증상 | 먼저 확인할 것 |
|---|---|
| 계좌가 연결되지 않음 | 실전·모의 키 구분, 계좌번호, 키 입력값·허용 IP |
| 주문되지 않음 | 「주문 허용」 스위치, 거래 시간·휴장 여부, 주문가능 잔액·수량 |
| 시장가인데 지정가로 보임 | 위 주문 방식 표의 시장성 지정가 대상인지 확인 |
| 주문 성공인데 미체결 | 지정가 범위 밖인지 확인. 주문 접수 성공은 체결 완료와 다름 |
| 자동 취소 안내가 없음 | 얼러트 주문인지, 지원 주문인지, 실제 미체결 상태인지 확인 |
더 많은 대처 방법은 주문이 안 될 때에 있습니다.