Tossinvest Cli

한국어 · English

tossinvest-cli

공식 API로는 못 보는 토스증권 데이터까지, CLI와 MCP로.
계좌·시세·주문에 수급·AI 시그널·배당·관심종목을 더하세요.
터미널, 스크립트, AI 에이전트에서 같은 tossctl로 사용합니다.

빠른 시작 · 왜 tossctl인가 · CLI와 MCP · 안전 · 문서

[!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로 로그인합니다.

irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex

tossctl openapi login
tossctl openapi status

이렇게 사용하세요

# 수급과 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

{
  "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를 참고하세요.

{
  "experimental": {
    "paper_trading": true
  }
}

문서

개발과 기여

로컬 빌드는 make build, 테스트는 make test로 실행합니다.

버그와 제안은 Issues, 변경 사항은 Pull Request로 보내주세요. 자세한 기준은 CONTRIBUTING.md, 보안 문제는 SECURITY.md를 확인하세요.

후원

_{현재 1분이 제 오픈소스 작업을 후원하고 있습니다 (일회성 포함). 후원은 tossinvest-cli를 포함한 제 작업 전반에 쓰입니다.}

Contributors

기여해 주신 모든 분께 감사합니다. 참여 방법은 CONTRIBUTING.md를 참고하세요.

tossinvest-cli contributors

Star History

License

MIT