공식 Open API 자동 라우팅
공식 키를 연결하면 지원 기능은 공식 OAuth 경로로, 나머지는 WTS 웹 세션으로 자동 라우팅됩니다
tossctl은 웹 세션(WTS)으로 WTS 전용 기능과 대부분의 hybrid 조회·일반주문을 사용할 수
있습니다. 공식 Open API 키를 등록하면 공식이 지원하는 기능은 공식 OAuth 경로로,
공식에 없는 기능은 WTS로 각각 처리하는 자동 라우팅이 켜집니다. account buying-power,
market business-days|stocks, quote metadata, 조건주문, stream 같은 official-only
명령까지 쓰려면 공식 키도 연결해야 합니다.
공식 Open API vs WTS 웹 세션
tossctl이 토스증권에 접근하는 두 경로입니다. 성격이 다르므로 차이를 이해하면 어떤 조합이 필요한지 판단할 수 있습니다.
| 공식 Open API | WTS 웹 세션 | |
|---|---|---|
| 무엇 | 토스가 공식 제공하는 OAuth REST API | 토스 웹/앱이 쓰는 내부 API를 비공식 재사용 |
| 인증 | API Key·Secret → OAuth 액세스 토큰 | QR + 폰 승인 로그인(세션 쿠키) |
| 갱신 | 서버의 만료값 기준 자동 재발급 | 세션 만료 시 폰 푸시 승인 또는 재로그인 필요 |
| 커버리지 | 공식 지원 기능(계좌·시세·주문 등) | WTS 기능 — 수급·시장지수·AI 시그널·스크리너·실시간 푸시·소수점 주문 등 포함 |
| 안정성 | 높음(공식 계약, 스펙 버전 관리) | 비공식, 예고 없이 변경 가능 |
| 사전 조건 | 공식 이용 자격·키 + 허용 IP 등록 | 로그인만 |
| 약관(TOS) | 공식 허용 | 위반 소지 |
| 무인 운영(CI·서버·에이전트) | 적합 | 주기적 사람(폰) 개입 필요 |
요약하면 — 공식 API는 안정적이지만 범위가 좁고, WTS는 고유 범위가 넓지만 비공식이고 세션이 더 자주 끊깁니다. tossctl은 둘을 합쳐 공식이 커버하는 요청은 공식 경로로(안정), 나머지는 WTS로(범위) 자동 라우팅합니다.
실전 시나리오 — 공식으로 막히는 것, tossctl로 되는 것
"범위가 넓다"가 실제로 무슨 차이인지. **공식만으로는 ❌ → tossctl(WTS 포함)이면 ✅**입니다.
세금·손익 (내 계좌 원장)
| 하고 싶은 것 | 공식 | tossctl |
|---|---|---|
| 내 계좌의 누적 실현손익 | 별도 손익 리포트 없음 | ✅ CLI profit으로 서버 제공 누적 실현손익 조회 |
| 연도별 배당·원천세 내역 확인 | ❌ | ✅ dividends (세전/세후·월별) |
| 해외주식 양도소득 내역 조회 | ❌ | ✅ CLI tax overseas (신고 전 증권사 자료와 대조) |
시장 수급·지수 (판단의 무게추)
| 하고 싶은 것 | 공식 | tossctl |
|---|---|---|
| 종목별 투자자(개인/외국인/기관) 순매수 흐름 | ❌ 체결량까지만 | ✅ trading_flows |
| 코스피·코스닥·VIX 등 지수 | ❌ 개별 종목만 | ✅ market_indices / index_detail |
| 오늘 외국인·기관이 담은 종목 top | ❌ | ✅ investor_rankings |
| 섹터·테마 등락 스캔 | ❌ | ✅ sectors / theme_rankings |
| 실시간 인기(관심 급등) 종목 | ❌ 종목 지정 필수 | ✅ stock_ranking |
리서치·계좌 대시보드
| 하고 싶은 것 | 공식 | tossctl |
|---|---|---|
| 조건검색(고배당·저PBR·성장) | ❌ | ✅ screener_presets |
| 실적발표(어닝콜) 일정·상세 | ❌ | ✅ earning_calls / earnings_major / earning_call_detail |
| 총자산·평가손익을 한 화면에 | △ holdings+buying_power 조합 | ✅ account_summary 한 번에 |
| 공식 키 없이 보유·대기주문 조회 | ❌ 키 필요 | ✅ positions / pending_orders |
외부 분석에 결합하기
아래는 원자료를 조합하는 사용 예입니다. 세금 계산·신고나 총수익 자동 계산을 제공한다는 뜻은 아닙니다. 조회 기간·페이지 제한을 확인하세요.
| 하고 싶은 것 | 공식 | tossctl |
|---|---|---|
| 체결·배당 데이터를 외부 분석 도구에 전달 | ❌ | ✅ completed_orders + dividends |
| 매수 후 그 종목 수급이 어땠나 사후분석 | ❌ | ✅ completed_orders + trading_flows |
한 줄 정리
공식 API의 계좌·시세·주문에 실현손익·배당·세금 기록, 시장 수급·지수, 종목 발굴·스크리닝을 더합니다. 필요한 데이터를 같은 CLI·MCP 인터페이스로 조회하고 외부 분석에 활용할 수 있습니다.
증권 WTS와 일반 토스 앱의 경계
현재 tossctl의 WTS 확장은 토스증권 범위입니다. 수급·시장지수·AI 시그널·스크리너처럼 구현된 증권 기능을 제공하며, 일반 토스 앱의 카드 결제내역·월 소비·은행 거래내역은 지원하지 않습니다.
같은 앱에 화면이 있어도 인증·동의·권한이 같다는 뜻은 아닙니다. 뱅킹 기능은 별도 API와 인증 경계를 검증해야 하며, WTS 쿠키만으로 호출 가능하다고 가정하지 않습니다.
공식 키를 써도 일부 작업은 웹 세션이 필요합니다
공식 키의 메타데이터·허용 IP 조회·변경(openapi status, openapi ip)은 토스
WTS 내부 엔드포인트(/api/v1/openapi/client)로 제공되므로 웹 세션 로그인이 선행되어야
합니다. 반면 런타임 호출(계좌·시세·주문)은 세션 없이 OAuth 토큰만으로 동작합니다. 허용 IP는
공식 키의 설정 화면에서 관리하며, 다른 IP(예: 서버)가 필요하면 WTS(토스 웹)에서
추가로 등록할 수 있습니다. 네트워크가 바뀐 경우 tossctl openapi ip replace-current로
preview한 뒤 --execute --confirm <token>을 붙여 교체할 수 있습니다.
현재 공인 IP 확인에는 https://api.ipify.org를 사용하며, 이 요청에는 토스 쿠키·Open API
키·계좌 정보가 전송되지 않습니다.
자동 라우팅 동작
각 명령은 source=official|wts|both|local 정책을 갖습니다. both 조회는 기본적으로 공식 키와 설정을 확인해 시작 경로를 선택합니다.
| 요청 | 경로와 실패 처리 |
|---|---|
| official-only | 공식 키 필요. 키가 없거나 WTS로 고정하면 오류. WTS 대체 없음 |
| WTS-only | 웹 세션 필요. 공식 키로 대체하지 않음 |
| both 조회 | 기본 공식 우선. 동등한 WTS 구현이 있고 fallback 설정이 켜진 경우에만 전환 가능 |
| CLI 일반 주문 | 시작할 때 공식 또는 WTS 한 경로 선택. 제출 후 교차 폴백 없음 |
| MCP·ops 실주문 / 조건주문 | 공식 API 전용 |
| local | 원격 API 호출 없음 |
지원 조회의 폴백 대상은 전송 오류·인증/IP 오류·429·5xx입니다. 일반 도메인 4xx 오류는 그대로 반환합니다. 주문·설정 쓰기는 교차 폴백하지 않습니다. --backend openapi도 조회 fallback 설정을 유지하므로, 공식 조회만 사용하려면 openapi.fallback=false를 함께 설정하세요.
예외적으로 market fx는 더 넓은 환율 피드를 보존하기 위해 WTS를 먼저 사용하고, 실패하면 공식 USD/KRW 조회를 시도합니다. 명령별 경로는 --help·카탈로그와 지원 범위를 확인하세요.
어떤 인증이 필요한가
| 시나리오 | 웹 세션 | 공식 키 | 비고 |
|---|---|---|---|
| 공식 지원 기능만 (가장 안정적) | 초기 설정 시 필요 | 필요 | 런타임은 토큰만, 키 IP·메타 조회엔 세션 필요 |
| WTS로 구현된 증권 기능 | 필요 | 불필요 | 더 빨리 끊김, 갱신 주기 짧음 |
| 둘 다 (권장) | 필요 | 필요 | 최대 안정성 + 최대 범위 + 폴백 |
공식 키 등록 이점
공식 키를 연결하면 서버가 반환한 만료 시각을 기준으로 OAuth 토큰을 자동 재발급합니다. 공식 경로의 호출에는 WTS 세션 갱신이 필요하지 않지만, 키·허용 IP·이용 자격은 유효해야 하며 재발급 실패도 처리해야 합니다.
공식 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
# → <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 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 # 공식 경로 우선 (fallback 설정 유지)
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 | "auto" | "openapi" | "wts" — 공식이 지원하는 기능의 시작 경로 (auto·openapi는 공식 우선, wts는 공식 비활성화) |
openapi.fallback | 지원 조회의 폴백 대상 오류에서만 WTS 전환 허용 (기본 true; 쓰기에는 적용 안 함) |
응답 범위와 정렬
quote chart와 ops/MCPcandles는 표·JSON·CSV 모두 과거→최신 순서로 반환합니다. 공식 API의 최신순 응답을 WTS 차트와 같은 순서로 변환하며 마지막 봉이 최신입니다.market indicator-candles는 공식 페이지의 최신순을 유지합니다.next_before는 더 오래된 페이지의 커서입니다.- 공식 ops/MCP
orders·order는 지정가·시장가·장마감지정가 등 공식 지원 호가 유형만 조회합니다. 장전·장후 시간외종가 등 미지원 호가 유형의 주문은 목록과 상세에서 제외됩니다. 모든 페이지를 읽거나 빈 목록을 받아도 전체 주문 내역을 확보했다는 뜻은 아닙니다. WTS 조회와 범위가 다르며, 이 누락은 HTTP 오류가 아니므로 자동 폴백되지 않습니다. stream은 숫자로 시작하는 6자리 영숫자 코드(005930,0101N0)를 KR로 추론합니다. 이는 클라이언트 분류 규칙이며 개별 종목의 실제 구독 지원은 서버가 결정합니다.
market business-days KR의 after_market은 KRX·NXT 애프터마켓을 합친 시간대입니다.
서버가 준 가장 이른 시작·가장 늦은 종료 시각을 보존하며, 양쪽 모두 애프터마켓이
휴장일 때만 해당 세션을 생략합니다. 세션이 있어도 NXT는 휴장일 수 있습니다.
single_price_auction_end는 NXT 기준이며 NXT 휴장 시 JSON에서 생략됩니다.
하루의 모든 세션이 없으면 holiday: true입니다. 장전·장후 시간외종가는 포함하지 않습니다.
공식 ops/MCP stock_supply의 type=short 비중은 서버가 준 소수 비율입니다
(예: 0.0318 = 3.18%). 분모는 장전·장후 시간외종가와 애프터마켓을 포함한
당일 누적 거래량·거래대금입니다. 기준 데이터가 없으면 null, 기준값이 0이면
비중도 0을 반환합니다. tossctl JSON에서는 원본 null에 해당하는 비중 필드를
생략하고 숫자 0은 그대로 남깁니다.
폴백 · 소스 표시
동등한 WTS 구현이 있는 조회에서 폴백 대상 오류가 발생하고 설정이 허용하면 전환 사실을 stderr로 알립니다:
tossctl: official path unavailable, falling back to web session (…)폴백이 잦으면 tossctl openapi status 와 tossctl doctor 로 원인을 확인하세요.
공식 지원 범위 전체 목록은 지원 범위 페이지를 참고하세요.