# FAQ

외부 개발자 문의 중 자주 반복되는 항목을 정리했습니다. 각 API 의 정확한 요청·응답 형식은 API 문서의 해당 엔드포인트 항목이 기준입니다.

## 인증 · 접속

| 질문 | 답변 |
|---|---|
| 액세스 토큰을 여러 개 발급해 동시에 쓸 수 있나요? | 클라이언트당 유효한 토큰은 1개입니다. 새로 발급하면 직전 토큰은 즉시 무효화되어 `401 token-revoked` 로 거부됩니다. 국내·해외 주식을 별도 프로세스로 운영하더라도 하나의 토큰을 공유해 사용하세요. 프로세스마다 토큰을 따로 발급하면 서로를 무효화합니다. |
| 키를 재발급했는데 401 이 계속 발생해요 | 재발급 과정에서 예전 토큰을 계속 쓰고 있는 경우가 대부분입니다. 마지막에 발급한 `client_id`·`client_secret` 으로 토큰을 다시 발급받고, 모든 프로세스가 그 토큰만 쓰도록 맞춰 주세요. |
| 토큰 발급 단계에서 `invalid_client` 가 발생해요 | 거의 모두 `client_id`·`client_secret` 오입력입니다. WTS 설정 > Open API 화면의 복사 버튼으로 값을 복사해 사용하고, 앞뒤 공백·줄바꿈이 섞이지 않았는지, 접미사가 붙은 다른 문자열을 넣지 않았는지 확인하세요. 응답 본문의 `error_description` 에 `client_id` 와 `client_secret` 중 어느 쪽 검증이 실패했는지 표시됩니다 (예: `Client authentication failed: client_secret`). 허용 IP 설정과는 무관합니다. 401 `invalid_client` 가 아니라 400 `invalid_request` 가 온다면 값이 아니라 요청 형식의 문제입니다. `OAuth 2.0 Parameter: client_secret` 은 해당 파라미터가 누락(빈 문자열 포함)된 것이고, `Malformed client authentication` 은 Authorization 헤더 형식이나 파라미터 중복을 확인하세요. |
| 허용 IP 를 등록했는데 403 이 발생해요 | 실행할 때마다 공인 IP 가 바뀌는 환경(클라우드 인스턴스, 서버리스, 모바일 네트워크 등)이면 등록한 IP 와 실제 호출 IP 가 달라져 차단됩니다. 고정 IP 를 확보한 뒤 허용 IP 목록에 등록하세요. 클라우드·데이터센터 대역이라는 이유로 별도 차단하지는 않습니다. |
| 특정 언어·환경(예: 32비트 Python)에서만 동작하나요? | 아닙니다. 별도 설치 모듈 없이 표준 HTTPS 요청만 보낼 수 있으면 어떤 언어·아키텍처에서든 사용할 수 있습니다. |
| 호출 한도는 어떻게 확인하나요? | API 소개의 Rate Limits 섹션을 참고하세요. 성공 응답에도 `X-RateLimit-*` 헤더가 항상 포함되며 클라이언트 단위로 매초 갱신됩니다. |
| 토큰 발급 요청이 `403 edge-blocked` 로 거부돼요 | 서버 앞단에서 허용되지 않은 형식의 요청을 차단한 것입니다. `client_id`·`client_secret` 자리에 발급받은 값이 아닌 다른 문자열(예: 클립보드를 읽는 스크립트 명령문)이 들어가지 않았는지 등 실제로 전송되는 요청값을 점검한 뒤 다시 시도하세요. |
| 오류를 문의할 때 무엇을 함께 보내야 하나요? | 오류 응답의 `requestId`(응답 헤더 `X-Request-Id` 와 동일한 값) 를 함께 보내 주세요. 요청을 특정할 수 있어야 원인을 확인할 수 있습니다. 응답에 `requestId` 가 없으면 응답 헤더의 `referenceId` 또는 `x-amz-cf-id` 값을 첨부해 주세요. |

## 시세 · 캔들

