공식 Open API 자동 라우팅

공식 키를 연결하면 지원 기능은 공식 OAuth 경로로, 나머지는 WTS 웹 세션으로 자동 라우팅됩니다

tossctl은 웹 세션(WTS)만으로도 모든 기능을 사용할 수 있습니다. 여기에 토스 공식 Open API 키를 등록하면, 공식이 지원하는 기능은 공식 OAuth 경로로, 공식에 없는 기능은 WTS로 각각 처리하는 자동 라우팅이 켜집니다. 키 없이도 전부 동작하고, 원하는 시점에 추가할 수 있습니다.

공식 Open API vs WTS 웹 세션

tossctl이 토스증권에 접근하는 두 경로입니다. 성격이 다르므로 차이를 이해하면 어떤 조합이 필요한지 판단할 수 있습니다.

	공식 Open API	WTS 웹 세션
무엇	토스가 공식 제공하는 OAuth REST API	토스 웹/앱이 쓰는 내부 API를 비공식 재사용
인증	API Key·Secret → OAuth 액세스 토큰	QR + 폰 승인 로그인(세션 쿠키)
갱신	토큰 자동 재발급(무중단)	약 7일 활동 만료, 폰 푸시 승인 필요
커버리지	공식 지원 기능(계좌·시세·주문 등)	WTS 전체 — 수급·시장지수·AI 시그널·스크리너·실시간 푸시·소수점 주문 등 포함
안정성	높음(공식 계약, 스펙 버전 관리)	비공식, 예고 없이 변경 가능
사전 조건	사전 신청·승인 + 허용 IP 등록	로그인만
약관(TOS)	공식 허용	위반 소지
무인 운영(CI·서버·에이전트)	적합	주기적 사람(폰) 개입 필요

요약하면 — 공식 API는 안정적이지만 범위가 좁고, WTS는 범위는 전부지만 비공식이고 세션이 더 자주 끊깁니다. tossctl은 둘을 합쳐 공식이 커버하는 요청은 공식 경로로(안정), 나머지는 WTS로(범위) 자동 라우팅합니다.

어느 플랫폼이든 자사 앱은 사용자 경험이 모이는 핵심 공간입니다. 새 기능을 가장 빠르게 실험하고 통합하기 좋은 곳도 앱이라, 신기능은 자연스럽게 앱(WTS)에 먼저 들어갑니다. 반면 외부 공개용 API는 버전·호환성·지원 부담이 크기 때문에, 안정적으로 열 수 있는 범위를 신중히 골라 뒤따라 공개합니다. 공식 API가 보수적인 건 인색해서가 아니라 합리적인 선택입니다.

그 결과 수급·시장지수·AI 시그널·스크리너·실시간 푸시처럼 토스의 색이 강한 기능일수록 앱에 먼저, 더 빨리 출시됩니다. 누구의 잘못이 아니라 플랫폼의 구조입니다. tossctl은 이 구조를 거스르지 않고 그대로 활용합니다. 앱이 쓰는 길(WTS)을 1차 경로로 삼아 지금 바로 쓰되, 공식이 지원하는 기능은 공식 경로로 자동 라우팅해 안정성도 함께 가져갑니다.

공식 키를 써도 일부 작업은 웹 세션이 필요합니다

공식 키의 메타데이터·허용 IP 조회(openapi status 의 IP 목록, doctor 진단)는 토스 WTS 내부 엔드포인트(/api/v1/openapi/client)로 제공되므로 웹 세션 로그인이 선행되어야 합니다. 반면 런타임 호출(계좌·시세·주문)은 세션 없이 OAuth 토큰만으로 동작합니다. 허용 IP는 보통 키를 쓰는 현재 컴퓨터 IP가 자동 등록되며, 다른 IP(예: 서버)가 필요하면 WTS(토스 웹)에서 추가로 등록할 수 있습니다.

자동 라우팅 동작

요청마다 "공식이 지원하는가 → 키가 있는가 → 설정(prefer)" 순으로 경로를 고릅니다.

요청 조건	선택 경로
공식 API 미지원 기능	→ WTS 웹 세션
공식 지원 · 공식 키 없음	→ WTS 웹 세션
공식 지원 · 공식 키 있음	→ 공식 Open API (OAuth)
공식 경로 일시 실패	→ 주문이면 오류(중복 방지), 그 외 WTS 폴백

공식이 지원하는 조회·거래는 OAuth 토큰으로 라우팅 → 더 안정적
공식 범위 밖(수급·시장지수·AI 시그널 등)은 항상 WTS
공식 경로가 일시적으로 불가하면 WTS로 자동 폴백(stderr 한 줄 알림)
주문은 교차 폴백하지 않음 (중복 주문 방지를 위해 공식 경로 실패 시 그냥 오류)

어떤 인증이 필요한가

시나리오	웹 세션	공식 키	비고
공식 지원 기능만 (가장 안정적)	초기 설정 시 필요	필요	런타임은 토큰만, 키 IP·메타 조회엔 세션 필요
고유·비공식 기능까지 전부	필요	불필요	더 빨리 끊김, 갱신 주기 짧음
둘 다 (권장)	필요	필요	최대 안정성 + 최대 범위 + 폴백

