[!WARNING] 이 프로젝트는 토스증권 공식 제품이 아닙니다. 공식 Open API 외 기능은 토스증권 웹 내부 API를 비공식적으로 사용하며, 이용약관 위반에 해당할 수 있고 예고 없이 변경될 수 있습니다. 계좌 제한·손실 등 사용 결과는 사용자 본인의 책임입니다.
왜 tossctl인가?
계좌와 주문을 넘어, 토스증권에서 보던 정보를 자동화에 연결합니다. 공식 Open API에 없는 투자자 수급, AI 시그널, 배당 내역, 관심종목 관리까지 WTS(토스증권 웹 트레이딩 시스템) API로 제공합니다.
공식 키가 있으면 지원되는 조회는 기본적으로 공식 API를 우선 사용합니다. WTS 기능은 웹 세션으로 연결합니다. 현재 지원 대상은 토스증권이며, 일반 토스뱅킹·카드 소비 내역은 지원하지 않습니다. 전체 기능 비교 →
빠른 시작
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh
tossctl auth login
tossctl account summary --output json
휴대폰 인증 후 이 기기 로그인 유지까지 승인하세요. QR 대신 링크를 쓰려면 tossctl auth login --link로 로그인합니다.
Windows PowerShell에서 설치한 뒤 위의 로그인·조회 명령을 실행하세요.
irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex
공식 Open API 키를 연결하려면:
tossctl openapi login
tossctl openapi status
Homebrew·소스 빌드는 설치 문서, 인증·연결 문제는 tossctl doctor --report를 참고하세요.
이렇게 사용하세요
# 수급과 AI 시그널로 시장 살펴보기 — WTS 전용
tossctl quote flows A005930
tossctl market signals
# 배당과 전체 계좌 자산 모아보기 — WTS 전용
tossctl portfolio dividends
tossctl account overview
# 보유 종목을 스크립트로 넘기기
tossctl portfolio positions --output json
# 실시간 체결 구독과 API 변경 감시
tossctl stream --trade A005930
tossctl monitor api # 82개 endpoint schema probe; 통과 0, 실패 1
관심종목 폴더·목표가 알림 관리, 조건검색, 거래 내역, 주문 미리보기도 제공합니다. 전체 사용법은 명령 레퍼런스, 개별 옵션은 tossctl <command> --help에서 확인하세요.
CLI와 MCP
터미널·스크립트에서는 CLI로, Claude Code·Codex·Cursor 같은 AI 에이전트에서는 MCP로 사용하세요. 별도 서버를 설치하지 않고 같은 바이너리에서 tossctl mcp를 실행합니다.
MCP의 기본 API 표면은 111개 오퍼레이션입니다. 세 개의 카탈로그 도구가 필요한 기능과 스키마를 찾아 호출하므로, 모든 기능 설명을 한꺼번에 컨텍스트에 넣지 않습니다.
# Claude Code
claude mcp add tossctl tossctl mcp
MCP 호스트가 아래 형식의 설정을 지원하면 추가하세요. 호스트별 등록 방법은 MCP 가이드를 참고하세요.
{
"mcpServers": {
"tossinvest": { "command": "tossctl", "args": ["mcp"] }
}
}
셸 기반 에이전트도 같은 카탈로그를 탐색할 수 있습니다.
tossctl ops list --query dividend
tossctl ops describe dividends
자세한 내용은 AI 에이전트 가이드와 MCP 가이드를 참고하세요.
안전 모델
[!IMPORTANT] 실거래는 설치 직후 모두 꺼져 있습니다. 설정에서 해당 액션을 허용하더라도 실제 제출 전마다 미리보기와 확인 토큰이 필요합니다.
tossctl order preview --symbol AAPL --side buy --qty 1 --price 200
# 미리보기만 실행합니다. 실제 주문은 사람이 결과와 확인 토큰을 검토한 뒤 진행하세요.
- 실주문: CLI 일반 주문은 공식 API 또는 WTS 중 한 경로로 제출하며, 실패해도 다른 경로로 재주문하지 않습니다. MCP·
ops주문과 조건주문은 공식 API 전용입니다. - 설정 변경: 관심종목·목표가 알림 등도 미리보기 후 현재 상태에 묶인 확인 토큰으로 실행합니다. 되돌릴 수 없는 작업은 추가 확인이 필요합니다.
- 모의투자: 별도 활성화·승인을 사용하며, 모의투자 승인이 실거래 승인으로 이어지지 않습니다.
전체 정책과 설정 예시는 안전 가이드와 docs/configuration.md를 참고하세요.
아직 안정화 중인 기능으로, 기본적으로 숨겨져 있습니다. config.json에 아래 설정을 추가하면 명령과 MCP 오퍼레이션에 나타납니다. 활성화해도 서버 측 이용 자격은 별도로 충족해야 합니다.
{
"experimental": {
"paper_trading": true
}
}
실험적 API는 변경될 수 있으며 실거래로 자동 승격되지 않습니다. 상태와 제한은 지원 범위 문서에 표시합니다.
문서
| 문서 | 내용 |
|---|---|
| 빠른 시작 | 설치 후 첫 조회까지 |
| 명령 레퍼런스 | 전체 CLI 명령과 예시 |
| 지원 범위 | 공식 API·WTS 기능 비교 |
| 설정 | config 필드와 로컬 상태 |
| 운영 | 세션 갱신, API 변경 감시, 예약 실행과 알림 |
| 아키텍처 | 라우팅·모듈·안전 경계 |
| 변경 내역 | 버전별 변경 사항과 기여자 크레딧 |
개발과 기여
로컬 빌드는 make build, 테스트는 make test로 실행합니다.
버그와 제안은 Issues, 변경 사항은 Pull Request로 보내주세요. 자세한 기준은 CONTRIBUTING.md, 보안 문제는 SECURITY.md를 확인하세요.
후원
Contributors
기여해 주신 모든 분께 감사합니다. 참여 방법은 CONTRIBUTING.md를 참고하세요.