Python交易API使用手冊

Python交易API流程說明

API驗證流程

STEP1

請先下載API元件,並使用您的程式登入元富API,登入測試環境。

STEP2

ROD下單、改單、刪單(依照數位API網站線上驗證下單內容,於您的程式進行委託下單)。

STEP3

IOC下單(依照數位API網站線上驗證下單內容,於您的程式進行委託下單)。

STEP4

FOK下單(依照數位API網站線上驗證下單內容,於您的程式進行委託下單)。

STEP5

下單完成後,於數位API網站線上驗證頁面輸入委託書號。

STEP6

以上3.4.5步驟均填入委託書號後,於數位API網站線上驗證頁面點選"驗證"。

STEP7

驗證成功後及驗證完成,須待人員審核,請稍待審核流程,方能開通權限。

關聯網站

Python交易API範例程式說明

1. 系統需求

  • Python 3.6以上版本

  • 交易python package

2. 環境準備

1

安裝交易API package:

32位元(x86):pip install MasterTradePy-X.X.X-py3-none-win32.whl

64位元(x64):pip install MasterTradePy-X.X.X-py3-none-win_amd64.whl

X.X.X為版號,請依據下載內容版號調整

2

建議可先參考執行Sample內容,確認執行下單交易內容後,再依此文件說明進行API開發

3. 執行Sample

1

取得驗證(第一次需驗證)

參數說明:

                
					python sample.py {使用者名稱} {密碼} {是否連測試(True/False)} {是否單一帳號通過強制登入(True/False)} {是否連接競賽主機(True/False)}
                
              
參數範例:python sample.py N123456789 1234 True True False
Docs UI Kit選1下單 Docs UI Kit範例如圖

根據取得結果在線上驗證回填結果,驗證成功後才可以開始使用

正式下單參數範例:python sample.py N123456789 1234 False True False
2

下單

Docs UI Kit選1 Docs UI Kit範例如圖
3

改量

Docs UI Kit選2 Docs UI Kit範例如圖
4

改價

Docs UI Kit選3 Docs UI Kit範例如圖
5

查詢委託回報,查成交回報

Docs UI Kit選4、5 Docs UI Kit範例如圖
6

期初庫存,庫存

Docs UI Kit選6、7 Docs UI Kit範例如圖
7

或有券源

Docs UI Kit選8 Docs UI Kit範例如圖
8

資券配額

Docs UI Kit選9 Docs UI Kit範例如圖

4. 回報狀態事件

4.1 OnReport

委託主動回報, 成交回報
                
				def OnReport(self, data) -> None:
				     if type(data) is ReportOrder:
					     # 回報資料
						 print(data.order.tableName)
					 if data.order.tableName == "ORD:TwsOrd":
					     print(f'回報資料: 委託書號={data.order.ordNo}, 股票代號={data.order.symbol}, 委託股數={data.orgOrder.qty}, 成交股數={data.order.cumQty}, 訊息={data.lastMessage}, 狀態={data.order.status}')
					 elif data.order.tableName == "RPT:TwsDeal":
					     print(f'回報資料: 委託書號={data.order.ordNo}, 股票代號={data.order.symbol}, 成交價格={data.order.dealPri}, 成交股數={data.order.cumQty}, 剩餘股數={data.order.leavesQty} 訊息={data.lastMessage}, 狀態={data.order.status}')
					 elif data.order.tableName == "RPT:TwsNew":
					     print(f'回報資料: 委託書號={data.order.ordNo}, 股票代號={data.order.symbol}, 委託價格={data.orgOrder.price}, 委託股數={data.orgOrder.qty}, 訊息={data.lastMessage}, 狀態={data.order.status}')
					 else:
					     print(f'回報資料: 委託書號={data.order.ordNo}, 股票代號={data.order.symbol}, 委託價格={data.orgOrder.price}, 委託股數={data.orgOrder.qty}, 成交股數={data.order.cumQty}, 訊息={data.lastMessage}, 狀態={data.order.status}')
				
              

Output:

下單:

RPT:TwsNew

回報資料: 委託書號=Y0003, 股票代號=2330, 委託價格=533, 委託股數=2000, 訊息=新單 2000 股OK!, 狀態=101

RPT:TwsDeal

回報資料: 委託書號=Y0003, 股票代號=2330, 成交價格=532, 成交股數=2000, 剩餘股數=0 訊息=, 狀態=111

改量:

RPT:TwsChg

回報資料: 委託書號=Y0004, 股票代號=2330, 委託價格=None, 委託股數=None, 成交股數=None, 訊息=減 1000 成功,剩餘 4000 股., 狀態=101

