Parin's Space
返回文章列表

從 Shioaji 新手到正式環境：Python API 開通、模擬測試與 AI 輔助開發筆記

· 閱讀時間 5 分鐘
python shioaji sinopac trading automation ai

從 Shioaji 新手到正式環境：Python API 開通、模擬測試與 AI 輔助開發筆記

最後更新：2026-05-06

這篇筆記整理我從 Shioaji 新手開始，完成 Python API 模擬測試、確認 signed=True、啟用 CA 憑證，最後切換到正式環境的完整流程。文章以 Shioaji Python API 為主，不涵蓋 T4 API 元件；如果你只打算用 Python 開發交易程式，T4 測試不是必要項目。

安全提醒：不要把 API_KEY、SECRET_KEY、憑證密碼、身分證字號、完整帳號、.env 或 .pfx 憑證提交到 Git。

引用文件

Shioaji 是什麼？

Shioaji 是永豐金證券提供的 Python 交易 API，用來在程式中串接台灣與全球金融市場的行情、帳務與交易功能。透過 Shioaji，可以用 Python 取得商品檔、即時行情、歷史資料、帳戶資訊，並在完成簽署、測試與憑證啟用後送出證券、期貨或選擇權委託。

它適合想把交易工作流程程式化的人，例如：

  • 先用模擬模式確認 API 登入與下單流程
  • 建立可重複執行的測試腳本
  • 查詢帳戶、委託、部位、損益與交易額度
  • 將策略訊號、風控、下單與回報整合成一套程式
  • 用 Python 生態系整合 pandas、NumPy、資料庫、排程工具、監控系統或 AI 輔助開發流程

官方總覽也提到，Shioaji 可以整合 NumPy、pandas、PyTorch、TensorFlow 等 Python 套件，並以跨平台方式建立交易模型。

為什麼需要 API 下單？

一般交易軟體適合手動操作；API 下單適合把固定、重複、需要嚴格控管的流程自動化。

常見原因包括：

  • 自動化固定規則的下單流程
  • 將策略、訊號、風控、下單、回報整合在同一套程式
  • 批次查詢行情、部位、損益與委託狀態
  • 減少手動輸入錯誤，並保留可追蹤的交易邏輯
  • 建立自己的交易監控、告警或研究環境

但 API 下單也代表程式可以直接送出委託，風險比手動操作更高。因此正式環境前必須完成：

  • API 文件簽署
  • 模擬模式登入與下單測試
  • signed=True 狀態確認
  • CA 憑證啟用
  • 正式下單前的人工審查與風控開關

Shioaji 支援 AI 輔助開發

Shioaji 官方文件說明，Shioaji 是台灣第一個支援 LLM.txt 與 AI Coding Agent Skills 的金融 API。這些資源讓 AI 開發助手更容易理解 Shioaji API 的文件、物件、下單流程與常見使用方式。

把官方文件交給 AI 助手

最簡單的方式是把完整純文字文件網址提供給 AI 助手：

https://sinotrade.github.io/llms-full.txt

官方提供的 AI 友善資源包括：

  • llms.txt：所有文件頁面的結構化連結
  • llms-full.txt：完整純文字文件內容，適合提供給 AI 助手作為上下文
  • AI Coding Agent Skills：更深度整合 AI 開發工具的 skills/plugins

Claude Code

Claude Code 是 Anthropic 官方的 AI 輔助開發 CLI 工具。安裝 Shioaji skill：

claude plugin marketplace add Sinotrade/Shioaji
claude plugin install shioaji

OpenAI Codex CLI

在 Codex 工作階段中，可以使用 skill-installer：

$skill-installer install shioaji from Sinotrade/Shioaji --path skills/shioaji

本文件就是在 Codex 中搭配 Shioaji skill，依照「新手入門提示詞」逐步排查與整理出來的實作紀錄。

通用安裝器

如果使用 Cursor、Windsurf、Copilot、Codex 或其他支援 skills 的工具，也可以參考這些通用 installer：

npx skills add Sinotrade/Shioaji
npx skillkit install Sinotrade/Shioaji
npx openskills install Sinotrade/Shioaji

不同 AI 工具支援的 skill 格式與安裝位置可能不同，實際使用前仍要依各工具文件確認。

Skill 能協助什麼？

安裝後，AI 程式開發助手可以協助：

  • 認證與登入流程
  • 商品檔規格，包含股票、期貨、選擇權
  • 下單與委託管理
  • 即時行情資料串流
  • 帳戶餘額與部位查詢
  • 歷史資料擷取

