비공식 증권 CLI를 실전에 붙이기 전에 봐야 할 것 2026 — tossinvest-cli의 6단계 안전 게이트와 TOS 리스크

Posted on by

비공식 CLI가 내 증권 계좌를 만지게 해도 괜찮을까.

이 질문 앞에서는, 평소 자동화 좋아하는 사람도 한 번쯤 손이 멈춘다.

조회 자동화는 솔깃하다. JSON으로 뽑아서 대시보드에 붙이고, 반복 조회를 줄이고, 내 포트폴리오 스냅샷을 스크립트로 남기고, 에이전트 워크플로에 연결하는 그림도 바로 나온다.

근데 주문은 다르다.

주문은 “기능이 되네”에서 끝나는 문제가 아니다. 약관, 실계좌, 브라우저 세션, 비공식 내부 API, 실수 비용이 전부 한 줄에 묶인다.

그래서 나는 이런 도구를 볼 때, “되냐?”보다 먼저 “어디까지 써도 되냐?”를 본다.

2026년 3월 25일 기준 tossinvest-cli는 토스증권 웹 세션을 재사용해 조회와 일부 거래를 터미널에서 다루게 해주는 비공식 Go CLI다. 실행 바이너리는 tossctl이고, README는 이 프로젝트가 공식 제품이 아니며 토스증권 이용약관 위반에 해당할 수 있다고 처음부터 경고한다.

이 점이 오히려 흥미로웠다.

대충 만든 위험한 도구라면 보통 안전 얘기를 얼버무린다. 반대로 이 프로젝트는 거래 기능을 기본 전부 꺼두고, 여러 단계의 권한 게이트를 거치게 만들었다.

이 글은 “오 이거 신기하네”에서 멈추는 소개글이 아니다. tossinvest-cli를 실전에 붙이기 전에 무엇을 체크해야 하는지, 왜 조회 자동화와 주문 자동화를 같은 선상에 놓으면 안 되는지, 그리고 CLI 설계 관점에서 왜 이 프로젝트가 의외로 배울 점이 많은지를 정리한다.

한 줄 요약
tossinvest-cli는 조회 자동화 후보로는 꽤 매력적이지만,
주문 자동화 도구로는 실계좌 리스크와 TOS 리스크를 먼저 계산해야 한다.

지금 결론

먼저 결론부터 짧게 정리하면 이렇다.

  • 토스증권 데이터를 스크립트나 개인 대시보드에 붙이고 싶다면 조회 전용으로는 검토해볼 만하다.
  • --output json, doctor, auth status, preview 같은 표면은 에이전트 친화적으로 설계돼 있다.
  • 하지만 이 프로젝트는 공식 API가 아니고, 웹 내부 API를 비공식적으로 재사용한다.
  • README도 이용약관 위반 가능성과 계좌 제한, 손실 같은 리스크를 명시한다.
  • 그래서 내 기준에선 지금 단계의 안전한 사용 범위는 “조회 자동화 우선, 주문 자동화는 보수적 접근”이다.

쉽게 말하면, 이건 “바로 자동매매 돌립시다”용 도구가 아니라, “읽기 전용 자동화부터 신중하게 붙여볼 수 있는가”를 보는 도구다.

왜 이 주제가 TECHTAEK에 맞나

겉으로 보면 이 글은 투자 얘기 같아 보인다. 근데 채널 관점에서는 금융 추천 글이 아니라 위험한 외부 시스템을 자동화할 때 어떤 경계와 게이트를 설계해야 하는가에 더 가깝다.

즉 핵심은 종목 추천이 아니다.

  • 비공식 API를 다루는 태도
  • 실계좌와 자동화 사이의 경계선
  • JSON 출력과 CLI 설계
  • 권한 부여와 실행 승인 분리
  • 사람이 끝까지 잡아야 할 마지막 버튼

이건 딱 TECHTAEK 감성이다.

도구를 소개하더라도, “이거 된다더라”가 아니라 “언제 쓰고 언제 멈춰야 하는가”를 같이 말해야 한다.

특히 요즘은 AI 에이전트나 개인 자동화 시스템이 증권, 은행, 결제, 메일, 캘린더 같은 실제 돈과 권한이 얽힌 시스템까지 건드리기 시작했다.

