PyhoodClient

The main interface for interacting with Robinhood's API.

pyhood.client.PyhoodClient

High-level Robinhood API client.

Usage

client = PyhoodClient(session) # explicit session client = PyhoodClient() # uses active session from pyhood.login()

get_quote(symbol)

Get a stock quote.

get_quotes(symbols)

Get quotes for multiple symbols (batched).

Robinhood's quotes endpoint supports up to ~1,000 symbols per request (limited by URL length ~5,700 chars). We use 1,000 as a safe batch size.

get_fundamentals(symbol)

Get fundamental data for a symbol (PE, market cap, 52w range).

get_fundamentals_batch(symbols)

Get fundamental data for multiple symbols (batched).

Returns dict mapping symbol to fundamentals. Robinhood's fundamentals endpoint supports exactly 100 symbols per request.

Returned fields include: high_52_weeks, low_52_weeks, market_cap, pb_ratio, pe_ratio, shares_outstanding, float, volume, average_volume, sector, industry, description, and more.

get_all_instruments(tradeable_only=True)

Get all stock symbols available on Robinhood.

Paginates through the instruments endpoint to collect every tradeable stock symbol. Typically returns ~5,000 symbols.

Parameters:

Name	Type	Description	Default
tradeable_only	bool	If True, only return actively tradeable stocks.	True

Returns:

Type	Description
list[str]	List of ticker symbols.

get_options_expirations(symbol)

Get available options expiration dates for a symbol.

Works for both equity options (AAPL, SPY) and index options (SPX, NDX, VIX, RUT).

get_options_chain(symbol, expiration, option_type=None)

Get the full options chain for a symbol + expiration.

Works for both equity options (AAPL, SPY) and index options (SPX, NDX, VIX, RUT).

Parameters:

Name	Type	Description	Default
symbol	str	Ticker symbol (e.g. "AAPL", "SPX").	required
expiration	str	Expiration date (YYYY-MM-DD).	required
option_type	str | None	Filter by 'call' or 'put'. None = both.	None

get_stock_historicals(symbol, interval='day', span='year', bounds='regular')

Get historical OHLCV data for a stock.

Parameters:

Name	Type	Description	Default
symbol	str	Ticker symbol.	required
interval	str	Candle interval. One of '5minute', '10minute', 'hour', 'day', 'week'. Default: 'day'.	'day'
span	str	Time range. One of 'day', 'week', 'month', '3month', 'year', '5year'. Default: 'year'.	'year'
bounds	str	Trading hours. One of 'regular', 'extended', 'trading'. Default: 'regular'. Extended/trading only valid with span='day'.	'regular'

Returns:

Type	Description
list[Candle]	List of Candle dataclasses with OHLCV data.

get_stock_historicals_batch(symbols, interval='day', span='year', bounds='regular')

Get historical data for multiple stocks in one request.

Parameters:

Name	Type	Description	Default
symbols	list[str]	List of ticker symbols.	required
interval	str	Candle interval. Default: 'day'.	'day'
span	str	Time range. Default: 'year'.	'year'
bounds	str	Trading hours. Default: 'regular'.	'regular'

Returns:

Type	Description
dict[str, list[Candle]]	Dict mapping symbol to list of Candle dataclasses.

get_earnings(symbol, lookahead_days=14)

Get upcoming earnings for a symbol within lookahead window.

get_ratings(symbol)

Get analyst buy/hold/sell ratings for a symbol.

get_news(symbol)

Get news articles for a symbol.

get_movers(direction='up')

Get S&P 500 top movers.

Parameters:

Name	Type	Description	Default
direction	str	'up' or 'down'.	'up'

get_tags(tag)

Get stock symbols for a discovery tag.

Parameters:

Name	Type	Description	Default
tag	str	Tag name (e.g. '100-most-popular', 'top-movers', 'etf', '10-most-popular', 'technology', 'healthcare').	required

get_popularity(symbol)

Get how many Robinhood users hold a stock.

Parameters:

Name	Type	Description	Default
symbol	str	Stock ticker.	required

Returns:

Type	Description
int	Number of open positions (popularity count).

get_splits(symbol)

Get stock split history for a symbol.

get_portfolio_historicals(account_number=None, interval='day', span='year', bounds='regular')

Get historical portfolio value over time.

Parameters:

Name	Type	Description	Default
account_number	str | None	Account number. If None, uses first account.	None
interval	str	'day', 'week', '5minute', '10minute', 'hour'.	'day'
span	str	'day', 'week', 'month', '3month', 'year', '5year', 'all'.	'year'
bounds	str	'regular', 'extended', 'trading'.	'regular'

get_option_historicals(option_id, interval='day', span='year')

Get historical pricing data for an option contract.

Parameters:

Name	Type	Description	Default
option_id	str	Option instrument ID.	required
interval	str	'day', 'week', 'hour', '5minute', '10minute'.	'day'
span	str	'day', 'week', 'month', '3month', 'year'.	'year'

get_documents(doc_type=None)

Get account documents (statements, confirmations, tax docs).

Parameters:

Name	Type	Description	Default
doc_type	str | None	Filter by type (e.g. 'account_statement', 'trade_confirm'). If None, returns all documents.	None

get_day_trades(account_id=None)

Get recent day trade history.

Parameters:

Name	Type	Description	Default
account_id	str | None	Account ID. If None, uses first account.	None

get_margin_calls()

Get active margin calls.

get_deposit_schedules()

Get all scheduled recurring deposits.

get_user_profile()

Get the authenticated user's profile.

get_notification_settings()

Get current notification preferences.

update_notification_settings(**kwargs)

Update notification preferences.

Pass notification keys as keyword arguments, e.g.: client.update_notification_settings(market_open=False, dividends=True)

get_bank_accounts()

Get all linked bank accounts.

get_transfers()

Get all ACH transfers (deposits and withdrawals).

initiate_transfer(amount, direction, ach_relationship_url)

Initiate an ACH transfer (deposit or withdrawal).

Parameters:

Name	Type	Description	Default
amount	float	Dollar amount to transfer.	required
direction	str	'deposit' or 'withdraw'.	required
ach_relationship_url	str	URL of the linked bank account.	required

cancel_transfer(transfer_id)

Cancel a pending ACH transfer.

get_card_transactions(card_type=None)

Get debit card (Cash Management) transactions.

Parameters:

Name	Type	Description	Default
card_type	str | None	Filter by type — 'pending' or 'settled'.	None

get_watchlists()

Get all user watchlists with their symbols.

get_watchlist(name='Default')

Get a single watchlist by name.

Parameters:

Name	Type	Description	Default
name	str	Watchlist name (default: 'Default', Robinhood's main watchlist).	'Default'

add_to_watchlist(symbols, name='Default')

Add symbols to a watchlist (max 32 at a time).

Parameters:

Name	Type	Description	Default
symbols	list[str]	List of stock symbols to add.	required
name	str	Watchlist name (default: 'Default').	'Default'

remove_from_watchlist(symbols, name='Default')

Remove symbols from a watchlist.

Parameters:

Name	Type	Description	Default
symbols	list[str]	List of stock symbols to remove.	required
name	str	Watchlist name (default: 'Default').	'Default'

get_markets()

Get all available stock exchanges/markets.

get_market_hours(market, date)

Get trading hours for a market on a specific date.

Parameters:

Name	Type	Description	Default
market	str	Market MIC code (e.g. 'XNYS' for NYSE, 'XNAS' for Nasdaq).	required
date	str	Date string in YYYY-MM-DD format.	required

get_dividends()

Get all dividend payments.

get_dividends_by_symbol(symbol)

Get dividend payments for a specific symbol.

get_all_accounts()

Get all accounts including IRA via bonfire unified endpoint.

The standard /accounts/ endpoint never returns IRA accounts. This uses the bonfire API which returns all account types.

get_positions(nonzero=True, account_number=None)

Get current stock positions.

Parameters:

Name	Type	Description	Default
nonzero	bool	Only return positions with quantity > 0.	True
account_number	str | None	Filter to a specific account (e.g. IRA).	None

get_option_positions(account_number=None, nonzero=True)

Get current option positions with fully resolved details.

Uses aggregate_positions endpoint which returns symbol, strike, expiry in the legs data. Also fetches current market data for P&L and greeks.

Parameters:

Name	Type	Description	Default
account_number	str | None	Filter to specific account (e.g. '915060792' for IRA).	None
nonzero	bool	Only return positions with quantity > 0.	True

get_buying_power(account_number=None)

Get available buying power.

Parameters:

Name	Type	Description	Default
account_number	str | None	Specific account number (e.g. IRA account). If provided, fetches directly from the account URL (bypasses /accounts/ which doesn't show IRA accounts).	None

buy_stock(symbol, quantity, price=None, stop_price=None, time_in_force='gtc', extended_hours=False, account_number=None)

Buy stock shares.

Parameters:

Name	Type	Description	Default
symbol	str	Stock ticker symbol.	required
quantity	float	Number of shares to buy.	required
price	float | None	Limit price. If None, places market order.	None
stop_price	float | None	Stop price for stop/stop-limit orders.	None
time_in_force	str	'gtc' (good till cancelled), 'gtd', 'ioc', 'fok'.	'gtc'
extended_hours	bool	Whether to allow extended hours trading.	False
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

sell_stock(symbol, quantity, price=None, stop_price=None, time_in_force='gtc', extended_hours=False, account_number=None)

Sell stock shares.

Parameters:

Name	Type	Description	Default
symbol	str	Stock ticker symbol.	required
quantity	float	Number of shares to sell.	required
price	float | None	Limit price. If None, places market order.	None
stop_price	float | None	Stop price for stop/stop-limit orders.	None
time_in_force	str	'gtc' (good till cancelled), 'gtd', 'ioc', 'fok'.	'gtc'
extended_hours	bool	Whether to allow extended hours trading.	False
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

order_stock(symbol, quantity, side, price=None, stop_price=None, time_in_force='gtc', extended_hours=False, account_number=None)

Place a stock order (core method).

Parameters:

Name	Type	Description	Default
symbol	str	Stock ticker symbol.	required
quantity	float	Number of shares.	required
side	str	'buy' or 'sell'.	required
price	float | None	Limit price. If None, places market order.	None
stop_price	float | None	Stop price for stop/stop-limit orders.	None
time_in_force	str	'gtc' (good till cancelled), 'gtd', 'ioc', 'fok'.	'gtc'
extended_hours	bool	Whether to allow extended hours trading.	False
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

buy_option(symbol, strike, expiration, option_type, quantity, price, position_effect='open', time_in_force='gtc', account_number=None)

Buy option contracts.

Parameters:

Name	Type	Description	Default
symbol	str	Underlying stock symbol.	required
strike	float	Strike price.	required
expiration	str	Expiration date (YYYY-MM-DD).	required
option_type	str	'call' or 'put'.	required
quantity	int	Number of contracts.	required
price	float	Limit price per contract.	required
position_effect	str	'open' or 'close'.	'open'
time_in_force	str	'gtc' (good till cancelled), 'gtd', 'ioc', 'fok'.	'gtc'
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

sell_option(symbol, strike, expiration, option_type, quantity, price, position_effect='close', time_in_force='gtc', account_number=None)

Sell option contracts.

Parameters:

Name	Type	Description	Default
symbol	str	Underlying stock symbol.	required
strike	float	Strike price.	required
expiration	str	Expiration date (YYYY-MM-DD).	required
option_type	str	'call' or 'put'.	required
quantity	int	Number of contracts.	required
price	float	Limit price per contract.	required
position_effect	str	'open' or 'close'.	'close'
time_in_force	str	'gtc' (good till cancelled), 'gtd', 'ioc', 'fok'.	'gtc'
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

order_option(symbol, strike, expiration, option_type, quantity, price, side, position_effect, credit_or_debit=None, time_in_force='gtc', account_number=None)

Place an option order (core method).

Parameters:

Name	Type	Description	Default
symbol	str	Underlying stock symbol.	required
strike	float	Strike price.	required
expiration	str	Expiration date (YYYY-MM-DD).	required
option_type	str	'call' or 'put'.	required
quantity	int	Number of contracts.	required
price	float	Limit price per contract.	required
side	str	'buy' or 'sell'.	required
position_effect	str	'open' or 'close'.	required
credit_or_debit	str | None	'debit' or 'credit'. Auto-determined from side if not provided (buy→debit, sell→credit).	None
time_in_force	str	'gtc' (good till cancelled), 'gtd', 'ioc', 'fok'.	'gtc'
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

get_stock_orders()

Get all stock orders (not options).

Returns:

Type	Description
list[Order]	List of Order objects for stock orders.

get_option_orders()

Get all option orders.

Returns:

Type	Description
list[Order]	List of Order objects for option orders.

get_order(order_id)

Get a specific order by ID.

Parameters:

Name	Type	Description	Default
order_id	str	The order ID to fetch.	required

Returns:

Type	Description
Order	Order object with details.

cancel_order(order_id)

Cancel a specific order.

Parameters:

Name	Type	Description	Default
order_id	str	The order ID to cancel.	required

Returns:

Type	Description
dict	Response dict from the cancellation.

cancel_all_stock_orders()

Cancel all pending stock orders.

Returns:

Type	Description
list[dict]	List of response dicts from cancellations.

get_futures_account_id()

Auto-discover the futures account ID.

Fetches all Ceres accounts and returns the first with accountType == 'FUTURES'.

Returns:

Type	Description
str	The futures account ID string.

Raises:

Type	Description
APIError	If no futures account is found.

get_futures_contract(symbol)

Get futures contract details by symbol.

Parameters:

Name	Type	Description	Default
symbol	str	Futures symbol (e.g. 'ESH26' for E-mini S&P 500 Mar 2026).	required

Returns:

Type	Description
FuturesContract	FuturesContract with contract details.

Raises:

Type	Description
SymbolNotFound	If symbol not recognized.

get_futures_contracts(symbols)

Get futures contract details for multiple symbols.

Parameters:

Name	Type	Description	Default
symbols	list[str]	List of futures symbols (e.g. ['ESH26', 'NQH26']).	required

Returns:

Type	Description
dict[str, FuturesContract]	Dict mapping symbol to FuturesContract.

get_futures_quote(symbol)

Get a real-time futures quote.

Parameters:

Name	Type	Description	Default
symbol	str	Futures symbol (e.g. 'ESH26').	required

Returns:

Type	Description
FuturesQuote	FuturesQuote with bid/ask/last price.

Raises:

Type	Description
SymbolNotFound	If symbol not recognized.

get_futures_quotes(symbols)

Get real-time futures quotes for multiple symbols.

Parameters:

Name	Type	Description	Default
symbols	list[str]	List of futures symbols.	required

Returns:

Type	Description
dict[str, FuturesQuote]	Dict mapping symbol to FuturesQuote.

get_futures_orders(account_id=None)

Get all historical futures orders.

Uses cursor-based pagination (different from standard Robinhood pagination). Automatically discovers futures account if not provided.

Parameters:

Name	Type	Description	Default
account_id	str | None	Futures account ID. Auto-discovered if None.	None

Returns:

Type	Description
list[FuturesOrder]	List of FuturesOrder objects.

get_filled_futures_orders(account_id=None)

Get only filled futures orders.

Parameters:

Name	Type	Description	Default
account_id	str | None	Futures account ID. Auto-discovered if None.	None

Returns:

Type	Description
list[FuturesOrder]	List of filled FuturesOrder objects.

calculate_futures_pnl(orders=None, account_id=None)

Calculate total realized P&L across futures orders.

Only counts CLOSING orders to avoid double-counting.

Parameters:

Name	Type	Description	Default
orders	list[FuturesOrder] | None	Pre-fetched orders. If None, fetches all filled orders.	None
account_id	str | None	Futures account ID (used if orders is None).	None

Returns:

Type	Description
float	Total realized P&L as a float.