req_contract_details: Request Contract Details

In JakeVestal/InteractiveTradeR: API

Request Contract Details

Description

Fetch a wealth of information about contracts at Interactive Brokers that are found to match parameters supplied in the contract argument.

Usage

req_contract_details(contract = NULL, channel = NULL)

Arguments

contract

Named character vector of contract parameter(s). The name of each element identifies the parameter – for example, secType, symbol, exchange... – and each element itself gives the set value (e.g., "STK", "IBM", "SMART"). The 'contract' parameters that may be used with req_contract_details() are: secId, tradingClass, primaryExchange, conId, symbol, secType, lastTradeDateOrContractMonth, strike, right, multiplier, exchange, currency, localSymbol, includeExpired, secIdType See contract for detailed information on all contract parameters.

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

Details

IB's documentation describes each column variable that can appear in the output of InteractiveTradeR's implementation of req_contract_details() in the ContractDetails Members section. A list of the contract parameters that may be passed in via the contract object can be found in IB's Contract Class Reference.

Pacing and Large Queries: req_contract_details() is able to send queries that involve the transfer of high amounts of data in cases where many contracts are found to match the selection criteria. As a consequence, Interactive Brokers may pace requests made by this function by placing similar or identical requests on hold for one minute, with the amount of time increasing each time subsequent similar/identical requests are made.

The exact criteria regarding what constitutes a "similar" request, and the rules governing pacing behavior, are not published. However, by following three general rules of thumb, pacing should not be a problem when using req_contract_details() in InteractiveTradeR:

• In SYNC mode ( channel = NULL) , bump up the timeout parameter for large queries with sync_timeout(). If a large number of contracts are found to match the parameters in contract, then the function might return an error if called with the default timeout because it needs bit more time than the default 5 seconds in order to complete. Try using sync_timeout(10) or sync_timeout(15).

• Using conId Only: If the object passed in as contract has length = 1, then req_contract_details() will assume that contract contains a conId, which is sufficient to specify a unique contract. This shortcut can help speed up usage.

See Also

Other asset info: req_matching_symbols(), req_sec_def_opt_params()

Examples

#### Example: supplying more parameters gives more specific results.
#### Goal: We would like to retrieve the contract details of IBM common stock,
####       which, at IB, happens to have conId = 8314.

# The fastest and simplest way to get IBM's contract details is by conId only:
contract_details <- req_contract_details(8314)
contract_details

# You can select, manipulate, and view the fetched details:
contract_details$exchange_info # View the exchange info
contract_details$orderTypes    # See what order types are available
contract_details$conId         # Check the conId

# ... and so on.

# You can also use glimpse() to print the information in what may be an
# easier-to-read format:
dplyr::glimpse(contract_details)

# But what if you didn't already know IBM's conId?

# 2) You could try to get IBM's contract details by symbol only, but because
# there are many securities across many exchanges that have the symbol "IBM"
# this query won't work -- IB responds by asking for more info.
contract_details_1 <- req_contract_details(contract = c(symbol = "IBM"))

# 3) So, try providing a valid security type:
contract_details_2 <- req_contract_details(
  contract = c(symbol = "IBM", secType  = "STK")
)
contract_details_2

# This call will work, but returns ALL of the contracts whose symbol is "IBM".
# Only one of these is the contract of interest, so this doesn't help much.

# 4) Narrow things down by specifying a currency:
contract_details_3 <- req_contract_details(
  contract = c(
    symbol   = "IBM",
    secType  = "STK",
    currency = "USD"
  )
)
contract_details_3

# This helped somewhat, but still have a large number of matching contracts.

# 5) Specify an exchange:
contract_details_4 <- req_contract_details(
  contract = c(
    symbol   = "IBM",
    secType  = "STK",
    currency = "USD",
    exchange = "SMART"
  )
)
contract_details_4

# Success! For IBM, these four exchanges are enough to specify the contract.

# Bond details return slightly different parameters. See the "ContractDetails"
# documentation on IB's website at the link provided in the "Value" section.
broadcom_bond <- req_contract_details(359401413)
broadcom_bond

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