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, resolve_symbols=True)

Get news articles for a symbol.

Parameters:

Name	Type	Description	Default
symbol	str	Ticker to fetch news for.	required
resolve_symbols	bool	Resolve each article's related instrument IDs to ticker symbols. Costs one extra request per unique instrument (cached per call). Set False to get the raw IDs back instead.	True

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')

Deprecated — Robinhood retired this endpoint.

Raises:

Type	Description
APIError	Always. /portfolios/historicals/ returns 404 for every parameter combination as of 2026-08-09.

Use get_portfolio_performance() instead. It is not a drop-in: the replacement returns a chart view model whose y values are returns rather than equity, so it cannot be mapped onto PortfolioCandle without inventing the equity figures.

get_portfolio_performance(account_number=None)

Get the portfolio performance chart.

Replaces get_portfolio_historicals(), whose endpoint Robinhood retired.

Parameters:

Name	Type	Description	Default
account_number	str | None	Account number. If None, uses the first account.	None

Returns:

Type	Description
dict	The raw chart view model: lines of plotted points with
dict	x_axis, y_axis, legend_data, fills and overlays.

Note

Returned unmapped on purpose. This is a rendering payload rather than a time series — the y values are returns, not equity, and each point carries display labels. Forcing it onto a dataclass would mean inventing figures the endpoint does not provide.

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

is_market_open(market='XNAS', extended_hours=False)

Whether the market is open for trading right now.

Parameters:

Name	Type	Description	Default
market	str	Market MIC code. Defaults to 'XNAS' (Nasdaq).	'XNAS'
extended_hours	bool	Check the extended session rather than the regular one.	False

Returns:

Type	Description
bool	True if trading is open now. False on weekends, holidays, and
bool	outside session hours.

Note

An order placed while closed is accepted and queued rather than rejected — it executes at the next open. Check this first if that distinction matters.

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 a specific account, e.g. an IRA account number.	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, trail_amount=None, trail_percent=None, market_hours=None, 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, trail_amount=None, trail_percent=None, market_hours=None, 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, trail_amount=None, trail_percent=None, market_hours=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
trail_amount	float | None	Trail by a dollar amount, for a trailing stop.	None
trail_percent	float | None	Trail by a percentage, for a trailing stop. Note that Robinhood currently blocks trailing stops for third-party clients — see the module docs.	None
market_hours	str | None	Trading session — 'regular_hours', 'extended_hours' or 'all_day_hours'. Defaults to regular hours. Anything other than regular hours sets extended_hours automatically; the two must agree or Robinhood rejects the order.	None

Returns:

Type	Description
Order	Order object with details.

Raises:

Type	Description
OrderError	If both trail_amount and trail_percent are given.

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.

order_option_spread(symbol, quantity, price, legs, direction, time_in_force='gtc', account_number=None)

Place a multi-leg option spread order.

Parameters:

Name	Type	Description	Default
symbol	str	Underlying stock symbol.	required
quantity	int	Number of spreads.	required
price	float	Net limit price per spread.	required
legs	list[dict]	One dict per leg, each with strike, expiration, option_type ('call'/'put'), side ('buy'/'sell') and effect ('open'/'close').	required
direction	str	'debit' or 'credit'.	required
time_in_force	str	'gtc', 'gtd', 'ioc' or 'fok'.	'gtc'
account_number	str | None	Specific account (e.g. IRA). None = default.	None

Returns:

Type	Description
Order	Order object with details.

Raises:

Type	Description
OrderError	If fewer than two legs are given, or a leg is missing a required key.

Note

The payload shape matches what robin_stocks sends in production, but placing a spread has not been verified against the live API — that would mean opening a real position.

buy_stock_by_price(symbol, amount_in_dollars, account_number=None, time_in_force='gfd')

Buy fractional shares by dollar amount.

Parameters:

Name	Type	Description	Default
symbol	str	Stock ticker symbol.	required
amount_in_dollars	float	Dollar amount to buy (minimum $1).	required
account_number	str | None	Specific account (e.g. IRA). None = default.	None
time_in_force	str	Defaults to 'gfd', which fractional orders require.	'gfd'

Returns:

Type	Description
Order	Order object with details.

Raises:

Type	Description
OrderError	If the amount is below $1 or the quote is unusable.

Note