그럴수록 중요한 건 기능 데모가 아니라 게이트 설계다.

그래서 tossinvest-cli는 금융 툴이면서 동시에 “위험한 자동화를 어떻게 설계해야 하는가”라는 좋은 사례로도 읽힌다.

tossinvest-cli가 실제로 하는 일

공식 GitHub README 기준으로 이 프로젝트는 토스증권 웹 세션을 재사용해 조회와 일부 거래를 터미널에서 다루는 비공식 CLI다.

실행 명령은 tossctl이다.

Quick Start 흐름은 대략 이렇다.

curl -fsSL <https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh> | sh

tossctl version
tossctl doctor
tossctl auth login
tossctl account summary --output json

여기서 바로 눈에 띄는 건 두 가지다.

첫째, 설치와 진단 명령이 분리돼 있다.

둘째, 처음 읽기 예시가 거래가 아니라 account summary다.

이 순서가 괜찮다. 위험한 도구일수록 첫 경험이 읽기 전용이어야 한다.

README를 보면 auth login은 Playwright 기반 브라우저 로그인이 필요하다.

python3 -m pip install playwright
python3 -m playwright install chromium

즉 이 CLI는 토스증권의 공식 토큰 발급 흐름을 쓰는 공개 API SDK가 아니라, 브라우저 세션을 확보하고 그 세션을 바탕으로 동작하는 구조에 가깝다.

이 구조만 봐도 감이 온다.

편의성은 좋을 수 있다. 하지만 안정성, 정책 적합성, 세션 지속성은 항상 따로 봐야 한다.

지원 범위는 생각보다 넓다

조회 기능만 놓고 보면 꽤 그럴듯하다.

README 기준 읽기 전용 명령은 아래를 포함한다.

  • 계좌 목록과 요약
  • 포트폴리오 구성
  • 시세 단건 조회와 배치 조회
  • 미체결 주문
  • 체결 내역
  • 단건 주문 조회
  • 관심 종목 조회
  • 포지션/주문 CSV 내보내기

예시 표면은 이렇게 생겼다.

tossctl account list
tossctl account summary
tossctl portfolio positions
tossctl portfolio allocation
tossctl orders list
tossctl orders completed --market us|kr|all
tossctl order show <id>
tossctl quote get <symbol>
tossctl quote batch <symbol> [symbol...]
tossctl watchlist list
tossctl export positions --market us|kr|all
tossctl export orders --market us|kr|all

솔직히 여기까지만 해도 꽤 많은 사람이 흔들린다.

왜냐면 개인 투자 자동화에서 진짜 필요한 건 대부분 “거래 실행”이 아니라 “반복 조회와 데이터 수집”이기 때문이다.

예를 들어 이런 건 바로 상상된다.

  • 아침마다 계좌 요약을 JSON으로 저장
  • 미국주식/국내주식 포지션을 하나의 표로 합치기
  • 미체결 주문이나 전일 체결 내역을 로그로 남기기
  • 시세 배치 조회 후 내가 만든 간단한 리스크 대시보드에 붙이기
  • CSV export를 주간 백업 루틴에 넣기

이런 흐름은 자동매매와 완전히 다르다.

리스크도 다르고, 복구 난이도도 다르고, 심리적 부담도 다르다.

그래서 나는 이 도구를 볼 때 거래 기능보다 먼저 조회 기능을 본다.

조회 자동화만으로도 이미 충분히 쓸모가 크기 때문이다.

거래 기능도 있다

문제는 그 다음이다.

README는 거래 기능도 적지 않게 열어둔다.

  • 지정가 매수
  • 지정가 매도
  • 국내주식 거래
  • 미국주식 소수점 매수
  • 주문 취소
  • 주문 정정
  • 거래 권한 관리

표면만 보면 꽤 강력하다.

tossctl order preview --symbol <sym> --side <buy|sell> --qty <n> --price <krw>
tossctl order preview --symbol <sym> --side buy --fractional --amount <krw> --qty 0
tossctl order place ...flags... --execute --dangerously-skip-permissions --confirm <token>
tossctl order cancel --order-id <id> --symbol <sym> ...
tossctl order amend --order-id <id> ...
tossctl order permissions grant --ttl 300
tossctl order permissions status
tossctl order permissions revoke

