빠른 시작

시작 방식 선택

tossctl은 두 경로로 토스증권에 접근합니다 — WTS 웹 세션(비공식, 전체 기능)과 공식 Open API(공식, 안정적이지만 범위가 좁음). 목적에 맞게 고르세요.

방식	설정	적합
① 빠른 시작 · WTS만	`tossctl auth login` 한 번	가장 빠르고 전체 기능. 사전 신청 불필요. 세션은 약 7일마다 폰 승인 필요
② 공식 API만 · openapi	`tossctl openapi login`	공식 지원 기능만(좁음). 토큰 자동 갱신 → 무인 운영(CI·서버)에 적합. 사전 신청·IP 등록 필요
③ 둘 다 · 자동 라우팅 (권장)	위 둘 다 등록	최대 안정성 + 최대 범위. 공식 지원은 공식 경로, 나머지는 WTS 로 자동 라우팅

대부분은 ①로 바로 시작하면 됩니다(아래 1번부터). 공식 키 발급 절차, 자동 라우팅 동작, 두 경로의 차이는 공식 Open API 자동 라우팅 가이드에 정리되어 있습니다. 처음이라면 tossctl init 위저드가 방식 선택부터 끝까지 안내합니다.

1. 로그인 (WTS 웹 세션)

tossctl auth login

QR이 표시되면 폰 토스 앱으로 스캔하고, "이 기기 로그인 유지" 확인까지 꼭 누르세요. 이 2차 확인을 건너뛰면 세션이 약 1시간 idle 후 만료됩니다.

확인:

tossctl auth status
# Persistence: persistent cookie (expires ...) 이면 정상

GUI 없는 환경 (SSH 서버·CI)

tossctl auth login --headless --qr-output /tmp/toss-qr.png

QR URL과 확인 문자가 stderr로 출력됩니다. URL을 폰으로 전달해 탭하면 카메라 없이 인증됩니다.

세션 연장

토스 서버는 약 7일짜리 활성 만료 시계를 운영합니다. 만료 24시간 전부터 경고가 뜨며, 재로그인 없이 폰 푸시 승인으로 연장할 수 있습니다.

tossctl auth extend

2. 조회

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 을 지원합니다.

tossctl account summary --output json

3. 거래 (선택, 기본 비활성)

거래는 config.json에서 명시적으로 허용해야 하고, 항상 미리보기를 먼저 실행하세요.

# 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 <token>

자세한 보호 장치는 안전 모델을 참고하세요.