群益API 權益數查詢封面:GetFutureRights 的 Python 寫法

群益API 權益數怎麼查?GetFutureRights 的 Python 寫法

呼叫 GetFutureRights 回傳 0,程式裡卻什麼資料都沒拿到。照網路範例把 sCoinType 填 0 當作台幣,收到的資料跟預期不一樣。連續查詢時,又不時冒出 1019。

群益API 權益數的查法可以先記三件事:

  1. GetFutureRights 本身不帶回資料,資料由 OnFutureRights 事件分筆回傳,最後一筆以 ## 開頭。
  2. sCoinType 填 0 是全幣別,只要台幣就填 1。
  3. 回傳 1019,官方說明是「查詢尚未結束請稍後再試」,稍後再查即可。

本文以官方元件說明文件 V2.13.59 為主。查詢與事件的行為,另以 Python 登入正式環境實測,條件寫在各段裡。

群益API 權益數查詢示意圖:GetFutureRights 發出查詢,OnFutureRights 分筆回傳,最後一筆以 ## 結束

群益API 權益數要用哪個函式查?

官方函式清單裡,國內權益數只有這一組:

名稱種類官方說明
GetFutureRights函式「查詢國內權益數。」
OnFutureRights事件國內權益數,查詢結果由這個事件回傳
OnFutureRightsStatus事件「國內權益數查詢的狀態。」

官方宣告:

Long GetFutureRights([in] BSTR bstrLogInID, [in] BSTR bstrAccount,[in]SHORT sCoinType)
參數官方說明
bstrLogInID登入ID。
bstrAccount委託帳號 ( IB+帳號) 。
sCoinType0:全幣別,1:基幣(台幣TWD),2:人民幣RMB。

bstrAccount 填期貨帳號,從 GetUserAccount 觸發的 OnAccount 事件取得,見〈群益API 下單初始化有哪 7 步〉。海外期貨的權益數另有函式,本文不談。

為什麼 GetFutureRights 回 0,程式卻沒拿到資料?

官方對回傳值與結果的說明:

0表示成功,其餘非0數值都表示失敗。 結果由 OnFutureRights 事件回傳。

查詢結果由 OnFutureRights 事件回傳,所以函式本身不會帶回資料。 以 STA 執行緒呼叫時,回 0 之後要持續處理 Windows 訊息,事件才會進來;我們實測用的是 STA 加 pythoncom.PumpWaitingMessages()。事件綁定與訊息幫浦的寫法見〈群益API Python 程式架構〉。

兩個順序要注意:

  • 先綁事件,再發查詢。 我們實測時就是這個順序。
  • comtypes.client.GetEvents 的回傳值要存起來,跟即時分K的寫法相同,見〈群益API 即時分K怎麼用〉。

Python 呼叫 GetFutureRights 要拆包嗎?

不用。 依 SKCOM 2.13.59 的元件型別,GetFutureRights 的三個參數都是 [in],沒有 bstrMessage 這類輸出參數,comtypes 直接回傳一個整數:

code = order.GetFutureRights(LOGIN_ID, ACCOUNT, 0)

這跟下單、刪改單函式不同。那些函式有 [out] bstrMessage,Python 要拆成 message, code,見〈群益API 期貨下單怎麼寫〉。哪些函式要拆包、為什麼,見〈群益API Python 回傳值為什麼是 list〉。

GetFutureRights 的回傳值就是 0 或非 0 的回傳碼。我們實測連續 20 次呼叫,int(order.GetFutureRights(...)) 每次都正常取得回傳碼。

群益API 權益數的 sCoinType 要填 0 還是 1?

只要台幣,填 1;要全部幣別,填 0。 官方原文:

sCoinType 0:全幣別,1:基幣(台幣TWD),2:人民幣RMB。 全幣別選項含基幣。

OnFutureRights 的備註另外寫明:「全幣別(含基幣),回傳第一筆資料為基幣。」

0 不是台幣。 0 是全幣別,官方寫明含基幣,回傳的第一筆是基幣(台幣)。

群益API OnFutureRights 回傳什麼格式?

官方說明:「回傳的字串內容,以「,」分隔每一個欄位」。每筆資料是一個字串,用逗號切開後共 41 欄。官方欄位表依序如下(索引從 0 起算,欄名一字未改):