공식 키 등록 이점

공식 키를 연결하면 tossctl이 OAuth 토큰을 무중단으로 자동 재발급합니다. CI·서버·에이전트에서 사람 개입 없이 무인 운영할 수 있고, 웹 세션 대비 만료 주기가 훨씬 길며, 토스 내부 API 변경의 영향도 적습니다.

공식 Open API 키 발급

사전 신청 — corp.tossinvest.com/ko/open-api 에서 신청합니다.
공식 문서 — developers.tossinvest.com/docs 에서 전체 스펙을 확인합니다.
키 발급 — 승인 후 토스 앱 설정 > Open API 에서 API Key · Secret을 발급합니다.
허용 IP — 키를 쓰는 현재 컴퓨터 IP는 보통 자동으로 등록됩니다. 다른 IP(예: 서버)가 필요하면 WTS(토스 웹)에서 추가로 등록할 수 있습니다. 미등록 IP에서 요청하면 차단됩니다 (tossctl openapi status 로 진단 — IP 목록 조회에는 웹 세션이 필요).

시크릿 안전 취급

키·시크릿은 비밀번호와 같습니다

유출되면 즉시 토스 앱에서 재발급하세요.

권장 방법 (우선순위 순)

① 환경변수 (CI·에이전트·자동화 환경 권장)

export TOSSCTL_OPENAPI_KEY=tsck_live_xxxxxxxxxxxxxxxxxxxx
export TOSSCTL_OPENAPI_SECRET=tssk_live_xxxxxxxxxxxxxxxxxxxx
tossctl openapi status   # 환경변수 자동 인식

② tossctl openapi login 이 만드는 자격증명 파일 (개인 개발 환경)

tossctl openapi login \
  --key tsck_live_xxxxxxxxxxxxxxxxxxxx \
  --secret tssk_live_xxxxxxxxxxxxxxxxxxxx
# → <config dir>/openapi-credentials.json (권한 0600) 에 저장

절대 하지 말 것

채팅·이슈·PR·커밋·스크린샷·로그에 평문 키·시크릿 붙여넣기
config.json·코드·문서에 하드코딩
--key/--secret 플래그 직접 입력 (셸 히스토리에 남음) — 환경변수를 씁니다
허용 IP를 0.0.0.0/0 등 무제한으로 설정하지 말 것
유출이 의심되면 토스 앱에서 즉시 재발급하세요

온보딩 위저드

처음 설정한다면 tossctl init 으로 안내를 따르세요.

tossctl init
# 웹 세션 로그인 여부 확인 → 공식 키 입력 여부 → 거래 설정까지 단계별 안내

공식 키 관리 커맨드

등록 / 갱신

# 환경변수로 넘기거나 대화형으로 입력
tossctl openapi login
tossctl openapi login --key tsck_live_xxxx --secret tssk_live_xxxx

상태 확인 · 진단

tossctl openapi status
# 출력 예:
#   Official key : ✓ (set via file)
#   Token        : valid (expires in 23m 41s)
#   Allowed IPs  : 203.0.113.42 ✓ (current IP matches)   # 웹 세션 필요
#   Routing      : auto (official + wts)

status 는 일반적인 오류 원인을 설명해 줍니다:

허용 IP 미등록 — 현재 출구 IP 가 키 허용 목록에 없음
IP 목록 조회 실패(웹세션 필요) — 허용 IP 조회는 WTS 세션이 선행되어야 함 (tossctl auth login)
토큰 만료 — 재발급은 자동, 수동 강제 갱신: tossctl openapi login
키 미설정 — 환경변수 또는 openapi login 필요

연결 테스트

tossctl openapi test
# → 실제 API 호출로 키 + IP + 토큰을 검증합니다

로그아웃 (자격증명 파일 삭제)

tossctl openapi logout

백엔드 라우팅 제어

전역 플래그 `--backend`

tossctl account summary --backend openapi   # 공식 경로 강제
tossctl account summary --backend wts        # WTS 경로 강제
tossctl account summary --backend auto       # 기본값: 자동 라우팅

official 은 openapi 의 deprecated 별칭으로 계속 동작합니다(--backend official, openapi.prefer: "official"). 신규 설정은 openapi 를 쓰세요.

Config 항목 `openapi.*`

{
  "openapi": {
    "enabled": true,
    "prefer": "openapi",
    "fallback": true
  }
}

키	설명
`openapi.enabled`	공식 경로 사용 여부 (기본 `true`, 키 있을 때만 실제 활성화)
`openapi.prefer`	`"openapi"` \| `"wts"` — 공식이 지원하는 기능의 기본 라우팅
`openapi.fallback`	공식 경로 실패 시 WTS 폴백 허용 (기본 `true`; 주문은 항상 `false`)

폴백 · 소스 표시

공식 경로가 일시적으로 쓸 수 없을 때 tossctl은 WTS로 자동 전환하고 stderr에 한 줄을 출력합니다:

[tossctl] official route unavailable, falling back to wts (account summary)

폴백이 잦으면 tossctl openapi status 와 tossctl doctor 로 원인을 확인하세요.

공식 지원 범위 전체 목록은 지원 범위 페이지를 참고하세요.