nhplug

NH투자증권 Open API 개발 규칙

SDK 를 쓴다 — 직접 HTTP 를 짜지 않는다

pip install nhplug                 # 인증·토큰캐시·에러판정·실시간·종목마스터 포함
pip install "nhplug[instruments]"  # 마스터를 DataFrame 으로 받을 때

from nhplug import call, NhplugError
call("/krstock/quote/v1/currentPrice", {"iem_cd": "005930", "market_cd": "KRX"})

토큰 발급·갱신·캐시, Input_0 봉투, 인증 헤더, 연속조회, 유량 제어를 call() 이 처리한다. 업무 성공/실패는 판정하지 않는다 — 아래 「에러 처리」 참조. requests 로 /oauth2/token 을 직접 부르는 코드를 새로 만들지 말 것.

명세 정본 — 도메인

• https://www.nhplug.com/llms.txt (N2: https://www.n2plug.com/llms.txt)
• 자산군: https://www.nhplug.com/openapi-docs/<자산>/openapi.json (common·krstock·gbstock·krfuture·gbfuture·krbond·krgold)
• 경로·필드명·필수여부는 openapi.json 이 정본. 추측 금지.

설정 (.env)

NHPLUG_APP_KEY=...
NHPLUG_APP_SECRET=...
NHPLUG_BASE_URL=https://api.nhplug.com:8443    # 모의투자: moapi.nhplug.com:8443
NHPLUG_AUTH_URL=https://api.nhplug.com:8443    # 토큰은 운영 전용
NHPLUG_INSTRUMENTS_BASE=https://www.nhplug.com/instruments

키는 코드에 하드코딩 금지. .env 는 .gitignore. N2 고객은 위 세 줄을 모두 n2plug 로 — 하나라도 빠지면 그 기능만 조용히 나무로 간다.

호출 규약

• 요청 {"Input_0": {...}} / 응답 Output_0(+Output_1) + rsp_cd·rsp_msg
• Output_0 은 객체일 수도 배열일 수도 있다. 타입을 추측하지 말고 openapi.json 확인.
• 계좌목록 POST /n2/acctinfo → Output_0[].acct_no 를 이후 act_no 로 사용.

⚠️ 성공 판정 — HTTP 200 ≠ 업무 성공

• 🔴 SDK 는 업무 성공/실패를 판정하지 않는다. 기준은 HTTP 상태코드 하나다. HTTP 200 → 응답 본문 그대로 반환(예외 없음) / 200 아님 → NhplugError(본문은 .raw 에 원문).
• 🔴 rsp_msg 문장을 읽고 판단한다. 같은 rsp_cd 값이 API 에 따라 정상일 수도 오류일 수도 있어 어떤 코드 목록도 기준이 될 수 없다. status_of(data) 로 (rsp_cd, rsp_msg) 를 꺼낸다(판정 아님).
• ⚠️ if rsp_cd == "00000" 같은 코드를 절대 쓰지 말 것. 코드값 비교는 API 를 바꾸면 무너진다.
• 🔴 주문 등 되돌릴 수 없는 처리 전에는 직전 응답의 rsp_msg 를 반드시 확인한다. SDK 가 막아 주지 않는다.
• ⚠️ is_success()·NHPLUG_SUCCESS_CODES·category="business" 는 0.4.0 에서 삭제됐다. 되살리지 말 것. 원본이 필요하면 call(..., raise_on_error=False).
• 429(초당 5회 초과)는 자동 재시도하지 않는다. 429 재시도에 토큰을 재발급하지 말 것(재발급은 401 에만).