Fractional quantities require a market order — Robinhood rejects a fractional limit order with "Limit order quantity cannot include fractional shares". Market orders were themselves being rejected until ORDER_FORM_VERSION was found and sent, which is fixed.

End to end this is unverified. A fractional order is a market order, so it executes immediately and cannot be exercised with a resting non-marketable limit the way the other order paths were. The payload and the rounding are covered by tests; the fill is not.

sell_stock_by_price(symbol, amount_in_dollars, account_number=None, time_in_force='gfd')

Sell fractional shares by dollar amount.

Parameters:

Name	Type	Description	Default
symbol	str	Stock ticker symbol.	required
amount_in_dollars	float	Dollar amount to sell (minimum $1).	required
account_number	str | None	Specific account (e.g. IRA). None = default.	None
time_in_force	str	Defaults to 'gfd', which fractional orders require.	'gfd'

Returns:

Type	Description
Order	Order object with details.

get_stock_orders(start_date=None)

Get all stock orders (not options).

Parameters:

Name	Type	Description	Default
start_date	str | datetime | None	Only return orders created on or after this point. Accepts a datetime or ISO-8601 string ('2026-01-01'); naive values are treated as UTC. Filtering is requested server-side to avoid paging through a long history, and re-applied locally.	None

Returns:

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

get_option_orders(start_date=None)

Get all option orders.

Parameters:

Name	Type	Description	Default
start_date	str | datetime | None	Only return orders created on or after this point. Accepts a datetime or ISO-8601 string ('2026-01-01'); naive values are treated as UTC. Filtering is requested server-side to avoid paging through a long history, and re-applied locally.	None

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.

export_stock_orders(path, start_date=None)

Write completed stock orders to a CSV file.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file, or a directory to write a default filename into.	required
start_date	str | datetime | None	Only include orders created on or after this point.	None

Returns:

Type	Description
Path	The path written.

export_option_orders(path, start_date=None)

Write completed option orders to a CSV file.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file, or a directory to write a default filename into.	required
start_date	str | datetime | None	Only include orders created on or after this point.	None

Returns:

Type	Description
Path	The path written.

unlink_bank_account(relationship_id)

Unlink a connected bank account.

Parameters:

Name	Type	Description	Default
relationship_id	str	ACH relationship ID from get_bank_accounts().	required

Returns:

Type	Description
dict	The API response.

Warning

This is irreversible — relinking requires re-verifying the account with Robinhood. Not exercised against a live account.

get_interest_payments()

Get cash sweep interest payments.

Returns:

Type	Description
list[InterestPayment]	List of InterestPayment, newest first as returned by the API.

get_margin_interest()

Get margin interest charges.

Returns:

Type	Description
list[dict]	List of raw charge dicts.

Note

The endpoint and its results envelope are verified, but the test account has never been charged margin interest, so no populated record has been observed. Records are returned unmapped rather than forced onto a dataclass built from guessed field names.

get_subscription_fees()

Get Robinhood Gold subscription fees.

Returns:

Type	Description
list[SubscriptionFee]	List of SubscriptionFee.

get_unified_transfers()

Get transfers from the unified payment hub.

Broader than get_transfers(), which covers ACH only — this also includes internal transfers such as brokerage to IRA.

Returns:

Type	Description
list[UnifiedTransfer]	List of UnifiedTransfer.

get_ipo_access_list()

Get the IPO Access list — offerings currently available to you.

When Robinhood has no offerings, the response carries an empty_state section instead of any offering.

Returns:

Type	Description
dict	The raw list view model. These are UI view models with deeply
dict	nested, offering-dependent structure, so they are returned as-is
dict	rather than mapped onto a dataclass.

has_ipo_offerings()

Whether any IPO Access offering is open for share requests.

Note

This is narrower than "an IPO exists". The list only carries offerings whose order book is still open, so an upcoming IPO reports False once its book closes. Verified against RVII on 2026-08-12: the instrument was live at ipo_access_status price_finalized and listing the next day, while this returned False. To detect an offering regardless of stage, look for instruments with type pre_ipo and an ipo_access_status.

get_ipo_access_cards(instrument_ids)

Get IPO Access cards for one or more instruments.

Parameters:

Name	Type	Description	Default
instrument_ids	str | list[str]	An instrument ID, or a list of them.	required

Returns:

