req_account_summary: Request Account Summary
In JakeVestal/InteractiveTradeR: API

req_account_summary

R Documentation

Request Account Summary

Description

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.

Usage

req_account_summary(
  groupName = "All",
  tags = "All",
  channel = NULL,
  return_data = is.null(channel)
)

Arguments

`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 `$LEDGER` tag to receive summary data in different currencies. See Details.
`channel`	One of the following: Not Specified (Default): Opens a new connection to IB, uses it to issue the request and retrieve the response, and closes connection behind itself upon completion. The Name of a Sock: Character vector, length 1. The name of an open, connected socket in the sock_drawer; e.g., "master", "tws", or "sock_123" Numeric Client ID: Numeric, length 1. The client ID for which open orders are to be retrieved; e.g., 0, 874, 123. If a client ID is passed, and no socket in the sock_drawer is connected on that ID, then a new socket will be opened on that ID, and closed upon function exit. A `sockconn` Connection: An open connection object of class "sockconn", connected to the IB API; e.g., `sock_drawer$tws`
`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 `treasury` is always updated regardless of the value passed as return_data in the function call.

Details

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.

Value

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.

Behavior

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.

ACCOUNTS Treasury Object

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.

Examples

# Fetch ACCOUNTS for all tags and groupName = "All", without creating
# a subscription.

req_account_summary()

# View the updated ACCOUNTS object in the treasury
treasury$ACCOUNTS

# 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")
)

# See that the data is stored in the treasury:
treasury$ACCOUNTS

# As above, using some example $LEDGER tags:
treasury$ACCOUNTS <- NULL
req_account_summary(tags = c("TotalCashValue", "BuyingPower", "$LEDGER"))
treasury$ACCOUNTS

treasury$ACCOUNTS <- NULL
req_account_summary(tags = c("TotalCashValue", "BuyingPower", "$LEDGER:ALL"))
treasury$ACCOUNTS

################################################################################
#### 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
# See when it was last updated:
acc_sum_update_time <- attr(treasury$ACCOUNTS, "last_updated")
acc_sum_update_time

# 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

# ...and compare your old ACCOUNTS update time -- stored in the variable
# "acct_sum_update_time" -- with your newly updated ACCOUNTS:
acc_sum_update_time
attr(treasury$ACCOUNTS, "last_updated")

# You can also take a look at the "account_summary" element of your 
# subscriptions object:
subscriptions$account_summary
subscriptions$account_summary$tags
dplyr::glimpse(subscriptions$account_summary)

# 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

# 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()

JakeVestal/InteractiveTradeR documentation built on June 5, 2024, 2:21 p.m.