改價:

RPT:TwsChg

回報資料: 委託書號=Y0004, 股票代號=2330, 委託價格=None, 委託股數=None, 成交股數=None, 訊息=改價 L$515 成功, 狀態=101

Order物件

參數 類別 說明
sorRID str SorRID
exchange str 交易所
tradingSession str 交易時段(NORMAL: 普通, FIXED_NORMAL: 盤後, FIXED_NORMAL: 盤中零股, FIXED_ODD:盤後零股)
side str 買賣別(Buy:買進, Sell:賣出)
symbol str 股票代碼
priceType str 委託方式(價格)(LMT:限價單, MKT:市價單)
price str 價錢
tradingUnit Int 交易單位(COMMON:1000, ODD:1)
qty str 股數
orderType str 委託方式(效期)(ROD:當日有效, IOC: 立即成交,否則取消, FOK: 立即全部成交,否則取消)
tradingType str 委託別(集保CUSTODY :G)
userDef str 客戶自訂內容
tradingAccount str 交易帳號
ordNo str 單號
trxTime str 新單、最後刪改交易所收到時間
status str 委託狀態, 如下表格
leavesQty str 剩餘股數
cumQty str 成交股數
dealPri str 成交價
tableName str 回報表格名稱

委託狀態

變數名稱 參數值 說明
TReqStep_Pending '0' 委託要求處理中
TReqStep_BackConfirm '3' 本機委託要求退回給使用者(或營業主管)確定or強迫
TReqStep_Queuing '5' 本機委託要求排隊中
TReqStep_Sending '6' 本機委託要求傳送中
TReqStep_Sent '7' 本機委託要求已送出(等回報)
TReqStep_PartReject '88' 部份結束(失敗):例如:收到報價單的Bid失敗
TReqStep_PartFinish '89' 部份結束:例如收到報價單的其中一邊
TReqStep_Finished '90' 委託要求已結束
TReqStep_DupFinished '91' 重複的[結束]回報
TReqStep_UnknownFail '95' 委託要求狀態不明(例如:送出後斷線)
TReqStep_Reject '99' 委託要求拒絕
TReqStep_RptSuggestNew '100' 先收到成交回報
TReqStep_RptPartFilled '110' 配合 TReqKind_RptFilled: 部份成交
TReqStep_RptFullFilled '111' 配合 TReqKind_RptFilled: 全部成交
TReqStep_RptExchgKilled '120' 委託因IOC/FOK未成交而取消
TOrderSt_NewPending TReqStep_Pending 尚未處理
TOrderSt_Force TReqStep_BackConfirm 新單要求退回給使用者(或營業主管)確定or強迫
TOrderSt_NewQueuing TReqStep_Queuing 新單排隊中
TOrderSt_NewSending TReqStep_Sending 新單傳送中
TOrderSt_Sent TReqStep_Sent 新單已送出(等回報)
TOrderSt_InternalCanceling '81' 內部刪除 [其他主機 NewQueuing] 的委託.
TOrderSt_InternalCanceled '91' 新單尚未送出就被刪單
TOrderSt_NewUnknownFail TReqStep_UnknownFail 新單要求狀態不明(例如:送出後斷線)
TOrderSt_NewReject TReqStep_Reject 新單要求拒絕
TOrderSt_Accepted '101' 委託已接受(交易所已接受)
TOrderSt_PartFilled TReqStep_RptPartFilled 部份成交
TOrderSt_FullFilled TReqStep_RptFullFilled 全部成交
TOrderSt_IOCFOKNotFilled TReqStep_RptExchgKilled 一般:委託因IOC/FOK未成交而取消.報價:時間到自動刪單
TOrderSt_ExchgKilled TOrderSt_IOCFOKNotFilled

4.2 OnReqResult

一般作業結果通知, 證券基本資料、庫存資料
                
				def OnReqResult(self, workID: str, data) -> None:
				    if type(data) is Basic:
					   # 基本資料
					   print(f'workid={workID}, 證券基本資料: 股票代號={data.symbol}, 參考價={data.refPrice}, 漲停價={data.riseStopPrice}, 跌停價={data.fallStopPrice}')
					if type(data) is Inventory:
					   # 庫存資料
					   print(f'workid={workID}, 庫存資料={data}')
				
              

Basic 物件

參數 類別 說明
symbol str 股票代碼
name str 交易所
refPrice str 參考價
riseStopPrice str 漲停價
fallStopPrice str 跌停價

