# 변경 이력 {/* AUTO-GENERATED from ../../../CHANGELOG.md by scripts/sync-changelog.mjs — do not edit directly. */} 버전별 변경 사항입니다. 각 릴리즈의 바이너리·릴리즈 노트는 [GitHub Releases](https://github.com/JungHoonGhae/tossinvest-cli/releases)에서도 볼 수 있습니다. [Unreleased] [#unreleased] [0.16.0] - 2026-07-02 [#0160---2026-07-02] 새 기능 [#새-기능] * **`account prime`** — 토스 Prime 구독 상태와 이번 달 수수료·이자 혜택(일반/Prime/내 적용 요율 비교)을 조회합니다. 비가입 상태에서도 조회 가능합니다. [0.15.0] - 2026-07-02 [#0150---2026-07-02] 새 기능 [#새-기능-1] * **`tossctl update`** — 설치 경로(Homebrew / install.sh·install.ps1 / 소스 빌드)를 자동 감지해 알맞은 방식으로 tossctl을 최신 버전으로 갱신합니다. `--check` 로 다운로드 없이 새 버전 여부만 확인, `--yes` 로 확인 프롬프트 생략 가능. [0.14.0] - 2026-07-01 [#0140---2026-07-01] 새 기능 [#새-기능-2] * **한국어 UI 라우팅** — `--lang ko` (또는 환경변수 `LANG`/`TOSSCTL_LANG`) 로 help·온보딩 프롬프트·표 출력을 한국어로 볼 수 있습니다. 기본값은 OS 로케일을 따르고, 감지되지 않으면 영어로 표시합니다. `--output json|csv` 는 언어 설정과 무관하게 항상 고정된 형식을 유지합니다. 개선 [#개선] * CLI 커맨드 설명(`--help`)을 영어로 통일하고, 각 커맨드가 어떤 경로로 동작하는지(공식 Open API / WTS / 둘 다 / 로컬) 구조화된 메타로 노출했습니다. [0.13.1] - 2026-06-29 [#0131---2026-06-29] 개선 [#개선-1] * `market themes` 테이블 정렬 개선 — 한글 표시폭을 반영해 열을 맞추고 헤더 구분선을 추가했습니다. [0.13.0] - 2026-06-29 [#0130---2026-06-29] 새 기능 [#새-기능-3] * **`market themes`** — 테마 등락 랭킹. 오늘 가장 많이 오른 토스 테마(예: 배터리·연예기획사)를 등락률·상승종목수와 함께 보여줍니다. `--size N` 으로 개수 조정(0=전체). 공식 Open API 에는 없는 토스 WTS 고유 기능입니다. `--output json|csv` 지원. 개선 [#개선-2] * 라우팅 백엔드 값 명칭 정리 — `--backend` 플래그와 `openapi.prefer` 의 `official` 값을 `openapi` 로 바꿨습니다(`tossctl openapi` 서브커맨드·`openapi.*` 설정과 일관). 기존 `official` 은 deprecated 별칭으로 계속 동작하므로 기존 설정·스크립트는 그대로 작동합니다. [0.12.0] - 2026-06-27 [#0120---2026-06-27] 새 기능 [#새-기능-4] * **대화형 주문·폴더 선택** — 터미널에서 `order cancel`, `order amend`, `order show`를 `--order-id` 없이 실행하면 대기/최근 주문 목록을 직접 골라 진행할 수 있습니다. `watchlist group delete`·`rename`도 폴더 이름 없이 실행하면 목록에서 선택합니다 (`rename "새이름"`처럼 새 이름만 전달하면 폴더를 고릅니다). 플래그·인자를 지정하면 기존과 동일하게 비대화형으로 동작하며, 파이프·비TTY에서는 프롬프트 없이 명확한 오류를 반환합니다. * **하이브리드 공식 Open API 연동** — 토스 공식 Open API 키를 선택적으로 연결할 수 있습니다. 연결하면 공식이 지원하는 조회·거래 기능은 OAuth 경로로 처리되어 더 안정적이며, 토큰을 자동 갱신합니다. 공식에 없는 기능은 기존대로 WTS 경로를 씁니다. 키 없이도 모든 기능이 동작하며, 원하는 시점에 선택적으로 추가할 수 있습니다. * **`tossctl init`** — 온보딩 위저드. 처음 설치한 사용자를 위해 웹 세션 로그인·공식 키 등록·거래 설정을 단계별로 안내합니다. * **`tossctl openapi login`** — 공식 API Key·Secret을 등록합니다. 환경변수(`TOSSCTL_OPENAPI_KEY`/`TOSSCTL_OPENAPI_SECRET`) 또는 플래그로 전달하거나 대화형으로 입력할 수 있습니다. 자격증명 파일은 `0600` 권한으로 저장됩니다. * **`tossctl openapi status`** — 현재 키·토큰·허용 IP·라우팅 상태를 진단합니다. IP 미허용·토큰 만료·키 미설정 등 오류 원인을 설명합니다. * **`tossctl openapi test`** — 실제 API 호출로 공식 키 연결을 검증합니다. * **`tossctl openapi logout`** — 자격증명 파일을 삭제합니다. * **`--backend auto|wts|official`** 전역 플래그 — 요청별로 라우팅 백엔드를 직접 지정합니다. * **`doctor` 하이브리드 진단** — `tossctl doctor` 가 공식 키·토큰·IP 허용 상태를 함께 점검합니다. 개선 [#개선-3] * **핵심 출력 손익 색상** — 포트폴리오·계좌·시세·관심종목의 주요 손익 수치에 한국식 색(상승/이익=빨강, 하락/손실=파랑)을 표시합니다. 파이프·비TTY·`NO_COLOR` 환경 및 `--output json|csv` 에서는 색 없이 기존과 동일하게 동작합니다. * **관심종목 등락·등락률 컬럼** — `watchlist list` 결과 표에 기준가 대비 등락액·등락률 컬럼이 추가됐습니다. JSON/CSV 출력은 변경 없습니다. 버그 수정 [#버그-수정] * 설치 스크립트(`curl ... install.sh | sh`)가 `/usr/local/bin` 이 없는 환경(주로 새로 설정한 Apple Silicon Mac — Homebrew 가 `/opt/homebrew` 에 있어 `/usr/local/bin` 이 아직 없는 경우)에서 `mv: ... No such file or directory` 로 설치에 실패하던 문제 수정. 설치 디렉터리를 먼저 만들고, 쓰기 권한이 있으면 sudo 없이 설치합니다. `INSTALL_DIR`·`SHARE_DIR` 환경변수로 설치 위치를 바꿀 수도 있습니다. [0.11.1] - 2026-06-25 [#0111---2026-06-25] 버그 수정 [#버그-수정-1] * 소수점 매수(`order place --fractional --amount <값>`, `--qty` 미사용)가 `required flag(s) "qty" not set` 로 거부되던 문제 수정. `--qty` 를 정적 필수에서 제외하고, 수량/금액 검증을 케이스별로 `order preview`·`place` 에서 일원화했습니다. (소수점 매도는 `--qty`, 소수점 매수는 `--amount` 사용.) [0.11.0] - 2026-06-25 [#0110---2026-06-25] 새 기능 [#새-기능-5] * **소수점 매도 (US, beta)** — 미국 주식 시장가에서 소수점 수량으로 매도할 수 있습니다: `order place --fractional --side sell --qty 0.5` (소수점 6자리까지). 공식 Open API 1.1.5에 추가된 기능을 반영했습니다. 소수점 매수는 기존대로 금액 기반(`--amount`)입니다. 계약 테스트는 통과했으나 라이브 검증 전이니 실거래 전 `order preview` 로 확인하세요. 문서 [#문서] * 공식 Open API 가 소수점 주문(금액 기반 매수 + 1.1.5 소수점 매도)을 지원함을 반영해 비교표·소개를 정정했습니다. tossctl 고유 부분은 **원화(KRW) 결제 모드**(공식 금액 주문은 USD)·dry-run preview·안전 게이트로 명확히 했습니다. [0.10.1] - 2026-06-23 [#0101---2026-06-23] 버그 수정 [#버그-수정-2] * Windows·Linux 에서 로그인은 성공하는데 `auth status` 와 모든 인증 요청이 거부(400/401/403)되던 문제 수정. tossctl 이 보내는 User-Agent 가 macOS 로 고정돼 있어, 다른 OS 에서 로그인한 세션과 불일치해 토스 서버가 거부하던 것이 원인이었습니다. 이제 로그인한 브라우저의 실제 User-Agent 를 세션에 저장해 그대로 쓰고, 기본값도 실행 OS 에 맞춰 만듭니다. (#36) * Windows 설치 시 playwright 설치 단계에서 실제로는 성공했는데도 빨간 `NativeCommandError` 가 표시되던 문제 수정 (PowerShell이 pip 진행 메시지를 오류로 처리). 이제 종료 코드로만 성공/실패를 판정합니다. (#35) [0.10.0] - 2026-06-21 [#0100---2026-06-21] 새 기능 [#새-기능-6] * **`market index <코드|이름>`** — 지수 상세 시세(OHLC·52주 고저·거래량). 예: `market index nasdaq`, `market index 코스피`. 인자 없으면 기존처럼 주요 지수 목록(코드 포함). [0.9.1] - 2026-06-19 [#091---2026-06-19] 버그 수정 [#버그-수정-3] * 소스 설치 경로 정정 — `go install github.com/JungHoonGhae/tossinvest-cli/cmd/tossctl@latest` 가 정상 동작합니다 (모듈 경로가 실제 저장소와 불일치하던 문제). 바이너리·Homebrew 설치에는 영향 없습니다. [0.9.0] - 2026-06-19 [#090---2026-06-19] 새 기능 [#새-기능-7] * **`portfolio dividends`** — 연간 배당 내역(총액·수령·예정, 지역별 KR/US, 월별). `--by-payment-date` 로 지급일 기준(세금·수수료 포함), `--year` 로 연도 선택. * **`community rankings --type influencer|profit|followers`** — 토스 커뮤니티 랭킹(인플루언서·수익금·팔로워 급증). * **`market sectors [id]`** — 업종별 등락(대분류 39개·하위 업종, 1일·1개월·1년 수익률). 인자로 업종 id 를 주면 하위 업종. * **`market briefing`** — 개인화 AI 뉴스 브리핑(테마별로 묶인 뉴스 헤드라인). * **`market earnings --major`** — 주요 기업 어닝콜만 큐레이션해서 표시. (모두 토스 공식 Open API 에는 없는 tossctl 고유 기능입니다.) [0.8.0] - 2026-06-19 [#080---2026-06-19] 새 기능 [#새-기능-8] * **`market investors`** — 외국인·기관·개인 투자자별 순매수 상위 종목. * **`market earnings`** — 다가오는 어닝콜(실적발표) 일정. (둘 다 토스 공식 Open API 에는 없는 tossctl 고유 기능입니다.) [0.7.0] - 2026-06-18 [#070---2026-06-18] 새 기능 [#새-기능-9] * **Windows 설치 지원** — PowerShell 한 줄로 설치합니다: `irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex`. 다운로드·체크섬 검증·PATH 등록·Chrome/Python 점검까지 자동으로 처리합니다. (기여: @thsvkd) 개선 [#개선-4] * Windows 설치 시 기존 PATH 환경변수가 손상되지 않도록 안전하게 등록합니다. [0.6.0] - 2026-06-04 [#060---2026-06-04] 새 기능 [#새-기능-10] * **`quote orderbook <종목>`** — 10단계 호가(매도·매수 잔량). * **`quote sellable <종목>`** — 보유 종목의 매도가능수량. * **`quote commission <종목>`** — 수수료율·거래세율. 이로써 토스 공식 Open API 가 제공하는 조회·거래 기능을 **100% 커버**합니다. [0.5.2] - 2026-06-04 [#052---2026-06-04] 개선 [#개선-5] * 국내주식 6자리 코드(예: `005930`)를 넣으면 `--market kr` 없이 자동으로 인식합니다. * 멀티 시세·시세 조회 속도 향상(병렬 처리). * 거래 설정 단순화 — 이제 US/KR 시장 구분 없이 동일하게 동작합니다 (기존엔 국내거래만 별도 옵션이 필요했습니다). [0.5.1] - 2026-06-04 [#051---2026-06-04] 개선 [#개선-6] * 실거래 실행 절차를 `--execute` + `--confirm ` 두 단계로 단순화했습니다(보호 강도는 동일). * 오래된 설정 항목이 남아 있으면 명령 실행 시 한 줄로 안내합니다. 지원 종료 예정 [#지원-종료-예정] * `--dangerously-skip-permissions` 플래그는 더 이상 필요 없습니다. 당분간 호환을 위해 받아들이지만 다음 릴리즈에서 제거됩니다. `--execute` + `--confirm ` 을 사용하세요. [0.5.0] - 2026-06-04 [#050---2026-06-04] 새 기능 [#새-기능-11] * **`market index`** — 코스피·코스닥·나스닥·S\&P500·VIX 등 주요 시장 지수. * **`market ranking`** — 실시간 인기 종목 순위. * **`quote flows <종목>`** — 종목별 투자자 수급(개인·외국인·기관, 국내). * **`market signals`** — 토스 AI 시그널. * **`market screener`** — 가치주·배당주·성장주 등 조건 검색. * **관심종목 관리** — 폴더 생성·이름변경·삭제, 종목 추가·제거 (`watchlist group ...`, `watchlist add|remove`). [0.4.19] - 2026-06-03 [#0419---2026-06-03] 새 기능 [#새-기능-12] * `quote get` 정보 확장 — 당일 OHLC, 52주 고저, 시가총액, 거래대금, 체결강도, 상/하한가. * **`market fx`** — 달러 환율·달러 인덱스. * `market hours` 가 휴장일에는 다음 영업일도 함께 표시합니다. [0.4.18] - 2026-06-03 [#0418---2026-06-03] 개선 [#개선-7] * 미국 종목에 `quote limits`(상/하한가)를 쓰면 친절한 안내를 표시합니다 (상/하한가는 국내 전용 제도). [0.4.17] - 2026-06-03 [#0417---2026-06-03] 새 기능 [#새-기능-13] * **`quote trades`** (체결 틱), **`quote limits`** (상/하한가), **`quote warnings`** (매수 유의사항), **`market hours`** (장 운영 시간). [0.4.16] - 2026-05-28 [#0416---2026-05-28] 새 기능 [#새-기능-14] * **`quote batch --live`** — 실시간 갱신 모드(`watch` 대체). (기여: @Castor103) * `quote batch` 에서 쉼표로 여러 종목을 한 번에 조회. [0.4.15] - 2026-05-20 [#0415---2026-05-20] 새 기능 [#새-기능-15] * **`quote chart <종목>`** — 분봉 ASCII 캔들 차트(색상 지원). `quote batch --chart` 로 스파크라인 표시. (기여: @Castor103) * `quote get` / `quote chart` 가 여러 단어 종목명(`"KODEX 인버스"` 등)을 지원합니다. [0.4.14] - 2026-05-14 [#0414---2026-05-14] 개선 [#개선-8] * 새 버전 알림이 AI 에이전트 환경에서도 표시되도록 했습니다(하루 1회). * `tossctl version` 에 최신 버전·업데이트 가능 여부를 표시합니다. [0.4.13] - 2026-05-14 [#0413---2026-05-14] 새 기능 [#새-기능-16] * **자동 업데이트 알림** — 새 버전이 있으면 명령 실행 후 한 줄로 안내합니다. 설정에서 끌 수 있고(`update_check.enabled=false`), 자동화 출력(JSON/CSV)은 오염시키지 않습니다. [0.4.12] - 2026-05-14 [#0412---2026-05-14] 버그 수정 [#버그-수정-4] * Windows 에서 `auth login` 이 중간에 멈추던 문제를 수정했습니다. (제보·수정: @netics01) [0.4.10] - 2026-05-13 [#0410---2026-05-13] 개선 [#개선-9] * `monitor api` 단순화 — 통과/실패만 반환하고 알림 채널(Discord·Slack·이메일 등)은 cron 에서 자유롭게 연결합니다. (가이드: `AGENTS.md`) [0.4.9] - 2026-05-13 [#049---2026-05-13] 새 기능 [#새-기능-17] * **`tossctl monitor api`** — 핵심 조회 API 상태를 점검해, 토스 서버 측 변경으로 명령이 깨지기 전에 조기 감지합니다. [0.4.8] - 2026-05-13 [#048---2026-05-13] 버그 수정 [#버그-수정-5] * 토스 서버 변경으로 `portfolio positions`·`watchlist list` 가 실패하던 문제를 긴급 수정했습니다. (제보: kwakmu18) [0.4.7] - 2026-05-06 [#047---2026-05-06] 버그 수정 [#버그-수정-6] * `order place --fractional --currency-mode USD` 가 거부되던 문제를 수정했습니다. (제보: @leesj10147) [0.4.6] - 2026-05-06 [#046---2026-05-06] 새 기능 [#새-기능-18] * **`tossctl auth extend`** — 폰 토스 앱 푸시 승인으로 세션을 약 7일 연장합니다(재로그인 불필요). (기여: @skyisle) * 세션 만료 24시간 전부터 경고를 표시합니다. [0.4.5] - 2026-04-29 [#045---2026-04-29] 새 기능 [#새-기능-19] * **`tossctl push listen`** — 실시간 푸시(주문/체결/보유 변경) 알림 스트림. (기여: @skyisle) [0.4.4] - 2026-04-23 [#044---2026-04-23] 새 기능 [#새-기능-20] * 미국 지정가 주문에 USD 가격 입력 허용 — `order place --currency-mode USD --price 158.01`. (기여: @skyisle) [0.4.3] - 2026-04-23 [#043---2026-04-23] 개선 [#개선-10] * 실제로 동작하지 않던 설정 항목들을 정리했습니다. 기존 설정은 그대로 둬도 되며, `doctor` 가 안내합니다. [0.4.2] - 2026-04-23 [#042---2026-04-23] 새 기능 [#새-기능-21] * **`tossctl doctor --report`** — 환경·세션·엔드포인트 상태를 JSON 한 번에 출력합니다. 홈 경로는 자동으로 가려져 GitHub 이슈에 그대로 붙일 수 있습니다. [0.4.1] - 2026-04-23 [#041---2026-04-23] 보안 [#보안] * 로그인 중간 파일·QR 이미지·상태 폴더 권한을 소유자 전용으로 강화했습니다(공유 컴퓨터에서 다른 사용자가 세션을 읽지 못하도록). [0.4.0] - 2026-04-23 [#040---2026-04-23] 새 기능 [#새-기능-22] * **거래내역·현금 요약** — `transactions list`(매매·입출금·배당·입출고), `transactions overview`(주문가능·출금가능·예정입금). (기여: @skyisle) * **로그인 유지(영속 세션)** — 폰에서 "이 기기 로그인 유지"까지 마치면 약 1시간 뒤 만료되던 문제가 해결됩니다. * **원격/헤드리스 로그인** — `auth login --headless`. QR URL 을 폰으로 보내 카메라 없이 인증. (기여: @skyisle) * helper Python 자동 탐지로 `uv` 설치 환경도 지원. (기여: @keenranger) [0.3.6] - 2026-04-17 [#036---2026-04-17] 버그 수정 [#버그-수정-7] * `auth login` 이 멈추거나 조회 API 가 차단(403)되던 문제를 수정했습니다. (제보: @pinion05) [0.3.5] - 2026-03-30 [#035---2026-03-30] 개선 [#개선-11] * 표 출력 정렬 개선(종목명 좌측, 숫자 우측, 천단위 쉼표). [0.3.4] - 2026-03-28 [#034---2026-03-28] 버그 수정 [#버그-수정-8] * `auth login` 브라우저 차단 해결 — 시스템 Google Chrome 을 사용합니다(별도 Chromium 설치 불필요). [0.3.3] - 2026-03-24 [#033---2026-03-24] 새 기능 [#새-기능-23] * 미국 포지션에 USD 금액 병기. (기여: @seilk) * 한 줄 설치 스크립트(`curl ... | sh`, macOS/Linux). 버그 수정 [#버그-수정-9] * Linux 에서 `auth login` 이 실패하던 문제 수정. [0.3.2] - 2026-03-23 [#032---2026-03-23] 새 기능 [#새-기능-24] * Windows·Linux 바이너리 제공. [0.3.1] - 2026-03-21 [#031---2026-03-21] 버그 수정 [#버그-수정-10] * 미국 주가가 센트($0.01) 단위로 반올림되도록 수정(가격 오류 해결). [0.3.0] - 2026-03-21 [#030---2026-03-21] 새 기능 [#새-기능-25] * **소수점(금액 기반) 주문** — `order place --symbol TSLL --fractional --amount 18000` (미국 시장가). [0.2.2] - 2026-03-21 [#022---2026-03-21] 새 기능 [#새-기능-26] * `quote batch` — 여러 종목 시세 한 번에. * `export positions|orders --market` — 시장별 CSV 내보내기. [0.1.7] - 2026-03-21 [#017---2026-03-21] 새 기능 [#새-기능-27] * 국내주식 거래 — `order place --symbol 005930 --market kr`. [0.1.6] - 2026-03-21 [#016---2026-03-21] 새 기능 [#새-기능-28] * 매도 주문 — `order place --side sell`. # FAQ 자주 묻는 질문을 모았습니다. 여기에 없는 문제는 [GitHub Issues](https://github.com/JungHoonGhae/tossinvest-cli/issues)에 남겨 주세요. 일반 [#일반] 합법인가요? 토스 공식인가요? [#합법인가요-토스-공식인가요] 공식이 아닙니다. tossctl은 토스증권 웹 내부 API를 비공식적으로 재사용하며, 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 바뀔 수 있고, 사용에 따른 계좌 제한·손실·불이익의 책임은 본인에게 있습니다. 공식 Open API와 무슨 관계인가요? [#공식-open-api와-무슨-관계인가요] 토스 공식 Open API는 사전 신청자에게 단계적으로 열리는 중이고, 현재 범위는 토스 WTS 전체 기능의 약 4%(\~20개)뿐입니다. tossctl은 그 범위를 100% 포함하고, 공식에 아직 없는 기능까지 제공합니다. 자세한 비교는 [지원 범위](/docs/reference/support-scope) 참고. 공식 API가 넓어지면 어떻게 되나요? [#공식-api가-넓어지면-어떻게-되나요] 선택적 자동 라우팅으로 갑니다 — 공식 API 없이도 전부 동작하고, 원하면 공식 API를 연결해 지원 기능은 공식 경로로 자동 라우팅해 안정성을 더할 수 있습니다. 설치 [#설치] 무엇이 필요한가요? [#무엇이-필요한가요] 조회 기능은 바이너리만으로 동작합니다. `auth login`(브라우저 로그인)에는 Google Chrome과 Python이 필요하며, 설치 스크립트가 자동으로 점검·설치합니다. Windows에서도 되나요? [#windows에서도-되나요] 됩니다. PowerShell 한 줄(`irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex`) 또는 GitHub Releases 바이너리로 설치하세요. 인증·세션 [#인증세션] 로그인은 됐는데 auth status가 invalid/거부(400·401·403)됩니다 [#로그인은-됐는데-auth-status가-invalid거부400401403됩니다] v0.10.1 이전 버전의 알려진 버그입니다. tossctl이 보내는 User-Agent가 macOS로 고정돼 있어, 다른 OS(Windows·Linux)에서 만든 세션과 불일치해 토스 서버가 거부했습니다. **v0.10.1 이상으로 업데이트**하면 해결됩니다. ```bash tossctl auth logout tossctl auth login tossctl auth status # 'Live Check: valid' 확인 ``` 로그인했는데 한 시간쯤 뒤 세션이 풀립니다 [#로그인했는데-한-시간쯤-뒤-세션이-풀립니다] QR 스캔 후 폰에서 **"이 기기 로그인 유지"** 확인을 꼭 눌러야 영속 세션이 발급됩니다. `tossctl auth status`가 `Persistence: persistent cookie (expires ...)`로 나오는지 확인하세요. 세션이 7일마다 만료됩니다 [#세션이-7일마다-만료됩니다] 토스는 SESSION 쿠키와 별개로 약 7일 서버측 활동 만료를 둡니다. 만료 24시간 전부터 경고가 뜨며, `tossctl auth extend`로 폰 토스 앱 푸시 승인을 받아 재로그인 없이 연장합니다. 서버(SSH)·CI처럼 브라우저가 없는 환경은? [#서버sshci처럼-브라우저가-없는-환경은] `tossctl auth login --headless [--qr-output /tmp/toss-qr.png]`. QR URL과 응답 글자가 stderr로 출력되니, URL을 폰으로 보내 카메라 없이 인증하세요. 거래 [#거래] 실수로 주문이 나갈 수 있나요? [#실수로-주문이-나갈-수-있나요] 없습니다. 거래는 설치 직후 전부 꺼져 있고, `config.json`에서 기능별로 직접 켜야 합니다. 실거래는 `--execute` + `--confirm ` 2단계를 거치고, 그 전에 `tossctl order preview`로 미리 확인할 수 있습니다. [안전 모델](/docs/guide/safety) 참고. 어떤 주문을 지원하나요? [#어떤-주문을-지원하나요] 한국·미국 주식 지정가 매수/매도, 미국 주식 소수점(금액) 시장가 주문, 당일 미체결 취소를 지원합니다(베타). 정정은 추가 검증 중입니다. 에이전트·출력 [#에이전트출력] AI 에이전트와 어떻게 연동하나요? [#ai-에이전트와-어떻게-연동하나요] 모든 명령이 `--output json`으로 구조화된 결과를 내보내고, 안전·정확하게 쓰는 규칙은 [AI 에이전트 가이드](/docs/guide/agents)에 정리돼 있습니다. LLM이 바로 읽도록 [`/llms.txt`](/llms.txt)·[`/llms-full.txt`](/llms-full.txt)도 제공합니다. 출력 형식은? [#출력-형식은] 표(table)·JSON·CSV·SSE를 지원해 스크립트·파이프라인에 바로 연결할 수 있습니다. 도움받기 [#도움받기] 문제·제안은 [GitHub Issues](https://github.com/JungHoonGhae/tossinvest-cli/issues)에 남겨 주세요. 버그 제보 시 `tossctl doctor --report` 출력을 함께 주시면 진단이 빠릅니다(민감정보는 자동 제외됩니다). # 소개 **토스증권을 AI 에이전트·터미널에서 다루는 비공식 CLI.** 실행 바이너리는 `tossctl`. 토스증권 웹 세션을 재사용해 계좌·시세·거래내역 조회와 제한된 거래를 터미널에서 수행합니다. Claude Code · Codex · Cursor · OpenClaw · bash · HTTP — 어떤 도구·에이전트든 동일한 명령 체계(`tossctl`)로 다룰 수 있고, 사람이 직접 터미널에서 쓸 수도 있습니다. 토스증권 공식 제품이 아닙니다. 웹 내부 API를 비공식적으로 사용하며, 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 변경될 수 있고, 사용으로 인한 계좌 제한·손실·기타 불이익에 대해 개발자는 책임지지 않습니다. 본인의 판단과 책임 하에 사용하세요. 설치 직후 모든 거래 기능이 꺼져 있습니다. `config.json`에서 기능별로 직접 허용해야만 실행되며, 실거래는 `--execute` + `--confirm ` 2단계를 거칩니다. 자세한 내용은 [안전 모델](/docs/guide/safety) 참고. 핵심 요약 [#핵심-요약] * **공식 Open API(예정)의 조회·거래 범위를 100% 커버**하고, 그 너머까지 다룹니다. * 공식에 없는 기능: 수급·시장지수·지수 상세 시세·토스 AI 시그널·뉴스 브리핑·조건검색· 배당 내역·업종별 등락·커뮤니티 랭킹·관심종목 관리·거래내역 ledger·실시간 푸시·소수점 주문 등. * 출력 형식: 표(table) · JSON · CSV · SSE — 자동화/에이전트 파이프라인에 바로 연결. 전체 비교는 [지원 범위](/docs/reference/support-scope)를 참고하세요. 30초 시작 [#30초-시작] ```bash # 설치 (macOS / Linux) curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh # 환경 점검 → 로그인 → 첫 조회 tossctl doctor tossctl auth login tossctl account summary --output json ``` 다음 단계 [#다음-단계] # AI 에이전트 가이드 `tossctl` 은 AI 에이전트(Claude Code · Codex · Cursor · OpenClaw 등)가 토스증권을 다루도록 설계됐습니다. 이 페이지는 에이전트가 안전하고 정확하게 쓰기 위한 규칙을 정리합니다. > LLM이 바로 읽기 좋은 형식: [`/llms.txt`](/llms.txt) (큐레이션 색인) · > [`/llms-full.txt`](/llms-full.txt) (전체 문서 단일 파일). 핵심 규칙 [#핵심-규칙] 1. **항상 `--output json` 으로 호출**하라. 표(table) 출력은 사람용이며, 파싱하지 말 것. 2. **읽기 먼저.** `account`, `portfolio`, `quote`, `market`, `transactions` 는 부작용이 없다. 3. **거래는 기본 비활성.** `config.json` 에서 허용되지 않으면 실패한다. 임의로 켜지 말고 사용자에게 확인받아라. 4. **주문 전 반드시 `order preview`** 를 실행해 수량·가격·금액을 확인하라(주문 안 나감). 5. **실거래는 2단계**: `--execute` + `--confirm `. token 은 preview/확인 흐름에서 나온 값이며, 추측하거나 우회하지 마라. 6. **개인정보 주의.** 응답에는 계좌번호·잔고·보유 종목이 들어있다. 외부로 전송·로깅하지 마라. 권장 워크플로 [#권장-워크플로] ```text 1. tossctl doctor --output json # 환경·세션 상태 확인 2. (세션 없으면) 사용자에게 `tossctl auth login` 안내 3. tossctl account summary --output json 4. tossctl portfolio positions --output json 5. (거래 요청 시) tossctl order preview ... --output json → 사용자 확인 6. 승인 후에만 tossctl order place ... --execute --confirm ``` 세션·인증 [#세션인증] * 세션은 `tossctl auth login` 으로 사람이 1회 생성한다(QR + 폰 승인). 에이전트는 로그인을 대신할 수 없다 — 세션이 없으면 사용자에게 로그인을 요청하라. * 만료가 가까우면 stderr 에 경고가 나온다. `tossctl auth extend` 로 폰 푸시 승인을 통해 연장할 수 있다. * `tossctl auth status --output json` 으로 세션 유효성·만료를 프로그램적으로 확인한다. 공식 Open API (선택) — 무인 운영에 유리 [#공식-open-api-선택--무인-운영에-유리] 토스 공식 Open API 키를 등록하면 공식이 지원하는 조회·거래는 OAuth 경로로 처리되고 토큰이 자동 갱신됩니다. 웹 세션(WTS)은 약 7일 활동 만료가 있어 사람의 폰 승인이 주기적으로 필요하지만, 공식 경로는 그 제약이 없어 CI·서버·장기 실행 에이전트에 유리합니다. 키 없이도 모든 기능이 동작합니다. * **비대화형 등록**: `TOSSCTL_OPENAPI_KEY` / `TOSSCTL_OPENAPI_SECRET` 환경변수를 설정한 뒤 `tossctl openapi login` (플래그로도 전달 가능). 자격증명 파일은 `0600` 으로 저장된다. * `tossctl openapi status --output json` — 키·토큰·허용 IP·라우팅 진단. 공식 키는 **IP 허용 목록**이 필요하니 서버 IP 등록 여부를 확인하라. * `tossctl <명령> --backend auto|wts|openapi` — 요청별 라우팅 백엔드 지정(기본 auto). * 처음 설정은 `tossctl init` 위저드로도 가능하다. * 자세한 내용: [공식 Open API 자동 라우팅](/docs/guide/hybrid-openapi). 출력 계약 [#출력-계약] * 성공 시 stdout 에 JSON, 실패 시 비정상 종료 코드 + stderr 메시지. * 시세·요약 등 자료형은 안정적인 키를 가진다. 서버측 변경은 `tossctl monitor api` 가 조기에 감지하도록 돼 있다. 하지 말 것 [#하지-말-것] * 실제 계좌 데이터를 공개 출력/커밋/로그에 남기기. * preview 없이 주문 실행, `--confirm` 토큰 추측, 거래 게이트 우회. * table 출력 파싱(형식이 사람용이라 깨지기 쉬움) — 항상 JSON. 같이 보기 [#같이-보기] * [명령 레퍼런스](/docs/reference/commands) — 전체 명령 목록 * [안전 모델](/docs/guide/safety) — 거래 보호 장치 상세 * [지원 범위](/docs/reference/support-scope) — 공식 API 대비 커버리지 # 설정 설정 파일 위치는 OS별 사용자 설정 디렉터리이며, `tossctl config status` 로 경로와 현재 상태를 확인할 수 있습니다. ```bash tossctl config status ``` 주요 항목 [#주요-항목] ```json { "trading": { "grant": ["place", "sell"] }, "update_check": { "enabled": true } } ``` | 키 | 설명 | | ---------------------- | -------------------------------------------- | | `trading.grant` | 허용할 거래 동작 배열 (`place`, `sell`). 비어 있으면 거래 불가 | | `update_check.enabled` | 새 버전 알림 on/off (자동화 출력은 오염시키지 않음) | * 스키마 버전은 자동 관리되며, 오래된/사용되지 않는 항목이 있으면 실행 시 한 줄 안내가 나오고 `config status`·`doctor` 가 표시합니다. * 설정 스키마(JSON Schema)는 저장소의 [`schemas/config.schema.json`](https://github.com/JungHoonGhae/tossinvest-cli/blob/main/schemas/config.schema.json) 에 있습니다. 진단 [#진단] ```bash tossctl doctor # 사람용 점검 tossctl doctor --report # JSON 진단 (홈 경로 마스킹, 이슈 첨부용) ``` 거래 보호 장치는 [안전 모델](/docs/guide/safety)에서 자세히 다룹니다. # 공식 Open API 자동 라우팅 tossctl은 **웹 세션(WTS)만으로도** 모든 기능을 사용할 수 있습니다. 여기에 토스 공식 Open API 키를 등록하면, *공식이 지원하는 기능은 공식 OAuth 경로*로, 공식에 없는 기능은 WTS로 각각 처리하는 **자동 라우팅**이 켜집니다. 키 없이도 전부 동작하고, 원하는 시점에 추가할 수 있습니다. 공식 Open API vs 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로(범위) 자동 라우팅합니다. 공식 API가 한 발 늦는 건 구조 때문입니다 [#공식-api가-한-발-늦는-건-구조-때문입니다] 어느 플랫폼이든 자사 앱은 사용자 경험이 모이는 핵심 공간입니다. 새 기능을 가장 빠르게 실험하고 통합하기 좋은 곳도 앱이라, 신기능은 자연스럽게 **앱(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 키 발급 [#공식-open-api-키-발급] 1. **사전 신청** — [corp.tossinvest.com/ko/open-api](https://corp.tossinvest.com/ko/open-api) 에서 신청합니다. 2. **공식 문서** — [developers.tossinvest.com/docs](https://developers.tossinvest.com/docs) 에서 전체 스펙을 확인합니다. 3. **키 발급** — 승인 후 **토스 앱 설정 > Open API** 에서 API Key · Secret을 발급합니다. 4. **허용 IP** — 키를 쓰는 현재 컴퓨터 IP는 보통 자동으로 등록됩니다. 다른 IP(예: 서버)가 필요하면 WTS(토스 웹)에서 추가로 등록할 수 있습니다. 미등록 IP에서 요청하면 차단됩니다 (`tossctl openapi status` 로 진단 — IP 목록 조회에는 웹 세션이 필요). 시크릿 안전 취급 [#시크릿-안전-취급] 유출되면 즉시 토스 앱에서 재발급하세요. 권장 방법 (우선순위 순) [#권장-방법-우선순위-순] **① 환경변수 (CI·에이전트·자동화 환경 권장)** ```bash export TOSSCTL_OPENAPI_KEY=tsck_live_xxxxxxxxxxxxxxxxxxxx export TOSSCTL_OPENAPI_SECRET=tssk_live_xxxxxxxxxxxxxxxxxxxx tossctl openapi status # 환경변수 자동 인식 ``` **② `tossctl openapi login` 이 만드는 자격증명 파일 (개인 개발 환경)** ```bash tossctl openapi login \ --key tsck_live_xxxxxxxxxxxxxxxxxxxx \ --secret tssk_live_xxxxxxxxxxxxxxxxxxxx # → /openapi-credentials.json (권한 0600) 에 저장 ``` 절대 하지 말 것 [#절대-하지-말-것] * 채팅·이슈·PR·커밋·스크린샷·로그에 평문 키·시크릿 붙여넣기 * `config.json`·코드·문서에 하드코딩 * `--key`/`--secret` 플래그 직접 입력 (셸 히스토리에 남음) — 환경변수를 씁니다 * 허용 IP를 `0.0.0.0/0` 등 무제한으로 설정하지 말 것 * 유출이 의심되면 **토스 앱에서 즉시 재발급**하세요 온보딩 위저드 [#온보딩-위저드] 처음 설정한다면 `tossctl init` 으로 안내를 따르세요. ```bash tossctl init # 웹 세션 로그인 여부 확인 → 공식 키 입력 여부 → 거래 설정까지 단계별 안내 ``` 공식 키 관리 커맨드 [#공식-키-관리-커맨드] 등록 / 갱신 [#등록--갱신] ```bash # 환경변수로 넘기거나 대화형으로 입력 tossctl openapi login tossctl openapi login --key tsck_live_xxxx --secret tssk_live_xxxx ``` 상태 확인 · 진단 [#상태-확인--진단] ```bash 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` 필요 연결 테스트 [#연결-테스트] ```bash tossctl openapi test # → 실제 API 호출로 키 + IP + 토큰을 검증합니다 ``` 로그아웃 (자격증명 파일 삭제) [#로그아웃-자격증명-파일-삭제] ```bash tossctl openapi logout ``` 백엔드 라우팅 제어 [#백엔드-라우팅-제어] 전역 플래그 --backend [#전역-플래그---backend] ```bash 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.* [#config-항목-openapi] ```json { "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` 로 원인을 확인하세요. *** 공식 지원 범위 전체 목록은 [지원 범위](/docs/reference/support-scope) 페이지를 참고하세요. # 안전 모델 tossctl 은 조회는 자유롭게, **거래는 여러 단계로 막아** 사고를 방지합니다. 기본 비활성 [#기본-비활성] 설치 직후 모든 거래 기능은 꺼져 있습니다. `config.json` 에서 명시적으로 허용하지 않으면 주문·취소·정정이 실패합니다. ```json { "trading": { "grant": ["place", "sell"] } } ``` * `place` 없이는 주문 자체가 불가 * 매도는 `sell` 추가 허용 필요 (유저가 "매수만 / 매도 포함"을 스스로 범위 제한) 실행 2단계 게이트 [#실행-2단계-게이트] 실거래는 두 가지를 모두 줘야 나갑니다. ```bash tossctl order place --symbol TSLA --side buy --qty 1 --price 250 \ --execute --confirm ``` * `--execute` 없이는 전부 dry-run으로 취급 * `--confirm ` 의 토큰은 확인 흐름에서 나온 값 — 추측·우회 불가 항상 미리보기 먼저 [#항상-미리보기-먼저] `order preview` 는 주문을 보내지 않고 수량·가격·체결금액·수수료를 계산해 보여줍니다. ```bash tossctl order preview --symbol TSLA --side buy --qty 1 --price 250 ``` 에이전트는 **반드시 preview → 사용자 확인 → place** 순서를 지켜야 합니다. 시장 대칭 [#시장-대칭] 국내(KR)와 미국(US) 거래는 동일한 게이트를 적용합니다. (KR 주문이 US 주문보다 더 위험하지 않으므로, 과거의 비대칭 옵션은 제거됐습니다.) 개인정보 보호 [#개인정보-보호] * 로그인 중간 파일·QR 이미지·세션 폴더는 소유자 전용 권한(`0600`)으로 저장됩니다. * `doctor --report` 의 JSON 진단은 홈 경로를 자동 마스킹합니다. * `monitor` 알림 경로는 응답 본문(계좌번호·잔고 등)을 외부로 전달하지 않습니다. 에이전트 주의사항 [#에이전트-주의사항] [AI 에이전트 가이드](/docs/guide/agents)에 정리된 규칙을 따르세요 — 특히 거래 게이트 우회 금지, 실데이터 비노출, preview 선행. # 설치 `tossctl` 은 단일 실행 바이너리입니다. macOS·Linux·Windows를 지원합니다. macOS / Linux (한 줄 설치) [#macos--linux-한-줄-설치] ```bash curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh ``` 다운로드·체크섬 검증·PATH 등록까지 자동으로 처리합니다. Windows (PowerShell) [#windows-powershell] ```powershell irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex ``` Homebrew [#homebrew] ```bash brew install JungHoonGhae/tossinvest-cli/tossctl # 업그레이드 brew upgrade tossctl ``` 소스 빌드 (Go 1.25+) [#소스-빌드-go-125] ```bash go install github.com/JungHoonGhae/tossinvest-cli/cmd/tossctl@latest ``` 사전 요구사항 [#사전-요구사항] * **로그인(`auth login`)에는 Google Chrome 과 Python 이 필요**합니다. 한 줄 설치 스크립트가 자동으로 설정하며, 수동 환경에서는 `tossctl doctor` 가 무엇이 빠졌는지 알려줍니다. 설치 확인 [#설치-확인] ```bash tossctl version tossctl doctor ``` `doctor` 는 바이너리·Chrome·Python·세션·엔드포인트 상태를 점검합니다. 문제가 있으면 `tossctl doctor --report` 로 JSON 진단(홈 경로 자동 마스킹)을 만들어 이슈에 붙일 수 있습니다. # 빠른 시작 시작 방식 선택 [#시작-방식-선택] tossctl은 두 경로로 토스증권에 접근합니다 — **WTS 웹 세션**(비공식, 전체 기능)과 **공식 Open API**(공식, 안정적이지만 범위가 좁음). 목적에 맞게 고르세요. | 방식 | 설정 | 적합 | | ----------------------- | ------------------------ | ---------------------------------------------------------- | | **① 빠른 시작 · WTS만** | `tossctl auth login` 한 번 | 가장 빠르고 전체 기능. 사전 신청 불필요. 세션은 약 7일마다 폰 승인 필요 | | **② 공식 API만 · openapi** | `tossctl openapi login` | 공식 지원 기능만(좁음). 토큰 자동 갱신 → 무인 운영(CI·서버)에 적합. 사전 신청·IP 등록 필요 | | **③ 둘 다 · 자동 라우팅 (권장)** | 위 둘 다 등록 | 최대 안정성 + 최대 범위. 공식 지원은 공식 경로, 나머지는 WTS 로 자동 라우팅 | 대부분은 **①로 바로 시작**하면 됩니다(아래 1번부터). 공식 키 **발급 절차**, 자동 라우팅 동작, 두 경로의 차이는 [공식 Open API 자동 라우팅](/docs/guide/hybrid-openapi) 가이드에 정리되어 있습니다. 처음이라면 `tossctl init` 위저드가 방식 선택부터 끝까지 안내합니다. 1. 로그인 (WTS 웹 세션) [#1-로그인-wts-웹-세션] ```bash tossctl auth login ``` QR이 표시되면 폰 토스 앱으로 스캔하고, **"이 기기 로그인 유지" 확인까지 꼭 누르세요.** 이 2차 확인을 건너뛰면 세션이 약 1시간 idle 후 만료됩니다. 확인: ```bash tossctl auth status # Persistence: persistent cookie (expires ...) 이면 정상 ``` GUI 없는 환경 (SSH 서버·CI) [#gui-없는-환경-ssh-서버ci] ```bash tossctl auth login --headless --qr-output /tmp/toss-qr.png ``` QR URL과 확인 문자가 stderr로 출력됩니다. URL을 폰으로 전달해 탭하면 카메라 없이 인증됩니다. 세션 연장 [#세션-연장] 토스 서버는 약 7일짜리 활성 만료 시계를 운영합니다. 만료 24시간 전부터 경고가 뜨며, 재로그인 없이 폰 푸시 승인으로 연장할 수 있습니다. ```bash tossctl auth extend ``` 2. 조회 [#2-조회] ```bash tossctl account summary # 계좌 요약 tossctl portfolio positions # 보유 종목 tossctl quote get 005930 # 종목 시세 (국내 6자리 코드 자동 인식) tossctl quote get TSLA # 미국 종목 tossctl market index # 주요 시장 지수 tossctl market index nasdaq # 지수 상세 (OHLC·52주) ``` 모든 조회는 `--output json|csv|table` 을 지원합니다. ```bash tossctl account summary --output json ``` 3. 거래 (선택, 기본 비활성) [#3-거래-선택-기본-비활성] 거래는 `config.json`에서 명시적으로 허용해야 하고, 항상 미리보기를 먼저 실행하세요. ```bash # 1) dry-run preview (주문 안 나감) tossctl order preview --symbol TSLA --side buy --qty 1 --price 250 # 2) 실제 실행 — 2단계 게이트 tossctl order place --symbol TSLA --side buy --qty 1 --price 250 --execute --confirm ``` 자세한 보호 장치는 [안전 모델](/docs/guide/safety)을 참고하세요. # 명령 레퍼런스 모든 조회 명령은 `--output table|json|csv` 를 지원합니다(기본 table). 자동화/에이전트는 `--output json` 을 쓰세요. 인증 (auth) [#인증-auth] | 명령 | 설명 | | ------------------------------------------------------ | --------------------- | | `tossctl auth login [--headless] [--qr-output ]` | QR + 폰 승인 로그인 | | `tossctl auth status` | 세션 유효성·만료 확인 | | `tossctl auth extend [--timeout 120s]` | 폰 푸시 승인으로 세션 연장(\~7일) | 계좌 · 포트폴리오 [#계좌--포트폴리오] | 명령 | 설명 | | ------------------------------------------------------------ | --------------------- | | `tossctl account list` | 계좌 목록 | | `tossctl account summary` | 총자산·평가손익·시장별 | | `tossctl portfolio positions` | 보유 종목 (미국은 USD 병기) | | `tossctl portfolio allocation` | 자산 배분 | | `tossctl portfolio dividends [--year N] [--by-payment-date]` | 연간 배당 내역(총액·지역·월별·세금) | 시세 (quote) [#시세-quote] | 명령 | 설명 | | ------------------------------------------------------ | ------------------------- | | `tossctl quote get ` | 시세(OHLC·52주·시총·거래대금·체결강도) | | `tossctl quote batch [--chart] [--live]` | 멀티 시세 / 실시간 갱신 | | `tossctl quote chart --interval 1m\|...\|60m` | ASCII 캔들 차트 | | `tossctl quote orderbook ` | 10단계 호가 | | `tossctl quote trades --count N` | 체결 틱 | | `tossctl quote limits ` | 상/하한가 (국내) | | `tossctl quote warnings ` | 매수 유의사항 | | `tossctl quote sellable ` | 매도가능수량 | | `tossctl quote commission ` | 수수료율·거래세율 | 시장 (market) [#시장-market] | 명령 | 설명 | | ----------------------------------------------------------------------------- | ----------------------------- | | `tossctl market index [<코드\|이름>]` | 주요 지수 목록 / 인자 주면 상세(OHLC·52주) | | `tossctl market ranking --size N` | 실시간 인기 종목 | | `tossctl market investors` | 투자자별(외국인·기관·개인) 순매수 상위 | | `tossctl market sectors []` | 업종별 등락(대분류/하위, 1일·1개월·1년) | | `tossctl market earnings [--major]` | 어닝콜 일정 / 주요 기업 | | `tossctl market briefing` | 개인화 AI 뉴스 브리핑(테마별) | | `tossctl market signals` | 토스 AI 시그널 | | `tossctl market fx` | 환율·달러 인덱스 | | `tossctl market hours` | 장 운영 시간 | | `tossctl market screener [] [--filter ''] [--nation kr\|us]` | 조건검색 | 커뮤니티 (community) [#커뮤니티-community] | 명령 | 설명 | | ----------------------------------------------------------------- | ------- | | `tossctl community rankings --type influencer\|profit\|followers` | 커뮤니티 랭킹 | 주문 · 거래 (order) [#주문--거래-order] 거래는 기본 비활성. [안전 모델](/docs/guide/safety) 참고. | 명령 | 설명 | | ----------------------------------------------------------------------------- | --------------------- | | `tossctl order preview --symbol --side --qty --price

