群益API 價差部位怎麼讀？合成代碼、買賣別、成本與一點價值

查回來的價差部位，買賣別寫著 S。程式把它當成「第一腳賣出」，反推出整組是哪一種價差——結果方向整個相反，平倉時送成了同向加碼。

群益API 價差部位在查詢結果裡是一列，而這一列的每個欄位，描述的都是整組價差，不是其中一隻腳。 讀價差部位，要把這一點放在最前面。

本文以〈群益API 未平倉查詢怎麼選〉介紹的 GW 查詢（GetOpenInterestGW）為例。

群益API 價差部位在查詢結果裡長什麼樣？一組價差是一列

用 GW 查未平倉，一組價差（兩隻腳）會以一列回來，不是兩列。這一列用到的欄位是（官方欄位表從 1 起算）：

商品、買賣別、成本，全部是「整組」的意思。以下逐一說明。

價差部位的商品代碼怎麼拆？

價差部位的商品欄是合成代碼：根碼＋履約價／履約價＋月份碼，兩個履約價以斜線相連。以下僅為格式示意：根碼 TXO、履約價 23000 與 23100、月份碼與年碼 J5，會組成 TXO23000/23100J5 這樣的形式。

這個格式的依據有兩個：官方 OnOpenInterestJson 的回傳範例裡，價差部位的商品是這種格式；我們實單查回來的 GW 部位列，商品欄也是這種格式。

這個代碼不能直接拿去查報價——要先拆成兩隻腳：根碼相同、月份碼相同，兩個履約價各自組回單腳代碼。

下面程式碼的切法（根碼 3 碼、尾端 2 碼）是我們對台指選擇權家族代碼的整理，不是官方規格；其他商品請先確認代碼結構再套用。

群益API 價差部位的買賣別，為什麼不是第一腳？

我們實單送出過幾組「收權利金」的價差（賣權多頭價差、買權空頭價差），GW 部位列的買賣別全部是 S。

所以 S 代表「賣出價差」（收權利金），跟第一腳是買還是賣無關。要注意這個結論的範圍：我們的樣本全是收權利金的價差。B 代表「買進價差」（付權利金），是從 S 的語意推出來的，我們沒有實單樣本。

這個落差，對照送單時就很清楚。官方 SendDuplexOrder 的備註，教的是逐腳指定買賣（節錄「Call多頭價差」一段）：

第一隻腳: bstrStockNo 填:高履約價(ex:11000)，sBuySell填:賣 第二隻腳: bstrStockNo2 填:低履約價(ex:10900)，sBuySell2填:買

送單時是兩個方向，查回來的部位只剩一個方向，而且是整組的。 兩邊的語意不一樣。

如果程式把 S 當成「第一腳賣出」，再反推整組是什麼價差，賣權、買權兩邊都會被推成方向相反的價差。我們在實單對帳時就發現過：拿反推的結果去平倉，會送成同向加碼。

價差部位查得到成本嗎？

用 GW 查，查得到。我們實單查回來的價差部位列，第 7 欄「平均成本(小數部分已處理)」有值。

從數值大小看，它像是整組價差的權利金點數，不是其中一隻腳的成本。但這是推論：官方欄位名只寫「平均成本(小數部分已處理)」，我們也沒有拿成交紀錄逐筆核對過。請用你自己的成交紀錄對一次。

換成其他查詢方式就不一定了。〈群益API 未平倉查詢怎麼選〉整理過：GetOpenInterestWithFormat 的「格式1」含價差但沒有成本欄，「格式2」有成本但不含價差。

群益API 價差部位的一點價值從哪裡來？

從查詢結果裡拿不到。依官方欄位表：

• 有「一點價值」欄的是 GetOpenInterest 與「格式2」——兩者都不含價差部位。
• 含價差部位的 GW、「完整」、「格式1」——都沒有一點價值欄。

所以含價差部位的查詢方式，都沒有一點價值欄，價差部位的損益要自己算，一點價值要自己維護一張表。數值以臺灣期貨交易所的契約規格為準，不要從部位資料裡猜。

