pytaifex 1.1.0

A Python wrapper for the official TTB API of the Taiwan Futures Exchange (TAIFEX).

PyTaifex - 臺灣期貨交易所 TTB API Python 封裝庫

English version available: README_en.md

PyTaifex 是一個專為臺灣期貨交易所（TAIFEX）官方 TTB 交易 API 設計的 Python 封裝庫。它提供了一個簡潔、穩定且功能完整的介面，讓開發者能夠輕鬆地進行期貨交易、市場數據訂閱、部位查詢等操作。

🚀 主要特色

• 即時市場數據訂閱 - 支援多商品同時訂閱，透過回調函數接收即時報價
• 完整的委託管理 - 支援委託建立、修改價格、修改數量、取消委託等完整生命週期管理
• 部位與帳戶查詢 - 提供即時部位查詢和帳戶保證金資訊
• 自動化登入與環境準備 - 內建 UI 自動化模組 (OfficialTTB)，可自動啟動 TTB、登入帳號並選擇競賽
• 多進程架構 - 採用獨立進程處理 TTB 操作，確保主程式穩定性
• 完善的錯誤處理 - 提供詳細的異常類型，便於錯誤診斷和處理
• Context Manager 支援 - 支援 with 語句，自動管理資源清理
• 完整的日誌系統 - 提供詳細的操作日誌，便於除錯和監控

📋 系統需求

• Python 3.13 或更高版本
• 臺灣期貨交易所官方 TTB API 模組檔案 (TTBHelp.pyc)
• 臺灣期貨交易所官方 TTB 軟體
• 臺灣期貨交易所的交易競賽帳號

🔧 安裝方式

使用 pip 安裝

pip install pytaifex

使用 uv 安裝

uv add pytaifex

從原始碼安裝

git clone https://github.com/coke5151/pytaifex.git
cd pytaifex
pip install -e .

📖 快速開始

1. 環境準備與登入

首先，您需要從臺灣期貨交易所官方網站下載 TTB API 模組檔案及 TTB 軟體 (TTBHelp.pyc)。

您可以手動啟動 TTB 軟體並登入，或者使用我們提供的全自動 UI 登入工具：

from pytaifex.official_ttb import OfficialTTB

# 自動啟動 TTB 軟體，force=True 表示若軟體已開啟則先強制關閉以確保乾淨啟動
ttb_app = OfficialTTB(r"C:\path\to\TaifexTradeBox.exe", force=True)

# 進行自動化登入
ttb_app.login("[e-mail]", "your_password")

# 查詢您可用的競賽清單，並指定競賽名稱 (或是直接給 index)
# competitions = ttb_app.get_competitions()
# print(competitions) 
ttb_app.select_competition("盤中延遲模式")  # 或 ttb_app.select_competition(0)

2. 基本交易與查詢範例

在確保 TTB 軟體啟動並選擇好競賽後，您就可以初始化 TTB 類別來串接進行程式交易了：

from pytaifex import TTB, QuoteData, OrderSide, TimeInForce, OrderType

# 定義報價 callback 函數
def on_quote_received(quote_data: QuoteData):
    print(f"收到報價: {quote_data.symbol}")
    print(f"最新價格: {quote_data.price}")
    print(f"買價: {quote_data.bid_ps}, 賣價: {quote_data.ask_ps}")
    print(f"時間: {quote_data.tick_time}")

# 使用 Context Manager 確保資源正確釋放（也可以手動呼叫 client.shutdown()）
with TTB("path/to/TTBHelp.pyc") as client:
    # 註冊報價回調函數
    client.register_quote_callback(on_quote_received)

    # 訂閱市場數據
    client.subscribe(["TXFF5", "MTXF5"])  # 訂閱 2025/06 的台指期和小台指期

    # 建立委託單
    client.create_order(
        symbol1="TXFF5",           # 商品代碼
        side1=OrderSide.BUY,       # 買賣別：買進
        price="17000",             # 委託價格
        time_in_force=TimeInForce.ROD,  # 委託時效：當日有效
        order_type=OrderType.LIMIT,     # 委託類型：限價單
        order_qty="1",             # 委託數量
        day_trade=False            # 是否為當沖
    )

    # 查詢委託單
    orders = client.get_orders()
    for order in orders:
        print(f"委託單號: {order.order_number}")
        print(f"商品: {order.symbol_name}")
        print(f"狀態: {order.status}")

    # 查詢部位
    positions = client.get_positions()
    for position in positions:
        print(f"部位ID: {position.deal_id}")
        print(f"商品: {position.symbol1_name}")
        print(f"未實現損益: {position.floating_profit_loss}")

    # 查詢帳戶資訊
    accounts = client.get_accounts()
    for account in accounts:
        print(account)

📚 詳細使用教學

1. 初始化 TTB 客戶端

from pytaifex import TTB
import logging

# 建立自定義 logger（可選）
logger = logging.getLogger("my_trading_app")
logger.setLevel(logging.INFO)

# 初始化 TTB 客戶端
client = TTB(
    pyc_file_path="path/to/TTBHelp.pyc",  # TTB API 模組路徑
    host="http://localhost:8080",         # TTB 伺服器位址（預設）
    zmq_port=51141,                       # ZeroMQ 連接埠（預設）
    logger=logger,                        # 自定義 logger（可選）
    timeout=5                             # 初始化超時時間（秒）
)

2. 市場數據訂閱

def quote_handler(quote: QuoteData):
    """處理即時報價數據"""
    print(f"商品: {quote.symbol} ({quote.name})")
    print(f"最新價: {quote.price}")
    print(f"漲跌: {quote.change_price} ({quote.change_ratio}%)")
    print(f"買價/量: {quote.bid_ps}/{quote.bid_pv}")
    print(f"賣價/量: {quote.ask_ps}/{quote.ask_pv}")
    print(f"成交量: {quote.volume}")
    print("-" * 40)