` | dry-run 미리보기(주문 안 나감) | | `tossctl order place ... --execute --confirm ` | 실제 주문(2단계 게이트) | | `tossctl order cancel --order-id --symbol ` | 주문 취소 | | `tossctl order amend --order-id ...` | 주문 정정 | | `tossctl orders list` · `orders completed` · `order show ` | 미체결/체결/단건 조회 | 소수점(금액 기반) 주문: `order place --fractional --amount --qty 0` (미국 시장가). 거래내역 · 내보내기 [#거래내역--내보내기] | 명령 | 설명 | | ------------------------------------------------------- | -------------------- | | `tossctl transactions list --market us\|kr` | 매매·입출금·배당·입출고 ledger | | `tossctl transactions overview --market us\|kr` | 주문가능·출금가능·예정입금 | | `tossctl export positions\|orders --market us\|kr\|all` | CSV 내보내기 | 관심종목 (watchlist) [#관심종목-watchlist] | 명령 | 설명 | | ------------------------------------------------ | ------------ | | `tossctl watchlist list` · `watchlist groups` | 관심종목 / 폴더 조회 | | `tossctl watchlist group create\|rename\|delete` | 폴더 관리 | | `tossctl watchlist add\|remove --group ` | 종목 추가/제거 | 공식 Open API · 자동 라우팅 [#공식-open-api--자동-라우팅] 공식 키를 연결하면 공식이 지원하는 조회·거래는 공식 OAuth 경로로 처리되고(자동 토큰 갱신), 나머지는 WTS 경로를 씁니다. 키 없이도 모든 기능이 동작합니다. 자세한 내용은 [자동 라우팅 가이드](/docs/guide/hybrid-openapi). | 명령 | 설명 | | ------------------------------------------- | --------------------------------------------- | | `tossctl init` | 온보딩 위저드(웹 세션 로그인·공식 키 등록·거래 설정 단계별 안내) | | `tossctl openapi login` | 공식 API Key·Secret 등록(환경변수·플래그·대화형, 파일 `0600`) | | `tossctl openapi status` | 키·토큰·허용 IP·라우팅 진단 | | `tossctl openapi test` | 실제 호출로 연결 검증 | | `tossctl openapi logout` | 자격증명 파일 삭제 | | `tossctl <명령> --backend auto\|wts\|openapi` | 요청별 라우팅 백엔드 지정(전역, 기본 auto) | 운영 (push · monitor · doctor) [#운영-push--monitor--doctor] | 명령 | 설명 | | --------------------------- | ------------------------------------------- | | `tossctl push listen` | 실시간 푸시(주문/체결/보유 변경) 스트림(SSE) | | `tossctl monitor api` | 핵심 조회 API 헬스 점검(서버측 변경 조기 감지) | | `tossctl doctor [--report]` | 환경·세션 진단 + 공식 키·토큰·IP 허용 점검(JSON, 홈 경로 마스킹) | | `tossctl version` | 버전·업데이트 가능 여부 | # 지원 범위 **tossctl 은 토스 공식 Open API의 조회·거래 범위를 100% 커버하고, 그 너머까지 다룹니다.** 공식 키를 등록하면 공식이 지원하는 기능은 **실제로 OAuth 경로로 라우팅**되며, 나머지는 WTS 경로로 처리됩니다. 자세한 설정 방법은 [하이브리드 가이드](/docs/guide/hybrid-openapi)를 참고하세요. * ✅ 지원 · ❌ 미지원 · 🔸 부분 지원 * `공식 API` 칼럼 = 공개 문서 기준 커버리지; 공식 키 등록 시 해당 기능은 OAuth로 라우팅 * 공식이 ❌ 인 행 = tossctl 고유 기능 (항상 WTS) openapi 커맨드 [#openapi-커맨드] | 커맨드 | 설명 | | ------------------------ | -------------------------------------------------------------------- | | `tossctl init` | 온보딩 위저드 — 세션·공식 키·거래 설정을 단계별 안내 | | `tossctl openapi login` | 공식 키 등록 (환경변수 `TOSSCTL_OPENAPI_KEY`/`TOSSCTL_OPENAPI_SECRET` 또는 플래그) | | `tossctl openapi status` | 키·토큰·허용 IP·라우팅 상태 진단 | | `tossctl openapi test` | 실제 API 호출로 연결 검증 | | `tossctl openapi logout` | 자격증명 파일 삭제 | 전역 플래그 `--backend auto|wts|openapi` 로 요청별 라우팅을 직접 지정할 수 있습니다. 조회 (읽기 전용) [#조회-읽기-전용] | 기능 | 명령 | 공식 API | tossctl | | ------------------------- | --------------------------------------------- | :----: | :-----: | | 계좌 목록 / 요약 | `account list`, `account summary` | ✅ | ✅ | | 포트폴리오 | `portfolio positions`, `portfolio allocation` | ✅ | ✅ | | 체결 틱 / 호가 | `quote trades`, `quote orderbook` | ✅ | ✅ | | 상·하한가 / 매수 유의 | `quote limits`, `quote warnings` | ✅ | ✅ | | 매도가능수량 / 수수료 | `quote sellable`, `quote commission` | ✅ | ✅ | | 시세 / 캔들 | `quote get`, `quote chart` | 🔸 | ✅ | | 멀티 시세 / 실시간 갱신 | `quote batch --live` | ❌ | ✅ | | 수급(투자자별 순매수) | `quote flows` | ❌ | ✅ | | 시장 지수 / 지수 상세 | `market index [<코드\|이름>]` | ❌ | ✅ | | 실시간 인기 순위 | `market ranking` | ❌ | ✅ | | 투자자별 순매수 상위 | `market investors` | ❌ | ✅ | | 업종별 등락 | `market sectors` | ❌ | ✅ | | 실적(어닝콜) 일정 | `market earnings [--major]` | ❌ | ✅ | | 개인화 뉴스 브리핑 | `market briefing` | ❌ | ✅ | | 토스 AI 시그널 | `market signals` | ❌ | ✅ | | 조건검색(스크리너) | `market screener` | ❌ | ✅ | | 배당 내역 | `portfolio dividends` | ❌ | ✅ | | 커뮤니티 랭킹 | `community rankings` | ❌ | ✅ | | 관심종목 조회·관리 | `watchlist ...` | ❌ | ✅ | | 거래내역 ledger / 현금 overview | `transactions list/overview` | ❌ | ✅ | | CSV 내보내기 | `export ...` | ❌ | ✅ | 거래 [#거래] | 기능 | 명령 | 공식 API | tossctl | | ------------------- | ---------------------------------------------- | :----: | :-----: | | 매수·매도 주문 | `order place` | ✅ | ✅ | | 주문 취소·정정 | `order cancel`, `order amend` | ✅ | ✅ | | dry-run preview | `order preview` | ❌ | ✅ | | 소수점 주문 (US, 금액/수량) | `order place --fractional` | ✅ | ✅ | | 소수점 주문 — 원화(KRW) 결제 | `order place --fractional --currency-mode KRW` | ❌ | ✅ | | 실시간 푸시(SSE) | `push listen` | ❌ | ✅ | 공식 Open API 1.1.5에 추가된 **미국 시장가 소수점 수량 매도**(`order place --fractional --side sell --qty 0.5`, 소수점 6자리)를 구현했습니다. 계약 테스트는 통과했으나 **라이브 검증은 아직**입니다 — 실거래 전 `order preview`로 확인하세요. 소수점 매수는 기존대로 금액 기반(`--amount`)입니다. 검증 기준 [#검증-기준] `공식 API` 칼럼은 [공식 Open API 문서](https://developers.tossinvest.com/docs)의 특정 버전 기준으로 검증됩니다. 검증된 버전·마지막 점검일은 저장소의 [`.openapi-snapshot.json`](https://github.com/JungHoonGhae/tossinvest-cli/blob/main/docs/migration/.openapi-snapshot.json) 에 기록되며, 전체 spec 사본을 매일 미러링하고 변경 시 자동 감지·갱신합니다. WTS 웹 API 전체 카탈로그(구현/다음 추가 후보/의도적 제외)는 [`wts-endpoints.json`](https://github.com/JungHoonGhae/tossinvest-cli/blob/main/docs/reverse-engineering/wts-endpoints.json) 에서 지속 추적합니다.