Show GN: 토스증권 Open API용 Agent Skill — 에이전트가 호출하는 한국 증권 API 첫걸음

2026년 6월 현재 토스증권이 Open API를 공개하면서 Codex, Claude Code 같은 코딩 에이전트가 한국 주식 조회·주문을 직접 다룰 길이 열렸습니다. 깃헙에서 화제가 된 BEOKS/tossinvest-skill 저장소는 그 API를 Agent Skill 형태로 한 번 감싸 설치 한 줄로 에이전트에 붙일 수 있게 해줍니다. SKILL.md + 공식 OpenAPI JSON + 표준 라이브러리 기반 CLI + 주문 dry-run 안전장치까지 한 묶음이라 "에이전트가 한국 주식을 만져도 되는가"라는 질문에 현실적인 답을 줍니다.

Agent Skill이란 — 토스증권 API를 에이전트에 붙이는 방식

기존에는 토스증권 Open API를 쓰려면 OAuth2 토큰 발급 → 엔드포인트 문서 직접 탐색 → 시세/계좌/주문 API 호출 코드를 직접 작성해야 했습니다. tossinvest-skill은 그 흐름을 Agent Skill이라는 배포 단위로 묶어, npx skills add BEOKS/tossinvest-skill 한 줄로 Codex, Claude Code 같은 에이전트가 SKILL.md를 읽고 references/ 안 공식 OpenAPI JSON과 scripts/tossinvest.py CLI를 자동으로 활용하게 만듭니다.

핵심 구성은 4가지입니다. SKILL.md(에이전트 진입점), references/openapi.json(공식 OpenAPI 사본), references/workflows.md(엔드포인트 맵과 작업 흐름), scripts/tossinvest.py(표준 라이브러리만 사용한 CLI 헬퍼). OpenAI/Codex 계열 UI용 agents/openai.yaml 메타데이터도 포함되어 있어 같은 스킬을 Codex 앱에서도 그대로 읽을 수 있습니다.

설치와 자격증명 — 5분이면 끝나는 셋업

에이전트 종류에 따라 설치 명령어가 나뉩니다.

# Codex, Claude Code 등 npx skills 지원 에이전트 전체
npx skills add BEOKS/tossinvest-skill

# Claude Code로만 한정
npx skills add BEOKS/tossinvest-skill --agent claude-code

# 설치 없이 한 세션만 시험
npx skills use BEOKS/tossinvest-skill --skill tossinvest-skill --agent claude-code

자격증명은 환경변수 두 개면 충분합니다. CLI는 프로세스 환경변수를 먼저 읽고, 없으면 ~/.zshrc, ~/.zprofile, ~/.profile의 단순 assignment도 읽습니다.

export TOSS_API_KEY="..."
export TOSS_SECRET_KEY="..."
export TOSSINVEST_ACCOUNT="1"   # 계좌 API를 자주 쓸 때

토큰은 기본 출력에서 마스킹되고, 전체 access token이 꼭 필요할 때만 token --show-token으로 명시적으로 노출합니다. 로그에 토큰이 평문으로 새는 일을 막는 가장 작은 안전장치입니다.

CLI 한 줄로 보는 토스증권 API 범위

scripts/tossinvest.py는 외부 의존성 없이 파이썬 표준 라이브러리만으로 동작합니다. 다음 한 줄이 토스증권 Open API가 현재 제공하는 기능 범위를 그대로 보여줍니다.

python3 scripts/tossinvest.py list-endpoints

읽어 들이는 기능은 OAuth2 Client Credentials 토큰 발급, 국내/미국 주식 종목·현재가·호가·체결·상하한가·캔들 조회, KRW/USD 환율과 장 운영 캘린더, 계좌 목록·보존 주식·주문 목록·상세, 매수 가능 금액·매도 가능 수량·수수료, 주문 생성·정정·취소 dry-run까지 모두 한 묶음입니다. 실제 호출 예시는 다음과 같습니다.

python3 scripts/tossinvest.py token
python3 scripts/tossinvest.py stocks --symbols 005930,AAPL
python3 scripts/tossinvest.py prices --symbols 005930,AAPL
python3 scripts/tossinvest.py orderbook --symbol 005930
python3 scripts/tossinvest.py candles --symbol 005930 --interval 1d --count 30
python3 scripts/tossinvest.py market-calendar --country KR
python3 scripts/tossinvest.py accounts
python3 scripts/tossinvest.py holdings --account 1
python3 scripts/tossinvest.py buying-power --account 1 --currency KRW

주문 안전장치 — dry-run이 기본값인 이유

주문 생성·정정·취소 3개 API는 실제 자금을 움직이기 때문에 기본값이 dry-run입니다. 실행하지 않으면 다음과 같이 요청 본문만 JSON으로 보여주고 끝납니다.

