[!WARNING]
이 프로젝트는 토스증권 공식 제품이 아닙니다. 공식 Open API 외 기능은 토스증권 웹 내부 API를 비공식적으로 사용하며, 이용약관 위반에 해당할 수 있고 예고 없이 변경될 수 있습니다. 계좌 제한·손실 등 사용 결과는 사용자 본인의 책임입니다.
공식 API에 없는 기능까지, tossctl로
tossctl은 공식 API에 없는 30가지 이상의 기능을 내 AI와 자동화에 연결합니다. 종목을 찾는 일부터 내 자산의 변화와 세금 자료를 확인하는 일까지 한곳에서 다루세요.
| 더 할 수 있는 일 | 공식 Open API | tossctl에서 연결하는 기능 |
|---|
| 종목 발굴·분석 | 미지원 | 토스 AI 시그널·등락 이유·조건검색·업종별 분석 |
| 뉴스·투자 일정 확인 | 미지원 | 보유·관심종목 뉴스·어닝콜·주요 경제지표 일정 |
| 내 자산·성과 모아 보기 | 미지원 | 전체 계좌 합산·평가 이력·배당·기간별 실현손익 |
| 세금·추가 수익 확인 | 미지원 | 해외 양도소득·예탁금 이자·주식대여 예상 수익 |
| 내 투자 관리 | 미지원 | 관심종목 폴더·목표가 알림·숨긴 종목·주식모으기 조회 |
“잔고가 얼마야?”에서 “내 자산 변화와 받은 배당, 보유 종목 뉴스까지 정리해 줘”로. 앱에서 따로 확인하던 정보를 이제 내 AI에게 요청하세요.
위 추가 기능은 WTS(토스증권 웹 내부 API)를 사용합니다. 지원 대상은 토스증권이며, 일반 토스뱅킹·카드 소비 내역은 포함하지 않습니다. 전체 기능 비교 →
빠른 시작
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를 참고하세요.
이렇게 사용하세요
# 시장 살펴보기
tossctl quote flows A005930
tossctl market signals
# 내 배당 확인하기
tossctl portfolio dividends
# 이번 달 이전의 완료·취소 주문도 확인하기
tossctl orders completed --all-dates --size 50
# 보유 종목을 스크립트로 넘기기
tossctl portfolio positions --output json
위 수급 명령은 WTS를 사용하며, 공식 API의 투자자별 매매동향 조회도 별도로 지원합니다. AI 시그널·배당 등 추가 기능의 사용법은 명령 레퍼런스에서 확인하세요.
# 전체 계좌 자산과 보유 종목 브리핑
tossctl account overview
tossctl portfolio briefing
# 실시간 체결 구독과 API 변경 감시
tossctl stream --trade A005930
tossctl monitor api # 읽기 전용 점검; 통과 0, 실패 1
tossctl history sync로 보유 종목·거래 내역 수집을 미리 확인할 수 있습니다. 저장 후 history list, history search, history compare는 오프라인으로 동작합니다.
--fields symbol,quantity --compact로 필요한 JSON 필드만 받으세요. 로컬 이력·브리핑 가이드 →
AI와 함께 사용하기
설치한 tossctl을 AI 앱에 연결하면 말로 요청할 수 있습니다. Claude Code·Codex·Cursor에서 MCP 연결을 지원합니다.
Claude Code에 MCP를 등록하려면:
claude mcp add tossctl tossctl mcp
연결한 에이전트에 이렇게 요청하세요.
내 자산 변화와 받은 배당을 정리하고, 보유 종목 뉴스도 함께 보여줘.
Codex·Cursor 등 앱별 등록 방법은 MCP 가이드를 참고하세요.
사용하는 AI 앱이 아래 형식의 MCP 설정을 지원하면 추가하세요.
{
"mcpServers": {
"tossinvest": { "command": "tossctl", "args": ["mcp"] }
}
}
주문 전 확인하세요
[!IMPORTANT]
실거래는 기본적으로 꺼져 있습니다. 에이전트는 주문을 미리보기합니다. 실제 주문은 사람이 검토·승인하고 실행하세요.
tossctl order preview --symbol AAPL --side buy --qty 1 --price 200
# 미리보기만 실행합니다. 실제 주문은 사람이 결과와 확인 토큰을 검토한 뒤 진행하세요.
- 주문 내용 확인: 종목·수량·가격을 미리보기에서 확인한 뒤 직접 승인하고 실행하세요.
- 관심종목·알림 변경: 무엇이 바뀌는지 미리 확인하고 승인하세요.
- 전송 결과를 모를 때: 다시 주문하기 전에 주문 상태부터 확인하세요.
아직 안정화 중이며 기본적으로 숨겨져 있습니다. 활성화해도 토스증권의 이용 자격을 별도로 충족해야 합니다. 모의투자와 실거래의 잔고·주문은 분리되고, 모의 주문 승인이 실거래 승인으로 이어지지 않습니다. 설정과 제한은 지원 범위에서 확인하세요.
거래를 활성화하는 방법과 확인 절차는 안전 가이드를 참고하세요.
문서
문제나 제안은 Issues에 남겨주세요. 보안 문제는 SECURITY.md를 참고하세요.
스폰서십 · 후원
스폰서십·브랜드 노출에 관심이 있다면 [email protected]로 연락해 주세요.
Contributors
기여해 주신 모든 분께 감사합니다. 참여 방법은 CONTRIBUTING.md를 참고하세요.
Star History
License
MIT