索引官方欄名索引官方欄名
0帳戶餘額21原始保證金
1浮動損益22昨日餘額
2已實現費用23選擇權組合單加不加收保證金
3交易稅24維持率
4預扣權利金25幣別
5權利金收付26足額原始保證金
6權益數27足額維持保證金
7超額保證金28足額可用
8存提款29抵繳金額
9買方市值30有價可用
10賣方市值31可用餘額
11期貨平倉損益32足額現金可用
12盤中未實現33有價價值
13原始保證金34風險指標
14維持保證金35選擇權到期差異
15部位原始保證金36選擇權到期差損
16部位維持保證金37期貨到期損益
17委託保證金38加收保證金
18超額最佳保證金39LOGIN_ID
19權利總值40ACCOUNT_NO
20預扣費用

本文的範例保留原始字串,不轉成數字,並且用索引取欄位。

查詢結束的判斷,官方備註:

當全部資料已經全部回傳完畢,將回傳一筆以「##」開頭的內容,表示查詢結束。

也就是說,資料陸續由事件回傳,最後一筆以 ## 開頭。程式收到事件時先判斷是不是 ## 開頭,是就代表查完了,不是才當資料列解析。

OnFutureRightsStatus:查詢狀態事件

官方另有一個查詢狀態事件:

void OnFutureRightsStatus ( [in] LONG nQueryStatus, [in] BSTR bstrErrorMsg);
參數官方說明
nQueryStatus0:查詢成功;1查詢失敗
bstrErrorMsg成功為”Success!”,失敗為錯誤訊息

群益API 權益數裡,選擇權的權利金看哪一欄?

選擇權買賣的價格就是權利金。 買方支付權利金,賣方收取權利金,所以選擇權這部分的收付,對應的是索引 5「權利金收付」,它不屬於期貨損益。

帳戶同時有期貨與選擇權時,「期貨平倉損益」只反映期貨部位。

部位對應欄位
期貨平倉索引 11「期貨平倉損益」
選擇權買賣索引 5「權利金收付」

群益API 權益數查詢回傳 1019,是失敗嗎?

不是失敗。 官方代碼定義表:

1019  SK_ERROR_QUERY_IN_PROCESSING  查詢尚未結束請稍後再試。

我們實測的條件:用期貨帳號呼叫 GetFutureRights(登入ID, 帳號, 0) 共 20 次,每次呼叫後持續處理 Windows 訊息 3 秒(PumpWaitingMessages),再呼叫下一次。結果:

  • 回傳碼是 0、1019、0、1019……交替出現,20 次裡有 10 次回 1019。
  • 回 0 的那次查詢,3 次 OnFutureRights 事件都在 3 秒內收到,之後不再增加;但緊接著的下一次呼叫,仍然回 1019。

所以「事件收完了」不等於可以馬上再查。回 1019 時的處理方式:

  1. 不要當成失敗中止。 官方原文是「請稍後再試」,稍後再查一次即可。
  2. 不要頻繁輪詢。 需要最新權益數時再查,例如成交之後、使用者按下重新整理。這是我們的建議,不是官方規定,理由就是連續查詢會被 1019 擋下。

從舊版元件升級,權益數的解析要改嗎?

程式若是照 2.13.43 之前的格式解析,就要改。 官方版本控管表 2.13.52 的補充說明:

【使用2.13.43版本之前用戶須留意】,OnFutureRights在2.13.43版本之前的版本格式為+0000000000000(例如100,會被表示為+0000000010000),新版調整成一般格式(100)

也就是說,2.13.43 之前把 100 表示成 +0000000010000,之後改成一般的 100。升版的整體注意事項見〈群益API 版本升級要注意什麼〉。

群益API 權益數查詢 Python 範例

前提是已經完成登入、下單元件初始化、讀取憑證、取得期貨帳號,見〈群益API 下單初始化有哪 7 步〉。元件載入與 order 物件的建立見〈群益API Python 入門〉,以下省略。

import time
import pythoncom
import comtypes.client

LOGIN_ID = "YOUR_ID"
ACCOUNT = "YOUR_ACCOUNT"     # 期貨帳號:IB+帳號

# OnFutureRights 欄位索引(官方欄位表,0 起算,共 41 欄);只列本例用到的
IDX_RIGHTS = 6               # 權益數
IDX_CURRENCY = 25            # 幣別

class OrderEvents:
    def __init__(self):
        self.rows = []       # 每筆是 41 欄的 list,用索引取欄位
        self.done = False

    def OnFutureRights(self, bstrData):
        if bstrData.startswith("##"):          # 官方:以「##」開頭表示查詢結束
            self.done = True
        else:
            self.rows.append(bstrData.split(","))

events = OrderEvents()
order_conn = comtypes.client.GetEvents(order, events)   # 回傳值要存起來

