Day Trader Skill改台股版12-延伸開發券商API串接

0Shares
Image

這一篇把券商接上:只選永豐 Shioaji,最花心思的不是「怎麼送單」,而是「哪些關卡不能拿掉」,以及送單出狀況時,程式要怎麼做才不會多送一筆。

跟著 Claude 把美股當沖 skill 改成台股版・第 12 篇

延伸開發:串接永豐 Shioaji API,讓程式在你同意後送單

第 9 篇我決定「先不串接券商」,由人親手下單。這一篇把券商接上:只選永豐 Shioaji,寫法參考我自己另一個網格交易系統的永豐串接。最花心思的不是「怎麼送單」,而是「哪些關卡不能拿掉」,以及送單出狀況時,程式要怎麼做才不會多送一筆。

  • 適合:想讓 Claude 幫忙送單,但不想失去控制的人
  • 工具:Claude 桌面版、永豐證券帳戶與 Shioaji API
  • 環境:永豐模擬環境(不是真實帳戶)

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、環境變數、設定檔

  1. 到永豐的網站申請 API Key,並依官方說明簽署 API 相關文件。
  2. 用 Windows 的 setx 把兩把鑰匙存成環境變數(在「命令提示字元」執行,換成你自己的值):
setx SHIOAJI_API_KEY "你的 API Key"
setx SHIOAJI_SECRET_KEY "你的 Secret Key"
  1. 打開專案裡的 trader/config.json,把 "broker": "manual" 改成 "broker": "shioaji","paper": true 不要動(模擬環境)。
  2. 關掉 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 的申請與使用規定以券商官方公告為準;資料與方案以撰文時為準。

0Shares


0 Comments
Oldest
Newest Most Voted

相關文章

Day Trader Skill改台股版11-延伸開發回測引擎

整套工具完成後,我發現一個問題:進場判斷只有一條固定規則,沒辦法比較參數,也沒有像樣的回測。於是請 Claude 再做一個回測引擎。

Day Trader Skill改台股版10-安裝與設定

這一篇是使用說明書:怎麼把 12 個工具裝進 Claude、怎麼填自己的資金與風控設定、一個交易日從開盤前到平倉怎麼用,以及盤中會跳出哪些訊息、看到時該怎麼做。

Day Trader Skill改台股版9-下單與安控

原版讓 Claude 透過券商工具送單,但前面要過三道關。台股版做了一個更保守的決定:程式完全不送單,只產生一張照著填就好的下單單據,由你親手在券商 App 送出,再把結果記回來。

Day Trader Skill改台股版8-台股回測測試

原版最有特色的工具,是在下單前把同一筆交易模擬一萬次。台股版加上了一件原版沒做的事:扣掉手續費和證交稅。結果很直接:一個不算成本時「接近擲銅板」的計畫,扣掉成本就變成偏向虧錢。
(adsbygoogle = window.adsbygoogle || []).push({});

最近發文

加入我們

Categories

最新留言

(adsbygoogle = window.adsbygoogle || []).push({});
0
本文有想法或疑問嗎?歡迎討論x
()
x