# 註冊 callback 函數
client.register_quote_callback(quote_handler)

# 訂閱多個商品
symbols = ["TXFF5", "MTXF5", "TXO21000F5"]  # 台指期、小台指、台指選擇權
client.subscribe(symbols)

3. 委託單管理

建立委託單

# 限價買單
client.create_order(
    symbol1="TXFF5",
    side1=OrderSide.BUY,
    price="21000",
    time_in_force=TimeInForce.ROD,  # ROD: 當日有效, IOC: 立即成交否則取消, FOK: 全部成交否則取消
    order_type=OrderType.LIMIT,     # LIMIT: 限價單, MARKET: 市價單
    order_qty="2",
    day_trade=True  # 當沖交易
)

# 價差單（跨月套利）
client.create_order(
    symbol1="TXFF5",      # 近月合約
    side1=OrderSide.BUY,
    symbol2="TXFG5",      # 遠月合約
    side2=OrderSide.SELL,
    price="50",           # 價差
    time_in_force=TimeInForce.ROD,
    order_type=OrderType.LIMIT,
    order_qty="1",
    day_trade=False
)

修改委託單

# 查詢現有委託
orders = client.get_orders()
if orders:
    order_number = orders[0].order_number

    # 修改價格
    client.change_price(order_number, "20000")

    # 修改數量
    client.change_qty(order_number, "3")

    # 取消委託
    client.cancel_order(order_number)

4. 部位與帳戶查詢

# 查詢部位
positions = client.get_positions()
for pos in positions:
    print(f"部位資訊:")
    print(f"  交易ID: {pos.deal_id}")
    print(f"  主要商品: {pos.symbol1_name} ({pos.symbol1_id})")
    print(f"  買賣別: {'買進' if pos.side1 == OrderSide.BUY else '賣出'}")
    print(f"  持有數量: {pos.hold}")
    print(f"  成交價格: {pos.deal_price}")
    print(f"  結算價格: {pos.settle_price}")
    print(f"  未實現損益: {pos.floating_profit_loss}")
    print(f"  幣別: {pos.currency}")  # 如果是價差單

# 查詢帳戶資訊
accounts = client.get_accounts()
for account in accounts:
    print(account) # account 是一個 dict

5. 錯誤處理

from pytaifex import (
    TTBConnectionError, TTBTimeoutError,
    OrderCreationError, OrderModificationError, OrderCancellationError,
    SubscribeError, ValidationError
)

try:
    client.create_order(
        symbol1="INVALID_SYMBOL",
        side1=OrderSide.BUY,
        price="17000",
        time_in_force=TimeInForce.ROD,
        order_type=OrderType.LIMIT,
        order_qty="1",
        day_trade=False
    )
except OrderCreationError as e:
    print(f"委託建立失敗: {e}")
except TTBTimeoutError as e:
    print(f"請求超時: {e}")
except TTBConnectionError as e:
    print(f"連線錯誤: {e}")
except Exception as e:
    print(f"未預期的錯誤: {e}")

🔍 商品代碼說明

臺灣期貨交易所的商品代碼格式為：

• 期貨：商品代碼 + 月份代碼 + 年份代碼
• 選擇權：商品代碼 + 履約價 + 月份代碼 + 年份代碼

月份代碼對照表

• A: 1月, B: 2月, C: 3月, D: 4月, E: 5月, F: 6月
• G: 7月, H: 8月, I: 9月, J: 10月, K: 11月, L: 12月

常見商品範例

• TXFF5: 台指期 2025 年 6 月合約 (TXF + F + 5)
• MTXF5: 小台指期 2025 年 6 月合約 (MTX + F + 5)
• TXO21000F5: 台指選擇權 2025 年 6 月，履約價 21000 的合約 (TXO + 21000 + F + 5)

⚠️ 重要注意事項

1. TTB 軟體需求: 使用前請確保臺灣期貨交易所官方 TTB 軟體正在運行
2. API 模組: 需要從官方網站下載最新的 TTBHelp.pyc 檔案
3. 網路連線: 確保網路連線穩定，避免交易中斷
4. 風險管理: 請謹慎使用自動交易功能，建議先在模擬環境測試
5. 資源管理: 使用完畢後請呼叫 client.shutdown() 或使用 Context Manager (with TTB(...) as client:)

🐛 疑難排解

常見問題

Q: 訂閱市場數據後 callback 函數沒有被呼叫 A: 請檢查：

• TTB 軟體是否正在運行
• 商品代碼格式是否正確
• 確認在 TTB 軟體中同時訂閱了相同商品
• 該商品是否在交易時間內
• 你是否可以在 TTB 軟體裡看到有報價更新

Q: 委託單建立失敗 A: 請檢查：

• 帳戶是否有足夠保證金
• 商品代碼是否正確
• 價格是否在合理範圍內
• 是否在交易時間內

Q: 連線超時錯誤 A: 請檢查：

• TTB 軟體連線狀態
• 網路連線是否穩定
• 防火牆設定是否阻擋連線

📄 授權條款

本專案採用 MIT 授權條款。詳細內容請參閱 LICENSE 檔案。

🤝 貢獻指南

歡迎提交 Issue 和 Pull Request！在提交前請確保：

1. 程式碼符合專案的編碼風格
2. 新增功能包含適當的測試
3. 更新相關文件

📞 聯絡資訊

• 作者: pytree
• Email: [e-mail]
• GitHub: https://github.com/coke5151

---

免責聲明: 本軟體僅供學習和研究使用。使用者應自行承擔交易風險，作者不對任何交易損失負責。