def query_rights(coin_type=0, timeout=10.0):
    """coin_type:0 全幣別、1 基幣(台幣TWD)、2 人民幣RMB。回傳 (資料列, 回傳碼)
    逾時仍沒收到 ## 時,events.done 為 False"""
    events.rows, events.done = [], False
    code = order.GetFutureRights(LOGIN_ID, ACCOUNT, coin_type)   # 直接回傳碼,沒有 bstrMessage 這類輸出參數
    if code != 0:                              # 1019:查詢尚未結束請稍後再試
        return [], code
    t0 = time.time()
    while not events.done and time.time() - t0 < timeout:
        pythoncom.PumpWaitingMessages()
        time.sleep(0.05)
    return events.rows, code

使用方式:

rows, code = query_rights()
for r in rows:
    print(r[IDX_CURRENCY], r[IDX_RIGHTS])    # 全幣別時第一筆是基幣

兩點補充:

  • timeout=10.0 是範例的保護值,避免沒收到 ## 時程式卡住;它不是官方數字,也不是查詢實際需要的時間。
  • 回傳 1019 時,範例直接回傳空資料與回傳碼,由呼叫端決定稍後再查。

群益API 權益數查詢的 5 個誤解

  1. 誤解: GetFutureRights 回 0 就拿到權益數了。其實: 查詢結果由 OnFutureRights 事件回傳,要先綁好 OnFutureRights 事件。
  2. 誤解: sCoinType 填 0 是台幣。其實: 官方寫 0 是全幣別,1 才是基幣(台幣)。
  3. 誤解: 回 1019 是查詢失敗。其實: 官方說明是「查詢尚未結束請稍後再試」,稍後再查即可。
  4. 誤解: 事件收完了就可以馬上再查。其實: 我們實測時,事件在 3 秒內收完,緊接著的下一次查詢仍回 1019。
  5. 誤解: Python 呼叫要拆成(訊息, 回傳碼)。其實: GetFutureRights 沒有 bstrMessage 這類輸出參數,回的就是回傳碼。

常見問題

群益API GetFutureRights 回 0,為什麼沒有資料?

官方寫明「結果由 OnFutureRights 事件回傳」,函式本身不會帶回資料。要先綁好 OnFutureRights 事件;以 STA 執行緒呼叫時,呼叫後還要持續處理 Windows 訊息,資料才會進來。

sCoinType 填 0 是台幣嗎?

不是。官方:「0:全幣別,1:基幣(台幣TWD),2:人民幣RMB。」只要台幣填 1;填 0 時第一筆是基幣。

怎麼知道權益數資料收完了?

官方說明全部資料回傳完畢後,會再回傳一筆以 ## 開頭的內容。收到 ## 開頭的就是結束,不要用固定筆數判斷。

查詢回傳 1019 怎麼辦?

1019 是「查詢尚未結束請稍後再試」,稍後再查即可。我們實測時,事件已經收完,緊接著的下一次查詢仍回 1019,所以不要頻繁輪詢(我們的建議)。

選擇權的權利金在權益數的哪一欄?

選擇權買賣的價格就是權利金,對應「權利金收付」欄,不屬於期貨損益。

風險揭露

期貨與選擇權屬高槓桿商品,價格波動可能造成超過原始保證金的損失,交易人須自負交易責任。本文為程式開發技術教學,說明 Python 呼叫群益API 查詢國內權益數的寫法,不構成投資建議,也不保證任何交易結果。

投資人教育資源

機構資源
臺灣期貨交易所(TAIFEX)期貨及選擇權數位學習網
證券暨期貨市場發展基金會證券期貨市場教育推廣
金融智慧網金管會金融知識平台
中華民國期貨業商業同業公會期貨業法規與宣導
證券投資人及期貨交易人保護中心投資人保護與申訴

延伸閱讀

參考資料

  • GetFutureRights 的說明、宣告與參數,OnFutureRights 的 41 個欄位與備註,OnFutureRightsStatus 的參數,代碼定義表 1019,版本控管表 2.13.52 的補充說明:依群益官方元件說明文件 V2.13.59。
  • GetFutureRights 的參數方向(三個都是 [in]):依 SKCOM 2.13.59 x64 的元件型別,我們 2026-11-07 以 comtypes 1.4.16 核對。
  • 回傳碼 0/1019 交替、每次成功查詢觸發 3 次 OnFutureRights:我們 2026-10-15 在 SKCOM 2.13.59 x64、Python 3.12.10、comtypes 1.4.16、正式環境的實測結果,非官方文件記載。

免責聲明

本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。

延伸閱讀|相關文章

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *