빠른 시작

API를 호출하려면 먼저 계좌를 개설하고, 로그인 후 발급 버튼을 눌러 API Key(client_id·client_secret)를 받으셔야 합니다. Live Key와 Sandbox Key는 서로 독립적으로 발급되며, 하나를 발급받으신다고 다른 하나가 자동으로 생기지 않습니다.

SANDBOX

pk_test_ / sk_test_

모의투자 환경입니다. 가상 자금으로 전 기능을 테스트하실 수 있습니다. Live 계좌·잔액과는 완전히 분리되어 있습니다.

LIVE

pk_live_ / sk_live_

실거래 환경입니다. 실제 주문이 체결되고 실제 자금이 이동합니다.

Secret Key는 발급 시 1회만 평문으로 노출되며, 이후에는 마스킹 처리됩니다. 재발급하면 기존 키는 즉시 무효화되지만, 반대편 환경(Live↔Sandbox)의 키에는 영향을 주지 않습니다.

발급받은 키는 모든 요청의 Authorization 헤더에 담아 전달합니다. 계좌·자산, 주문 카테고리는 계좌를 식별하는 헤더가 추가로 필요합니다.

1. 액세스 토큰 발급

client_id·client_secret으로 POST /v1/oauth/token을 호출하여 액세스 토큰을 발급받으세요.

Example Request

curl -X POST \
  "https://api.nextsecurities.dev/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={pk_test_...}" \
  -d "client_secret={sk_test_...}"

액세스 토큰 유효기간은 12시간입니다. Refresh Token은 제공되지 않으니, 만료 시 위 요청을 다시 호출하여 재발급받으시면 됩니다.

환경은 요청에 별도로 표시하지 않습니다. 키의 prefix(pk_test_ / pk_live_)로 게이트웨이가 자동으로 판단합니다.

2. 요청 헤더 구성

발급받으신 토큰은 모든 요청의 Authorization 헤더에 담아 전달해 주세요. 계좌·자산, 주문 카테고리는 계좌를 식별하는 헤더가 추가로 필요합니다.

Example Request

# 모든 요청 공통 — 인증
Authorization: Bearer {access_token}
# 모든 요청 공통 — 요청 추적 (누락 시 400 request-id-required)
X-Next-Request-Id: {uuid}
# 계좌·자산, 주문 카테고리에만 추가
X-Next-Account-Id: {account_id}

빠른 시작

curl -X POST \ "https://api.nextsecurities.dev/v1/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id={pk_test_...}" \ -d "client_secret={sk_test_...}"

# 모든 요청 공통 — 인증 Authorization: Bearer {access_token} # 모든 요청 공통 — 요청 추적 (누락 시 400 request-id-required) X-Next-Request-Id: {uuid} # 계좌·자산, 주문 카테고리에만 추가 X-Next-Account-Id: {account_id}