mcpField
T
tossinvest-skill

tossinvest-skill

github.com/beoks其他4896 次安装7 周前更新
代码仓库

关于 tossinvest-skill

tossinvest-skill 提供使用 Toss Securities Open API 的指南和命令行工具，面向 API 开发者及账户操作人员。它附带官方 API 参考资料，并为实时订单变更设置执行保护。

主要功能

  1. 01用于认证和查询端点的命令行工具
  2. 02访问市场、账户和订单数据
  3. 03通过 REST 请求调用支持的端点
  4. 04模拟运行及受保护的实时订单操作
  5. 05速率限制重试和响应处理

适用场景

  1. 01查询股票价格和市场数据
  2. 02查看账户持仓和订单历史
  3. 03通过明确的执行标志创建或管理订单

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/beoks/tossinvest-skill --skill tossinvest-skill

安装后在 Claude Code 中输入/tossinvest-skill确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
README.md
agents/
openai.yaml
references/
current-api.md
api-reference-index.md
workflows.md
official-overview.md
asyncapi.json
openapi.json
scripts/
tossinvest.py
scripts/tests/
test_tossinvest.py

详细介绍

Toss Securities Open API

概述

使用此技能构建或操作 Toss Securities Open API。随附的参考资料保留了官方 OpenAPI 源文件，scripts/tossinvest.py 则提供确定性的 CLI，用于身份验证、市场数据、账户数据、订单历史记录、订单信息，以及由用户委托的自主订单变更。

来源选择

  • 随附的官方参考资料于 2026-09-08 更新（OpenAPI 1.2.14）。这些资料是一个快照；如需了解未来的 API 变更，请再次查看官方来源。
  • 阅读 references/current-api.md，了解新增的 REST API、更新后的订单规则和 WebSocket 路由。CLI 可通过 request 支持新的 REST 端点；但它不实现 WebSocket 客户端。
  • 阅读 references/asyncapi.json，了解准确的实时订阅和消息架构。
  • 阅读 references/workflows.md，了解任务路由、端点分组、安全规则、速率限制和常见工作流。
  • 当需要了解确切的请求参数、架构、枚举值、示例或响应封装时，阅读 references/openapi.json。
  • 阅读 references/official-overview.md，了解官方快速入门、速率限制模型和错误模型。
  • 阅读 references/api-reference-index.md，查找官方的各 API 和模型 Markdown 页面。

凭据

使用 TOSS_API_KEY 作为 OAuth 客户端 ID，使用 TOSS_SECRET_KEY 作为 OAuth 客户端密钥。存在以下别名时也接受：TOSSINVEST_CLIENT_ID、TOSS_CLIENT_ID、TOSSINVEST_CLIENT_SECRET 和 TOSS_CLIENT_SECRET。随附的 CLI 会先读取进程环境变量，再回退到 ~/.zshrc、~/.zprofile 或 ~/.profile 中的简单赋值。

更改 shell 凭据后，请在调用进程中重新加载，或启动新的 shell：继承的环境变量优先于 shell 文件回退值。遇到 invalid_client 时，检查配置的客户端 ID/密钥；遇到 403 时，检查 WTS Open API 允许的 IP 列表。不要反复重新获取令牌来排查授权错误。

切勿打印密钥。除非用户明确需要将完整访问令牌用于外部工具，否则避免打印；默认情况下，scripts/tossinvest.py token 会对令牌进行脱敏。

CLI 快速入门

在技能目录中运行：

python3 scripts/tossinvest.py list-endpoints
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 accounts

账户、资产、订单历史记录和订单信息 API 需要账户序号：

python3 scripts/tossinvest.py holdings --account 1
python3 scripts/tossinvest.py buying-power --account 1 --currency KRW
python3 scripts/tossinvest.py orders --account 1 --status OPEN

为方便起见，可设置 TOSSINVEST_ACCOUNT、TOSS_ACCOUNT 或 TOSS_ACCOUNT_SEQ，然后省略 --account。

交易操作

将通过 request 执行的 create-order、modify-order、cancel-order 以及条件订单的创建、修改和取消视为会产生实际金融影响的操作。条件订单可能在 Agent 未运行时于之后触发交易；授权必须涵盖此行为及其到期时间。

  • 当用户以自然语言委托自主交易时，将此委托视为允许在指令有效期间反复执行买入、卖出、修改和取消操作。委托执行期间无需逐笔订单重新确认。
  • 使用当前账户状态、市场时段、购买力、可卖数量、警告、费用、价格、订单簿、成交记录和 K 线数据来决定每次实际变更。
  • 实际变更前优先立即进行一次试运行，以验证确切的请求正文；如果该操作仍符合委托目标且当前市场数据仍然适用，则自主执行同一操作。
  • 执行实际变更后，检查订单状态，并在适当时继续委托循环：等待、修改、取消、下达后续订单，或以简短报告结束。
  • 执行实际订单变更时，必须同时指定 --execute 和 --yes。
  • 创建订单时优先使用 --client-order-id。除非同时提供 --allow-no-client-order-id，否则 CLI 会阻止缺少此参数的实际 create-order 调用。

试运行示例：

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

实际执行示例：

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

响应处理

预期成功的非身份验证响应使用包含 result 的通用 JSON 信封。OAuth 令牌响应使用 OAuth2 格式。发生错误时，记录 HTTP 状态、X-Request-Id，并在其不可用时使用 referenceId、x-amz-cf-id 或旧版 cf-ray 作为备用值，同时记录 Toss 错误代码、消息、数据及速率限制标头。

CLI 会自动处理两种失败情况：

  • 使用缓存令牌时遇到 401：重新获取令牌一次并重试。每个客户端只能有一个有效访问令牌，因此其他进程获取令牌会在不提示的情况下使缓存失效。
  • 遇到 429：最多重试 --max-retries 次（默认值为 2，或使用 TOSSINVEST_MAX_RETRIES），并根据 Retry-After 或 X-RateLimit-Reset 等待，同时加入随机抖动。传入 --max-retries 0 可禁用重试。

不使用 CLI 调用 API 时，请实现相同的行为。list-endpoints 会报告每个端点的 rateLimitGroup——按组控制循环请求速率，并在 X-RateLimit-Remaining 降至零之前密切关注。

CLI 会解码 gzip 响应。如果订单结果无法确定，请先检查订单状态再重试，并在 10 分钟的有效窗口内保留相同的请求正文和 clientOrderId；如果无法核对结果，请停止操作。

评论

支持 Markdown