範例提示詞：

如何使用 Shioaji 訂閱即時股票報價？
幫我下一張台積電的限價單
顯示我的帳戶部位

AI 使用原則

AI 可以協助產生範例程式、整理流程與排查錯誤，但交易程式碼不能未經審查就直接上線。

正式使用前應該做到：

  • 人工審查 AI 產生的程式碼
  • 先用 simulation=True 模擬模式測試
  • 明確確認商品、價格、數量、帳戶與交易方向
  • 正式下單程式加上 LIVE_TRADING 之類的明確開關
  • 不把 API Key、憑證或帳戶個資貼給 AI 或提交到版本庫

安裝 Shioaji

官方提供多種安裝方式。

pip

pip install shioaji

更新 Shioaji：

pip install -U shioaji

uv

uv add shioaji

安裝加速版本：

uv add shioaji --extra speed

Docker

互動模式：

docker run -it sinotrade/shioaji:latest

Jupyter Lab 或 Notebook：

docker run -p 8888:8888 sinotrade/shioaji:jupyter

本專案使用 PDM

本專案使用 PDM 管理 Python 套件：

pdm add "shioaji[speed]"
pdm add python-dotenv

確認版本：

pdm run python -c "import shioaji as sj; print(sj.__version__)"

前置條件

在正式使用 Python API 前，需要完成：

  • 永豐金證券帳戶已開立
  • 已申請 Shioaji API Key / Secret Key
  • 已線上簽署 API 電子交易風險預告書暨使用同意書
  • Python 環境已安裝 shioaji
  • 若使用 .env，需安裝 python-dotenv
  • 正式下單前已申請並啟用 CA 憑證

官方要求 Python API 測試需使用支援版本，建議維持最新版本。

.env 設定

把敏感資訊放在 .env，不要寫死在 Python 檔案裡。

API_KEY=your_api_key
SECRET_KEY=your_secret_key
CA_CERT_PATH=/absolute/path/to/Sinopac.pfx
CA_PASSWORD=your_ca_password
PERSON_ID=your_person_id
LIVE_TRADING=false

程式中先載入 .env：

import os
from dotenv import load_dotenv

load_dotenv()

.gitignore 建議至少包含：

.env
*.pfx
*.log
.venv/

第一步：模擬模式登入測試

模擬模式必須使用：

api = sj.Shioaji(simulation=True)

登入測試範例：

import os
import shioaji as sj
from dotenv import load_dotenv

load_dotenv()

api = sj.Shioaji(simulation=True)
accounts = api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

print(accounts)

成功時會看到 StockAccount。若有期貨帳戶，也可能看到 FutureAccount。

第二步：證券模擬下單測試

證券下單測試仍然使用 simulation=True，不會送正式市場。

import os
import time
import shioaji as sj
from dotenv import load_dotenv
from shioaji.constant import Action, StockPriceType, OrderType

load_dotenv()

api = sj.Shioaji(simulation=True)
api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

contract = api.Contracts.Stocks["2890"]

order = sj.order.StockOrder(
    action=Action.Buy,
    price=contract.reference,
    quantity=1,
    price_type=StockPriceType.LMT,
    order_type=OrderType.ROD,
    account=api.stock_account,
)

trade = api.place_order(contract=contract, order=order)
time.sleep(1)
api.update_status()

print(trade)
print(trade.status)

通過條件範例：

status=<Status.Submitted: 'Submitted'>
status_code='00'

若出現：

Please sign 9A95xxxxxxx first.

代表該證券帳戶尚未完成 API 下單文件簽署，或簽署時間晚於測試時間。需先完成簽署後再重新測試。

第三步：期貨模擬下單測試

期貨戶需要另外測試。若沒有期貨帳戶，api.futopt_account 會是 None，期貨測試可略過。

確認帳戶：

import os
import shioaji as sj
from dotenv import load_dotenv

load_dotenv()

api = sj.Shioaji(simulation=True)
accounts = api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

print("accounts:", accounts)
print("stock_account:", api.stock_account)
print("futopt_account:", api.futopt_account)

若輸出：

futopt_account: None

代表目前沒有可用期貨/選擇權帳戶。沒有期貨帳戶時，不需要完成期貨測試。

如果有期貨帳戶，才使用期貨測試範例：

import os
import time
import shioaji as sj
from dotenv import load_dotenv
from shioaji.constant import Action, FuturesPriceType, OrderType, FuturesOCType

load_dotenv()

api = sj.Shioaji(simulation=True)
api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

