群益 API 串接教學：Python 自動下單入門

你有沒有過這種經驗——盯著盤面等進場訊號，結果上個廁所回來就錯過了？或是明明設好停損，手一抖就把單砍在最低點？

如果你已經有一套自己的交易邏輯，想讓電腦幫你執行，那群益 Capital API 就是你的起點。這篇文章會帶你從零開始，用 Python 串接群益 API，完成自動下單的第一步。

什麼是群益 Capital API？

群益 Capital API 是群益期貨提供的程式交易介面，讓你可以透過程式碼直接連線到群益的交易系統。簡單來說，就是把「你用滑鼠點下單」這個動作，變成「程式自動幫你下單」。

它的底層是 COM 元件（SKCOM），支援 C#、VB.NET、Python 等語言（實際支援語言版本以群益官方文件為準）。對大多數自學的交易者來說，Python 是最友善的選擇——語法簡潔、套件豐富，學習曲線比較平。

Capital API 能做的事包括：

• 即時報價接收：拿到 Tick 資料、五檔報價、成交明細
• 委託下單：送出新單、改單、刪單
• 回報接收：即時收到成交回報、委託回報
• 帳務查詢：查詢未平倉部位、保證金餘額

誰適合用 API 做交易？

不是每個人都需要用 API，先確認你屬於哪一種：

適合用 API 的人

• 有明確交易策略的人：你的進出場規則可以寫成 if-else 邏輯，不是靠盤感
• 想做量化回測的人：你需要歷史資料來驗證策略，然後直接上線執行
• 多商品同時監控的人：你同時看台指、小台、選擇權，手動盯盤根本忙不過來
• 想排除情緒干擾的人：你知道自己的策略沒問題，但手動執行總是亂改

不太適合用 API 的人

• 還沒有穩定獲利策略，想靠程式交易「自動賺錢」——程式只是工具，策略才是核心
• 完全沒有程式基礎，連 Python 安裝都不會——建議先從 MultiCharts 開始

API vs MultiCharts vs 手動下單比較

這三種方式各有優缺點，看看哪個最適合你現在的狀況：

申請 API 使用權限

使用 Capital API 之前，你得先完成幾個步驟：

1. 開立群益期貨帳戶：這是前提。還沒開戶的話，可以透過線上開戶，大約 2~3 個工作天就能完成。
2. 簽署 API 使用同意書：登入群益期貨官網，進入「憑證與 API」專區，線上簽署同意書。
3. 下載 API 元件：在群益官網的「Capital API」專區下載最新版的 SKCOM 安裝檔。目前最新版本是 2.13.58（2026 年 4 月更新），實際版本以群益官方文件為準。
4. 安裝憑證：開啟群益的憑證管理工具，匯入你的個人憑證。這步很重要，沒有憑證就無法登入 API。

開發環境建置

Capital API 的 COM 元件只支援 Windows，所以你需要一台 Windows 電腦。以下是建議的環境設定：

系統需求

• Windows 10 / 11（64 位元）
• Python 3.8 ~ 3.11（建議 3.10，相容性最好）
• 群益 SKCOM 元件（安裝後會自動註冊 COM）

安裝 Python 環境

如果你電腦還沒有 Python，到 python.org 下載安裝，記得勾選「Add Python to PATH」。

接著開啟命令提示字元，安裝必要套件：

pip install comtypes
pip install pandas
pip install numpy

comtypes 是關鍵套件，讓 Python 能跟群益的 COM 元件溝通。pandas 和 numpy 是處理資料用的，之後做回測也會用到。

安裝 SKCOM 元件

1. 從群益官網下載 SKCOM 安裝檔（.exe）
2. 以系統管理員身分執行安裝——這點很重要，不然 COM 元件註冊會失敗
3. 安裝完成後，開啟「元件管理員」確認 SKCOMLib 已經註冊成功

Python 連線基礎：載入元件與登入

環境準備好了，來寫第一支程式。Capital API v2 的正確初始化方式分兩步：先用 GetModule 載入 DLL，再以 型別介面 建立物件（這是官方範例的標準寫法，不可省略）：

import comtypes.client
import os

# 步驟 1：載入 SKCOM.dll，讓 Python 認識所有型別
# DLL 放在 py 檔同目錄；或填入完整路徑
dll_path = os.path.join(os.path.dirname(__file__), "SKCOM.dll")
comtypes.client.GetModule(dll_path)

# 步驟 2：匯入自動產生的型別模組
import comtypes.gen.SKCOMLib as sk

# 步驟 3：建立 COM 物件（使用型別介面，官方建議寫法）
m_pSKCenter = comtypes.client.CreateObject(sk.SKCenterLib, interface=sk.ISKCenterLib)
m_pSKReply  = comtypes.client.CreateObject(sk.SKReplyLib,  interface=sk.ISKReplyLib)
m_pSKOrder  = comtypes.client.CreateObject(sk.SKOrderLib,  interface=sk.ISKOrderLib)
m_pSKQuote  = comtypes.client.CreateObject(sk.SKQuoteLib,  interface=sk.ISKQuoteLib)

元件建好後，設定連線環境並登入：

# 設定環境（0=正式, 1=正式SGX, 2=測試, 3=測試SGX）
# 開發階段建議先用測試環境（值 2），確認程式無誤再切換正式
m_pSKCenter.SKCenterLib_SetAuthority(2)

# 登入（帳號為身分證字號）
login_id = os.environ.get("CAPITAL_USER")
login_pw  = os.environ.get("CAPITAL_PASS")

nCode = m_pSKCenter.SKCenterLib_Login(login_id, login_pw)

if nCode == 0:
    print("登入成功")
else:
    msg = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode)
    print(f"登入失敗，錯誤碼：{nCode}，原因：{msg}")

這段程式做了幾件事：

1. GetModule 將 DLL 解析成 Python 可呼叫的型別（只需在程式啟動時執行一次）
2. 以 介面型別 建立物件，確保事件回呼能正確綁定
3. SKCenterLib_SetAuthority 選擇正式或測試環境——初期請用測試環境
4. 登入回傳 0 表示成功，其他數字請呼叫 GetReturnCodeMessage 取得說明

⚠️ 安全提醒：帳號密碼不要直接寫在程式碼裡面。請用環境變數（os.environ）或 .env 檔管理。

接收即時報價

登入成功後，可以開始訂閱即時報價。報價採事件驅動模式：先掛上 callback class，再呼叫訂閱函式，有新成交就會自動觸發。

import pythoncom

# 報價事件 callback（繼承無需特定基底，comtypes 自動綁定）
class SKQuoteLibEvent:
    def OnConnection(self, nKind, nCode):
        if nKind == 3001:  # 連線成功
            print("報價連線成功")
            # 訂閱台指期近月（商品代碼 TXFR1）
            m_pSKQuote.SKQuoteLib_RequestStocks("0", "TXFR1")
        elif nKind == 3002:
            print(f"報價連線中斷，錯誤碼：{nCode}")

    def OnNotifyQuote(self, sMarketNo, nStockIdx):
        # 有報價更新時觸發；用索引取出完整結構
        ts = sk.STOCKINDEX()
        nCode = m_pSKQuote.SKQuoteLib_GetStockByIndex(sMarketNo, nStockIdx, ts)
        if nCode == 0:
            print(f"商品：{ts.bstrStockName}")
            print(f"成交價：{ts.nClose / 100:.0f}")   # 除以 100 還原價格
            print(f"成交量：{ts.nTQty}")

# 掛上事件
skQuoteEvent = SKQuoteLibEvent()
skQuoteEventHandler = comtypes.client.GetEvents(m_pSKQuote, skQuoteEvent)

# 啟動連線（需在 Login 成功後呼叫）
m_pSKQuote.SKQuoteLib_EnterMonitorOSQ(0)

# 持續跑訊息迴圈，讓 COM 事件能被推送
import pythoncom
while True:
    pythoncom.PumpMessages()

幾個重要細節：

• comtypes.client.GetEvents 把 callback 物件與 COM 元件綁定，一定要保留回傳的 handler 物件（不然 GC 會把它回收，事件就不觸發了）
• 訂閱商品在 OnConnection(nKind=3001) 時呼叫，確保連線已就緒
• TXFR1 代表台指期近月；第一個參數 "0" 是市場別（0=上市期貨）
• 價格欄位（如 nClose）要除以 100 才是實際點數——這是群益的固定慣例
• PumpMessages() 讓主執行緒持續處理 COM 事件；若改用多執行緒架構，可改用 pythoncom.CoInitialize()