여기서 중요한 건 “거래가 된다”가 아니다.

거래가 되더라도 얼마나 불편하게 만들었는가다.

이 프로젝트는 그 부분이 꽤 인상적이다.

실제 돈이 오가는 명령일수록 쉽게 되면 안 된다.

진짜 좋은 자동화는 위험한 동작을 빠르게 만드는 자동화가 아니라, 위험한 동작을 함부로 못 하게 만드는 자동화다.

tossinvest-cli는 적어도 README 수준에선 그 철학이 보인다.

내가 이 도구에서 제일 먼저 본 건 6단계 안전 게이트였다

README의 핵심은 기능표보다 이 줄이다.

config.json 허용 → permissions grant (TTL) → preview → --execute
  → --dangerously-skip-permissions → --confirm <token>

이 순서가 재밌다.

이걸 그냥 “안전장치 많네” 정도로 보면 아깝다. 이건 위험한 자동화 시스템의 설계 패턴으로 볼 가치가 있다.

하나씩 보면 이렇다.

1. config.json 허용

거래 기능은 설치 직후 전부 꺼져 있다.

README는 이 점을 아주 명확하게 말한다. config.json에서 기능별로 직접 허용해야만 거래 관련 동작이 열린다.

예시 설정은 이런 구조다.

{
  "schema_version": 2,
  "trading": {
    "grant": false,
    "place": false,
    "sell": false,
    "kr": false,
    "fractional": false,
    "cancel": false,
    "amend": false,
    "allow_live_order_actions": false,
    "dangerous_automation": {
      "complete_trade_auth": false,
      "accept_product_ack": false,
      "accept_fx_consent": false
    }
  }
}

이건 좋다.

설치만 했다고 거래가 열리면 안 된다. 기본값이 닫혀 있어야 한다.

2. permissions grant

권한 부여가 또 한 번 필요하다. 게다가 TTL 기반이다.

즉 영구적으로 “한 번 열어두고 계속 쓴다”보다 일시적으로 문을 연 뒤 다시 닫히는 형태에 가깝다.

실거래 자동화에서 이 TTL 개념은 꽤 중요하다.

장시간 살아 있는 거래 권한은 편하지만 위험하다. 반대로 짧은 TTL은 불편하지만 사고 범위를 줄인다.

3. preview

이 프로젝트가 마음에 드는 지점 중 하나다.

바로 place가 아니라 preview가 먼저 나온다.

즉 시스템은 “지금 네가 넣으려는 주문이 이런 형태”라는 중간 단계를 강제한다.

개인 자동화에서 이 preview 단계는 자주 빠진다. 근데 돈이 걸린 순간 preview가 없는 자동화는 사실상 총알 없는 안전장치다.

4. --execute

실행 플래그는 명시적이어야 한다.

조회 명령과 거래 명령은 겉으로 비슷해 보여도 리스크 레벨이 전혀 다르다.

그래서 실행 여부를 별도 플래그로 분리한 건 맞는 방향이다.

5. --dangerously-skip-permissions

이 이름이 아주 노골적이라 좋다.

많은 도구는 위험한 옵션 이름을 너무 점잖게 짓는다. 그래서 사람들이 덜 경계한다.

반대로 dangerously가 이름에 들어가면 최소한 사용자가 “내가 지금 뭘 생략하는지”를 의식하게 된다.

이건 사소해 보여도 중요하다.

CLI 설계에서 이름은 정책이다.

6. --confirm <token>

마지막으로 확인 토큰이 또 들어간다.

즉 실수로 플래그 하나 잘못 쳤다고 바로 실거래가 나가게 만들지 않겠다는 뜻이다.

이건 UX만 보면 불편하다. 근데 실계좌라면 이 불편이 맞다.

왜 이 안전 모델이 오히려 더 흥미로운가

솔직히 말하면, 나는 이 프로젝트에서 “토스증권을 CLI로 다룬다”는 사실 자체보다 위험한 자동화를 어떻게 불편하게 설계했는가가 더 흥미로웠다.

요즘 우리는 자동화를 자꾸 속도의 문제로만 본다.

빨라야 하고, 짧아야 하고, 클릭이 적어야 하고, 에이전트가 한 번에 끝내야 하고, 그래야 좋아 보인다고 느낀다.

근데 증권 계좌는 다르다.

