Trading Tools

交易工具

交易服務同時包含 13 個寫入工具與 11 個唯讀委託查詢工具。正式帳戶上呼叫寫入工具會產生外部交易效果；MCP Host 應在工具層做 allowlist、人工確認與參數回顯。

Caution

不得把「tool call 逾時」當成「券商未收到」。任何送單、改單或刪單逾時都必須先查 get_order_results、get_order_results_detail、成交與 callback 回報，再決定是否能重試。

寫入工具清單

place_order、cancel_order、modify_price、modify_quantity、batch_place_order、place_condition_order、place_multi_condition_order、place_daytrade_condition_order、place_daytrade_multi_condition_order、place_time_slice_order、place_tpsl_condition_order、cancel_condition_order、place_trail_profit。

普通委託

place_order

欄位	必填	預設／限制
account	是	必須對應登入回傳的帳戶
buy_sell	是	Buy／Sell
symbol	是	商品代碼
price	視價別	限價時提供字串價格；市價等價別可為空
quantity	是	單位為股
market_type	否	Common
price_type	否	Limit
time_in_force	否	ROD
order_type	否	Stock
user_def	否	1–10 個 ASCII 英數字

{
  "args": {
    "account": "<ACCOUNT>",
    "buy_sell": "Buy",
    "symbol": "2330",
    "price": "<CONFIRMED_LIMIT_PRICE>",
    "quantity": 1000,
    "market_type": "Common",
    "price_type": "Limit",
    "time_in_force": "ROD",
    "order_type": "Stock",
    "user_def": "MCP001"
  }
}

batch_place_order 接受 orders[]，並使用平行處理。批次部分成功是可能狀態；呼叫端必須逐筆保存結果並對每筆回讀。

修改與取消

• cancel_order：以 order_no 或 SDK order result 內容識別委託，可選 unblock。
• modify_price：可傳 new_price 或 price_type，並以 order_no／order_res 識別委託。
• modify_quantity：account、order_no、new_quantity 均必填。

修改與取消都可能和成交事件競爭；最終狀態以券商查詢及成交資料為準。

條件單共用結構

condition

{
  "market_type": "Reference",
  "symbol": "2330",
  "trigger": "MatchedPrice",
  "trigger_value": "<TRIGGER_PRICE>",
  "comparison": "GreaterThanOrEqual"
}

常用值：

• market_type：Reference、Scheduled。
• trigger：BidPrice、AskPrice、MatchedPrice、TotalQuantity、Time。
• comparison：LessThan、LessThanOrEqual、Equal、GreaterThan、GreaterThanOrEqual。

order

{
  "buy_sell": "Sell",
  "symbol": "2330",
  "price": "<ORDER_PRICE>",
  "quantity": 1000,
  "market_type": "Common",
  "price_type": "Limit",
  "time_in_force": "ROD",
  "order_type": "Stock"
}

tpsl

{
  "stop_sign": "Full",
  "tp": {
    "time_in_force": "ROD",
    "price_type": "Limit",
    "order_type": "Stock",
    "target_price": "<TP_TRIGGER>",
    "price": "<TP_ORDER_PRICE>",
    "trigger": "MatchedPrice"
  },
  "sl": {
    "time_in_force": "ROD",
    "price_type": "Market",
    "order_type": "Stock",
    "target_price": "<SL_TRIGGER>",
    "price": "",
    "trigger": "MatchedPrice"
  },
  "end_date": "YYYYMMDD",
  "intraday": false
}

市價 TPSL 的 price 必須是空字串。停損停利代表觸發送單，不保證成交。

條件單工具

Tool	核心參數
place_condition_order	account, start_date, end_date, stop_sign, condition, order, tpsl?
place_multi_condition_order	同上，但使用 conditions[]
place_tpsl_condition_order	單一 condition、order 與必填 tpsl
place_daytrade_condition_order	start_date, end_date, conditions[], order
place_daytrade_multi_condition_order	end_time, conditions[], order, daytrade, tpsl?, fix_session?

stop_sign 常用 Full、Partial、UntilEnd。日期格式為 YYYYMMDD；時間格式為 HHMMSS。

當沖回補結構：

{
  "day_trade_end_time": "131500",
  "auto_cancel": true,
  "price": "",
  "price_type": "Market"
}

當沖與資券互抵規則需由呼叫者依帳戶及市場規範確認。

分時分量

place_time_slice_order 使用 split 與 order：

{
  "args": {
    "account": "<ACCOUNT>",
    "start_date": "YYYYMMDD",
    "end_date": "YYYYMMDD",
    "stop_sign": "Full",
    "split": {
      "method": "Type2",
      "interval": 30,
      "single_quantity": 1000,
      "split_count": 5,
      "start_time": "090000",
      "end_time": "133000"
    },
    "order": {
      "buy_sell": "Buy",
      "symbol": "2330",
      "price": "<ORDER_PRICE>",
      "quantity": 5000,
      "market_type": "Common",
      "price_type": "Limit",
      "time_in_force": "ROD",
      "order_type": "Stock"
    }
  }
}

• Type1：依間隔與單筆數量送出。
• Type2／Type3：使用開始與結束時間分配數量。
• split_count × single_quantity 可計算 total_quantity。
• 拆單單位與數量必須符合官方 SDK 與市場規則。

要取消已產生的子委託，先用 get_order_results_detail 找到實際 order_no，再逐筆 cancel_order。不要把 batch number 當一般條件單 GUID 傳給 cancel_condition_order。

移動鎖利

place_trail_profit 的頂層欄位是 account、start_date、end_date、stop_sign、trail。trail 包含：

symbol、price、direction (Up／Down)、percentage、buy_sell、quantity、price_type、diff、time_in_force、order_type。

基準價 price 最多兩位小數。可用 get_trail_order 與 get_trail_history 回讀。

唯讀回讀工具

在任何寫入後，依序使用：

1. get_order_results：當日委託總覽。
2. get_order_results_detail：狀態、已成交數量、錯誤與修改歷史。
3. get_filled_history 或 get_filled_reports：成交確認。
4. 條件單用 get_condition_order_by_id／get_daytrade_condition_by_id／get_condition_history。

get_order_history 與 get_filled_history 接受 start_date 及選填 end_date；未提供結束日時使用開始日。

生產環境控制建議

• 將 READ 與 WRITE tools 分成不同 MCP policy lane。
• 寫入前回顯帳戶、商品、買賣別、數量、價別、價格、有效期間。
• 每次寫入建立唯一 correlation ID；可用合法 user_def 協助追蹤普通單。
• 設定單次與單日名目金額、數量和批次筆數上限。
• 不做盲目 retry；所有未知結果先查詢。
• 自動化測試以 mock SDK 為主，除非人工明確啟用，不得使用真實交易帳戶。