NH투자증권 Namuh PLUG OpenAPI 파이썬 자동매매 가이드
Namuh PLUG는 NH투자증권의 REST Open API로, REST·WebSocket과 공식 Python SDK·MCP 자료를 제공합니다. 게만아 구현 기준 연동 순서는 ① NH투자증권 계좌 → ② Namuh PLUG에서 API 키 발급 → ③ 앱키·앱시크릿·계좌번호를 설정 파일(yaml)에 입력 → ④ 테스트 파일로 조회 확인입니다. 다른 증권사와 달리 API 키가 1개만 제공되고 계좌번호 11자리를 따로 넣는다는 점이 특징입니다.
게만아 NH투자증권 공통모듈 대표 포스팅
게만아 NH투자증권 공통모듈(패키지 96번)의 준비 과정과 설정·사용 방법은 게만아 블로그의 대표 포스팅에서 설명합니다. 실제로 자동매매를 연결할 때는 이 포스팅을 먼저 읽어 주세요.
NH투자증권 공통모듈 설명 포스팅 보기 →한눈에 보기
| 방식 | REST API와 WebSocket 기반 실시간 기능을 공식 개발자 환경(Namuh PLUG)에서 제공합니다. 공식 GitHub에서 Python SDK·샘플·MCP와 AI 개발 자료도 제공합니다. |
|---|---|
| 신청 | Namuh PLUG에서 신청해 앱키와 앱시크릿 2개를 복사합니다. |
| API 키 | 키가 계정당 1개만 제공됩니다. 다계좌여도 키·시크릿 값이 같고 토큰 경로도 같아도 됩니다(게만아가 지원하는 증권사 중 NH투자증권만 이렇습니다). |
| 계좌번호 | 설정 파일에 계좌번호 11자리(REAL_ACT_NO)를 함께 입력합니다. 다계좌는 계좌번호만 계좌별로 다르게 넣습니다. |
| 허용 IP | 별도 IP 등록 없이 사용합니다. IP 등록이 필요한 곳은 토스증권과 키움증권입니다. |
| 모의투자 | 모의계좌가 자동으로 지원되는 것으로 보이며 설정 파일에 모의 URL(moapi.nhplug.com:8443)이 따로 있습니다. 다만 게만아는 모의계좌가 불안정한 경우가 많았던 경험상 모든 증권사에서 모의계좌를 잘 활용(신뢰)하지는 않습니다. |
| 지원 계좌 | 게시 시점(2026년 8월)에는 일반 계좌 중심이며, 개인연금 등 일반 계좌 외 계좌 지원은 아직인 것으로 보였습니다. 현재 지원 여부는 공식 안내를 확인하세요. |
| 게만아 연결 | Broker="NH" · 패키지 96번 · 파일 NH_Common.py, NH_API_Helper_KR.py, NH_API_Helper_US.py, 설정 파일 myNH_StockInfo.yaml, 테스트 NH_KR_Test.py·NH_US_Test.py |
| 연결 확인 | 테스트 파일에서 장 개장 여부, 잔고, 보유종목, 현재가, 캔들(GetOhlcv)을 조회하고, 시장가·지정가 주문과 주문 목록 조회는 주석을 풀어서 확인하는 구성입니다. |
| 서버 배치 | AWS 서버라면 공통모듈 3개 파일은 /var/autobot에, 설정 파일 myNH_StockInfo.yaml은 /home/ec2-user에 둡니다. 서버가 없어도 내 PC를 계속 켜두고 주기 실행을 설정하면 자동매매가 가능합니다. |
파이썬 자동매매 연동 순서
- NH투자증권 계좌를 준비합니다.
- Namuh PLUG에서 API 키를 신청해 앱키와 앱시크릿을 복사합니다.
myNH_StockInfo.yaml에 앱키·앱시크릿과 계좌번호 11자리를 입력합니다.NH_KR_Test.py,NH_US_Test.py로 조회부터 확인합니다.- 봇의
Broker를"NH"로,accountMode를"REAL"로 바꾸고, 주문은 가장 작은 수량으로 먼저 확인합니다.
설정 파일(myNH_StockInfo.yaml)은 이렇게 채웁니다
NH투자증권은 계좌번호 11자리(REAL_ACT_NO)도 함께 넣습니다. 계좌가 여러 개라면 REAL2, REAL3를 복사해 계좌번호만 바꿉니다.
# 실계좌 정보
REAL_APP_KEY: '' # 실계좌 앱키
REAL_APP_SECRET: '' # 실계좌 앱시크릿
REAL_TOKEN_PATH: './nh_token.json'
REAL_ACT_NO: '' # 실계좌 계좌번호 11자리
# 멀티계좌 확장 예시
REAL2_APP_KEY: ''
REAL2_APP_SECRET: ''
REAL2_TOKEN_PATH: './nh_token.json'
REAL2_ACT_NO: ''
# 운영 / 인증 URL
REAL_URL: 'https://api.nhplug.com:8443'
AUTH_URL: 'https://api.nhplug.com:8443'
# 모의투자
VIRTUAL_APP_KEY: ''
VIRTUAL_APP_SECRET: ''
VIRTUAL_TOKEN_PATH: './nh_token.json'
VIRTUAL_ACT_NO: ''
VIRTUAL_URL: 'https://moapi.nhplug.com:8443'다른 증권사와 다른 점: NH투자증권은 API 키가 단 1개만 제공됩니다. 그래서 다계좌여도 REAL_APP_KEY·SECRET과 REAL2_APP_KEY·SECRET에 들어갈 값이 정확히 같고, 토큰 경로도 같아도 상관없습니다. 게만아가 지원하는 증권사 중 NH투자증권만 이렇습니다.
게만아 공통모듈로 쓰면
NH투자증권 공통모듈도 다른 증권사와 같은 파일 구조(NH_Common, NH_API_Helper_KR, NH_API_Helper_US, myNH_StockInfo.yaml)로 만들었습니다. 그래서 패키지의 주식 봇은 상단의 증권사 설정만 바꿔 NH투자증권 계좌에서 운용할 수 있습니다. 다운로드한 공통모듈과 봇을 한 폴더에 두면 내 PC에서도 바로 동작합니다.
Broker = "NH" # 증권사 선택(KIS / DBI / LS / KIW / TOSS / KB / NH / MR)
Market = "KR" # KR=국내주식 / US=미국주식 (국내상장 전용 봇은 바꾸지 마세요)
accountMode = "REAL" # yaml 설정의 계좌명(REAL·REAL2·REAL3 등)다른 증권사 공통모듈과 같은 구조라서 같은 봇을 증권사만 바꿔 쓸 수 있습니다. 한국투자·LS·키움·토스·KB증권에서 쓰던 봇도 Broker 값만 바꾸면 NH투자증권으로 옮길 수 있습니다.
실전에서 주의할 점
- API 키가 1개뿐입니다. 다계좌에서도 키·시크릿은 같은 값을 넣고, 계좌는
REAL_ACT_NO(계좌번호 11자리)로 구분합니다. - 계좌번호를 빠뜨리지 마세요. NH투자증권은 앱키만으로 계좌가 정해지지 않으므로 매매할 계좌번호를 설정 파일에 넣어야 합니다.
- 시장가 주문도 체결이 지연될 수 있습니다. 테스트 코드는 3초 쉬어주지만 3초 후 체결 완료를 보장하지는 않으니, 주문 직후 바로 후속 주문을 내는 코드는 주의하세요.
- 게시 시점에는 일반 계좌 중심이었습니다. 개인연금 등 다른 계좌의 자동매매를 계획한다면 현재 지원 여부를 공식 안내에서 먼저 확인하세요.
- 앱키·시크릿·계좌번호가 담긴 설정 파일은 다른 사람과 공유하거나 공개 저장소에 올리지 마세요. 노출됐다면 폐기 후 재발급하세요.
자주 묻는 질문
NH투자증권 API 키는 몇 개 발급되나요?
게만아 구현 기준으로 키가 1개만 제공됩니다. 그래서 다계좌 설정에서도 REAL_APP_KEY·SECRET과 REAL2_APP_KEY·SECRET에 같은 값을 넣고, 토큰 경로도 같아도 됩니다. 게만아가 지원하는 증권사 중 NH투자증권만 이렇습니다.
NH투자증권 설정 파일에는 왜 계좌번호가 필요한가요?
앱키 하나로 여러 계좌를 다루기 때문에 매매할 계좌를 계좌번호로 정합니다. 설정 파일의 REAL_ACT_NO에 계좌번호 11자리를 넣고, 다계좌는 REAL2_ACT_NO처럼 계좌별로 입력합니다.
NH투자증권 API는 어디에서 신청하나요?
Namuh PLUG(nhplug.com)에서 신청합니다. 발급받은 앱키와 앱시크릿 2개를 복사해 설정 파일에 넣으면 됩니다.
NH투자증권도 모의투자로 테스트할 수 있나요?
모의계좌가 자동으로 지원되는 것으로 보이고 설정 파일에 모의 URL이 따로 있습니다. 다만 게만아는 모의계좌가 불안정한 경우가 많아 모든 증권사에서 모의계좌를 크게 신뢰하지 않고, 조회부터 확인한 뒤 실계좌에서 최소 수량으로 검증하는 편입니다.
NH투자증권 API로 연금계좌도 자동매매할 수 있나요?
게만아 포스팅 게시 시점(2026년 8월)에는 개인연금 등 일반 계좌 외 계좌 지원은 아직인 것으로 보였습니다. 현재 상태는 NH투자증권 공식 안내에서 확인하세요.
NH투자증권 API는 IP를 등록해야 하나요?
게만아 구현 기준으로 별도 IP 등록 없이 사용합니다. IP 등록이 필요한 곳은 토스증권과 키움증권입니다.
근거와 확인 시점
이 페이지는 게만아의 NH투자증권 공통모듈 구현 포스팅(2026-08-14 게시)에서 직접 구현·운용하며 확인한 내용과 Namuh PLUG 공식 개발 환경 안내를 정리한 것입니다. 지원 계좌·정책은 바뀔 수 있어 이후 변경은 반영되지 않았을 수 있습니다. API 사양과 정책은 바뀔 수 있으므로 키 발급과 실제 주문 전에 공식 문서의 최신 내용을 확인하세요.
공식 자료: Namuh PLUG · PLUG 공식 GitHub
함께 보기
KB증권 Open API · 메리츠증권 Open API · 한국투자증권 Open API · 무료 Starter로 먼저 체험하기 · 게만아 패키지 · API가 처음이라면 용어 풀이
API 보안
발급받은 API 키·Secret·접근토큰은 비밀번호와 같은 민감한 정보입니다. 다른 사람에게 보이거나 공개적으로 노출되지 않게 주의하고, 노출됐다면 폐기·재발급하는 것이 안전합니다.
문서 업데이트: 2026-10-16 · 교육·기술 정보 제공 목적이며 투자 권유가 아닙니다.