委託下單實作

收到訊號後，下一步就是送出委託。注意：FUTUREORDER 的欄位型別要嚴格對應，例如價格是字串（bstrPrice），口數才是整數（nQty）。

# 組成期貨委託物件
oOrder = sk.FUTUREORDER()

# 完整帳號格式：IB代號4碼 + 帳號7碼，例如 "6A3412345678"
oOrder.bstrFullAccount = "你的完整帳號"
oOrder.bstrStockNo     = "TXF"       # 台指期（不含月份，由近月自動處理）
oOrder.sBuySell        = 0           # 0=買進, 1=賣出（short 型別）
oOrder.sTradeType      = 0           # 0=ROD, 1=IOC, 2=FOK
oOrder.sDayTrade       = 0           # 0=非當沖, 1=當沖
oOrder.bstrPrice       = "22500"     # 委託價：字串型別！市價填 "0"
oOrder.nQty            = 1           # 委託口數

# 送出同步委託
# 回傳 tuple：(委託書號字串, 錯誤碼整數)
message, nCode = m_pSKOrder.SendFutureOrder(login_id, False, oOrder)

if nCode == 0:
    print(f"委託成功，書號：{message}")
else:
    err = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode)
    print(f"委託失敗：{err}")

幾個關鍵參數說明：

同步 vs 非同步委託：SendFutureOrder 第二個參數 bAsyncOrder 填 False 為同步（等委託結果後才繼續執行），True 為非同步（立即返回，結果透過 OnAsyncOrder 事件回報）。策略交易建議用非同步，避免主執行緒被阻塞。

接收委託與成交回報

送出委託之後，透過 SKOrderLib 的事件接收各種狀態回報。官方 SDK 有三種主要回報 callback：

class SKOrderLibEvent:
    def OnAccount(self, bstrLogInID, bstrAccountData):
        """登入後取得帳號清單；完整帳號 = IB代號4碼 + 帳號7碼"""
        values = bstrAccountData.split(',')
        full_account = values[1] + values[3]
        print(f"帳號：{full_account}")

    def OnProxyStatus(self, bstrUserId, nCode):
        """Proxy 連線狀態（下單通道健康度）"""
        msg = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode)
        print(f"Proxy 狀態 [{bstrUserId}]: {msg}")

    def OnAsyncOrder(self, nThreadID, nCode, bstrMessage):
        """非同步委託結果（bAsyncOrder=True 時觸發）"""
        if nCode == 0:
            print(f"非同步委託成功，書號：{bstrMessage}")
        else:
            err = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode)
            print(f"非同步委託失敗：{err}")

    def OnProxyOrder(self, nStampID, nCode, bstrMessage):
        """Proxy 委託回報"""
        print(f"Proxy 委託 [{nStampID}] 碼：{nCode}，訊息：{bstrMessage}")

    def OnOpenInterest(self, bstrData):
        """未平倉部位回報（呼叫 GetOpenInterestGW 後觸發）"""
        print(f"未平倉：{bstrData}")

    def OnFutureRights(self, bstrData):
        """期貨權益數回報（呼叫 GetFutureRights 後觸發）"""
        print(f"權益數：{bstrData}")

# 掛上事件
skOrderEvent = SKOrderLibEvent()
skOrderEventHandler = comtypes.client.GetEvents(m_pSKOrder, skOrderEvent)

常用回報說明：

• OnAccount：登入後自動觸發，用來取得完整帳號字串（格式：IB代號4碼 + 帳號7碼）
• OnProxyStatus：監控下單通道是否正常，策略掛單前可先確認
• OnAsyncOrder：非同步下單的結果回報，nCode == 0 才算成功
• OnOpenInterest：查詢未平倉部位，呼叫 m_pSKOrder.GetOpenInterestGW(login_id) 後觸發

錯誤處理與常見問題

API 串接最頭痛的就是各種錯誤碼。以下是我遇過最常見的幾個：

