KIS 체결조회 FHPST01060000 — 체결강도까지 온다

KIS 분봉 데이터를 받는 방법을 정리해 두었더니 "1분 안에서 어떻게 체결됐는지"를 묻는 문의가 따라옵니다. 체결강도, 매수·매도 어느 쪽 호가에 붙어서 체결됐는지, 큰 물량이 한 번에 나갔는지 잘게 쪼개졌는지 — 전부 분봉으로 집계되는 순간 사라지는 정보입니다.

그 층을 보는 TR이 FHPST01060000입니다. 이 글은 한국투자증권 공식 저장소 koreainvestment/open-trading-api의 examples_llm/domestic_stock/inquire_time_itemconclusion/ 예제와 API 메타데이터를 2026년 9월 20일 기준으로 읽어 정리한 것입니다.

무엇을 주는 API인가

주목할 점 하나 — 공식 예제 코드는 env_dv로 실전·모의를 받아 분기하는 모양을 하고 있지만, 두 갈래가 모두 같은 FHPST01060000을 씁니다.

# 공식 예제의 분기 — 양쪽 값이 같다
if env_dv == "real":
    tr_id = "FHPST01060000"
elif env_dv == "demo":
    tr_id = "FHPST01060000"
else:
    raise ValueError("env_dv can only be 'real' or 'demo'")

즉 이 조회에는 모의투자용 별도 TR이 없습니다. 주문 계열이 실전·모의 TR을 명확히 나누는 것과는 구조가 다릅니다 — 시세 조회는 대체로 한 TR을 공유합니다.

함정 1 — 현재가 필드명이 덩어리마다 다르다

응답은 두 덩어리입니다. output1은 객체 하나(종목 요약), output2는 배열(체결 목록)입니다. 여기서 사고가 납니다.

한글명을 기준으로 컬럼을 매핑하는 코드(엑셀 헤더를 한글로 뽑는 툴 같은 것)라면 같은 이름이 두 번 나와 덮어쓰기가 일어납니다. 덩어리별로 영문 키를 따로 고정해 두는 편이 안전합니다.

SUMMARY_KEYS = ["stck_prpr", "acml_vol", "prdy_vol", "rprs_mrkt_kor_name"]
TICK_KEYS    = ["stck_cntg_hour", "stck_pbpr",   # ← output2는 pbpr
                "askp", "bidp", "cnqn", "tday_rltv", "acml_vol"]

def parse(body):
    summary = {k: body["output1"].get(k) for k in SUMMARY_KEYS}
    ticks   = [{k: row.get(k) for k in TICK_KEYS} for row in body["output2"]]
    return summary, ticks

함정 2 — 공식 예제가 종목이 아니라 업종이다

inquire_time_itemconclusion의 docstring은 시장 분류 코드를 이렇게 안내합니다.

fid_cond_mrkt_div_code (str): [필수] 조건 시장 분류 코드 (J:KRX, NX:NXT, UN:통합)
fid_input_iscd (str)        : [필수] 입력 종목코드
fid_input_hour_1 (str)      : [필수] 입력 시간1

Example:
    >>> df1, df2 = inquire_time_itemconclusion("real", "U", "0001", "115959")

설명은 J·NX·UN 셋인데 예제는 "U"를 넣고, 종목코드 자리에는 "0001"이 들어 있습니다. 0001은 여섯 자리 종목코드가 아니라 업종 코드 형식입니다.

삼성전자 체결을 보려면 문서에 적힌 값으로 바꿔야 합니다.

# 예제를 그대로 복사하면 안 된다
df1, df2 = inquire_time_itemconclusion("real", "U", "0001", "115959")

# 종목 체결을 보려면
df1, df2 = inquire_time_itemconclusion("real", "J", "005930", "115959")
#                                               ↑ KRX    ↑ 삼성전자

함정 3 — FID_INPUT_HOUR_1이 사실상 페이지 커서다

이 TR에는 연속조회 키에 해당하는 CTX_AREA_FK100·CTX_AREA_NK100 파라미터가 없습니다. 요청 바디는 셋뿐입니다.

