AI 에이전트 가이드

tossctl 은 AI 에이전트(Claude Code · Codex · Cursor · OpenClaw 등)가 토스증권을 다루도록 설계됐습니다. 이 페이지는 에이전트가 안전하고 정확하게 쓰기 위한 규칙을 정리합니다.

LLM이 바로 읽기 좋은 형식: /llms.txt (큐레이션 색인) · /llms-full.txt (전체 문서 단일 파일).

핵심 규칙

항상 --output json 으로 호출하라. 표(table) 출력은 사람용이며, 파싱하지 말 것.
말단 명령의 정책을 확인하라. quote alert·portfolio hidden·watchlist에는 쓰기가 있다. 상위 명령 이름만으로 읽기 전용이라 판단하지 말고 mutating, writes_state, environment와 ops의 mutation 정책을 확인하라.
거래는 기본 비활성. config.json 에서 허용되지 않으면 실패한다. 임의로 켜지 말고 사용자에게 확인받아라.
주문 전 반드시 order preview 를 실행해 수량·가격·금액을 확인하라(주문 안 나감).
실거래는 2단계: --execute + --confirm <token>. token 은 preview/확인 흐름에서 나온 값이며, 추측하거나 우회하지 마라.
비거래 쓰기·모의투자도 현재 요청의 승인이 필요하다. 설정 변경은 preview와 상태에 묶인 confirm, 불가역 작업은 추가 acknowledgement를 요구한다. paper 쓰기는 별도 옵트인 후 --execute를 사용하며 실거래 승인으로 재사용하지 않는다.
개인정보 주의. 응답에는 계좌번호·잔고·보유 종목이 들어있다. 외부로 전송·로깅하지 마라.

권장 워크플로

1. tossctl doctor --output json        # 환경·세션 상태 확인
2. (세션 없으면) 사용자에게 `tossctl auth login` 안내
3. tossctl account summary --output json
4. tossctl portfolio positions --output json
5. (거래 요청 시) tossctl order preview ... --output json  → 사용자 확인
6. 사람이 최종 확인한 뒤 live 명령 실행 (에이전트가 자동 주문하지 않음)

세션·인증

세션은 tossctl auth login 으로 사람이 1회 생성한다(QR + 폰 승인). 에이전트는 로그인을 대신할 수 없다 — 세션이 없으면 사용자에게 로그인을 요청하라.
만료가 가까우면 stderr 에 경고가 나온다. tossctl auth extend 로 폰 푸시 승인을 통해 연장할 수 있다.
tossctl auth status --output json 으로 세션 유효성·만료를 프로그램적으로 확인한다.

토스 공식 Open API 키를 등록하면 공식이 지원하는 조회·거래는 OAuth 경로로 처리되고 토큰이 자동 갱신됩니다. 웹 세션(WTS)은 약 7일 활동 만료가 있어 사람의 폰 승인이 주기적으로 필요하지만, 공식 경로는 그 제약이 없어 CI·서버·장기 실행 에이전트에 유리합니다. 웹 세션만 있으면 WTS 기능은 동작하지만 official-only 조회·조건주문·stream에는 공식 키가 필요합니다.

비대화형 등록: TOSSCTL_OPENAPI_KEY / TOSSCTL_OPENAPI_SECRET 환경변수를 설정한 뒤 tossctl openapi login (플래그로도 전달 가능). 자격증명 파일은 0600 으로 저장된다.
tossctl openapi status --output json — 키·토큰·허용 IP·라우팅 진단. 공식 키는 IP 허용 목록이 필요하니 서버 IP 등록 여부를 확인하라.
tossctl openapi ip replace-current --output json — 현재 공인 IP와 기존 목록을 비교한 교체 계획만 반환한다. 사용자가 계획을 승인한 뒤 preview의 confirm_token으로 --execute --confirm <token>을 호출한다. 각 변경을 서버에서 재검증하며 실패 시 실제 상태를 조회해 기존 허용 목록을 복구한다.
tossctl <명령> --backend auto|wts|openapi — 요청별 라우팅 백엔드 지정(기본 auto).
처음 설정은 tossctl init 위저드로도 가능하다.
자세한 내용: 공식 Open API 자동 라우팅.

출력 계약

성공 시 stdout 에 JSON, 실패 시 비정상 종료 코드 + stderr 메시지.
tossctl monitor api는 기본 86개 조회 endpoint를 점검한다. paper 옵트인 시 전용 4개가 추가된다. 모든 장애나 데이터 오류를 보장해서 탐지하지는 않는다.

하지 말 것

실제 계좌 데이터를 공개 출력/커밋/로그에 남기기.
preview 없이 주문 실행, --confirm 토큰 추측, 거래 게이트 우회.
table 출력 파싱(형식이 사람용이라 깨지기 쉬움) — 항상 JSON.
에이전트가 tossctl update를 자동 실행하기. 업데이트 확인은 읽기 전용 tossctl update --check를 사용한다.

같이 보기

명령 레퍼런스 — 전체 명령 목록
안전 모델 — 거래 보호 장치 상세
지원 범위 — 공식 API 대비 커버리지

로컬 이력과 작은 응답

--fields로 JSON 키·중첩 경로를 선택하고 --compact로 들여쓰기를 제거할 수 있습니다. 예: tossctl portfolio positions --fields symbol,quantity --compact. 없는 필드는 생략되므로 먼저 전체 JSON을 확인하세요. 이력 조회 시 snapshot.collected_at, 수집 범위, complete·warnings를 확인하고, 브리핑에서는 partial·sections를 보존하세요. history sync는 로컬 쓰기이지만 현재 요청의 저장 승인을 받은 뒤 preview의 confirm_token으로만 실행합니다. 이력·브리핑 가이드