tdameritrade_client package

Submodules

tdameritrade_client.auth module

class tdameritrade_client.auth.TDAuthenticator(host: str, port: int, oauth_user_id: str, token_path: str)

Bases: object

Object for running TDAmeritrade’s OAuth2 flow. An instance of this class is a member of the TDClient class and is meant to be called from the TDClient.

authenticate() → str

Runs the OAUTH flow for the TDA API.

Returns:A string containing the decoded access token to authorize API requests.
refresh_auth_token(refresh_token: str) → Tuple[bool, str]

Request a new access token via a refresh token.

Parameters:refresh_token – A refresh token as a decoded string.
Returns:A bool that is True if auth was successful, and a valid access token.
run_full_flow() → str

Request an access token and a refresh token by authorizing through TDA online. Should be run if the auth-token.json does not exist or if the refresh token fails to authorize a new access token.

Returns:A decoded access token as a string.

tdameritrade_client.client module

class tdameritrade_client.client.TDClient(acct_number: int, oauth_user_id: str, redirect_uri: str, token_path: str = None)

Bases: object

Python client for the TDAmeritrade API.

classmethod from_dict(acct_info: Dict[KT, VT]) → T

Create an instance of this class from a dictionary.

Parameters:acct_info – A dictionary of init parameters
Returns:An instance of this class
get_dated_price_history(symbol: str, start_date: datetime.datetime, end_date: datetime.datetime, need_extended_hours_data: bool = True) → Dict[KT, VT]

Get price history for a symbol by date

Provide a ticker symbol and a start/endDate to receive price history candles given at the the frequency of one candle per minute. Responses are a dict with a “candles” key whose value is a list of objects each containing “open”, “close”, “low”, “high”, “volume”, and “datetime” key-value pairs.

Parameters:
  • symbol – Ticker symbol to search for.
  • start_date – Start date for price history period in UTC.
  • end_date – End date for price history period in UTC.
  • need_extended_hours_data – False to only return regular market hours data. Default: True.
Returns:

Price history for the ticker symbol as set of candles.
Raises:

ValueError – If passed arguments are invalid, or if start_date/end_date range contains no data.
get_hours(markets: str, date: datetime.datetime) → Dict[KT, VT]

Return market hours for a given market.

Parameters:
  • markets – Which market to get hours for
  • date – Which date to retrieve market hours for. Must be in the future.
Returns:

A dict containing market hours for the passed asset class.
get_instrument(symbol: str, projection: str = 'symbol-search')

Return fundamental information for an instrument by ticker, CUSIP, or description.

Parameters:
  • symbol – The search string. Can be a ticker or a regex.
  • projection –

    Type of search to perform. Supports:

    symbol-search: Search by exact ticker or CUSIP.

    symbol-regex: Return all instruments that match a regex.

    desc-regex: Return all instruments whose descriptions contain a regex.
Returns:

A dict of results where keys are tickers and values are objects containing fundamental information.
get_movers(index: str, direction: str, change: str = 'percent') → Dict[KT, VT]

Return top 10 movers (up or down) by percent or value of one of the DOW, NASDAQ, or S&P500 indices.

Parameters:
  • index – The index symbol from which to get movers. Must be one of [‘$COMPX’, ‘$DJIA’, ‘$SPX.X’]
  • direction – Return stocks that are moving ‘up’ or ‘down’
  • change – Return movers as ‘percent’ change or ‘value’ change (default: percent)
Returns:

A dict of list of movers with keys [‘change’, ‘description’, ‘direction’, ‘last’, ‘symbol’, ‘totalVolume’]
get_period_price_history(symbol: str, frequency_type: str, frequency: int, period_type: str = 'day', period: int = None, need_extended_hours_data: bool = True) → Dict[KT, VT]

Get price history for a symbol by period

Provide a ticker symbol, a frequency/frequencyType and a period/periodType to receive price history candles given at the requested frequency and within the requested period/date range. Responses are a dict with a “candles” key whose value is a list of objects each containing “open”, “close”, “low”, “high”, “volume”, and “datetime” key-value pairs.

Parameters:
  • symbol – Ticker symbol to search for.
  • frequency_type – The type of frequency with which a new candle is formed. Must be either ‘minute’, ‘daily’, ‘weekly’, or ‘monthly’.
  • frequency – Frequency with which to return candles.
  • period_type – The type of period-data to return. Must be either ‘day’, ‘month’, ‘year’, or ‘ytd’. Default: ‘day’.
  • period – The length of periodType over which to receive price history.
  • need_extended_hours_data – False to only return regular market hours data. Default: True.
Returns:

Price history for the ticker symbol as set of candles.
Raises:

ValueError – If passed arguments are invalid.
get_positions(positions: bool = True, orders: bool = True) → Dict[KT, VT]

Requests the positions information of self._acct_number

Parameters:
  • positions – Whether to include positions in returned output
  • orders – Whether to include orders in returned output
Returns:

A json object containing the account positions information.
get_quote(symbol: str)

Return quote for a given symbol.

Parameters:symbol – The ticker symbol for a quote.
Returns:A dict of results where keys are tickers and values are objects containing a quote.
get_transactions(start_date: datetime.datetime, end_date: datetime.datetime, symbol: str = None, type: str = None) → Dict[KT, VT]

Return the transactions associated with self._acct_number between start_date and end_date for the given symbol filtered to the given type.

Parameters:
  • start_date – Earliest transactions to return.
  • end_date – Latest transactions to return.
  • symbol – Return transactions of a specific symbol (optional)
  • type – Optional filter on the transactions to return. Must be one of [“ALL”, “TRADE”, “BUY_ONLY”, “SELL_ONLY”, “CASH_IN_OR_CASH_OUT”, “CHECKING”, “DIVIDEND”, “INTEREST”, “OTHER”, “ADVISOR_FEES”]
Returns:

A dict containing the account’s transactions within the passed criteria.
run_auth() → None

Runs the authentication flow. See the TDAuthenticator class for details.

Module contents

python client for the TDA API