toss-securities

Toss Securities

技能功能

执行Toss证券只读流程。有两种路径：

1. 官方Open API（推荐） — 使用OAuth 2.0客户端凭证令牌调用Toss证券官方Open API（https://openapi.tossinvest.com）。
2. tossctl回退 — 当没有官方凭证时，使用JungHoonGhae/tossinvest-cli的tossctl。

查询项目：

• 账户列表/持仓股票
• 行情（当前价/买卖盘/成交/涨跌停价/K线）/股票信息/买入注意事项
• 汇率/市场运营日历（韩国·美国）
• 待处理订单查询/订单详情/可买入金额/可卖出数量/手续费
• （tossctl回退）账户摘要、投资组合权重、关注股票

使用时机

• "帮我查一下Toss证券三星电子的当前价"
• "显示我的持仓股票"
• "查询待处理订单"
• "告诉我美元兑韩元汇率"

1. 优先使用官方Open API

前提条件

• 从Toss证券OpenAPI控制台获取的client_id/client_secret
• Node.js 18+（全局fetch）

凭证存储在用户环境变量中，助手直接调用Toss服务器，不通过共享代理。

环境变量	说明
TOSSINVEST_CLIENT_ID	客户端ID（必需）
TOSSINVEST_CLIENT_SECRET	客户端密钥（必需）
TOSSINVEST_ACCOUNT	accountSeq，查询账户/资产/订单时需要（可选）
TOSSINVEST_API_BASE_URL	默认为https://openapi.tossinvest.com（可选）

工作流程

助手内部通过POST /oauth2/token获取令牌（客户端凭证），并使用Authorization: Bearer进行调用。账户/资产/订单查询API还需要X-Tossinvest-Account头。

const {
  getPrices,
  listOfficialAccounts,
  getHoldings
} = require("toss-securities");

async function main() {
  const prices = await getPrices(["005930", "AAPL"]);

  const accounts = await listOfficialAccounts();
  const accountSeq = accounts.data.result[0].accountSeq;
  const holdings = await getHoldings({ account: accountSeq });

  console.log(prices.data);
  console.log(holdings.data);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

• 遇到429时，等待Retry-After/X-RateLimit-Reset指定的时间后重试。
• 遇到401时，重新获取令牌一次后重试。
• client_secret/令牌会在错误消息中被屏蔽。

2. tossctl回退

如果没有官方凭证，则使用非官方的tossctl作为回退。

首次安装tossctl

brew tap JungHoonGhae/tossinvest-cli
brew install tossctl
tossctl doctor
tossctl auth doctor
tossctl auth login

如果没有登录会话，请先完成上述流程。不要通过其他非官方爬虫或自定义HTTP实现来绕过。

支持的只读命令：

• tossctl account summary --output json
• tossctl portfolio positions --output json
• tossctl quote get TSLA --output json
• tossctl watchlist list --output json
• tossctl orders completed --market all --output json

也可以直接使用包封装函数（getAccountSummary、getPortfolioPositions、getQuote、listWatchlist等）。

谨慎回答

• 仅暴露必要的账户号码/敏感信息范围。
• 如果用户提到"今天"等相对日期，则转换为绝对日期回答。
• 此技能仅用于查询。明确说明实际交易变更不在范围内。

完成条件

• 已确认官方API凭证（或tossctl登录）状态。
• 已执行请求对应的只读调用。
• 结果已用韩语简要整理。

失败模式

• 如果没有官方API凭证（TOSSINVEST_CLIENT_ID/SECRET），则明确抛出TossCredentialsError。
• 如果账户/资产/订单查询助手缺少X-Tossinvest-Account，则在网络调用前失败。
• tossctl回退在未执行auth login时，账户/投资组合查询可能失败。
• 账户/订单信息敏感，不要过度扩大输出范围。