NH투자증권 REST Open API(NHPLUG)의 공식 개발자 지원 계정입니다. 국내·해외 주식, 파생, 채권, 금현물의 시세·계좌·주문 API를 코드와 AI 도구로 쉽게 쓰도록 라이브러리·샘플·명세를 제공합니다.

🔗 포털 — 나무 www.nhplug.com · N2 www.n2plug.com  ·  ✉️ apisupport@nhsec.com

1. 앱키·앱시크릿 발급 — 포털에서 신청하세요. 모든 API 호출에 필요합니다.

    나무 → www.nhplug.com/intro  ·  N2 → www.n2plug.com/intro

2. 실행 환경 — 아래 중 쓰실 것만 준비하시면 됩니다.

세 가지는 경쟁이 아니라 단계입니다. 대화로 확인해 보고 → 예제로 익히고 → 내 프로그램에 넣는 흐름이 자연스럽습니다.

⚠️ 별도 설정이 없으면 운영에 접속합니다. 시세·잔고 조회는 그대로 쓰시면 되고, 주문 코드를 개발·테스트할 때는 모의투자(moapi)로 전환해서 진행하세요.

전환은 NHPLUG_BASE_URL 한 줄입니다.

NHPLUG_BASE_URL=https://moapi.nhplug.com:8443

접근토큰(/oauth2/token)은 운영 전용이라 NHPLUG_AUTH_URL 은 그대로 두세요. 호출이 모의투자여도 토큰은 운영에서 발급됩니다.

Claude Desktop 설정에 붙여넣고 완전히 종료 후 재실행하세요.

{ "mcpServers": { "nhplug": {
  "command": "npx", "args": ["-y", "github:PLUG-OpenAPI/nhplug-mcp"],
  "env": { "NHPLUG_APP_KEY": "발급받은_APP_KEY", "NHPLUG_APP_SECRET": "발급받은_APP_SECRET" }
} } }

Claude에게 "삼성전자 현재가 알려줘" 라고 하면 시세가 나옵니다.

개발·테스트용 모의투자로 붙이려면 env 에 한 줄을 추가하세요 — "NHPLUG_BASE_URL": "https://moapi.nhplug.com:8443" MCP 는 안전 기본값으로 주문 도구가 꺼져 있습니다(NHPLUG_ENABLE_TRADING=false).

pip install nhplug

from nhplug import call
from nhplug.instruments import load_master

call("/krstock/quote/v1/currentPrice", {"iem_cd": "005930", "market_cd": "KRX"})
load_master("m_new_stock")     # 전 종목 마스터 (자동 다운로드·캐시)

인증·토큰 캐시(24시간)·에러 판정이 모두 포함되어 있어 직접 짜실 필요가 없습니다.

🔒 접속 주소에 오타가 있으면 호출하기 전에 막고 비슷한 이름을 알려줍니다. 앱키·시크릿이 엉뚱한 서버로 전송되는 것을 방지합니다.

git clone https://github.com/PLUG-OpenAPI/nhplug-sdk
cd nhplug-sdk && cp .env.example .env    # .env 에 앱키/시크릿 입력
python snippets/krstock/current_price/chk_current_price.py

✅ 삼성전자 231,000원        ← 예시. 실제 시세가 출력됩니다

이렇게 나오면 준비 완료입니다.

1. 명세 정본 — llms.txt (N2: n2plug.com/llms.txt) 전체 문맥이 한 번에 필요하면 llms-full.txt (약 160KB)
2. 규칙 파일 — templates/ 를 프로젝트에 넣으세요 Antigravity·Codex → AGENTS.md · Claude Code → CLAUDE.md · Cursor → .cursor/rules/nhplug.mdc
3. IDE 가이드 — Antigravity·Cursor 로 바이브코딩하기
4. ⚠️ 호출 식별자 주의 — Python SDK 는 URI 경로(/krstock/quote/v1/currentPrice), MCP 는 operationId(krstockQuoteCurrentPrice). 섞어 쓰면 동작하지 않습니다.

전 종목 코드·종목명·업종·지수편입 등 정적 종목정보는 REST API 가 아니라 마스터 파일(.mst) 로 제공합니다. 28종(국내·해외주식, 국내선물옵션, 해외파생, 장내채권).

• 마스터 파일 — https://www.nhplug.com/instruments/<파일명>.mst (N2: www.n2plug.com)
• 구조체 정의 — https://www.nhplug.com/instruments/<파일명>.h 마스터와 1:1 대응(m_new_stock.mst → m_new_stock.h) · 오프셋·길이·코드값 · 파이썬 파서 코드 내장
• 둘 다 인증 불필요 — 토큰·헤더 없이 공개 다운로드
• 파이썬으로 바로 쓰기 — pip install "nhplug[instruments]" → load_master("m_new_stock") 파서가 위 구조체 파일을 자동으로 받아 쓰므로, 구조가 개정돼도 패키지를 업데이트할 필요가 없습니다.

대화형 AI 는 안전정책상 실제 주문을 대신 체결하지 않습니다. MCP 는 조회·분석·주문 준비까지 담당하고, 실제 매수/매도는 코드(SDK) 로 실행하는 구성을 권장합니다.

나무(Namuh)=nhplug.com / N2=n2plug.com. API·저장소·패키지는 공용이며 접속 도메인만 다릅니다. 본인 브랜드의 도메인과 키를 사용하세요.

N2 고객은 .env 의 세 줄(NHPLUG_BASE_URL·NHPLUG_AUTH_URL·NHPLUG_INSTRUMENTS_BASE)을 모두 n2plug 로 바꾸세요. 하나라도 빠지면 그 기능만 조용히 나무 도메인으로 갑니다.

공식 여부 확인: 이 계정과 저장소는 포털에서 상호 링크됩니다. 앱키/앱시크릿은 계좌 접근 권한이므로 반드시 포털에서 발급한 자격증명만 사용하세요.

_{⚠️ 자동매매·주문 기능은 실제 손실이 발생할 수 있습니다. 반드시 모의투자(moapi) 환경에서 검증한 뒤 사용하시고, 실거래 적용은 이용자 책임입니다. · MIT License · © NH Investment & Securities Co., Ltd.}