contract = api.Contracts.Futures["TXFR1"]

order = sj.order.FuturesOrder(
    action=Action.Buy,
    price=contract.reference,
    quantity=1,
    price_type=FuturesPriceType.LMT,
    order_type=OrderType.ROD,
    octype=FuturesOCType.Auto,
    account=api.futopt_account,
)

trade = api.place_order(contract=contract, order=order)
time.sleep(1)
api.update_status()

print(trade)
print(trade.status)

第四步：確認 Python API 測試通過，看到 signed=True

模擬測試完成後，等待審核狀態更新。官方文件提到約需 5 分鐘。

signed=True 需要在正式環境登入後確認：

import os
import shioaji as sj
from dotenv import load_dotenv

load_dotenv()

api = sj.Shioaji(simulation=False)
accounts = api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

for account in accounts:
    print({
        "type": type(account).__name__,
        "broker_id": getattr(account, "broker_id", None),
        "signed": getattr(account, "signed", None),
    })

通過範例：

{'type': 'StockAccount', 'broker_id': '9A95', 'signed': True}

若同時看到一般 Account 類型為 signed=False，但 StockAccount signed=True，證券 Python API 測試仍可視為通過。正式證券交易使用的是 StockAccount。

第五步：申請並啟用 CA 憑證

正式下單前必須啟用 CA 憑證。模擬下單不需要憑證，但正式下單需要。

憑證啟用範例：

import os
import shioaji as sj
from dotenv import load_dotenv

load_dotenv()

api = sj.Shioaji(simulation=False)
api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

result = api.activate_ca(
    ca_path=os.environ["CA_CERT_PATH"],
    ca_passwd=os.environ["CA_PASSWORD"],
    person_id=os.environ["PERSON_ID"],
)

print("activate_ca:", result)
print("ca_expiretime:", api.get_ca_expiretime(os.environ["PERSON_ID"]))

成功範例：

activate_ca: True
ca_expiretime: 2028-05-06 23:59:59

第六步：切換到正式環境

正式環境使用：

api = sj.Shioaji(simulation=False)

或：

api = sj.Shioaji()

建議先只做「登入 + 啟用憑證 + 查帳戶」，確認無誤後再處理正式下單。

import os
import shioaji as sj
from dotenv import load_dotenv

load_dotenv()

api = sj.Shioaji(simulation=False)
accounts = api.login(
    api_key=os.environ["API_KEY"],
    secret_key=os.environ["SECRET_KEY"],
)

api.activate_ca(
    ca_path=os.environ["CA_CERT_PATH"],
    ca_passwd=os.environ["CA_PASSWORD"],
    person_id=os.environ["PERSON_ID"],
)

print(api.stock_account)
print(api.get_ca_expiretime(os.environ["PERSON_ID"]))

正式下單前加入明確開關：

if os.environ.get("LIVE_TRADING") != "true":
    raise RuntimeError("LIVE_TRADING is not true; refusing to place live order")

只有在 .env 明確改成：

LIVE_TRADING=true

時才允許送正式委託。

需要做 T4 測試嗎？

若只使用 Shioaji / Python API，不需要做 T4 測試。

T4 API 是另一套 Windows 取向的 API 元件，基於 Native C++ Win32 DLL / Excel VBA 等元件使用方式。Shioaji Python API 則是跨平台 Python API。

判斷方式：

  • python 測試與否：已測試
  • 正式環境登入後 StockAccount signed=True
  • activate_ca: True

以上三項完成後，即可使用 Shioaji Python API。T4 測試與否：未測試 不影響 Python API 使用。

本次實際完成狀態

本次流程確認：

  • 模擬登入：已通過
  • 證券模擬下單：已通過，Submitted / status_code='00'
  • 期貨模擬下單：不適用，沒有期貨帳戶
  • 正式環境 StockAccount signed=True：已通過
  • CA 憑證啟用：已通過
  • T4 測試：不需要，除非未來要使用 T4 API 元件

收尾：我的建議工作流

實務上，我會把 Shioaji 專案拆成三層：

  1. 設定層：處理 .env、登入、帳戶選擇、CA 憑證
  2. 測試層：保留 login.py、stock_test.py、check_signed.py 這類最小測試腳本
  3. 交易層：正式策略與下單程式，必須先通過模擬測試並加上 LIVE_TRADING 開關

AI 助手可以放在第二層與第三層之間：協助查文件、產生初版程式、整理例外處理與測試案例。但最後是否能送真單，仍應由人檢查並明確打開正式交易開關。