還有一條原則：表裡查不到的商品，損益不要硬算。 我們的做法是一點價值未知就不計算損益——寧可不顯示，也不用錯的值。要注意的是，漏掉一個新商品時，損益會悄悄地不算，所以新增交易商品時要記得更新這張表。

部位代碼為什麼跟自己用的對不上？

我們遇過一次：GW 部位查詢回來的期貨商品代碼是短碼（根碼＋月份的形式），跟交易所格式的長碼（根碼＋年月）不一樣。

所以拿部位代碼去比對時，兩種格式都要能認，例如只比前面的根碼。

群益API 價差部位的 6 條讀取原則＋程式碼

1. 價差部位是一列，商品、買賣別、成本都是整組的意思。
2. 合成代碼要先拆成兩隻腳才能查報價；根碼與月份碼共用。
3. 買賣別是整組價差的方向：S 是賣出價差（收權利金）；不要當成第一腳的買賣。
4. GW 查得到價差部位的平均成本；它看起來是整組價差的點數，請用成交紀錄核對一次。
5. 一點價值自己維護，數值以期交所契約規格為準；查不到的商品不要硬算損益。
6. 部位代碼的長短碼都要能認。

// 價差部位的商品是合成碼：根碼 + 履約價1 / 履約價2 + 月份碼（僅為格式示意）
bool TrySplitSpread(string symbol, out string leg1, out string leg2)
{
    leg1 = leg2 = null;
    int slash = symbol.IndexOf('/');
    if (slash < 0) return false;                       // 不是價差
    // 我們的整理（台指選擇權家族）：根碼 3 碼、尾端 2 碼是月份碼＋年碼
    string root   = symbol.Substring(0, 3);
    string suffix = symbol.Substring(symbol.Length - 2);
    string k1     = symbol.Substring(3, slash - 3);
    string k2     = symbol.Substring(slash + 1, symbol.Length - 2 - (slash + 1));
    leg1 = root + k1 + suffix;
    leg2 = root + k2 + suffix;
    return true;
}

void OnSpreadPosition(string symbol, string side, int qty, decimal avgCost)
{
    // side 是整組價差的方向：S＝賣出價差（收權利金），不是第一腳的買賣
    bool isCreditSpread = side == "S";
    decimal? pointValue = LookupPointValue(symbol);    // 自己維護的表；數值以期交所契約規格為準
    decimal? pnl = pointValue.HasValue ? CalcSpreadPnl(isCreditSpread, qty, avgCost, pointValue.Value) : (decimal?)null;
    // 查不到一點價值：不計算損益，寧可不顯示也不用錯值
    Show(symbol, side, qty, avgCost, pnl);
}

損益怎麼算，牽涉到現價與兩隻腳報價的取得方式，超出本文範圍，這段程式碼只示意「查不到一點價值就不算」這個分支。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明價差部位查詢結果的讀法，不構成投資建議，也不保證任何交易結果，文中提到的價差類型僅用於說明欄位語意。程式化交易並不降低市場風險，誤讀價差部位的方向或成本，可能讓程式送出與預期相反的委託。

投資人教育資源

延伸閱讀

• 〈群益API 未平倉查詢怎麼選〉——四種查詢方式的差異，以及為什麼用 GW。
• 〈群益API 委託回報怎麼解析〉——回報那一側的欄位，包括複式單兩隻腳的成交價。
• 〈群益API 委託回報怎麼對帳〉——對帳結果要跟查詢對一次，價差部位要先讀懂才能對。
• 〈群益API 下單價格為什麼是字串〉——下單物件與特殊值要逐個查。

參考資料

• OnOpenInterest 欄位表（含「一點價值」欄的分布）與 OnOpenInterestJson 回傳範例，依群益官方元件說明文件 V2.13.59 主手冊；SendDuplexOrder 備註依官方元件說明文件 V2.13.57。
• 價差部位的買賣別語意、GW 成本欄有值、反推錯誤的後果、短碼與長碼：實單經驗，非官方文件記載。
• 合成代碼的切法：我們對台指選擇權家族代碼的整理，非官方規格。
• 一點價值的數值：以臺灣期貨交易所契約規格為準。

免責聲明

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