以上錯誤碼僅供參考，實際錯誤碼定義以群益官方文件為準，建議搭配 SKCenterLib_GetReturnCodeMessage 取得最新說明。

建議你在程式裡面加上完善的錯誤處理：

def safe_call(func, *args, func_name="API call"):
    """包裝 API 呼叫，統一處理錯誤"""
    try:
        result = func(*args)
        # API 回傳值：0 成功，非 0 為錯誤碼
        nCode = result[1] if isinstance(result, tuple) else result
        if isinstance(nCode, int) and nCode != 0:
            msg = m_pSKCenter.SKCenterLib_GetReturnCodeMessage(nCode)
            print(f"[錯誤] {func_name} 失敗: {nCode} - {msg}")
            return None
        return result
    except Exception as e:
        print(f"[例外] {func_name}: {e}")
        return None

查詢 K 線歷史資料

除了即時報價，Capital API 也能拉取歷史 K 線——做回測驗證策略時非常好用：

class SKQuoteLibEvent:
    def OnKLineData(self, bstrStockNo, nPtr, bstrData):
        """K 線資料回報；bstrData 為 CSV 格式"""
        print(f"[{bstrStockNo}] K 線: {bstrData}")

    def OnHistoryRequestDone(self, bstrStockNo):
        """歷史資料傳輸完畢"""
        print(f"{bstrStockNo} 歷史 K 線下載完成")

skQuoteEvent = SKQuoteLibEvent()
skQuoteEventHandler = comtypes.client.GetEvents(m_pSKQuote, skQuoteEvent)

# 請求台指期近月 1 分鐘 K 線（最近 100 根）
# 第三參數 nType：0=1分鐘, 4=日線, 5=週線, 6=月線
# 第四參數 nOutType：0=舊格式, 1=新格式（建議用 1）
# 第五參數 nTradeSession：0=全盤, 1=AM盤
m_pSKQuote.SKQuoteLib_RequestKLine("TXFR1", 0, 100, 1, 0)

回傳的 bstrData 是逗號分隔字串，可直接用 str.split(',') 解析後存入 DataFrame 進行量化分析。

安全性注意事項

程式交易牽涉到真金白銀，安全這塊一定不能馬虎：

密碼管理

絕對不要把帳號密碼寫死在程式碼裡面。正確做法是用環境變數：

import os

login_id = os.environ.get("CAPITAL_USER")
login_pw = os.environ.get("CAPITAL_PASS")

if not login_id or not login_pw:
    raise ValueError("請設定環境變數 CAPITAL_USER 和 CAPITAL_PASS")

或者用 .env 檔搭配 python-dotenv 套件，記得把 .env 加入 .gitignore。

憑證保護

• 憑證檔案不要放在雲端硬碟或共用資料夾
• 定期更新憑證（群益的憑證有效期限是一年）
• 如果懷疑憑證外洩，立刻打電話給營業員作廢重發

下單防呆機制

在程式裡面一定要設保護機制，避免失控：

# 下單前的安全檢查
MAX_ORDER_QTY = 5        # 單筆最大口數
MAX_DAILY_ORDERS = 50    # 每日最大委託次數
daily_order_count = 0

def pre_order_check(qty, price):
    global daily_order_count

    if qty > MAX_ORDER_QTY:
        print(f"口數 {qty} 超過上限 {MAX_ORDER_QTY}")
        return False

    if daily_order_count >= MAX_DAILY_ORDERS:
        print("已達每日委託上限")
        return False

    if price <= 0:
        print("價格異常")
        return False

    daily_order_count += 1
    return True

常見問題 FAQ

結論

群益 Capital API 是台灣期貨市場上常見的程式交易介面之一。免費、文件算完整、社群資源也不少。如果你有 Python 基礎，又有一套想自動化的交易策略，花個兩週時間上手 API 是值得的投資。

記住幾個重點：環境建好、模擬先跑、密碼別寫死、下單加防呆。做好這四件事，可以大幅降低初次使用 API 的風險與錯誤機率。

劉安清

群益期貨營業員，專精 MultiCharts 程式交易與海外期貨。

📌 想了解更多？歡迎加入我的 LINE 好友，免費諮詢！

LINE 加好友免費諮詢