빨라서 좋은 것보다, 잘못 눌러도 덜 터지는 게 먼저다.

이 프로젝트의 게이트 설계는 바로 그 상식을 다시 떠올리게 한다.

자동화를 붙일수록 “어떻게 더 많이 하게 할까”보다 “어떻게 선을 넘기 어렵게 만들까”가 더 중요해진다.

이건 tossinvest-cli를 넘어서 AI 에이전트 설계에도 그대로 적용된다.

승인 없이 메일 보내지 않기, 미리보기 없이 외부 시스템 수정하지 않기, TTL 없이 민감 권한 오래 쥐지 않기, 위험 옵션에 애매한 이름 붙이지 않기, 이런 패턴 전부 비슷하다.

내가 이걸 당장 주문 자동화로 안 보는 이유

여기서 솔직하게 선을 긋자.

이번 글 준비에서도 나는 이 도구를 “실계좌 주문 자동화 후보”로 보지 않았다.

이유는 간단하다.

되는지보다, 안전한지와 감당 가능한지가 먼저라서다.

그리고 이번 정리에서도 나는 일부러 tossctl auth login까지는 밀어붙이지 않았다.

실계좌가 연결되는 순간 이건 단순한 CLI 체험이 아니라 실제 금융 계정 실험이 되기 때문이다.

이 선을 일부러 넘지 않은 것 자체가, 오히려 이 도구를 보는 현실적인 태도라고 생각한다.

증권 계좌 자동화는 개인 메모 앱 자동화랑 같은 급이 아니다.

실수 비용이 다르다.

  • 주문 수량 오입력
  • 시장/국가 구분 실수
  • 세션 상태 꼬임
  • 정정/취소 ref 변경
  • 밤사이 unattended 실행
  • 약관/정책 이슈

이런 건 “한 번 잘못되면 귀찮다”가 아니라 실제 손실과 계정 리스크로 이어질 수 있다.

README도 이 점을 숨기지 않는다.

  • 공식 제품이 아님
  • 웹 내부 API를 비공식적으로 사용
  • 이용약관 위반 가능성
  • API 변경 가능성
  • 계좌 제한, 손실, 기타 불이익 가능성

이 정도면 신호는 충분하다.

도구가 스스로 “조심하라”고 말하면 사용자는 그 말을 문자 그대로 들어야 한다.

내가 이걸 실전에 붙인다면 1단계는 조회 자동화뿐이다

그럼 이 도구를 아예 무시해야 하냐.

그건 또 아니다.

내 기준에서 이 프로젝트의 현실적인 첫 단계는 조회 자동화다.

그것도 아주 좁게 시작하는 게 좋다.

예를 들면 이런 흐름이다.

시나리오 1. 계좌 요약 스냅샷 저장

아침에 한 번 계좌 요약을 JSON으로 저장한다.

tossctl account summary --output json > snapshots/account-summary.json

여기서 핵심은 거래가 아니다. 상태 기록이다.

내가 원하는 건 오늘 내 계좌가 어떤 모습이었는지 남기는 것이다.

이 정도는 리스크가 낮고, 활용도는 생각보다 높다.

시나리오 2. 포트폴리오와 시세 배치 조회

포지션과 시세를 따로 가져와 내가 만든 간단한 표나 노트에 붙일 수 있다.

tossctl portfolio positions --output json
tossctl quote batch TSLL 005930 GOOG VOO --output table

여기서도 중요한 건 주문이 아니라 관찰이다.

투자 자동화의 첫 단계는 대개 실행이 아니라 관측이다.

시나리오 3. 주문/체결 내역 백업

체결 내역과 주문 내역을 CSV로 빼두는 것도 꽤 실용적이다.

tossctl export positions --market us
tossctl export orders --market all

이건 나중에 회고할 때 유용하다. 내가 언제 무엇을 샀는지, 어떤 패턴으로 움직였는지, 별도 대시보드 없이도 기록이 남는다.

시나리오 4. 읽기 전용 에이전트 연결

--output json이 있는 CLI는 에이전트나 쉘 파이프라인에 붙이기 좋다.

예를 들면:

  • “오늘 내 계좌 요약 알려줘”
  • “어제 대비 큰 변동 있는 종목만 뽑아줘”
  • “미체결 주문 남아 있는지 확인해줘”