| 질문 | 답변 |
|---|---|
| 국내 캔들·체결은 KRX 만 집계하나요? | KRX + NXT 통합 시세입니다. 거래소를 지정해 조회하는 파라미터나 거래소를 식별하는 응답 필드는 없습니다. NXT 에서 거래되지 않는 종목은 KRX 시세로 자동 제공됩니다. |
| 캔들의 `timestamp` 는 봉 시작 시각인가요, 종료 시각인가요? | `1m` 은 봉 종료 시각입니다. `09:01` 봉은 `09:00:00.000 ~ 09:00:59.999` 구간의 체결을 집계하며, `09:02:00` 정각 체결은 `09:03` 봉에 포함됩니다. `1d` 는 해당 거래일의 현지 자정을 한국시간으로 표기한 값입니다 (예: 미국 2026-10-05 거래일 → `2026-10-05T13:00:00+09:00`, 서머타임이 아닐 때는 `T14:00:00+09:00`). 미국 거래일은 뉴욕 시각 기준 전일 20:00 ~ 당일 20:00 입니다. |
| 시가·종가 단일가 체결은 어느 봉에 들어가나요? | 국내 기준 시가 단일가 체결(09:00)은 `09:01` 봉, 종가 단일가 체결(15:30)은 `15:31` 봉에 포함됩니다. 종가 단일가 접수 구간(15:20 ~ 15:30)은 체결이 없으므로 직전가로 채워진 거래량 0 봉이 내려갑니다. NXT 에서 거래되지 않는 종목은 종가 단일가와 장 종료 후 시간외종가(~16:00) 체결이 `15:30` 봉에 합산되어, 이 봉은 16:00 까지 바뀔 수 있습니다. |
| 국내 1분봉은 몇 시부터 몇 시까지 제공되나요? | NXT 에서 거래되는 종목은 통합 장 운영 시간인 08:01 ~ 20:00 (프리마켓 시작 ~ 애프터마켓 종료) 의 봉이 제공됩니다. NXT 에서 거래되지 않는 종목은 09:01 부터 제공되며, KRX 애프터마켓 대상 종목이면 20:00, 아니면 15:30 봉까지 제공됩니다. |
| 가격은 있는데 거래량이 0 인 봉은 무엇인가요? | 국내 1분봉에서 해당 구간에 체결이 없었다는 뜻입니다. 시가·고가·저가·종가를 직전 종가(그날 첫 체결 전에는 기준가)로 채우고 거래량만 0 으로 내려가며, 데이터 오류가 아닙니다. 장중에도 거래 임시정지·서킷브레이커·VI 발동 등으로 발생할 수 있습니다. 미국 1분봉은 체결이 없는 분의 봉을 만들지 않아 응답에 포함되지 않습니다. |
| 일봉 거래량과 1분봉 거래량 합계가 다릅니다 | 정상입니다. 두 봉은 집계 범위가 다릅니다. 일봉은 그날의 모든 매매 구분을 합산하고, 1분봉은 일부만 분 단위로 누적합니다. 국내 1분봉은 NXT 에서 거래되는 종목은 KRX 정규장(시가·종가·VI 단일가 포함)·KRX 애프터마켓·NXT 프리·메인·애프터마켓 체결을, NXT 에서 거래되지 않는 종목은 KRX 정규장·장 종료 후 시간외종가·KRX 애프터마켓 체결을 포함합니다. 장 개시 전·장 종료 후 시간외종가(NXT 거래 종목), NXT 종가매매, 대량·바스켓·경쟁대량·협의대량 매매는 일봉에만 들어갑니다. 미국 1분봉은 일부 거래소의 실시간 체결, 일봉 거래량은 종합 거래량 기준이라 원천이 다릅니다. 1분봉 합계가 일봉과 다른 것은 의도된 구조이며, 1분봉만으로 일봉을 재구성할 수 없습니다. |
| 다른 증권사 데이터와 분봉 거래량이 달라요 | 아직 끝나지 않은 분(진행 중인 봉)을 조회한 경우가 대부분입니다. 봉이 완성된 뒤 다시 조회하면 일치합니다. |
| 수정주가를 적용하면 거래량도 바뀌나요? | 바뀝니다. 국내 종목은 가격을 `가격 × 수정비율` 후 원 단위 반올림, 거래량을 `거래량 ÷ 수정비율` 후 버림으로 조정합니다. 미국 종목은 가격을 `가격 × 수정비율` 값 그대로(반올림 없음), 거래량을 `거래량 ÷ 수정비율` 후 정수로 반올림합니다. 당시 실제 체결 가격·수량이 필요하면 `adjusted=false` 로 조회하세요. 수정주가는 국내 종목은 당일 기준가가 직전 정규장 종가와 다르면 적용되고, 미국 종목은 기준가가 직전 정규장 종가와 5% 를 초과해 차이 날 때만 적용됩니다(정확히 5% 는 미적용). 분할·배당 등 기업행위의 종류는 구분하지 않으므로, 미국 종목에서 차이가 5% 이하인 현금배당·분배락은 반영되지 않습니다. |
| `adjusted=false` 인데도 과거 가격이 분할 조정된 값으로 나옵니다 | 제공 시작 이전의 과거 구간은 이미 수정주가가 반영된 데이터만 보유하고 있어, 해당 구간은 `adjusted=false` 로도 당시 원 가격을 제공하기 어렵습니다. |
| 과거 데이터는 어디까지 제공되나요? | 1분봉(`1m`)은 국내 2022-11-23 이후, 미국 2021-12-01 이후 데이터가 제공되며 그 이전 구간은 제공되지 않습니다. 일봉(`1d`)은 이 기간 제한이 적용되지 않습니다. |
| 과거 캔들이 나중에 정정되나요? | 국내 캔들의 가격·거래량을 사후에 정정하거나 동기화하는 시점은 없습니다. 미국 1분봉은 거래소의 정정·취소는 반영되지 않지만, 늦게 보고된 체결은 실제 체결 시각의 과거 봉에 반영되어 값이 바뀔 수 있습니다. 또한 액면분할·유상증자·배당락 등 기업행위가 발생하면 수정주가 기능으로 조정된 값이 보일 수 있습니다. |
| 상장폐지 종목의 과거 시세를 조회할 수 있나요? | 조회할 수 없습니다. `404 stock-not-found` 로 응답합니다. |
| 미국 시세는 전체 시장 기준인가요? | 아닙니다. 호가·최근 체결·캔들·실시간 체결/호가 모두 일부 미국 거래소의 데이터를 기준으로 하며, NBBO(전체 시장 최우선 호가) 가 아닙니다. 시점과 세션(정규장·프리/애프터·데이마켓)에 따라 데이터 원천이 다를 수 있습니다. |
| 미국 1분봉에 주변과 동떨어진 고가·저가가 하나 섞여 있어요 | 원천 체결이 그대로 반영된 것입니다. 1분봉은 그 1분 안의 모든 체결가 중 최고·최저를 그대로 쓰며 이상값을 걸러내지 않습니다. 장외·특수 체결(일반 투자자가 체결할 수 없는 거래)이 포함될 수 있고, 거래소의 정정·취소 전문은 반영되지 않습니다. 정정 여부를 알려주는 응답 필드도 없습니다. |
| 미국 일봉 종가는 정규장 기준인가요? | 네, 정규장 공식 종가입니다. 프리마켓·애프터마켓·데이마켓 체결은 일봉의 시가·고가·저가·종가에 포함되지 않습니다. 다만 거래량은 종합 거래량이라 시간외 체결이 포함될 수 있습니다. |
| 한 번에 최대 몇 건까지 받을 수 있나요? | 캔들은 최대 200 개(`before` 로 과거 페이지네이션), 최근 체결은 최대 50 건입니다. 최근 체결은 과거 방향 페이지네이션 파라미터가 없어 당일 전체 체결을 조회할 수 없습니다. |
| 국내 호가에서 매도 1호가가 매수 1호가보다 낮거나 같게 나올 수 있나요? | 나올 수 있습니다. 국내 호가(`orderbook:kr`, `GET /api/v1/orderbook`)는 KRX와 NXT 호가를 가격별로 합친 통합 호가입니다. 서로 다른 거래소의 매수·매도 호가는 서로 체결되지 않아 가격이 겹쳐도 함께 남아 있을 수 있습니다. 또 한 거래소의 갱신이 먼저 도착하면 잠깐 교차된 것처럼 보일 수도 있습니다. |
| 실시간 호가는 전체 스냅샷인가요, 변경분만 오나요? | 전체 스냅샷입니다. 실시간 호가 프레임의 `data` 는 REST 호가 조회(`GET /api/v1/orderbook`) 응답과 같은 모양이며, 매 프레임마다 그 시점의 매도호가(`asks`, 낮은 가격순)·매수호가(`bids`, 높은 가격순) 전체가 전달됩니다. 증분 갱신은 제공하지 않습니다. |
| 거래소(KRX·NXT)를 지정해 호가를 따로 조회할 수 있나요? | 지원하지 않습니다. REST·웹소켓 모두 국내 호가는 통합 호가로만 제공되며, 호가 단계별 거래소 구분 필드나 매도·매수별 갱신 시각도 응답에 없습니다. |