params = {
    "FID_COND_MRKT_DIV_CODE": fid_cond_mrkt_div_code,   # J / NX / UN
    "FID_INPUT_ISCD"        : fid_input_iscd,           # 005930
    "FID_INPUT_HOUR_1"      : fid_input_hour_1          # HHMMSS, 예: 115959
}

과거 구간을 더 보려면 FID_INPUT_HOUR_1의 시각을 뒤로 밀면서 반복 호출하는 모양이 됩니다. 한 번에 하루치를 받는 API가 아닙니다.

여기서 설계 판단이 하나 갈립니다. 하루치 전체 체결이나 여러 날의 체결을 쌓아야 한다면 이 TR로 반복 호출을 돌리는 건 호출 제한만 잡아먹습니다. 실시간으로 쌓는 쪽(H0STCNT0 주식체결가 웹소켓)이나 이미 집계된 분봉을 쓰는 편이 맞습니다. 이 TR은 "지금 이 종목이 어떻게 체결되고 있는지"를 스냅샷으로 확인하는 용도에 가깝습니다.

분봉에 없는 것 — tday_rltv와 양쪽 호가

output2의 각 행에서 분봉이 절대 주지 못하는 값은 셋입니다.

• tday_rltv — 당일 체결강도. 체결 건마다의 값이라 "이 구간에서 매수 체결이 몰렸는가"를 분 단위보다 잘게 볼 수 있습니다.
• askp·bidp — 그 체결 순간의 매도·매수호가. 체결가가 askp에 붙었는지 bidp에 붙었는지로 능동 매수인지 능동 매도인지를 가릅니다. 분봉에는 이 구분이 없습니다.
• cnqn — 건별 체결량. 같은 1분 거래량 10만 주라도 한 건에 9만 주가 나갔는지 잘게 쪼개졌는지가 완전히 다른 상황인데, 분봉은 이 둘을 같은 숫자로 보여 줍니다.

시간외는 다른 TR이다 — FHPST02310000

"장 끝나고 나서도 같은 걸로 보면 되죠?"라는 질문을 자주 받는데, 아닙니다. 시간외 체결은 주식현재가 시간외시간별체결 FHPST02310000이고 엔드포인트도 /quotations/inquire-time-overtimeconclusion으로 다릅니다.

두 가지를 주의하십시오.

① 시간외 쪽에는 NX·UN이 없습니다. KRX·NXT로 주문을 라우팅하는 봇이라면 정규장은 시장별로 나눠 볼 수 있지만 시간외는 J 하나로만 조회됩니다.

② 응답 필드가 ovtm_untp_(시간외 단일가) 접두어입니다 — ovtm_untp_prpr·ovtm_untp_antc_cnpr(예상 체결가)·ovtm_untp_vol 등. 2026-09-14 시간외 관련 제도가 바뀌면서 증권사에 따라 시간외 계열 TR이 정리된 사례가 있으므로, 이 계열을 쓰는 코드라면 현재 명세를 반드시 다시 확인하십시오.

자주 묻는 것

분봉 대신 이걸 쓰면 되나요?

용도가 다릅니다. 과거 데이터를 쌓아 백테스트하려면 분봉이나 일봉이 맞습니다. 이 TR은 지금 체결이 어떻게 붙고 있는지 확인하는 쪽입니다.

output2가 비어 있습니다.

stck_prpr로 꺼내고 있지 않은지부터 보십시오. output2의 체결가는 stck_pbpr입니다. 그다음은 FID_COND_MRKT_DIV_CODE가 예제의 "U"로 남아 있지 않은지 확인하십시오.

NXT 체결도 볼 수 있나요?

FID_COND_MRKT_DIV_CODE에 NX(NXT) 또는 UN(통합)을 넣습니다. 다만 시간외 TR FHPST02310000에는 이 값이 없습니다.

모의투자에서도 되나요?

공식 예제상 실전·모의가 같은 FHPST01060000을 씁니다. 다만 모의투자 환경에서 제한되는 항목은 별도로 있으니 실제 응답으로 확인하십시오.