이 정도는 충분히 현실적인 개인 자동화다.

중요한 건 읽기 전용으로만 연결하는 것이다.

반대로 내가 당장 안 할 것들

아래는 적어도 지금 단계에서 내가 안 할 것들이다.

1. unattended 주문 실행

cron, 야간 배치, 승인 없는 정기 실행, 이런 건 안 한다.

증권 주문은 사람이 마지막 확인을 갖고 있어야 한다.

2. AI 에이전트에게 주문 권한 직접 위임

이건 더 안 한다.

AI가 요약하고, 후보를 정리하고, 내가 볼 대시보드를 만드는 건 괜찮다.

근데 실제 주문 실행 플래그를 AI가 잡는 건 현재 기준에선 선 넘는다고 본다.

3. dangerously가 붙은 플래그 상시 사용

이건 이름부터 경고다.

한 번 문제를 해결하려고 넣은 우회 플래그가 나중에 루틴이 되기 시작하면 그때부터 사고는 시간 문제다.

4. 국내주식/미국주식/소수점 주문을 한 흐름에 섞기

시장마다 맥락이 다르다. 국내주식과 미국주식은 세션, 호가, 주문 감각, 환전 맥락까지 다르다.

처음에는 한 시장만 다루는 게 맞다.

5. 약관과 정책을 확인하지 않은 채 “베타니까 괜찮겠지”라고 넘기기

베타라는 말은 문제가 있어도 괜찮다는 면허증이 아니다.

오히려 실계좌와 만나면 베타일수록 더 보수적으로 봐야 한다.

TOS 리스크는 어떻게 봐야 하나

여기서 조심해야 할 게 있다.

나는 이 글에서 “무조건 약관 위반이다”라고 단정하고 싶진 않다. 그건 공식 약관 문구와 실제 집행 기준을 더 세밀하게 봐야 하는 영역이다.

하지만 적어도 확실한 건 두 가지다.

첫째, 프로젝트 README가 스스로 토스증권 공식 제품이 아니고, 웹 내부 API를 비공식적으로 사용하며, 이용약관 위반에 해당할 수 있다고 경고한다.

둘째, 토스증권은 공식 서비스 약관과 전자금융/온라인 서비스 약관 체계 아래에서 운영되는 금융 서비스다.

이 두 사실만으로도 보수적으로 접근할 이유는 충분하다.

즉 이 문제는 법률 해석 놀이보다 먼저 운영 리스크 문제다.

공식 지원이 없는 내부 API를 붙인 자동화는 언제든 깨질 수 있다. 그리고 깨질 때 가장 아픈 쪽이 사용자일 수 있다.

그래서 내 기준에서는 TOS 리스크를 “문제가 생길 수도 있다더라” 정도로 가볍게 보지 않는다.

이건 도구 선택 단계에서부터 사용 범위를 제한해야 하는 신호다.

이 프로젝트가 에이전트 친화적으로 보이는 이유

웃긴 얘기지만, 나는 이걸 보면서 증권 얘기보다 CLI 설계 얘기를 더 많이 생각했다.

tossinvest-cli는 에이전트 친화적인 표면을 몇 가지 갖고 있다.

1. JSON 출력

이건 요즘 CLI에서 거의 필수다.

사람이 읽기 좋은 텍스트만 뿜는 도구는 자동화 파이프라인에 붙이는 순간 피곤해진다.

반대로 JSON이 있으면 에이전트, 쉘 스크립트, 대시보드, 로그 적재 모두 쉬워진다.

2. doctor

환경 진단 명령이 있는 건 좋다.

자동화 도구는 동작보다 실패 원인 파악이 더 중요할 때가 많다. 특히 브라우저 로그인, 세션 파일, Playwright 의존성, config 경로 같은 건 자주 꼬인다.

이럴 때 doctor가 있으면 운영 난이도가 확 내려간다.

3. auth status

세션 기반 도구는 현재 인증 상태를 보여줘야 한다.

안 그러면 “왜 안 되지?”를 사람 머리로 추측하게 만든다. 이건 작은 차이 같지만, 실사용성에서 아주 크다.

4. preview

아까도 말했지만, 미리보기는 단순 편의 기능이 아니다. 안전한 자동화의 핵심이다.

