Client¶
All communication with the Robinhood servers is done through the
RobinhoodClient
.
-
class
RobinhoodClient
(timeout, session=None, session_file='.aiorobinhood.pickle')¶ An HTTP client for interacting with Robinhood.
By default, the device token is saved to the session_file in order to avoid re-triggering the SFA challenge flow upon every
login()
. With MFA, a passcode will need to be manually supplied every time.The access and refresh tokens for a particular session can be saved and reloaded to the same file using the
dump()
andload()
methods, respectively.- Parameters
timeout (
int
) – The request timeout, in seconds.session (
Optional
[ClientSession
]) – An open client session to inject, if possible.session_file (
str
) – A path to a binary file for saving session variables.
All RobinhoodClient
request methods call the request()
helper
method below. This method can also be used to craft custom API requests that are not
encapsulated by RobinhoodClient
API methods.
-
async
RobinhoodClient.
request
(method, url, json=None, headers=None, success_code=200)¶ Make a custom request to the Robinhood API servers.
- Parameters
- Return type
- Returns
The JSON response from the Robinhood API servers.
- Raises
ClientAPIError – Robinhood servers responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – The url does not originate from the Robinhood API servers.
Authentication¶
-
async
RobinhoodClient.
login
(username, password, expires_in=86400, challenge_type=<ChallengeType.SMS: 'sms'>, **kwargs)¶ Authenticate the user (for both SFA and MFA accounts).
- Parameters
username (
str
) – The account username.password (
str
) – The account password.expires_in (
int
) – The session duration, in seconds.challenge_type (
ChallengeType
) – The challenge type (SFA only).
- Raises
ClientAPIError – Robinhood servers responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
-
async
RobinhoodClient.
logout
()¶ Invalidate the current session tokens.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
-
async
RobinhoodClient.
refresh
(expires_in=86400)¶ Fetch a fresh set session tokens.
- Parameters
expires_in (
int
) – The session duration, in seconds.- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
-
async
RobinhoodClient.
dump
()¶ Write the session tokens to the session file.
- Raises
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.- Return type
None
-
async
RobinhoodClient.
load
()¶ Read the session tokens from the session file.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
Profile¶
-
async
RobinhoodClient.
get_account
()¶ Fetch information associated with the Robinhood account.
- Return type
- Returns
The account information.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
get_portfolio
()¶ Fetch the portfolio information associated with the Robinhood account.
- Return type
- Returns
The account’s portfolio characteristics including equity value, margin, and withdrawable amount.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
get_historical_portfolio
(interval, span, extended_hours=False)¶ Fetch the historical value of the account portfolio.
- Parameters
interval (
HistoricalInterval
) – The granularity of the historical data.span (
HistoricalSpan
) – The period of the historical data.extended_hours (
bool
) – Include data from extended trading hours.
- Return type
- Returns
Historical equity values of the account portfolio over the given interval and span.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
Warning
Certain combinations of
interval
andspan
will be rejected by Robinhood.
Account¶
-
async
RobinhoodClient.
get_positions
(nonzero=True, pages=None)¶ Fetch all the positions held by the account.
- Parameters
- Return type
- Returns
Position data for each holding, including quantity of shares held and average buy price.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
get_watchlist
(watchlist='Default', pages=None)¶ Fetch the securities in a given watchlist.
- Parameters
- Return type
- Returns
A list of instrument URLs in the watchlist.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
add_to_watchlist
(instrument, watchlist='Default')¶ Add a security to the given watchlist.
- Parameters
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
-
async
RobinhoodClient.
remove_from_watchlist
(id_, watchlist='Default')¶ Remove a security from the given watchlist.
- Parameters
id – The instrument ID.
watchlist (
str
) – The name of the watchlist.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
Stocks¶
-
async
RobinhoodClient.
get_fundamentals
(symbols=None, instruments=None)¶ Fetch the fundamental information pertaining to a list of securities.
- Parameters
- Return type
- Returns
Fundamental data for each security, including most recent OHLC prices, market capitalization, P/E and P/B ratios, etc.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – Both/neither of
symbols
andinstruments
are supplied.
-
async
RobinhoodClient.
get_instruments
(symbol=None, ids=None, pages=None)¶ Fetch the instrument information pertaining to a list of securities.
- Parameters
- Return type
- Returns
Instrument data for each security, including ID and various URLs for fetching particular information.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – Both/neither of
symbol
andids
are supplied.
-
async
RobinhoodClient.
get_quotes
(symbols=None, instruments=None)¶ Fetch the quote information pertaining to a list of securities.
- Parameters
- Return type
- Returns
Quote data for each security, including ask/bid pricing data (both during regular and extended trading hours).
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – Both/neither of
symbols
andinstruments
are supplied.
-
async
RobinhoodClient.
get_historical_quotes
(interval, span, extended_hours=False, symbols=None, instruments=None)¶ Fetch historical quote information pertaining to a list of securities.
- Parameters
interval (
HistoricalInterval
) – The granularity of the historical data.span (
HistoricalSpan
) – The period of the historical data.extended_hours (
bool
) – Include data from extended trading hours.symbols (
Optional
[Iterable
[str
]]) – A sequence of stock symbols.instruments (
Optional
[Iterable
[str
]]) – A sequence of instrument URLs.
- Return type
- Returns
Historical quote data for each security, including OHLC pricing data at every interval in the given span.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – Both/neither of
symbols
andinstruments
are supplied.
Warning
Certain combinations of
interval
andspan
will be rejected by Robinhood.
Fetch the tags for a particular security.
- Parameters
id – An instrument ID.
- Return type
- Returns
A list of Robinhood tags for the given security.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
get_tag_members
(tag)¶ Fetch the instruments belonging to a particular tag.
- Parameters
tag (
str
) – The tag name.- Return type
- Returns
A list of instruments that match the given tag.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
Orders¶
-
async
RobinhoodClient.
get_orders
(order_id=None, pages=None)¶ Fetch historical order information.
- Parameters
- Return type
- Returns
Order information for a particular order ID, or every order placed on the Robinhood account. Order information includes the price, type, and status of the order.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
cancel_order
(order_id)¶ Cancel an order.
- Parameters
order_id (
str
) – The ID of a particular order.- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
- Return type
None
Placing Orders¶
Warning
Robinhood rate limits the /orders
endpoint used by the following methods.
All RobinhoodClient
order methods call the place_order()
helper
method below. This method can also be used to craft custom order requests that are not
encapsulated by RobinhoodClient
order API methods.
-
async
RobinhoodClient.
place_order
(**kwargs)¶ Place a custom order.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
place_limit_buy_order
(symbol, price, quantity, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a limit buy order.
- Parameters
symbol (
str
) – A stock symbol.quantity (
int
) – The quantity of shares to buy.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
place_limit_sell_order
(symbol, price, quantity, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a limit sell order.
- Parameters
symbol (
str
) – A stock symbol.quantity (
int
) – The quantity of shares to sell.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
place_market_buy_order
(symbol, amount=None, quantity=None, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a market buy order by quantity of shares or dollar amount.
- Parameters
symbol (
str
) – A stock symbol.amount (
Union
[int
,float
,None
]) – The amount to buy, in dollars.quantity (
Union
[int
,float
,None
]) – The quantity of shares to buy.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – Both/neither of
amount
andquantity
are supplied.
-
async
RobinhoodClient.
place_market_sell_order
(symbol, amount=None, quantity=None, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a market sell order by quantity of shares or dollar amount.
- Parameters
symbol (
str
) – A stock symbol.amount (
Union
[int
,float
,None
]) – The amount to sell, in dollars.quantity (
Union
[int
,float
,None
]) – The quantity of shares to sell.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.ValueError – Both/neither of
amount
andquantity
are supplied.
-
async
RobinhoodClient.
place_stop_buy_order
(symbol, price, quantity, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a stop buy order.
- Parameters
symbol (
str
) – A stock symbol.quantity (
int
) – The quantity of shares to buy.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
place_stop_sell_order
(symbol, price, quantity, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a stop sell order.
- Parameters
symbol (
str
) – A stock symbol.quantity (
int
) – The quantity of shares to sell.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
place_stop_limit_buy_order
(symbol, price, quantity, stop_price, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a limit buy order triggered at a given stop price.
- Parameters
symbol (
str
) – A stock symbol.quantity (
int
) – The quantity of shares to buy.stop_price (
Union
[int
,float
]) – The stop price at which to place the limit order, in dollars.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.
-
async
RobinhoodClient.
place_stop_limit_sell_order
(symbol, price, quantity, stop_price, time_in_force=<OrderTimeInForce.GFD: 'gfd'>, extended_hours=False)¶ Place a limit sell order triggered at a given stop price.
- Parameters
symbol (
str
) – A stock symbol.quantity (
int
) – The quantity of shares to sell.stop_price (
Union
[int
,float
]) – The stop price at which to place the limit order, in dollars.time_in_force (
OrderTimeInForce
) – Indicates how long the order should remain active before it executes or expires.extended_hours (
bool
) – The order can be executed in extended trading hours.
- Return type
- Returns
The order ID.
- Raises
ClientAPIError – Robinhood server responded with an error.
ClientRequestError – The HTTP request timed out or failed.
ClientUnauthenticatedError – The
RobinhoodClient
is not logged in.ClientUninitializedError – The
RobinhoodClient
is not initialized.