This function will either initiate an ongoing subscription for account
summary data (if a persistant ASYNC socket is passed as input to
channel), or quickly fetch the data on a socket that is opened for that
purpose and then closed (if no value is passed as input to channel).
All data retrieved by this function is stored in the ACCOUNT_SUMARY
object accessible in the treasury. The accounts to be included in the
output are specified by the groupName parameter. The user may choose to
include any/all of a selection of account values by passing appropriate
values as tags.
req_account_summary( groupName = "All", tags = "All", channel = NULL, return_data = is.null(channel) )
| groupName | Character vector of length 1 containing the name of an existing group of accounts. Default value is "All". Descriptions of each parameter can be found on IB's accountSummary Tags page. |
|---|---|
| tags | A character vector containing any or all of the following allowed tags (Default is all tags): AccountType, AccruedCash, AvailableFunds, BuyingPower, Cushion, DayTradesRemaining, EquityWithLoanValue, ExcessLiquidity, FullAvailableFunds, FullExcessLiquidity, FullInitMarginReq, FullMaintMarginReq, GrossPositionValue, HighestSeverity, InitMarginReq, Leverage, LookAheadAvailableFunds, LookAheadExcessLiquidity, LookAheadInitMarginReq, LookAheadMaintMarginReq, LookAheadNextChange, MaintMarginReq, NetLiquidation, PreviousEquityWithLoanValue, ReqTEquity, ReqTMargin, SettledCash, SMA, TotalCashValue You may also make use of the |
| channel | One of the following:
|
| return_data | Boolean of length 1. Defaults to TRUE unless argument channel is
specified. If FALSE, data retrieved by the function will be returned as the
funciton's output. If TRUE, then a Boolean succeses flag will be returned as
the function's output indicating the success (TRUE) or failure (FALSE) of the
function's attempt to transceive data to/from IB. Data in the
|
This function is called for its side effect of updating the
treasury, which takes place every time the function executes.
Additionally, the function's return value depends upon the value passed in as
return_data as follows:
If return_data == FALSE: A Boolean success flag,
returned invisibly, indicating that the function executed correctly and
updated the treasury with any new data retrieved.
If return_data == TRUE: Any new data retrieved will
be returned in a tibble in addition to being added to the
treasury. If no new data is available, returns NULL.
return_data defaults to TRUE unless channel is specified.
Groups: Interactive Brokers' instructions for creating account groups can be in the Creating Account Groups section of IB's TWS webinar notes. Any group create in TWS can be input as groupName.
"$LEDGER" tags: If you hold assets in your various accounts
that are denominated in different currencies, you can use the use the tag
"$LEDGER:<currency>" to summarize holdings by currency. Here,
<currency> is a three-letter currency abbreviation, e.g.,
"$LEDGER:USD", "$LEDGER:GBP", "$LEDGER:CHF", etc.
Use the tag "$LEDGER", with no currency specified, to get
summary data in only the currency you have set as your BASE currency in
Account Management.
Use "$LEDGER:ALL" tag to get summary data for all currencies.
Max of 50 subaccounts for groupName = "All": If there are
more than 50 subaccounts accessible to a particular user, then the tag "All"
may not be used for groupName.
When a subscription is created by calling
req_account_summary() on a socket, the server immediately responds
by providing values for the requested tags for all of the requested
accounts, and the ACCOUNTS object is immediately updated in the treasury.
Thereafter, IB will send updated account summary data to the socket,
including only the tags whose values have changed since the last
request was made. IB will continue to update the socket until either the
socket is closed (i.e., with disconnect(), or the subscription is
cancelled by cancel_account_summary()).
The "3-minute" update rule: IB's documentation states that
after the initial call to req_account_summary(), those account tags
whose values have changed will be updated every three (3) minutes. However,
during market hours, you may observe much shorter, more frequent update
intervals. You can explore your observed update frequency by experimenting
with the "Update Behavior" example in the "Examples" section below.
Only two (2) active summary subscriptions are allowed at a
time: In practice, only subscription at a time should be needed if the API
is well designed. If you do have two live subscriptions to
req_account_summary(), InteractiveTradeR will not allow you to
create another one until one of the two existing subscriptions is
cancel_account_summarycancelled. This rule differs from IB's
standard API, in which one of the existing subscriptions is overwritten
with the new one. The reason for the change is to make it difficult for
user to overwrite a subscription unintentionally.
Adjusting req_account_summary() Subscriptions:
Calling req_account_summary() with a groupName that is
identical to that of one of the two possible existing live subscriptions to
req_account_summary() will overwrite the existing subscription with
the new one. This can be used to change subscribed tags.
req_account_summary() updates the ACCOUNTS object in the
treasury. ACCOUNTS is a tibble in which each row represents a
parameter pertaining to a particular account. Has the following columns:
account <chr>: Account ID (e.g., "DF1234567")
tag <chr>: Name of account tag (e.g., "BuyingPower")
tag_value <chr>: Value of tag (e.g., "500000")
currency <chr>: 3-letter currency abbreviation if
tag_value is a monetary amount, "" otherwise.
Other treasury:
cancel_account_summary(),
cancel_account_updates_multi(),
req_account_updates_multi(),
req_account_updates()
# Fetch ACCOUNTS for all tags and groupName = "All", without creating # a subscription. req_account_summary()#> # A tibble: 137 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 AccountType INDIVIDUAL "" #> 2 DF1267859 Cushion 1 "" #> 3 DF1267859 LookAheadNextChange 0 "" #> 4 DF1267859 AccruedCash 0.00 "USD" #> 5 DF1267859 AvailableFunds 0.00 "USD" #> 6 DF1267859 BuyingPower 0.00 "USD" #> 7 DF1267859 EquityWithLoanValue 0.00 "USD" #> 8 DF1267859 ExcessLiquidity 0.00 "USD" #> 9 DF1267859 FullAvailableFunds 0.00 "USD" #> 10 DF1267859 FullExcessLiquidity 0.00 "USD" #> # … with 127 more rows# View the updated ACCOUNTS object in the treasury treasury$ACCOUNTS#> # A tibble: 209 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 AccountType INDIVIDUAL "" #> 2 DF1267859 Cushion 1 "" #> 3 DF1267859 LookAheadNextChange 0 "" #> 4 DF1267859 AccruedCash 0.00 "USD" #> 5 DF1267859 AvailableFunds 0.00 "USD" #> 6 DF1267859 BuyingPower 0.00 "USD" #> 7 DF1267859 EquityWithLoanValue 0.00 "USD" #> 8 DF1267859 ExcessLiquidity 0.00 "USD" #> 9 DF1267859 FullAvailableFunds 0.00 "USD" #> 10 DF1267859 FullExcessLiquidity 0.00 "USD" #> # … with 199 more rows# Reset the ACCOUNTS object when you're ready treasury$ACCOUNTS <- NULL # Fetch just the TotalCashValue, BuyingPower, and GrossPositionValue for # groupName = "All", again without creating a subscription req_account_summary( tags = c("TotalCashValue", "BuyingPower", "GrossPositionValue") )#> # A tibble: 18 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 BuyingPower 0.00 USD #> 2 DF1267859 GrossPositionValue 0.00 USD #> 3 DF1267859 TotalCashValue 0.00 USD #> 4 DU1267860 BuyingPower 4074096.59 USD #> 5 DU1267860 GrossPositionValue 4559.26 USD #> 6 DU1267860 TotalCashValue 1014815.02 USD #> 7 DU1267861 BuyingPower 3801322.86 USD #> 8 DU1267861 GrossPositionValue 177852.71 USD #> 9 DU1267861 TotalCashValue 818303.31 USD #> 10 DU1267862 BuyingPower 4077227.21 USD #> 11 DU1267862 GrossPositionValue 1787.35 USD #> 12 DU1267862 TotalCashValue 1021574.85 USD #> 13 DU1267863 BuyingPower 4082946.57 USD #> 14 DU1267863 GrossPositionValue 471.15 USD #> 15 DU1267863 TotalCashValue 1020092.16 USD #> 16 DU1267864 BuyingPower 4077959.53 USD #> 17 DU1267864 GrossPositionValue 31122.04 USD #> 18 DU1267864 TotalCashValue 997367.27 USD# See that the data is stored in the treasury: treasury$ACCOUNTS#> # A tibble: 18 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 BuyingPower 0.00 USD #> 2 DF1267859 GrossPositionValue 0.00 USD #> 3 DF1267859 TotalCashValue 0.00 USD #> 4 DU1267860 BuyingPower 4074096.59 USD #> 5 DU1267860 GrossPositionValue 4559.26 USD #> 6 DU1267860 TotalCashValue 1014815.02 USD #> 7 DU1267861 BuyingPower 3801322.86 USD #> 8 DU1267861 GrossPositionValue 177852.71 USD #> 9 DU1267861 TotalCashValue 818303.31 USD #> 10 DU1267862 BuyingPower 4077227.21 USD #> 11 DU1267862 GrossPositionValue 1787.35 USD #> 12 DU1267862 TotalCashValue 1021574.85 USD #> 13 DU1267863 BuyingPower 4082946.57 USD #> 14 DU1267863 GrossPositionValue 471.15 USD #> 15 DU1267863 TotalCashValue 1020092.16 USD #> 16 DU1267864 BuyingPower 4077959.53 USD #> 17 DU1267864 GrossPositionValue 31122.04 USD #> 18 DU1267864 TotalCashValue 997367.27 USD# As above, using some example $LEDGER tags: treasury$ACCOUNTS <- NULL req_account_summary(tags = c("TotalCashValue", "BuyingPower", "$LEDGER"))#> # A tibble: 156 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 BuyingPower 0.00 USD #> 2 DF1267859 TotalCashValue 0.00 USD #> 3 DF1267859 Currency BASE BASE #> 4 DF1267859 CashBalance 0.00 BASE #> 5 DF1267859 TotalCashBalance 0.00 BASE #> 6 DF1267859 AccruedCash 0.00 BASE #> 7 DF1267859 StockMarketValue 0.00 BASE #> 8 DF1267859 OptionMarketValue 0.00 BASE #> 9 DF1267859 FutureOptionValue 0.00 BASE #> 10 DF1267859 FuturesPNL 0.00 BASE #> # … with 146 more rowstreasury$ACCOUNTS#> # A tibble: 156 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 BuyingPower 0.00 USD #> 2 DF1267859 TotalCashValue 0.00 USD #> 3 DF1267859 Currency BASE BASE #> 4 DF1267859 CashBalance 0.00 BASE #> 5 DF1267859 TotalCashBalance 0.00 BASE #> 6 DF1267859 AccruedCash 0.00 BASE #> 7 DF1267859 StockMarketValue 0.00 BASE #> 8 DF1267859 OptionMarketValue 0.00 BASE #> 9 DF1267859 FutureOptionValue 0.00 BASE #> 10 DF1267859 FuturesPNL 0.00 BASE #> # … with 146 more rowstreasury$ACCOUNTS <- NULL req_account_summary(tags = c("TotalCashValue", "BuyingPower", "$LEDGER:ALL"))#> # A tibble: 84 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 BuyingPower 0.00 USD #> 2 DF1267859 TotalCashValue 0.00 USD #> 3 DU1267860 BuyingPower 4074096.59 USD #> 4 DU1267860 TotalCashValue 1014815.02 USD #> 5 DU1267861 BuyingPower 3801322.86 USD #> 6 DU1267861 TotalCashValue 818303.31 USD #> 7 DU1267862 BuyingPower 4077227.21 USD #> 8 DU1267862 TotalCashValue 1021574.85 USD #> 9 DU1267863 BuyingPower 4082946.57 USD #> 10 DU1267863 TotalCashValue 1020092.16 USD #> # … with 74 more rowstreasury$ACCOUNTS#> # A tibble: 84 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 BuyingPower 0.00 USD #> 2 DF1267859 TotalCashValue 0.00 USD #> 3 DU1267860 BuyingPower 4074096.59 USD #> 4 DU1267860 TotalCashValue 1014815.02 USD #> 5 DU1267861 BuyingPower 3801322.86 USD #> 6 DU1267861 TotalCashValue 818303.31 USD #> 7 DU1267862 BuyingPower 4077227.21 USD #> 8 DU1267862 TotalCashValue 1021574.85 USD #> 9 DU1267863 BuyingPower 4082946.57 USD #> 10 DU1267863 TotalCashValue 1020092.16 USD #> # … with 74 more rows################################################################################ #### Update Behavior Example: Async Mode ####################################### ################################################################################ #### This example involves setting up account summary subscriptions. Make sure #### that you actually have positions whose values are changing; i.e., #### accounts aren't empty, the market is currently open, etc. ## Open up a socket connection (unless you have one open already): create_new_connections(1) # Start an account summary subscription for the default group ("All") using # all of the possible tags: req_account_summary(channel = "async") # Within three minutes of starting the subscription, take a look at the # ACCOUNTS object in the treasury: treasury$ACCOUNTS#> # A tibble: 209 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DF1267859 AccountType INDIVIDUAL "" #> 2 DF1267859 Cushion 1 "" #> 3 DF1267859 LookAheadNextChange 0 "" #> 4 DF1267859 AccruedCash 0.00 "USD" #> 5 DF1267859 AvailableFunds 0.00 "USD" #> 6 DF1267859 BuyingPower 0.00 "USD" #> 7 DF1267859 EquityWithLoanValue 0.00 "USD" #> 8 DF1267859 ExcessLiquidity 0.00 "USD" #> 9 DF1267859 FullAvailableFunds 0.00 "USD" #> 10 DF1267859 FullExcessLiquidity 0.00 "USD" #> # … with 199 more rows# See when it was last updated: acc_sum_update_time <- attr(treasury$ACCOUNTS, "last_updated") acc_sum_update_time#> [1] "2020-03-17 13:12:05 EDT"# Soon after creating the subscription, try to update the ACCOUNTS # object in the treasury by calling read_sock_drawer(): read_sock_drawer() # If you're quick enough, you won't get any updated information because IB has # not sent updated data to the socket. # So, wait a while. For example's sake, let's wait a little over 3 minutes: Sys.sleep(200) # Keep calling... read_sock_drawer() # ...a few times, waiting 10 or 20 seconds in between calls. After 3 minutes # have passed -- and probably before that -- you should see the # ACCOUNTS object update. # After updating, take a look in your treasury... treasury$ACCOUNTS#> # A tibble: 209 x 4 #> account tag tag_value currency #> * <chr> <chr> <chr> <chr> #> 1 DU1267861 Cushion 0.955264 "" #> 2 DU1267861 EquityWithLoanValue 994908.81 "USD" #> 3 DU1267861 NetLiquidation 994947.04 "USD" #> 4 DU1267861 TotalCashValue 818302.86 "USD" #> 5 DU1267861 BuyingPower 3800497.54 "USD" #> 6 DU1267861 GrossPositionValue 177608.71 "USD" #> 7 DU1267861 InitMarginReq 44784.43 "USD" #> 8 DU1267861 MaintMarginReq 44510.34 "USD" #> 9 DU1267861 AvailableFunds 950124.39 "USD" #> 10 DU1267861 ExcessLiquidity 950436.70 "USD" #> # … with 199 more rows# ...and compare your old ACCOUNTS update time -- stored in the variable # "acct_sum_update_time" -- with your newly updated ACCOUNTS: acc_sum_update_time#> [1] "2020-03-17 13:12:05 EDT"#> [1] "2020-03-17 13:15:25 EDT"# You can also take a look at the "account_summary" element of your # subscriptions object: subscriptions$account_summary#> # A tibble: 1 x 5 #> req_name tags req_id conn_row client_id #> <chr> <chr> <dbl> <dbl> <int> #> 1 All AccountType, NetLiquidation, TotalCashValu… 9 4 1subscriptions$account_summary$tags#> [1] "AccountType, NetLiquidation, TotalCashValue, SettledCash, AccruedCash, BuyingPower, EquityWithLoanValue, PreviousEquityWithLoanValue, GrossPositionValue, ReqTEquity, ReqTMargin, SMA, InitMarginReq, MaintMarginReq, AvailableFunds, ExcessLiquidity, Cushion, FullInitMarginReq, FullMaintMarginReq, FullAvailableFunds, FullExcessLiquidity, LookAheadNextChange, LookAheadInitMarginReq, LookAheadMaintMarginReq, LookAheadAvailableFunds, LookAheadExcessLiquidity, HighestSeverity, DayTradesRemaining, Leverage"#> Observations: 1 #> Variables: 5 #> $ req_name <chr> "All" #> $ tags <chr> "AccountType, NetLiquidation, TotalCashValue, SettledCash, … #> $ req_id <dbl> 9 #> $ conn_row <dbl> 4 #> $ client_id <int> 1# Finally, cancel the subscription. In this case, we want to cancel the one # subscribed to the groupName "All". cancel_account_summary("All") # The subscription no longer appears in the subscription object: subscriptions$account_summary#> NULL# From this point in time onward (until you create another subscription and/or # unless there is an update on the socket left over from before you cancelled # the subscription in this example), the account summary will no longer update # no matter how many times you call read_sock_drawer()