## 주문

| 질문 | 답변 |
|---|---|
| 조건주문에서 감시할 장(거래소)을 선택할 수 있나요? | 선택할 수 없습니다. Open API 로 등록한 조건주문은 앱의 "장 상관없이" 설정으로 감시합니다. 시장별 발동 세션은 조건주문 생성 API 의 발동 세션 설명을 참고하세요. |
| 미국 레버리지·인버스 ETF 주문이 `prerequisite-required` 로 거부돼요 | 투자자 성향 등록·위험 고지·약관 동의 등 해당 종목 거래에 필요한 사전 요건이 완료되지 않은 상태입니다. Open API 로는 등록 절차를 진행할 수 없으므로 토스증권 앱에서 해당 종목 구매 화면에 진입해 안내되는 등록 절차를 마친 뒤 다시 시도하세요. |
| 국내 주문 가능 시간이 앱과 다른가요? | 같습니다. Open API 가 별도로 제한하지 않고 매매 시스템의 주문 가능 시간을 그대로 따릅니다. 애프터마켓도 동일하게 적용되며, 주문 불가 시간에는 `422 order-hours-closed` 로 응답합니다. 세션별 시간은 장 운영 정보 조회 API 로 확인하세요. |
| 매수·매도 건수 한도가 따로 있나요? | 따로 없습니다. `ORDER` Rate Limits Group 은 매수·매도를 합산해 초당 요청 수를 계산합니다. |
| 주문이 갑자기 거부되기 시작했어요 | 짧은 시간에 대량으로 주문을 반복하면(예: 소액 주문을 수십 분 내 수백 건) 어뷰징으로 판단되어 일정 시간 매매가 제한될 수 있습니다. 반복되면 제한 기간이 연장됩니다. 주문 빈도를 조정한 뒤 다시 시도하세요. |
| 반대 방향 미체결 주문이 있으면 주문이 409 로 거부돼요 | 국내 주식에만 적용되는 제한이며 미국 주식에는 적용되지 않습니다. 동일 종목에 반대 방향의 체결 대기 주문이 남아 있으면 가격이 겹치지 않더라도 `409 opposite-pending-order-exists` 로 거부됩니다. 기존 미체결 주문을 취소하거나 체결된 뒤 다시 주문하세요. |
| 미국 주식을 소수점 수량으로 주문할 수 있나요? | 소수점 수량(`quantity`)은 미국 주식 시장가 매도(`MARKET` + `SELL`)에만 허용되며 소수점 6자리까지 지원합니다. 소수점 매수는 수량 대신 금액(`orderAmount`) 주문을 사용하세요. 금액 주문과 소수점 수량 주문은 정규장 시작부터 정규장 종료 1시간 전까지만 접수할 수 있습니다. |
| 조건주문 수정 요청의 응답을 받지 못했어요 | 수정은 기존 조건주문을 취소하고 새 조건주문을 생성하는 방식이라, 반영되면 새 `conditionalOrderId` 가 발급되고 기존 ID 는 무효화됩니다. 기존 ID 로 조건주문 상세 조회를 해서 `404` 가 오면 수정이 반영된 것이므로 목록 조회에서 새 ID 를 확인하고, 정상 조회되면 반영되지 않은 것이므로 다시 요청하세요. |
| 주문 요청의 응답을 받지 못했어요 | 주문 생성 시 `clientOrderId` 를 지정했다면 10분 안에 같은 `clientOrderId`·같은 내용으로 다시 요청하세요. 새 주문을 만들지 않고 처음 주문 결과를 그대로 반환합니다. 처음 요청이 아직 처리 중이면 `409 request-in-progress`, 같은 `clientOrderId` 로 내용을 바꿔 요청하면 `422 idempotency-key-conflict` 로 응답합니다. 10분이 지나면 같은 값이어도 새 주문으로 처리되며, `clientOrderId` 를 지정하지 않은 요청은 다시 보낼 때마다 별개 주문이 됩니다. |
| 미국 주식을 살 때 달러가 부족하면 자동으로 환전되나요? | 환전되지 않습니다. Open API 주문은 자동환전을 지원하지 않으므로 달러 주문 가능 금액이 부족하면 `422 insufficient-buying-power` 로 거부됩니다. |

