這一篇把券商接上:只選永豐 Shioaji,最花心思的不是「怎麼送單」,而是「哪些關卡不能拿掉」,以及送單出狀況時,程式要怎麼做才不會多送一筆。
跟著 Claude 把美股當沖 skill 改成台股版・第 12 篇
延伸開發:串接永豐 Shioaji API,讓程式在你同意後送單
第 9 篇我決定「先不串接券商」,由人親手下單。這一篇把券商接上:只選永豐 Shioaji,寫法參考我自己另一個網格交易系統的永豐串接。最花心思的不是「怎麼送單」,而是「哪些關卡不能拿掉」,以及送單出狀況時,程式要怎麼做才不會多送一筆。
1. 為什麼現在才串接,為什麼只選永豐
第 9 篇做下單單據時,我刻意讓程式「沒有任何送單的能力」:它只產生一張照著填就好的單據,由你自己打開券商 App 送出。那時候整套工具還沒做完,讓程式碰到真正的委託,風險大於方便。
現在工具都完成了,也用回測知道了這套規則的真實樣子,才回頭處理串接。我對 Claude 說:
可以開始 P7 券商串接。券商的部分可以參考我另一個專案「網格自動交易系統」的券商串接寫法。這次只先用永豐 Shioaji 的 API。
只選永豐的理由很實際:
- 有模擬環境:登入時切換一個參數就是模擬帳戶,可以放心測試送單、刪單。
- 有 Python 套件:
pip install shioaji就能用,和這套工具的其他程式同一種語言。 - 我已經在用:網格交易系統用永豐的 API 交易期貨好一段時間,踩過的坑(呼叫卡住、斷線、回報比下單結果先到)都有對應的寫法可以沿用。
小辭典
- API
- 讓程式和券商系統溝通的介面。程式透過它登入、送單、查委託,不用人去按 App。
- API Key/Secret Key
- 券商發給你的一組鑰匙,等於程式用的帳號密碼。外洩就等於別人可以用你的帳戶下單。
- 憑證
- 正式環境下單需要的電子憑證檔(.pfx)與密碼,模擬環境不需要。
- 模擬環境
- 券商提供的練習用系統,委託不會送到交易所、不會動到真錢。
- 環境變數
- 存在 Windows 系統裡的設定值。程式從這裡讀金鑰,就不用把金鑰寫進任何檔案。
- 委託書號
- 券商給每一筆委託的編號,用來查詢狀態、刪單。
2. 先決定:哪些關卡不能少
第 9 篇的每一筆委託都要過三道關。串接之後,第 3 道從「你親手送」變成「程式送」,所以要把條件訂得更緊:
| 關卡 | 第 9 篇(手動模式) | 這一篇(永豐 API 模式) |
|---|---|---|
| 1. 風控 | tw-risk 今天 PASS 了這一筆一模一樣的委託(指紋相符) | 完全一樣 |
| 2. 你同意 | 你在對話中明確說要下這一筆,原話逐字記錄;含糊或否定不算 | 完全一樣 |
| 3. 送出 | 你自己打開券商 App 照單據送出 | 程式送出,但只限:同意後 10 分鐘內、盤中 09:00–13:30、同一筆只送一次 |
這裡有一個要誠實說明的改變:第 9 篇說過「就算串接,也要保留你確認送出這一關」。實際做的時候,我和 Claude 討論後的結論是:你對「這一筆」的明確同意,本身就是那個確認。同意的內容(股票、張數、價格)被指紋鎖住,改任何一個欄位都要重新風控、重新同意;同意也會過期,10 分鐘後價格可能已經不一樣,就要重來。
模擬切到實盤,只有你能做
設定檔裡 paper(模擬帳戶)和 shioaji_simulation(永豐模擬環境)兩個欄位必須一致,不一致程式就不連線。這兩個欄位寫在 skill 的規則裡:Claude 不能改。從模擬切到實盤,一定是你自己打開檔案改。
還有幾件事程式一律不做:不替你同意、同意過期不送、背景監看到價格時不會直接下單(那時沒有人在場可以說要),也不做先賣後買和融資融券。
3. 開發過程:參考網格系統的寫法
Claude 先讀了網格系統的永豐串接程式。那是期貨版,但很多問題是一樣的。它整理出可以沿用的做法,以及要改成現股的地方:
| 問題 | 網格系統遇過什麼 | 台股版怎麼做 |
|---|---|---|
| 呼叫卡住 | 刪單曾經卡住 1~5 分鐘不回來,整個程式停住 | 每次呼叫永豐都放在另一個執行緒,最多等 20 秒 |
| 送單逾時 | 逾時不代表沒送出 | 先記「送單中」再送;逾時就標記「結果不明」,絕不重送 |
| 對回委託 | 回報可能比下單結果先到 | 每筆委託帶一個 6 碼標記(指紋前 6 碼),結果不明時用它把券商的委託對回紀錄 |
| 金鑰 | 網格系統放在 .env 檔 | 改成只讀環境變數,和 FinMind token 同一套做法;任何檔案都沒有金鑰 |
| 數量單位 | 期貨以口計 | 整張用「整股」、數量填張;不到一張用「盤中零股」、數量填股 |
| 成交入帳 | 同一筆成交可能從好幾個地方回來 | 記錄已入帳的成交筆數,同一筆不會記兩次 |
數量單位這一點很容易出錯:工具裡的委託一律用「股」記,永豐的整股委託卻是用「張」。換算錯了,就是 1,000 倍的差距。1,500 股這種「1 張又 500 股」的數量,程式不會自己拆,而是要求拆成兩筆委託,避免你同意的和實際送出的不一樣。
做完之後,tw-broker 多了四個指令:
| 指令 | 做什麼 | 會不會下單 |
|---|---|---|
| check | 登入、看帳號(只顯示末四碼)、API 簽署狀態 | 不會 |
| sign-test | 永豐要求的 API 測試單:一律模擬環境、用跌停價買 1 張、送出後立刻刪單 | 只在模擬環境 |
| send | 把你同意的那一筆送到永豐 | 會 |
| sync | 從永豐取回委託狀態和成交,更新持股與損益 | 不會 |
原本的 cancel 也升級了:在 API 模式下會同時向永豐刪單。測試方面,Claude 寫了一個「假的永豐套件」,模擬掛單、成交、部分成交、拒單、逾時等情況,新增 19 個測試,整套工具累計 124 個測試全部通過。
4. 準備:API、環境變數、設定檔
- 到永豐的網站申請 API Key,並依官方說明簽署 API 相關文件。
- 用 Windows 的
setx把兩把鑰匙存成環境變數(在「命令提示字元」執行,換成你自己的值):
setx SHIOAJI_API_KEY "你的 API Key"
setx SHIOAJI_SECRET_KEY "你的 Secret Key"
- 打開專案裡的
trader/config.json,把"broker": "manual"改成"broker": "shioaji","paper": true不要動(模擬環境)。 - 關掉 Claude 桌面版再重開(環境變數要重開才讀得到),對 Claude 說:
檢查永豐連線,不要下單。
金鑰絕對不要貼進對話
API Key、Secret Key、憑證密碼都只放在環境變數。不要貼給 Claude,也不要寫進任何檔案。程式缺少金鑰時,只會告訴你「哪個名字沒設定」,不會叫你把值給它。
正式環境另外需要憑證檔路徑、憑證密碼、身分證字號三個環境變數。本篇只用模擬環境,不需要。第一次使用 API 的帳號,永豐會要求先在模擬環境送一張測試單(sign-test 做的就是這件事,服務時間是週一到週五 08:00–20:00),約 5 分鐘後再檢查簽署狀態。
5. 第一次連線,就抓到兩個問題
第一次 check 就登入成功,也讀到了模擬環境的證券帳號和「已簽署」狀態,但有兩個地方不對。
問題一:股票名稱和參考價是空的
[OK] 讀取合約:2330 (參考價 -)
Claude 查到的原因
Shioaji 1.7.9 新的合約查詢(contracts.get)只回傳代號和交易所,名稱、參考價、跌停價都是空的。舊的查法有完整資料,但已經標示為「即將淘汰」。正確的做法是先用 contracts.get 取得下單用的合約,再用 contracts.info 取名稱與漲跌停。
這不只是畫面好不好看:sign-test 要用跌停價送一張「不會成交」的測試單,拿不到跌停價就送不出去。用假券商跑的測試抓不到這種問題,只有連上真的系統才會發現。
問題二:畫面上出現了身分證字號
登入時,永豐的套件會自己在畫面印出幾行連線訊息,其中一行含有身分證字號。如果讀者把執行結果截圖或貼到網路上問問題,就會外洩。Claude 在登入前把這些訊息關掉了。
自己寫程式的讀者請注意
用 Shioaji 寫程式時,貼輸出到網路之前先檢查有沒有身分證字號、完整帳號。這套工具顯示帳號時只留末四碼。
修正後的 check(帳號以示意值取代):
[OK] 登入永豐:模擬環境 證券帳號 XXXX-***1234
[OK] 證券帳號 API 簽署:已簽署
[OK] 讀取合約:2330 台積電(參考價 2340.0)
[OK] 今天的證券委託 0 筆
模式:模擬環境(paper)。這個指令不會下單。
6. 一筆交易從頭走一遍
本節以第 5 篇同一筆 2409 為例,展示整個流程的畫面;委託書號、成交價等數字為示範。
前面的流程和第 10 篇一樣:tw-entry 觸發 → tw-exit 規劃停損停利 → tw-budget 算張數 → tw-risk 檢查。接著問 Claude 有哪些單可以下,單據最後一行會告訴你這是永豐模擬環境:
#1 READY 買進 2409 2 張(2000 股)
送到永豐的委託內容:
股票代號 2409
買賣 買進(現股當沖,先買後賣)
交易方式 整股
價格 限價 29
數量 2 張(2000 股)
條件 ROD
停損出場最多虧 1,282 元(含成本),扣成本後報酬風險比 1.568
……
模擬環境:會送到永豐的模擬環境,不是真實帳戶。
券商模式:永豐 API(模擬環境)。要下哪一筆,請在對話中明確說出(例如「確認下單第 1 筆」);記錄你的同意後,10 分鐘內才能由程式送出。
你在對話中說:
確認下單第 1 筆
Claude 記錄你的原話,然後立刻送出:
已記錄你的同意(原文:「確認下單第 1 筆」)。
已透過永豐 API 送出第 1 筆(模擬環境):買進 2409 2 張(2000 股),限價 29。
委託書號 A0001,狀態:已送達交易所,等待成交
還沒成交:之後用 sync 更新成交,或用 cancel 刪單。
還沒成交時,就算再叫它送一次,也不會多送一筆:
不執行:第 1 筆已經送出過了,不會重送;查狀態請用 sync
過一會兒問 Claude「成交了沒」,它會從永豐取回成交,更新現金與持股:
第 1 筆 買進 2409 2 張(2000 股):全部成交
成交:買進 2409 2 張(2000 股) @ 29
帳上現金 241,951 元;持股 2409 2 張(2000 股);今天已實現損益(含成本)0 元。
出場也是同一套流程:產生平倉單 → tw-risk 檢查 → 你明確同意 → 程式送出。這一筆在停利價 30.1 賣出:
已透過永豐 API 送出第 1 筆(模擬環境):賣出 2409 2 張(2000 股),限價 30.1。
委託書號 A0002,狀態:全部成交
成交:賣出 2409 2 張(2000 股) @ 30.1
帳上現金 302,010 元;持股 無;今天已實現損益(含成本)2,010 元。
已實現損益 +2,010 元,和第 5 篇手動流程、tw-budget 的估算一致。
停損停利還是要靠提醒
台股交易所沒有停損停利單,這一版也沒有用程式設定券商的條件單。成交後要用 tw-alerts 建立提醒;到價時,一樣要重新走一次風控、你同意、送出。
7. 出狀況的時候
串接券商真正的難處在出錯的時候。以下是程式在各種情況下的回應:
| 情況 | 程式怎麼做 |
|---|---|
| 同意超過 10 分鐘 | 不送:「你的同意是 09:21 給的,已經超過 10 分鐘;價格可能變了,請重新執行 tw-risk 並再確認一次」 |
| 送單逾時、斷線 | 標記「結果不明」,不重送;用 sync 以 6 碼標記對回券商的委託,或請你打開永豐 App 確認。結果不明的委託也算進每日上限 |
| 部分成交 | 成交的部分記進持股;剩下的可以刪單,成交的部分要另外平倉 |
| 券商拒單 | 把券商訊息原樣告訴你;修正後要重新風控、重新同意 |
| 設定不一致 | 不連線:「paper 是 true、shioaji_simulation 是 false。模擬帳戶兩個都要是 true;實盤兩個都要是 false(請你自己改 trader/config.json)」 |
| 環境變數沒設 | 不連線,只列出缺少的名字,提醒你用 setx 設定,不會向你要金鑰 |
| 盤後 | 不送:「現在 13:31 不是盤中(09:00–13:30),不送單」 |
其中最重要的是「結果不明」。送單的那一瞬間如果網路斷了,程式無從得知委託到底有沒有送到券商。這時候「保險起見再送一次」是最危險的做法,可能變成兩筆。所以程式在送單前先把紀錄改成「送單中」,就算程式當掉,下次也不會再送;確認之前,一律當作「可能已經送出」。
送單結果不明:OutcomeUnknown: timeout
委託可能已經送到券商,也可能沒有。程式不會重送。請執行 sync 查詢,或打開永豐 App 確認。
第 1 筆 買進 2409 2 張(2000 股):已送達交易所,等待成交
8. 學到的事、照著說的話
01
先想關卡,再想功能
送單本身只有幾行程式;花時間的是決定什麼情況下絕對不送。
02
逾時不等於沒送出
結果不明時先查、不重送,是串接券商最重要的一條規則。
03
假的測試抓不到真的問題
合約資料是空的、畫面印出身分證字號,都是連上真系統才發現。
04
有舊專案就拿來參考
網格系統踩過的坑,直接變成台股版的防護。
你可以照著說的話
檢查永豐連線,告訴我帳號(只顯示末四碼)和 API 簽署狀態,不要下單。
第 1 筆風控過了嗎?念給我聽:股票、張數、價格、停損出場最多虧多少、是不是模擬環境。
第 1 筆成交了沒?有成交就更新我的持股和今天的損益。
第 1 筆還沒成交的話,幫我刪單。
沒有台股版程式的話:用永豐 Shioaji 的 Python 套件,幫我寫一個只在模擬環境下單的程式。金鑰從環境變數讀,不要寫進檔案;每一筆都要我在對話中明確說「確認」才送出;送單逾時就標記結果不明、不要重送;畫面上不要印出身分證字號和完整帳號。
常見問題
可以讓程式在到價時自動停損嗎?
這一版刻意不做。自動停損代表在沒有人同意的情況下送單,等於拿掉第 2 道關。到價時工具會提醒你,你同意後才送。
其他券商(富邦、元大、凱基)可以用嗎?
這次只串了永豐。程式把「跟券商溝通」的部分獨立成一個檔案,之後要接別家券商,主要就是換掉這一塊,三道關的流程不用改。
模擬環境的成交會跟真實市場一樣嗎?
不一定。模擬環境是練習用的系統,成交規則和速度可能和真實市場不同。它適合用來確認流程與程式行為,不能拿來估計實際績效。
台股版的程式可以下載嗎?
台股版還在開發中,暫不提供下載。等整個系列完成後,我會整理好放上 GitHub,並詳細說明安裝與使用方式。在那之前,可以用上面最後一句「照著說的話」請 Claude 寫一個簡易版。
進階:給習慣終端機的讀者
python .claude/skills/tw-broker/ticket.py check
python .claude/skills/tw-broker/ticket.py sign-test # 一律模擬環境
python .claude/skills/tw-broker/ticket.py approve --index 1 --reply "確認下單第 1 筆"
python .claude/skills/tw-broker/ticket.py send --index 1
python .claude/skills/tw-broker/ticket.py sync
python .claude/skills/tw-broker/ticket.py cancel --index 1 # 同時向永豐刪單
設定:"broker": "shioaji"、"shioaji_simulation"(須與 paper 一致)、"shioaji_account"(多個證券帳號時指定)、"approval_ttl_minutes"(預設 10)。環境變數:SHIOAJI_API_KEY、SHIOAJI_SECRET_KEY;正式環境另需 SHIOAJI_CA_PATH、SHIOAJI_CA_PASSWORD、SHIOAJI_PERSON_ID。委託:整張 → StockOrderLot.Common(數量=張),不到 1 張 → IntradayOdd(數量=股),StockOrderCond.Cash;市價 → MKT+IOC;零股只限價。Shioaji 1.7.9 起 order_type 改名 time_in_force。每筆委託的 custom_field 為指紋前 6 碼。紀錄狀態:approved → sending → placed/unknown → filled/cancelled/rejected;sending 與 unknown 也計入 tw-risk 的每日上限。
下一篇預告
整套工具到這裡都做完了。但寫完券商串接後,我回頭問了 Claude 兩個問題:盤中到底還有哪些地方需要 AI 判斷?既然交易邏輯幾乎是固定的,為什麼要寫成 skill,而不是寫成一個獨立程式(AP)?下一篇就來談這段討論。
本文僅為軟體工具教學與開發經驗分享,不構成任何投資建議。文中示範皆在券商模擬環境進行,個股僅為示範。程式交易與當沖風險極高,請自行評估並為自己的交易決策負責。券商 API 的申請與使用規定以券商官方公告為準;資料與方案以撰文時為準。









