toss-securities

Toss Securities

此技能功能

執行Toss證券**唯讀（read-only）**流程。有兩種途徑：

1. 官方Open API（建議） — 使用OAuth 2.0 Client Credentials Token呼叫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）

憑證設為使用者環境變數，helper會直接向Toss伺服器呼叫，不會經由共享代理轉送。

環境變數	說明
TOSSINVEST_CLIENT_ID	client id（必要）
TOSSINVEST_CLIENT_SECRET	client secret（必要）
TOSSINVEST_ACCOUNT	accountSeq，查詢帳戶、資產、訂單時需要（選填）
TOSSINVEST_API_BASE_URL	預設為https://openapi.tossinvest.com（選填）

流程

helper內部會透過POST /oauth2/token取得Token（Client Credentials），並以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，會重新取得Token一次後重試。
• client_secret/Token會在錯誤訊息中被遮罩。

2. tossctl備援

若無官方憑證，則使用非官方的tossctl作為備援。

若尚未安裝，請先安裝tossctl

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

若無登入Session，請先完成上述流程。請勿使用其他非官方爬蟲或自行實作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失敗。
• 若帳戶、資產、訂單查詢helper缺少X-Tossinvest-Account，會在網路呼叫前失敗。
• tossctl備援若尚未auth login，帳戶/投資組合查詢可能失敗。
• 帳戶/訂單資訊敏感，請勿過度擴大輸出範圍。