6.3.1 TWS API v9.72 線上文件 ——訂單管理/替換訂單【翻譯】
Order Management(訂單管理)
· Placing Orders
· Modifying Orders
· Cancelling Orders
· Retrieving currently active orders
· Executions and Commissions
· Order Limitations
· MiFIR Transaction Reporting Fields
Placing Orders(替換訂單)
The Next Valid Identifier
Perhaps the most important event received after successfully connecting to the TWS is the IBApi.EWrapper.nextValidId, which is also triggered after invoking the IBApi.EClient.reqIds method. As its name indicates, the nextValidId event provides the next valid identifier needed to place an order. This identifier is nothing more than the next number in the sequence. This means that if there is a single client application submitting orders to an account, it does not have to obtain a new valid identifier every time it needs to submit a new order. It is enough to increase the last value received from the nextValidId method by one. For example, if the valid identifier for your first API order is 1, the next valid identifier would be 2 and so on.
【譯】對於成功地連線到TWS之後,可能最重要的訊息就是接收到“IBApi.EWrapper.nextValidId”,也可以使用IBApi.EClient.reqIds 方法獲得。正如它的名字,nextValidId 事件提供了下一個訂單的可用識別符號。它非常重要,如果在單客戶端模式下,不必每次提交訂單時都請求,只需要給“IBApi.EWrapper.nextValidId”加1。舉例來說,如果你一開始的nextValidId 是1,那麼接下來第二份訂單的值就是2,以此類推。
However if there are multiple client applications connected to one account, it is necessary to use an order ID with new orders which is greater than all previous order IDs returned to the client application in openOrder or orderStatus callbacks. For instance, if the client is set as the Master client, it will automatically receive order status and trade callbacks from orders placed from other clients. In such a case, any orderID used in placeOrder must be greater than the orderIDs returned in these status callbacks. Alternatively if the function reqAllOpenOrders is used by a client, subsequent orders placed by that client must have order IDs greater than the order IDs of all orders returned because of that function call. You can always use the IBApi.EClient.reqIds method in the event that your client application loses track of the sequence.
【譯】如果有多個客戶端連線到了一個賬戶,那麼就需要使用給每個訂單一個訂單ID,這個ID必須要比之前所有的從openOrder 或者orderStatus 回撥函式獲得的ID要大。舉例來說,如果客戶端設定為主客戶端,它將自動的接收訂單狀態以及從其他從客戶端傳送的交易回撥返回。在這樣的情況下,任何一個在placeOrder 的orderID 都必須比這些返回的orderIDs 要大。如果某個客戶端呼叫了reqAllOpenOrders 函式,新的ID需要比通過這個函式返回的全部的ID的最大值要大(譯者注:id > max(reqAllOpenOrders))。因此,你可以使用IBApi.EClient.reqIds 獲取到所有已用訂單。
//The parameter is always ignored.
client.reqIds(-1);
The above will result in IBApi.EWrapper.nextValidId callback being invoked:
【譯】這個方法會導致IBApi.EWrapper.nextValidId函式被啟用
publicclassEWrapperImpl implementsEWrapper {
{
…
@Override
publicvoidnextValidId(intorderId){
System.out.println("Next Valid Id: ["+orderId+"]");
currentOrderId =orderId;
}
The next valid identifier is persistent between TWS sessions.
If necessary, you can reset the order ID sequence within the API Settings dialogue. Note however that the order sequence Id can only be reset if there are no active API orders.
【譯】如果需要,你可以在API設定對話方塊中重製訂單ID序列。主意:只有在沒有啟用訂單的情況下,才可以重製訂單序列。
Placing Orders
Orders are submitted via the IBApi.EClient.placeOrder method. From the snippet below, note how a variable holding the nextValidId is incremented automatically:
【譯】訂單由IBApi.EClient.placeOrder 函式提交。注意nextValidId 是需要自增長的。
client.placeOrder(nextOrderId++,
ContractSamples.USStock(),
OrderSamples.TrailingStopLimit("BUY",1,5,5,110));
Immediately after the order was submitted correctly, the TWS will start sending events concerning the order’s activity via IBApi.EWrapper.openOrder and IBApi.EWrapper.orderStatus
【譯】如果提交的訂單正確,TWS將立即通過IBApi.EWrapper.openOrder 和IBApi.EWrapper.orderStatus 返回關於訂單活動狀態的資訊。
An order can be sent to TWS but not transmitted to the IB server by setting the IBApi.Order.Transmit flag in the order class to False. Untransmitted orders will only be available within that TWS session (not for other usernames) and will be cleared on restart. Also, they can be cancelled or transmitted from the API but not viewed while they remain in the untransmitted state.
【譯】可以在訂單類中,設定IBApi.Order.Transmit 為False, 阻止訂單經由TWS直接提交到IB的伺服器。沒有提交到伺服器的訂單,只駐留在TWS中,並在下次重啟時失效。儘管可以對這些訂單進行取消或傳送,但是仍然沒有傳送的訂單,將不可見。
The openOrder callback
The IBApi.EWrapper.openOrder method delivers an IBApi.Order object representing the open order within the system. Additionally, an IBApi.OrderState object containing margin and commission information about this particular order.
【譯】IBApi.EWrapper.openOrder 函式,在系統中傳遞代表開放訂單物件的IBApi.Order。另外的,IBApi.OrderState 物件包含該訂單的頭寸與佣金資訊。
publicclassEWrapperImpl implementsEWrapper {
…
@Override
publicvoidopenOrder(intorderId,
Contract contract,Order order,
OrderState orderState){
System.out.println(
EWrapperMsgGenerator.openOrder(orderId,
contract,order,orderState));
}
The orderStatus callback
The IBApi.EWrapper.orderStatus method contains all relevant information on the current status of the order execution-wise (i.e. amount filled and pending, filling price, etc.).
【譯】IBApi.EWrapper.orderStatus 函式包含訂單執行的全部關聯資訊(例如:成交,掛起,成交價格等)。
publicclassEWrapperImpl implementsEWrapper {
…
@Override
publicvoidorderStatus(intorderId,
String status,doublefilled,
doubleremaining,doubleavgFillPrice,
intpermId,intparentId,
doublelastFillPrice,
intclientId,String whyHeld,doublemktCapPrice){
System.out.println(
"OrderStatus. Id: "+orderId+
", Status: "+status+
", Filled"+filled+
", Remaining: "+remaining+
", AvgFillPrice: "+avgFillPrice+
", PermId: "+permId+
", ParentId: "+parentId+
", LastFillPrice: "+lastFillPrice+
", ClientId: "+clientId+
", WhyHeld: "+whyHeld+
", MktCapPrice: "+mktCapPrice);
}
Automatic Order Status Messages (without invoking reqOpenOrders or reqAllOpenOrders)
自動化訂單狀態(不啟用reqOpenOrders 或reqAllOpenOrders)
· Clients with the ID of the client submitting the order will receive order status messages indicating changes in the order status.
· The client with Master Client ID (set in TWS/IBG) will receive order status messages for all clients.
· Client ID 0 will receive order status messages for its own (client ID 0) orders and also for orders submitted manually from TWS.
· 包含從ID的客戶端提交訂單後會受到訂單狀態訊息,指示訂單狀態的改變。
· 包含主ID的客戶端(在TWS/IBG中設置)會接受到全部從客戶端的訂單狀態訊息。
· ID 0 會收到只關於自己的的訂單資訊。
Possible Order States
可能的訂單狀態
· ApiPending - indicates order has not yet been sent to IB server, for instance if there is a delay in receiving the security definition. Uncommonly received.
· 【ApiPending】- 指示訂單沒有發送到IB的服務器上,如:接受安全資產定義有延遲。不通常收到。
· PendingSubmit - indicates the order was sent from TWS, but confirmation has not been received that it has been received by the destination. Most commonly because exchange is closed.
· 【PendingSubmit】- 指示訂單已經發送給了TWS,但是確認訊息還未收到。通常因為交易所休市,會經常收到。
· PendingCancel - indicates that a request has been sent to cancel an order but confirmation has not been received of its cancellation.
· 【PendingCancel】- 指示取消訂單請求已經發送但是確認訊息還未收到。
· PreSubmitted - indicates that a simulated order type has been accepted by the IB system and that this order has yet to be elected. The order is held in the IB system until the election criteria are met. At that time the order is transmitted to the order destination as specified.
· 【PreSubmitted】- 指示模擬訂單類型已經由IB確認,但還未選中。該訂單由IB保留,直到條件符合。訂單將發送到對應的交易場所。
· Submitted - indicates that your order has been accepted at the order destination and is working.
· 【Submitted】- 指示你的訂單已被接受,並開始執行。
· ApiCancelled - after an order has been submitted and before it has been acknowledged, an API client client can request its cancellation, producing this state.
· 【ApiCancelled】- 在訂單提交後,但在被識別到之前,API客戶端可以請求取消它,此時將產生這個狀態。
· Cancelled - indicates that the balance of your order has been confirmed cancelled by the IB system. This could occur unexpectedly when IB or the destination has rejected your order.
· 【Cancelled】- 指示由於訂單資產負債情況由IB系統主動的取消,當IB或目的地取消時。
· Filled - indicates that the order has been completely filled.
· 【Filled】- 指示訂單完全成交。
· Inactive - indicates an order is not working, possible reasons include:
· 【不活躍】- 指示訂單沒有工作,可能原因如下:
o it is invalid or triggered an error. A corresponding error code is expected to the error() function.
o 它是不合法的,或者激發了一個錯誤。對應的錯誤代碼在error()中。
o the order is to short shares but the order is being held while shares are being located.
o 做空池為空時,不能做空股票。
o an order is placed manually in TWS while the exchange is closed.
o 在交易所關閉時,訂單由TWS手動修改了。
o an order is blocked by TWS due to a precautionary setting and appears there in an untransmitted state
o 訂單因TWS保護性策略,阻止了交易,將導致未發送狀態。
Important notes concerning IBApi.EWrapper.orderStatus :
· Typically there are duplicate orderStatus messages with the same information that will be received by a client. This corresponds to messages sent back from TWS, the IB server, or the exchange.
· 通常的,一個客戶端會同時收到多條重複資訊。這些訊息由TWS、IB服務器,交易所返回。
· There are not guaranteed to be orderStatus callbacks for every change in order status. For example with market orders when the order is accepted and executes immediately, there commonly will not be any corresponding orderStatus callbacks. For that reason it is recommended to monitor the IBApi.EWrapper.execDetails function in addition to IBApi.EWrapper.orderStatus.
· 不保證orderStatus會返回所有的訂單狀態。舉例來說,訂單被接受並立即執行,就通常情況就不會返回訂單狀態。因此,建議監控IBApi.EWrapper.execDetails函式作為訂單狀態IBApi.EWrapper.orderStatus 的補充手段。
· Beginning in API v973.04, a parameter mktCapPrice is included in the orderStatus callback. If an order has been price-capped, mktCapPrice will indicate the price at which it has been capped.
· 從v973.04開始,mktCapPrice 作為引數被加入到了orderStatus 回調函式中。如果訂單已被限制價格,mktCapPrice將指示其上限的價格。
Attaching Orders
Advanced orders such as Bracket Orders or Hedging involve attaching child orders to a parent. This can be easily done via the IBApi.Order.ParentId attribute by assigning a child order’s IBApi.Order.ParentId to an existing order’s IBApi.Order.OrderId. When an order is attached to another, the system will keep the child order ‘on hold’ until its parent fills. Once the parent order is completely filled, its children will automatically become active.
【譯】高階訂單,包含交叉交易、對衝訂單涉及到將子訂單附加到父級。通過將子訂單的IBApi.Order.ParentId分配給現有訂單的IBApi.Order.OrderId輕鬆完成。當訂單附加到另一個訂單時,系統將保留子訂單,直到其父訂單成交。父訂單完成後,其子將自動變為活動狀態。
Important: When attaching orders and to prevent accidental executions it is a very good idea to make use of the IBApi.Order.Transmit flag as demonstrated in Bracket Orders
當附加訂單時,為了避免執行過程中產生意外,在交叉訂單中使用IBApi.Order.Transmit 標記是個很好的習慣。