Type	Description
list[dict]	List of card dicts. Shape verified against a live offering
RVII, 2026-08-12	instrument_id, name, title (the
list[dict]	ticker), subtitle (the price, e.g. '$25.00'), accent_color,
list[dict]	action (a deeplink) and logo_images.

Note

Cards resolve by instrument ID at any stage, including after the order book has closed and has_ipo_offerings() reports False.

get_ipo_access_summary(instrument_id)

Get an IPO's summary view model — company, dates and price range.

Warning

Unconfirmed. This returned 404 against a live offering (RVII, 2026-08-12, phase price_finalized), as did seven other spellings of the path on the same base that serves web_order_entry successfully. Either the route is stage-specific — reachable only while the order book is open — or this path is wrong. Prefer get_ipo_access_order_entry(), whose context carries the symbol, phase, cut-off deadline and enrolment state.

get_ipo_access_order_entry(instrument_id, account_number=None)

Get an IPO's order-entry view model — eligibility and price range.

Returns:

Type	Description
dict	The raw view model. Shape verified against a live offering (RVII,
dict	2026-08-12): account_number, instrument_id, context,
dict	form_state, order_entry_view_model, trade_receipt_view_model,
dict	action_required_view_model and ipoa_new_orders_blocked_details.
dict	context is the useful part: phase (e.g. 'price_finalized'),
dict	instrument_symbol, instrument_url, ipo_access_quote,
dict	ipo_access_cob_deadline, has_cob_deadline_passed,
dict	user_is_enrolled, account_type, existing_order and
dict	available_buying_power.
dict	trade_receipt_view_model is None until an order exists.

Note

This is the most informative of the IPO endpoints and the one to reach for — it resolves after the order book closes, when get_ipo_access_list() has already reverted to its empty state. Requesting shares is not wrapped; an IPO Access order is an ordinary equity order.

get_ipo_access_allocation_results(instrument_id)

Get how many shares you were allocated in an IPO you requested.

Note

Returns 404 before allocations are decided — confirmed against a live offering the day before it listed (RVII, 2026-08-12). That is the endpoint behaving correctly rather than a fault: there is no allocation to report until after pricing. The populated shape remains unobserved, since it needs a filled request.

get_ipo_access_trade_receipt(order_id)

Get the trade receipt for a filled IPO Access order.

Note

This response shape has not been observed against a real offering.

get_ipo_access_orders(start_date=None)

Get stock orders placed through IPO Access.

IPO Access orders are ordinary equity orders flagged with is_ipo_access_order, so this filters the stock order history.

Parameters:

Name	Type	Description	Default
start_date	str | datetime | None	Only return orders created on or after this point. See get_stock_orders for accepted formats.	None

Returns:

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

cancel_all_option_orders()

Cancel all pending option 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_quote_by_id(contract_id, symbol='')

Get a real-time futures quote by contract ID.

Avoids the contract lookup that get_futures_quote performs when the contract ID is already known.

Parameters:

Name	Type	Description	Default
contract_id	str	Futures contract instrument ID.	required
symbol	str	Optional symbol to label the quote with.	''

Returns:

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

Raises:

Type	Description
SymbolNotFound	If no quote is returned for the contract.

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, start_date=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
start_date	str | datetime | None	Only return orders created on or after this point. Accepts a datetime or ISO-8601 string ('2026-01-01'); naive values are treated as UTC. The futures service is not confirmed to support server-side date filtering, so this may only filter locally rather than reduce the number of pages fetched.	None

Returns:

Type	Description
list[FuturesOrder]	List of FuturesOrder objects.

get_futures_positions(account_id=None)

Get open futures positions.

Parameters:

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

Returns:

Type	Description
list[dict]	List of raw position dicts.

Note

The endpoint and its results envelope are verified, but no populated position record has been observed — the test account holds no futures positions. Records are therefore returned unmapped rather than forced onto a dataclass whose field names would be guesswork.

get_futures_order_info(order_id, account_id=None)

Get a single futures order by ID.

The futures service has no single-order endpoint, so this scans the order history client-side.

Parameters:

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

Returns:

Type	Description
FuturesOrder | None	The matching FuturesOrder, or None if not found.

get_filled_futures_orders(account_id=None, start_date=None)

Get only filled futures orders.

Parameters:

Name	Type	Description	Default
account_id	str | None	Futures account ID. Auto-discovered if None.	None
start_date	str | datetime | None	Only return orders created on or after this point. See get_futures_orders for accepted formats.	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.