## 주문 · 체결 조회

| 질문 | 답변 |
|---|---|
| 어떤 주문이 조회되나요? | 장전/장후 시간외종가 등 Open API 가 지원하지 않는 호가 유형을 제외한 모든 주문이 조회됩니다. 앱·WTS 로 낸 주문도 채널과 무관하게 포함되며, 소수점 주문·예약 주문도 포함됩니다. |
| 앱에서는 체결됐는데 조회 결과에 없어요 | 위의 미지원 호가 유형으로 접수된 주문일 가능성이 가장 큽니다. 앱에서 해당 주문의 호가 유형을 확인하세요. |
| 기간을 지정하지 않으면 어디까지 조회되나요? | 계좌 개설 이후 전체 기간이 대상입니다. `status=CLOSED` 는 한 번에 최대 100 건이며 `cursor` 로 이어서 조회합니다. `status=OPEN` 은 전량 반환합니다. |
| 체결 내역이 건별로 나오나요? | 아닙니다. 주문 1건이 1행입니다. 여러 번 나누어 체결된 주문은 평균 체결가·총 체결 수량으로 합산되고, 체결 시각은 마지막 체결 기준입니다. 계좌 전체의 체결 이벤트를 건별로 조회하는 REST API 는 없으며, 실시간 체결 이벤트가 필요하면 웹소켓 `personal:order` 채널을 사용하세요. |
| 일부만 체결된 뒤 취소한 주문은 어떻게 표시되나요? | 체결된 수량을 유지한 채 종료된 주문(`status=CLOSED`) 목록에 남습니다. |

