SnapTrade Portfolio
概覽
透過 SnapTrade 連接券商帳戶,並產生每日總價值報告。此技能使用官方的 SnapTrade Python SDK (snaptrade_client),請求簽章會自動處理。
工作流程
2d) 下達買入/賣出訂單(股票/ETF)
執行:
python3 scripts/snaptrade_order.py buy|sell TICKER UNITS --account-id <ACCOUNT_ID> [--order-type market|limit] [--limit-price <PRICE>] [--tif Day|GTC|IOC|FOK]
預設值:
- 訂單類型:market
- 有效期限:Day
- 限價:僅限價單需要
可選的監控功能(輪詢最近訂單):
python3 scripts/snaptrade_order.py buy|sell TICKER UNITS --account-id <ACCOUNT_ID> --watch
- 預設每 10 秒 輪詢一次,最多持續 120 秒
- 可使用
--watch-interval和--watch-seconds調整
按 ID 監控現有訂單:
python3 scripts/snaptrade_watch_order.py --account-id <ACCOUNT_ID> --order-id <BROKERAGE_ORDER_ID>
- 同樣使用 10 秒/120 秒的預設值,可透過
--watch-interval和--watch-seconds調整
當使用者詢問時,請使用帳戶訂單端點來確認成交並回報未成交訂單。
0) 建立 SnapTrade 帳戶 + 取得 API 金鑰
您需要一個 SnapTrade 帳戶才能連接券商。前往 https://snaptrade.com 免費建立帳戶,產生您的客戶端 ID (Client ID) 和消費者金鑰 (Consumer Key),然後將其加入技能設定。
1) 安裝相依套件
pip3 install -r requirements.txt
2) 設定憑證(一次性)
將憑證儲存在本地設定檔中(請勿提交)。user_id 會在首次執行時自動產生:
/home/openclaw/.openclaw/workspace/secrets/snaptrade.json
範例:
{
"client_id": "YOUR_CLIENT_ID",
"consumer_key": "YOUR_CONSUMER_KEY",
"user_id": "<auto-generated-uuid>"
}
2) 註冊使用者 + 產生連線入口連結
執行:
python3 scripts/snaptrade_portal.py
這將會:
- 若缺少
user_secret,則註冊使用者 - 將
user_secret儲存回設定檔 - 列印一個連線入口 URL,使用者必須開啟此連結來連結帳戶
2b) 重新連結已停用的連線
執行:
python3 scripts/snaptrade_reconnect.py [brokerage-name]
這將會:
- 列出已停用的連線
- 產生一個重新連結連結(可選擇性地按券商名稱比對)
- 列印一個重新連結 URL,供使用者重新啟用該連線
2c) 列出可用券商(允許的連線)
執行:
python3 scripts/snaptrade_brokers.py
這會呼叫 /snaptrade/partners 並回傳 allowed_brokerages 清單(顯示名稱)。
3) 擷取投資組合總價值
執行:
python3 scripts/snaptrade_total.py
輸出為 JSON,格式如:
{"total_value": 123456.78, "currency": "CAD"}
3b) 各券商總計(貨幣換算後)
執行:
python3 scripts/snaptrade_broker_totals.py --currency CAD
輸出的 JSON 包含以所選貨幣為單位的各券商總計,以及使用的匯率。
實作注意事項: 盡量避免使用 get_user_holdings。擷取持股/持倉資料時,請優先使用 get_user_account_positions(持倉端點)。除非使用者明確要求,否則僅在必要時才從持股資料中取用餘額/現金;否則請勿呼叫持股端點。
4) 排程每日報表
使用 cron 來定期執行 snaptrade_total.py,將結果格式化為簡潔的 WhatsApp 訊息,然後傳送給使用者。只需要總價值即可。
腳本
scripts/snaptrade_common.py— 設定檔載入/儲存 + 客戶端建立scripts/snaptrade_portal.py— 註冊使用者 + 產生連線入口連結scripts/snaptrade_reconnect.py— 為已停用的連線產生重新連結連結scripts/snaptrade_brokers.py— 列出此客戶端允許的券商scripts/snaptrade_order.py— 下達買入/賣出訂單(市價/限價),可選監控功能scripts/snaptrade_watch_order.py— 按 ID 監控現有訂單的成交狀況scripts/snaptrade_total.py— 計算所有帳戶的總價值scripts/snaptrade_broker_totals.py— 各券商總計(含匯率換算)
備註
- SDK 會透過
request_after_hook搭配consumer_key自動處理請求簽章。 - 總價值是透過加總每個帳戶的
account.balance.total(來自 holdings)來計算;這可以避免在新增或移除帳戶時發生錯誤。 - 如果存在多種貨幣,腳本會使用遇到的第一種貨幣。
- 請將秘密資訊保存在本地設定檔中,並使用
chmod 600設定權限。