python3 scripts/tossinvest.py create-order \
  --account 1 \
  --symbol 005930 \
  --side BUY \
  --order-type LIMIT \
  --quantity 1 \
  --price 70000 \
  --client-order-id dryrun-001

출력에는 dryRun: true, method: POST, path: /api/v1/orders, executeHint: "Re-run with --execute --yes only after explicit user confirmation."이 들어가 있어 의도치 않은 매수/매도를 미연에 잡습니다. 실제 주문을 넣을 때는 사용자가 계좌·종목·방향·수량·가격을 직접 확인한 뒤 --execute --yes를 같이 넘겨야만 실행됩니다.

라이브 주문 생성은 기본적으로 --client-order-id도 요구합니다. 멱등성 키 없이 실행하려면 의도적으로 --allow-no-client-order-id 플래그를 추가해야 해서, 네트워크 재시도로 인한 중복 주문 가능성을 줄여 줍니다.

| 안전장치 | 기본값 | 해제 방법 | 의도 |

|---------|--------|----------|------|

| dry-run | 항상 켜짐 | --execute --yes 명시 | 실제 주문 차단 |

| clientOrderId | 항상 요구 | --allow-no-client-order-id | 중복 주문 방지 |

| 토큰 마스킹 | 항상 켜짐 | token --show-token | 로그 노출 방지 |

비슷한 도구와 차이점 — k-skill, tossctl, 토스증권 공식 OpenAPI

긱뉴스 댓글에 나온 NomaDamas/k-skill은 토스증권 조회용 SKILL.md만 두고 각 API별 스크립트는 포함하지 않은 형태입니다. tossinvest-skill은 거기에 scripts/tossinvest.py라는 실행 가능한 CLI를 얹어 "에이전트가 문서만 읽고 끝나지 않고 실제 조회 호출까지 검증"할 수 있다는 차이가 있습니다. toss-securities 같은 tossctl 기반 CLI는 OAuth2 우선 + fallback 구조로 조회 전용 흐름을 제공하지만, Agent Skill 형태로 배포되지 않아 에이전트가 자동으로 인덱싱하지 못합니다.

| 도구 | 배포 형태 | 주문 영역 | 에이전트 통합 |

|------|----------|----------|---------------|

| tossinvest-skill | npx skills | dry-run + 실행 | SKILL.md + scripts |

| NomaDamas/k-skill | npx skills | 문서 중심 | SKILL.md |

| toss-securities (tossctl) | pip | 조회 전용 | 없음 |

| 토스증권 공식 OpenAPI | 직접 호출 | 주문 가능 | 직접 통합 필요 |

에이전트 기반 자동화 워크플로를 만들 생각이라면 tossinvest-skill 한 줄 설치 + CLI 호출이 가장 짧은 경로입니다.

에이전트에게 시킬 수 있는 일 — 프롬프트 예시

SKILL.md에는 에이전트가 이 스킬을 어떻게 활용할지 보여주는 3가지 예시 프롬프트가 들어 있습니다. 첫 번째는 사용 가능한 엔드포인트 요약, 두 번째는 보유 종목과 응답 필드 해설, 세 번째는 dry-run 주문 본문 준비입니다.

• Use $tossinvest-skill to summarize available Toss Securities Open API endpoints.
• Use $tossinvest-skill to check my account holdings and explain the response fields.
• Use $tossinvest-skill to prepare a dry-run order request for Samsung Electronics.

즉, 사용자는 자연어로 "내 토스증권 계좌에 뭐가 들었는지 알려줘" 한마디만 던지면, 에이전트가 SKILL.md를 읽고 holdings --account 1을 호출해서 응답을 사람이 읽기 좋게 풀어 줍니다.

결론 — 누구에게 추천하는가

2026년 6월 기준으로 토스증권 Open API용 Agent Skill은 다음 3가지 조건이 모두 맞는 개발자에게 가장 잘 맞습니다. (1) Codex, Claude Code 같은 에이전트 워크플로를 이미 쓰고 있고, (2) 한국 주식 포트폴리오를 코드에서 조회하거나 시뮬레이션하고 싶고, (3) 실제 주문 실행은 사람이 명시적으로 confirm 한 뒤에만 일어나야 한다고 느끼는 경우. 표준 라이브러리만으로 동작하는 CLI + dry-run 기본값 + 토큰 마스킹 + clientOrderId 강제는 2026년 시점의 금융 API 안전장치 기준을 거의 그대로 따라간 형태라, "에이전트한테 주문을 맡겨도 되나" 망설이는 팀이 도입을 검토할 만한 첫 단계로 적합합니다.