Inventory 物件

參數 類別 說明
symbol str 股票代碼
qty str 現股股數
qtyCredit str 融資股數
qtyDebit str 融券股數

4.3 OnSystemEvent

系統狀態事件回報
                
				def OnSystemEvent(self, data: SystemEvent) -> None:
				      print(f'OnSystemEvent{data}')
				
              

4.4 OnError

錯誤事件回報
                
				 def OnError(self, data):
				      print(data)
				
              

Python交易API實作使用說明

1. 登入Login

                
					rc = api.Login(username, password, is_sim, is_force, is_event)
                
              
參數 In/Out 類別 說明
username Input str 使用者ID
password Input str 使用者密碼
is_sim Input bool 是否連接測試機True:測試,False:正式
is_force Input bool 是否單一帳號通過驗證就強制登入
is_event Input bool 是否連接競賽主機
rc Output Enum 回傳結果RCode

2. 下單

                
                  order = Order(tradingSession=TradingSession.NORMAL, 
                        side=Side.Buy, //買賣別
                        symbol=symbol, //股票代碼
                        priceType=priceType, //價格類別(L:限價, M:市價)
                        price=price, //委託價格
                        tradingUnit=TradingUnit.COMMON, 
                        qty=qty, //委託股數
                        orderType=OrderType.ROD, //委託方式(ROD, IOC, FOK)
                        tradingAccount=account, //交易帳號
                        userDef='') //客戶自訂內容
                  rcode = api.NewOrder(order)	
                
              
參數 In/Out 類別 說明
tradingSession Input Enum 交易時段(NORMAL: 普通, FIXED_NORMAL: 盤後, FIXED_NORMAL: 盤中零股, FIXED_ODD:盤後零股)
side Input Enum 買賣別(Buy:買進, Sell:賣出)
symbol Input str 股票代碼
priceType Input Enum 委託方式(價格)(LMT:限價單, MKT:市價單)
price Input str 價錢
tradingUnit Input Enum 交易單位(COMMON:1000, ODD:1)
qty Input str 委託股數
orderType Input Enum 委託方式(效期)(ROD:當日有效, IOC: 立即成交,否則取消, FOK: 立即全部成交,否則取消)
tradingAccount Input str 交易帳號
userDef Input str 客戶自訂內容
rcode Output Enum 回傳結果RCode

3. 改量

                
                 replaceOrder = OrderQtyChange(ordNo=ordNo, qty = qty, tradingAccount=account)
                 //代入委託書號、改量股數、交易帳號
                 rcode = api.ChangeOrderQty(replaceOrder)
                
              
參數 In/Out 類別 說明
ordNo Input str 單號
qty Input str 改量股數
tradingAccount Input str 交易帳號
rcode Output Enum 回傳結果RCode

4. 改價

                
                 replaceOrder = OrderPriceChange(ordNo=ordNo, price = price, tradingAccount=account)
				 //代入委託書號、改價價格、交易帳號
				 rcode = api.ChangeOrderPrice(replaceOrder)
                
              
參數 In/Out 類別 說明
ordNo Input str 單號
price Input str 改價價錢
tradingAccount Input str 交易帳號
rcode Output Enum 回傳結果RCode

5. 查詢委託回報

				
				api.QryRepAll(account)
				
			
參數 In/Out 類別 說明
account Input str 交易帳號

6. 查詢成交回報

					
					api.QryRepDeal(account)
					
				
參數 In/Out 類別 說明
account Input str 交易帳號

7. 查詢期初庫存

					
					api.ReqInventoryOpen(account)
					
				
參數 In/Out 類別 說明
account Input str 交易帳號

8. 查詢庫存

									
									api.ReqInventoryRayinTotal(account)
									
								
參數 In/Out 類別 說明
account Input str 交易帳號

9. 查詢或有券源

					
					api.QrySecInvQty_Rayin(account, symbol)
					
				
參數 In/Out 類別 說明
account Input str 交易帳號
symbol Input str 商品代碼

查詢資券配額

					
					api.QryProdCrQty_Rayin(account, symbol)
					
				
參數 In/Out 類別 說明
account Input str 交易帳號
symbol Input str 商品代碼

元富證券股份有限公司 |台北市敦化南路二段97號22樓|客服專線:0800-088-148|手機及國外客服專線:(02)2708-3972 |108年金管證總字第0031號

元富證券股份有限公司
台北市敦化南路二段97號22樓
客服專線:0800-088-148
手機及國外客服專線:(02)2708-3972
108年金管證總字第0031號