5. lineage 추적

README는 amend나 cancel 이후 주문 ref가 바뀔 수 있고, local lineage cache가 새 ref를 추적한다고 적는다.

이건 꽤 운영적인 디테일이다.

외부 시스템은 항상 “내가 처음 알던 ID”로만 움직이지 않는다. 이런 변화를 로컬에서 추적해주는 장치는 작아 보여도 중요하다.

즉 이 프로젝트는 단순히 기능만 넣은 게 아니라, 운영 중 생길 귀찮은 문제를 꽤 의식한 흔적이 있다.

그럼 이걸 누구에게 추천할 수 있나

모두에게 추천하진 못한다.

오히려 대상은 꽤 좁다.

추천 가능한 사람

  • 토스증권 데이터를 반복 조회하는 수고가 큰 사람
  • 포트폴리오/체결/시세를 개인 대시보드에 붙이고 싶은 사람
  • JSON 기반 개인 자동화나 에이전트 파이프라인을 이미 굴리는 사람
  • 실거래 자동화보다 조회 자동화를 먼저 붙일 수 있는 사람
  • 비공식 API 리스크를 감수할지 직접 판단할 수 있는 사람

추천하기 어려운 사람

  • 설치만 하면 바로 안전하게 자동매매가 된다고 기대하는 사람
  • 약관/TOS 리스크를 확인할 생각이 없는 사람
  • 실계좌에 붙는 스크립트를 unattended로 돌리고 싶은 사람
  • 브라우저 로그인 세션 관리나 Playwright 의존성이 부담스러운 사람
  • 장애나 정책 변경이 나면 스스로 복구하기 어려운 사람

이런 구분이 중요하다.

모든 자동화 도구는 “누구에게는 레버리지”지만 다른 누구에게는 “사고 증폭기”가 될 수 있다.

내가 이걸 실전에 붙인다면 이렇게 시작할 거다

만약 정말 붙인다면 나는 아래 순서로 갈 거다.

1단계. 조회 전용만 허용

거래 설정은 건드리지 않는다.

우선은 account summary, portfolio positions, quote batch, orders completed, export positions 이 정도만 본다.

2단계. 스냅샷 저장만 자동화

바로 분석이나 판단 자동화를 붙이지 않고, 먼저 raw snapshot을 저장한다.

왜냐면 자동화는 처음부터 똑똑해야 하는 게 아니라 먼저 관측 가능해야 하기 때문이다.

3단계. 내가 읽는 대시보드부터 만든다

이 단계에서도 주문은 안 한다.

그냥 “오늘 내 계좌는 어떤 상태인가” “어제 대비 뭐가 달라졌나” 이 정도만 본다.

4단계. 경고만 만들고 실행은 안 한다

예를 들면:

  • 특정 종목 비중 초과 경고
  • 미체결 주문 잔존 경고
  • 체결 내역 이상치 알림

이런 알림은 괜찮다. 하지만 알림과 주문 실행은 다르다.

5단계. 그래도 주문 자동화는 별도 프로젝트로 분리

만약 정말 주문 쪽을 만진다면, 그건 조회 자동화의 연장이 아니라 별도 위험 프로젝트로 다룰 거다.

검토 항목도 더 많아져야 한다.

  • 권한 TTL
  • 사람이 마지막 버튼을 누르는 구조
  • dry run / preview 로그 보관
  • 장애 시 fail-closed
  • 주문 실패/중복 제출 방지
  • 약관/정책 재확인

이 정도는 기본이다.

실수 TOP 5

1. 조회 자동화와 주문 자동화를 같은 수준으로 보는 실수

둘은 전혀 다르다.

조회 자동화는 정보 수집이다. 주문 자동화는 실계좌 액션이다.

같이 묶는 순간 판단이 흐려진다.

2. README의 경고 문구를 “법무용 문장” 정도로 흘리는 실수

이건 흘리면 안 된다.

공식 제품이 아니고, 비공식 내부 API를 쓰고, TOS 위반 가능성을 적었다면 그건 제품의 핵심 맥락이다.

3. preview를 생략하고 바로 실행 흐름부터 보는 실수

위험한 자동화에서 preview는 사치가 아니다. 핵심이다.

4. 브라우저 세션 기반이라는 사실을 가볍게 보는 실수