## 수수료

| 질문 | 답변 |
|---|---|
| 수수료율 `commissionRate` 의 단위는 무엇인가요? | 소수 비율입니다. 예: `0.00015` = 0.015%. 수수료 금액은 `거래 금액 × commissionRate` 로 계산합니다. |
| KRX 와 NXT 수수료를 구분해야 하나요? | 구분하지 않습니다. Open API 주문은 통합(SOR) 모드만 지원해 거래소를 지정한 주문 자체가 불가능하며, 수수료도 하나의 값으로 내려갑니다. |

## 장 운영 시간 · 휴장

| 질문 | 답변 |
|---|---|
| 휴장일은 어떻게 구분하나요? | 국내 장 운영 정보 조회에서 해당 일자의 통합 장 정보(`integrated`) 가 `null` 이면 휴장일입니다. 세션 단위로도 `preMarket`·`regularMarket`·`afterMarket` 각각 휴장이면 `null` 입니다. |
| KRX 와 NXT 의 개장·폐장 시간을 각각 확인할 수 있나요? | 거래소별로 구분된 시간은 제공하지 않습니다. 통합 모드 기준 시간만 제공합니다. |
| 국내 애프터마켓 시간은 어떤 기준인가요? | KRX 와 NXT 애프터마켓의 합집합(가장 이른 시작 ~ 가장 늦은 종료) 입니다. 정규장도 같은 방식입니다. |
| 종목의 거래정지 여부를 알 수 있나요? | 현재 거래정지 여부는 종목 정보 조회 응답의 `krxTradingSuspended`·`nxtTradingSuspended` 로 확인할 수 있습니다. 과거 거래정지 이력은 제공하지 않습니다. |

## 데이터 이용 정책

API를 통해 제공받는 정보는 투자자 본인의 매매 목적에 한하여 이용하여야 합니다. 상업적 이용이 제외될 뿐만 아니라 비상업적인 용도라 하더라도 제 3자에게 배포하는 행위는 엄격히 금지됩니다.