12 Tracking trade executions

IB-Matlab provides several distinct ways to programmatically track trade executions:

12.1 User requests

To retrieve the list of trade executions done in the IB account today,144 use Action='executions' as follows (note the similarities to the orders query, §10.1 above):

>> data = IBMatlab('action','executions')
data =
1x3 struct array with fields:
orderId
execId
time
exchange
side
shares
symbol
price
permId
liquidation
cumQty
avgPrice
contract
execution
commission

This returns a Matlab struct array, where each array element represents a different execution event.

You can access any of the orders using the standard Matlab dot notation:

>> data(1)
ans =
orderId: 154735358
execId: '00018037.4ff27b0e.01.01'
time: '20120216 18:50:14'
exchange: 'ISLAND'
side: 'BOT'
shares: 1
symbol: 'GOOG'
price: 602.82
permId: 300757703
liquidation: 0
cumQty: 1
avgPrice: 602.82
contract: [1x1 struct]
execution: [1x1 struct]
commission: [1x1 struct]

>> data(2)
ans =
orderId: 154737092
execId: '00018037.4ff2a3b8.01.01'
time: '20120216 18:58:57'
exchange: 'BEX'
side: 'SLD'
shares: 3
symbol: 'GOOG'
price: 605.19
permId: 300757711
liquidation: 0
cumQty: 3
avgPrice: 605.19
contract: [1x1 struct]
execution: [1x1 struct]
commission: [1x1 struct]

Each of the order structs contains the following data fields:145

orderId – ID returned by IBMatlab when a trade order is submitted, used by IB to uniquely identify the trade. TWS orders have a fixed order ID of zero (0).

execId – unique ID assigned to this execution

time – time of execution (local user time, not IB server time)

exchange – name of the exchange which executed the trade

side – BOT (=buy) or SLD (=sell)

shares – number of executed shares

symbol – security’s symbol (use the contract field to get the LocalSymbol)

price – execution price

permId – permanent ID used to store the order in the IB server

liquidation – identifies the position as one to be liquidated last, should the need arise

cumQty – cumulative number of shares filled in this trade (used for partial fills)

avgPrice – weighted average price of partial executions for this trade

contract – this struct object contains the contract information, including all the relevant information about the affected security

execution – this struct object contains information about the specific execution’s parameters

commission – this struct object contains information about the execution’s commission, realized P&L and yield. This information is not always available/ reported. For example, P&L is only reported when you close a position, etc.

For example:

>> data(2).contract
ans =
conId: 30351181
symbol: 'GOOG'
secType: 'STK'
expiry: []
strike: 0
right: []
multiplier: []
exchange: 'BEX'
currency: 'USD'
localSymbol: 'GOOG'
primaryExch: []
includeExpired: 0
secIdType: []
secId: []
comboLegsDescrip: []
comboLegs: []
underComp: []

>> data(2).execution
ans =
orderId: 154737092
clientId: 8101
execId: '00018037.4ff2a3b8.01.01'
time: '20120216 18:58:57'
acctNumber: 'DU90912'
exchange: 'BEX'
side: 'SLD'
shares: 3
price: 605.19
permId: 300757711
liquidation: 0
cumQty: 3
avgPrice: 605.19
orderRef: []
evRule: []
evMultiplier: 0

>> data(2).commission
ans =
execId: '00018037.4ff2a3b8.01.01'
commission: 1.107675
currency: 'USD'
realizedPNL: 15.527415
yield: Inf
yieldRedemptionDate: 0

Note: in IB-Matlab v2.19 (11/2022) and newer, values of Inf indicate an undefined/uninitialized value; in IB-Matlab v2.18 and older such values were reported as 1.79769313486232e+308 (realmax) or 2147483647 (intmax).

We can filter the results based on a specific Symbol and/or OrderId. For example:

>> data = IBMatlab('action','executions', 'OrderId',154737092)
data =
orderId: 154737092
execId: '00018037.4ff2a3b8.01.01'
(etc.)

Or alternatively (note that symbol filtering is case insensitive):

>> data = IBMatlab('action','executions', 'symbol','goog')

Of course, it is possible that there are no executions that match the filtering criteria:

>> data = IBMatlab('action','executions', 'symbol','xyz')
data =
[]

12.2 Automated log files

IB-Matlab automatically stores two log files of trade executions. Both files have the same name, and different extensions:

A CSV (comma separated values) text file named <LogFileName>.csv. A separate line is stored for each execution event. This file can be opened in Excel as well as by any text editor.

A MAT (Matlab compressed format) binary file named <LogFileName>.mat that stores the struct array explained in §12.1 above, excluding the sub-structs contract and execution.

The default file name (<LogFileName>) for these files is IB_tradeslog_yyyymmdd, where yyyymmdd is the current date. For example, on 2012-02-15 the log files will be called IB_tradeslog_20120215.csv and IB_tradeslog_20120215.mat. The log file name will remain unchanged until you modify it or restart Matlab.

The log filename can be modified by setting the LogFileName parameter (default = ‘./IB_tradeslog_YYYYMMDD.csv’) when you specify a trade order:

newLogFileName = ['./IB_tradeslog_' datestr(now,'yyyymmdd') '.csv'];
orderId = IBMatlab('Action','Buy', 'LogFileName',newLogFileName, ...);

Note the leading ‘./’ in the default value of LogFileName – you can use any other folder path if you want to store the log files in a different folder than the current Matlab folder. Also note that the new LogFileName should end with ‘.csv’.

Also note that commission information is NOT included in the CSV log file, since it is reported by IB in a separate message (CommissionReport) which is sent after the execution message that is logged in the file. In contrast, the MAT file is updated upon CommissionReport events, so the MAT files does contain commission information.

Another difference between the CSV and MAT log files is that CSV log files only record execution events that started after the CSV log file was started. In contrast, MAT files contain all execution events since IB-Matlab connected to IB, until query time.

warningNote: using log files, which is done by default, can have a significant performance impact in cases of rapid partial executions. For example, if we buy 1000 shares of a security whose normal ask size is 5 shares, then we should expect about 200 separate execution messages when the order is filled. This in turns translates into 200 separate file saves, for each of the two log files (CSV, MAT), and additional save operations in case the CommissionReport events are also received. This could cause MATLAB to appear frozen for quite a long time until all this I/O is done.

To solve the performance issue in cases where the execution logs are not really needed, set the LogFileName parameter to the empty string ('') to prevent logging.

12.3 Using CallbackExecDetails

You can set the CallbackExecDetails parameter to a user-defined Matlab function that will process each execution event at the moment that it is reported. Section §11.2 above contains a working example of such a function.

As noted in §11.1, you only need to set CallbackExecDetails once (this is normally done in the same IBMatlab command that sends the trade order). You do not need to re-specify this callback in subsequent IBMatlab commands, unless you wish to override the parameter with a different function, or to cancel it (in which case you would set it to [] or '').

144 To view executions from previous days, open the Trades Log in TWS and request executions while the Trades Log is displayed

145 http://interactivebrokers.github.io/tws-api/classIBApi_1_1Execution.html