세션은 만료되고, 브라우저 환경은 바뀌고, Playwright 의존성은 깨질 수 있다.

실서비스용 자동화라면 이 불안정성을 먼저 계산해야 한다.

5. “내가 직접 누르는 마지막 버튼”을 없애는 실수

자동화의 끝은 무인 실행이 아니라 안전한 승인 설계일 때가 많다.

특히 돈이 오가는 시스템은 더 그렇다.

그래서 내 판단은 이렇다

tossinvest-cli는 무작정 위험한 프로젝트라고만 보기엔 아쉽다.

오히려 읽어보면 꽤 현실적으로 게이트를 설계한 흔적이 있고, 조회 자동화 관점에서는 매력적인 표면도 많다.

특히 --output json, doctor, auth status, preview, 권한 TTL, confirm token 같은 요소는 에이전트 시대 CLI 설계 참고 사례로도 볼 만하다.

하지만 동시에 실계좌를 다루는 비공식 도구라는 사실은 전혀 가벼워지지 않는다.

그래서 나는 이 도구를 “토스증권 자동매매 CLI”라고 부르고 싶지 않다.

내 기준에서 이건 조회 자동화와 안전한 경계 설계를 먼저 고민하게 만드는 비공식 CLI에 더 가깝다.

이 프레임이면 기대치가 건강해진다.

조회 자동화부터 좁게 시작하고, 실행 권한은 끝까지 보수적으로 다루고, README의 경고를 기능표보다 먼저 읽고, 사람 승인 루프를 절대 지우지 않는 것.

그 정도 태도가 있으면 이 프로젝트는 꽤 흥미로운 실험 대상이 된다.

반대로, “이제 토스증권도 에이전트가 알아서 매매해주겠네” 같은 기대라면 지금은 멈추는 게 맞다.

FAQ

Q1. tossinvest-cli는 토스증권 공식 API인가요?

아니다.

프로젝트 README는 이 도구가 공식 제품이 아니며, 웹 내부 API를 비공식적으로 사용한다고 명시한다.

Q2. 바로 주문 자동화까지 해도 되나요?

내 기준에선 아니다.

README에 다단계 게이트가 있고, TOS 위반 가능성과 실계좌 리스크도 적혀 있다. 처음엔 조회 자동화만 보는 게 훨씬 현실적이다.

Q3. 왜 Playwright가 필요한가요?

브라우저 로그인 세션을 확보하기 위해서다.

즉 공개 API 키 기반 CLI라기보다, 브라우저 흐름과 세션 재사용에 더 가까운 구조다.

Q4. 그래도 배울 점이 있나요?

있다.

위험한 자동화에서 권한 부여, TTL, preview, confirm token, 위험 옵션 네이밍을 어떻게 설계해야 하는지 꽤 좋은 힌트를 준다.

Q5. 누구에게 제일 먼저 맞을까요?

토스증권 데이터를 반복 조회하고, 그 결과를 개인 대시보드나 에이전트 파이프라인에 읽기 전용으로 붙이고 싶은 사람에게 더 맞다.

공식 출처

관련 글

SNS 초안

X용 280자

tossinvest-cli 재밌긴 한데, 내 기준엔 “자동매매 도구”보다 “조회 자동화 후보”에 더 가까움. 토스증권 웹 세션 재사용 비공식 CLI라서 JSON 출력, doctor, preview, confirm token 설계는 꽤 좋다. 근데 README도 TOS 위반 가능성과 실계좌 리스크를 명시한다. 핵심은 기능보다 경계선이다.

스레드용 500자

토스증권을 CLI로 다루는 tossinvest-cli가 재밌는 이유는 “주문도 된다”가 아니라 “위험한 자동화를 꽤 불편하게 설계했다”는 데 있다.

README 기준으로 거래 기능은 기본 전부 꺼져 있고, config.json 허용 -> permissions grant(TTL) -> preview -> --execute -> --dangerously-skip-permissions -> --confirm token 같은 6단계 게이트를 거친다.

내 판단은 이거다. 조회 자동화는 검토해볼 만하다. 주문 자동화는 아직 훨씬 보수적으로 봐야 한다. 비공식 내부 API, 브라우저 세션, 실계좌, TOS 리스크가 한 줄에 묶여 있기 때문이다.