pi-toss

토스증권 Open API 클라이언트 pi 패키지 — 시세·시장 데이터·자산·주문·조건주문.

pi-kis v0.3.0에서 분리된 독립 패키지입니다. KIS 툴(kis_*)이 필요하면 pi-kis를 함께 설치하세요.

설치

pi install npm:pi-toss
# (KIS도 함께: pi install npm:pi-kis)
# pi 재시작

키 마이그레이션 불필요: pi-kis 0.2.x에서 토스 키를 등록해 뒀다면 그대로 사용됩니다. 두 패키지는 같은 키 저장소(OS 키체인 pi-kis SERVICE / ~/.pi/agent/kis-keys.json)를 공유합니다. pi install npm:pi-kis와 pi install npm:pi-toss는 설치 순서 무관.

타점 분석(kis-timing) 스킬은 pi-kis가 단독 제공합니다. 두 패키지가 같은 번들 스킬을 동시에 등록하면 pi가 이름 충돌 경고([Skill conflicts])를 내므로, 공용 스킬 등록은 pi-kis만 담당합니다. pi-kis 없이 pi-toss만 쓰는 경우에는 toss_chart로 직접 분석하세요 (예: "005930 일봉 RSI 알려줘").

사용

# pi 안에서:
/toss-key      # client_id/client_secret 등록 (developers.tossinvest.com 발급) → 공용 키 저장소

# 그 다음 자연어로:
"AAPL 현재가"                  # toss_price
"005930 1분봉"                 # toss_chart (interval: 1m — KIS에는 없는 분봉)
"달러 환율"                     # toss_market (kind: exchange-rate)
"코스피 투자자별 매매대금"        # toss_market (kind: investor-trading)
"테슬라 매수 유의사항"            # toss_market (kind: warnings)
"내 자산 조회"                  # toss_balance
"삼성전자 10주 시장가 매수"       # toss_order  (실전 — 사용자 확인 후)
"손절+목표 OCO 조건주문"          # toss_conditional (KIS에 없는 강점)

도구

도구	설명
toss_price	현재가 — 복수 종목 (KRX 6자리 / US 티커, 콤마 구분 최대 200)
toss_chart	캔들 차트·지표 — 일봉(1d)/1분봉(1m), 공용 지표 로직(pi-finance-core)
toss_market	토스 전용 시장 데이터 (환율·장운영시간·랭킹·투자자별 매매대금·종목경고 — KIS 비겹침)
toss_balance	자산 종합 (계좌·보유종목·매수여력 KRW/USD·수수료)
toss_order	주문 생성 (지정가/시장가, clientOrderId 멱등, 1억원 이상 confirm 필수)
toss_orders	주문 목록/상세/정정/취소
toss_conditional	조건주문 (SINGLE/OCO/OTO — KIS에 없는 강점)

📘 조건주문 사용 패턴 (예약 매수 + 체결 시 위아래 로스/익절 브래킷, OTO secondSide, 주의사항)은 skills/toss-conditional/SKILL.md 참고.

⚠️ 실전 전용 패키지입니다 (모의투자 없음). 주문·취소·정정 툴은 사용자 확인 후에만 호출하세요.

에이전트 디버깅 가이드 (툴 발견·파라미터 확인)

toss_* 툴은 MCP가 아닌 네이티브 pi 툴입니다 — mcp({ describe / search }) 게이트웨이는 MCP 서버 전용이라 여기서 조회되지 않습니다 ("Tool not found"). 툴은 직접 호출하고, 파라미터·동작이 궁금하면 아래 순서로 확인하세요 (빠른 것부터).

1. 세션 툴 스키마 — pi가 로드한 툴 함수 정의에 파라미터 설명·필수값이 이미 있음
2. src/agent/tools.ts (설치본: ~/.pi/agent/npm/node_modules/pi-toss/src/agent/tools.ts) — 툴 등록·입력 검증·에러 메시지 원본 (예: toss_conditional modify는 conditionalOrderId/type/side/quantity/orderType/expireDate/triggerPrice 필수, OCO/OTO는 secondTriggerPrice 추가 필요, OTO(연속주문)는 secondSide로 자식 방향 지정 — first=BUY 체결 후 second=SELL) (참고: OTO/OCO는 지정가 LIMIT만 지원 — 공식 스펙 openapi.tossinvest.com)
3. src/roles/toss.ts — 실제 API 호출 로직·기본값·제약 (예: OCO/OTO 조건주문은 LIMIT만 허용)

• 실전 API는 서버 에러 메시지가 가장 빠른 피드백 — 반복 호출하며 파라미터 교정 (예: "지정가 주문 시 가격을 지정해야 합니다" → orderPrice 누락, "호가 단위에 맞지 않습니다" → 소수점 자리수 조정)
• rg 검색 시 glob은 -g '*.ts' (ripgrep에는 --include 플래그 없음)
• 주문·취소·정정 계열 툴은 실전 반영 전 사용자 확인 필수

아키텍처

index.ts             — thin entry: export default registerExtension
src/
  client.ts          토스 transport — OAuth2 client_credentials + 토큰 캐시 + { result } 언랩 + 재시도 정책
  ratelimit.ts       그룹별 레이트리밋 (ACCOUNT 1/s ~ MARKET_DATA 10/s, 429 백오프)
  secret.ts          공용 키 저장소 위 토스 키 뷰 (pi-kis와 공유 — mergeWrite)
  roles/             — 도메인 역할 (typed wrapper, 에이전트가 직접 import)
    toss.ts          시세·시장·자산·주문·조건주문 (그룹별 ratelimit 명시)
  agent/             — pi 통합
    extension.ts     registerExtension
    tools.ts         toss_* 7 툴 (execute는 roles 위임)
    commands.ts      /toss-key

시크릿 저장소

pi-kis와 공유합니다 (namespace pi-kis, env KIS_SECRET_STORE/KIS_KEYS_FILE). 백엔드 우선순위: OS 키체인(@napi-rs/keyring) → 0600 파일 폴백(~/.pi/agent/kis-keys.json). 자세한 동작(적응형 폴백/마이그레이션)은 pi-finance-core 참고.

개발

이 패키지는 pi-finances 모노레포(pnpm workspace)의 일부입니다.

pnpm install        # 루트에서
pnpm typecheck      # 전체 타입체크