Package com.studerw.tda.client

Interface TdaClient

All Known Implementing Classes:
HttpTdaClient
public interface TdaClient
Main interface of the TDA Client. Implementations should be thread safe.
See Also:

  • Method Details

    • priceHistory

      PriceHistory priceHistory(String symbol)

      Retrieve historical intraday and end of day quote data for an equity, index, mutual fund, forex, option chain, etc. See AssetType for possible types, though your account must explicitly have access for some of these. TDA has not implemented all the API calls either (Sep 2019).

      • periodType: day
      • period: 10
      • frequencyType: minute
      • frequency: 1
      Parameters:
      symbol - uppercase symbol
      Returns:
      PriceHistory using all other TDA default request parameters. This appears to be a quote every minute for 10 days.

    • priceHistory

      PriceHistory priceHistory(PriceHistReq priceHistReq)

      Retrieve historical intraday and end of day quote data for an equity, index, mutual fund, forex, option chain, etc. See AssetType for possibly types, though your account must explicitly have access for some of these. TDA has not implemented all the API calls either (Sep 2019). Note that some of the parameters within the PriceHistReq param be null, and then some of the other arguments will be assumed by the non null parameters.

      Parameters:
      priceHistReq - validated object of request parameters
      Returns:
      PriceHistory with a list of Candle Candles based on the frequency and period / date length.

    • fetchQuotes

      List<Quote> fetchQuotes(List<String> symbols)

      Fetch detailed quote information for one or more symbols. Currently the API allows symbol types of Stocks, Options, Mutual Funds Indexes, and ETFs. Quotes are real-time for accounts subscribed to this service; otherwise, quotes are delayed according to exchange and TDA rules. The following types of Quote are actually returned and can be casted: 

        Quote quote = client.fetchQuote("ATD");
  EquityQuote equityQuote = (EquityQuote)quote;
      Parameters:
      symbols - list of valid symbols. Max of 300 based on TDA docs. Index symbols need to be prefixed with a $, e.g. $INX or $SPX.X. Options are in a format like the following: MSFT_061518P60 for a put, or MSFT_061518C60 for a call. This is the Microsoft June 15, 2018 Put/Call at $60.
      Returns:
      list of quotes. The Quote is the base class, but all objects in the list can be cast to their actual types by looking at the AssetType attribute. field.

    • fetchQuote

      Quote fetchQuote(String symbol)

      Fetch Detailed quote information for one or more symbols. Currently the API allows symbol types of Stocks, Options, Mutual Funds and Indexes, and ETFs. Quotes are real-time for accounts subscribed to this service; otherwise, quotes are delayed according to exchange and TDA rules. 

        Quote quote = client.fetchQuote("ATD");
  EquityQuote equityQuote = (EquityQuote)quote;
      Parameters:
      symbol - list of valid symbols. Max of 300 based on TDA docs. Index symbols need to be prefixed with a $, e.g. $INX or $SPX.X. Options are in a format like the following: MSFT_061518P60 for a put, or MSFT_061518C60 for a call. This is the Microsoft June 15, 2018 Put/Call at $60.
      Returns:
      a quote. The Quote is the base class, but all quotes can be cast to their actual types by looking at the com.studerw.tda.model.quote.Quote.assetType field.

    • getAccount

      SecuritiesAccount getAccount(String accountId, boolean positions, boolean orders)
      Fetch an account by the id. By default, balances are included. Positions and Orders can also be included based on the parameters.
      Parameters:
      accountId - the account. Most users only have a single account
      positions - whether to include positions
      orders - whether to include orders
      Returns:
      SecuritiesAccount with the passed id.

    • getMarketHours

      List<Hours> getMarketHours(List<Hours.MarketType> marketTypes, LocalDateTime date)
      Fetch market hours.
      Parameters:
      marketTypes - the market of the hours to return Valid markets are EQUITY, OPTION, FUTURE, BOND, FOREX.
      date - the date of the market hours (default is now)
      Returns:
      Hours

    • getMarketHours

      List<Hours> getMarketHours(List<Hours.MarketType> marketTypes)

    • getAccounts

      List<SecuritiesAccount> getAccounts(boolean positions, boolean orders)
      Fetch all your accounts. By default, balances are included. Positions and Orders can also be included based on the parameters.
      Parameters:
      positions - whether to include positions
      orders - whether to include orders
      Returns:
      List of all the user's SecuritiesAccount.

    • placeOrder

      void placeOrder(String accountId, Order order)
      Place an Order.
      Parameters:
      accountId - the account under which the order is to be placed
      order - the order to place
      See Also:

    • placeOrderReturnId

      Optional<Long> placeOrderReturnId(String accountId, Order order)
      Place an Order and return the order ID. According to TDA docs, this order ID can be obtained from the response within a location header. Users need to check the response code as it is wrapped in a Optional.

      Note the documentation on the official TDA site is not all that clear on what kinds of orders and in which cases the order ID will and will not be returned.

      For example, if the TDA system is overloaded, the order may be queued and the ID cannot yet be known by the time the call must return (it is synchronous). Users are then required to poll for the new order using fetchOrders() or similar.

      In order to deal with this case without throwing an exception we return the ID wrapped in a Optional. We do this instead of throwing an exception to differentiate between an order that likely failed and one that will eventually be placed but didn't have the order ID at the time of return. Users need check the Optional themselves and handle accordingly.

      Parameters:
      accountId - the account under which the order is to be placed
      order - the order to place
      Returns:
      the order ID wrapped in an Optional which will be empty if the order ID was not returned by TDA, but the call otherwise returned a successful response. It's likely the order will eventually be placed, and users will need to poll for that ordeer ID using existing methods.
      See Also:

    • fetchOrders

      List<Order> fetchOrders(String accountId, OrderRequest orderRequest)

      Fetch all orders for a given account using the criteria of the orderRequest. You can just use a blank order to use sane defaults. 

         Order order = client.fetchOrders("123456789", new OrderRequest());
      Parameters:
      accountId - the orders from only this account
      orderRequest - the request.
      Returns:
      list of orders specified by the OrderRequest param.

    • fetchOrders

      List<Order> fetchOrders(OrderRequest orderRequest)

      Fetch all orders for all accounts using the criteria of the orderRequest. You can use a blank order to use sane defaults. 

         Order order = client.fetchOrders(new OrderRequest());
      Parameters:
      orderRequest - the request.
      Returns:
      list of orders specified by the OrderRequest param.

    • fetchOrders

      List<Order> fetchOrders()
      Fetch all orders for all accounts using TDA defaults.
      Returns:
      list of orders for all accounts, using TDA default criteria.

    • fetchOrder

      Order fetchOrder(String accountId, Long orderId)
      This call assumes the order under the given parameters definitely exists. If not, a RuntimeException is thrown as, behind the scenes, the TDA API will return a 404 response.
      Parameters:
      accountId - account under which the order was originally placed
      orderId - the id of the order
      Returns:
      Order or a RuntimeException if it doesn't exist.

    • cancelOrder

      void cancelOrder(String accountId, String orderId)
      Cancel an order by account Id and order Id.
      Parameters:
      accountId - the account under which this order was placed
      orderId - the order to cancel

    • getInstrumentByCUSIP

      Instrument getInstrumentByCUSIP(String cusip)
      Get basic data for an instrument via its CUSIP number. Data includes attributes such as description, possible symbol, exchange, etc.

      Apparently the following instrument types are able to be looked up: Instrument.AssetType.

      Parameters:
      cusip - (committee on uniform securities identification procedures numbers).
      Returns:
      Basic data using a security's CUSIP. The Instrument.getBondPrice() will return null unless the cusip parameter references a bond.
      See Also:

    • getBond

      Instrument getBond(String cusip)
      Get basic info for a bond via its CUSIP number.
      Parameters:
      cusip - (committee on uniform securities identification procedures numbers).
      Returns:
      Basic data of the bond including the price.
      See Also:

    • queryInstruments

      List<Instrument> queryInstruments(Query query)

      Query TDA for Instruments using symbol, name, description, cusip, etc. Apparently the following instrument types are queryable: Instrument.AssetType.

      The following QueryTypes can be made:

      • SYMBOL_SEARCH: retrieve an instrument using the exact symbol name or CUSIP
      • SYMBOL_REGEX: Retrieve instrument data for all symbols matching regex. For example XYZ.* will return all symbols beginning with XYZ
      • DESCRIPTION_SEARCH: Retrieve instrument data for instruments whose description contains the word supplied. Example: Bank will return all instruments with Bank in the description.
      • DESCRIPTION_REGEX: Search description with full regex support. For example XYZ.[A-C] returns all instruments whose descriptions contain a word beginning with XYZ followed by a character A through C.
      Parameters:
      query - contains the type of query and the search string.
      Returns:
      List of 0 or more instruments that matched the query. If you want the full data of an instrument, you must use getFundamentalData(java.lang.String) using the exact CUSIP or symbol. Note that Instrument.getBondPrice() will return null for any instruments not of type BOND.
      See Also:

    • getFundamentalData

      FullInstrument getFundamentalData(String id)
      Get full fundamental data for a specific security via its CUSIP number or ticker symbol (e.g. MSFT). Not all CUSIP numbers work, for example those referencing BONDs, at least as of Nov. 2019.
      Parameters:
      id - CUSIP number or symbol (e.g. MSFT)
      Returns:
      full fundamentals of an instrument using a CUSIP or symbol. The Instrument.getBondPrice() will be empty unless it is a bond referenced by cusip.
      See Also:

    • fetchMovers

      List<Mover> fetchMovers(MoversReq moversReq)
      Note that this call can return an empty list on days the market is closed. Top 10 (up or down) movers by value or percent for a particular market
      Parameters:
      moversReq - Index must be set, the other fields can be null which will use TDA defaults.
      Returns:
      List of top 10 market movers defined by the request.

    • getOptionChain

      OptionChain getOptionChain(String symbol)
      Parameters:
      symbol - - should be upper case (e.g. MSFT)
      Returns:
      an option chain using all TDA Default parameters

    • getOptionChain

      OptionChain getOptionChain(OptionChainReq request)
      Parameters:
      request - - should be upper case (e.g. MSFT)
      Returns:
      an option chain using all TDA Default parameters

    • fetchTransactions

      List<Transaction> fetchTransactions(String accountId)
      Parameters:
      accountId - the account under which these transactions occurred
      Returns:
      list of all transactions

    • fetchTransactions

      List<Transaction> fetchTransactions(String accountId, TransactionRequest request)
      Parameters:
      accountId - the account under which these transactions occurred
      request - transaction request which may be empty or using one or more parameters. If you add a startDate then you do need an endDate and vice versa.
      Returns:
      list of all transactions

    • getTransaction

      Transaction getTransaction(String accountId, Long transactionId)
      Parameters:
      accountId - the account under which this transactions occurred
      transactionId - transaction id
      Returns:
      single transaction

    • getPreferences

      Preferences getPreferences(String accountId)
      Get preferences for a specific account
      Parameters:
      accountId - user's account id
      Returns:
      user's preferences

    • getUserPrincipals

      UserPrincipals getUserPrincipals(UserPrincipals.Field... fields)
      Parameters:
      fields - zero or more additonal UserPrincipals.Field fields to return.
      Returns:
      user principals