FAQ
tossctl 자주 묻는 질문 — 합법성·인증·세션·거래·에이전트
자주 묻는 질문을 모았습니다. 여기에 없는 문제는 GitHub Issues에 남겨 주세요.
일반
합법인가요? 토스 공식인가요?
공식이 아닙니다. tossctl은 토스증권 웹 내부 API를 비공식적으로 재사용하며, 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 바뀔 수 있고, 사용에 따른 계좌 제한·손실·불이익의 책임은 본인에게 있습니다.
공식 Open API와 무슨 관계인가요?
토스 공식 Open API는 사전 신청자에게 단계적으로 열리는 중이고, 현재 범위는 토스 WTS 전체 기능의 약 4%(~20개)뿐입니다. tossctl은 그 범위를 100% 포함하고, 공식에 아직 없는 기능까지 제공합니다. 자세한 비교는 지원 범위 참고.
공식 API가 넓어지면 어떻게 되나요?
선택적 자동 라우팅으로 갑니다 — 공식 API 없이도 전부 동작하고, 원하면 공식 API를 연결해 지원 기능은 공식 경로로 자동 라우팅해 안정성을 더할 수 있습니다.
설치
무엇이 필요한가요?
조회 기능은 바이너리만으로 동작합니다. auth login(브라우저 로그인)에는 Google Chrome과 Python이 필요하며, 설치 스크립트가 자동으로 점검·설치합니다.
Windows에서도 되나요?
됩니다. PowerShell 한 줄(irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex) 또는 GitHub Releases 바이너리로 설치하세요.
인증·세션
로그인은 됐는데 auth status가 invalid/거부(400·401·403)됩니다
v0.10.1 이전 버전의 알려진 버그입니다. tossctl이 보내는 User-Agent가 macOS로 고정돼 있어, 다른 OS(Windows·Linux)에서 만든 세션과 불일치해 토스 서버가 거부했습니다. v0.10.1 이상으로 업데이트하면 해결됩니다.
tossctl auth logout
tossctl auth login
tossctl auth status # 'Live Check: valid' 확인로그인했는데 한 시간쯤 뒤 세션이 풀립니다
QR 스캔 후 폰에서 "이 기기 로그인 유지" 확인을 꼭 눌러야 영속 세션이 발급됩니다. tossctl auth status가 Persistence: persistent cookie (expires ...)로 나오는지 확인하세요.
세션이 7일마다 만료됩니다
토스는 SESSION 쿠키와 별개로 약 7일 서버측 활동 만료를 둡니다. 만료 24시간 전부터 경고가 뜨며, tossctl auth extend로 폰 토스 앱 푸시 승인을 받아 재로그인 없이 연장합니다.
서버(SSH)·CI처럼 브라우저가 없는 환경은?
tossctl auth login --headless [--qr-output /tmp/toss-qr.png]. QR URL과 응답 글자가 stderr로 출력되니, URL을 폰으로 보내 카메라 없이 인증하세요.
거래
실수로 주문이 나갈 수 있나요?
없습니다. 거래는 설치 직후 전부 꺼져 있고, config.json에서 기능별로 직접 켜야 합니다. 실거래는 --execute + --confirm <token> 2단계를 거치고, 그 전에 tossctl order preview로 미리 확인할 수 있습니다. 안전 모델 참고.
어떤 주문을 지원하나요?
한국·미국 주식 지정가 매수/매도, 미국 주식 소수점(금액) 시장가 주문, 당일 미체결 취소를 지원합니다(베타). 정정은 추가 검증 중입니다.
에이전트·출력
AI 에이전트와 어떻게 연동하나요?
모든 명령이 --output json으로 구조화된 결과를 내보내고, 안전·정확하게 쓰는 규칙은 AI 에이전트 가이드에 정리돼 있습니다. LLM이 바로 읽도록 /llms.txt·/llms-full.txt도 제공합니다.
출력 형식은?
표(table)·JSON·CSV·SSE를 지원해 스크립트·파이프라인에 바로 연결할 수 있습니다.
도움받기
문제·제안은 GitHub Issues에 남겨 주세요. 버그 제보 시 tossctl doctor --report 출력을 함께 주시면 진단이 빠릅니다(민감정보는 자동 제외됩니다).