Headline fields (in `base_currency`): net_liquidation, total_cash_value, settled_cash,
buying_power, available_funds, excess_liquidity, equity_with_loan_value,
gross_position_value, init/maint margin requirement, sma, cushion (fraction), leverage
and day_trades_remaining (-1 = unlimited). `values` holds every summary row,
including per-currency ledger rows (CashBalance, UnrealizedPnL... with currency BASE
for converted totals). IBKR refreshes the summary about every 3 minutes, and right
after trades. No market-data subscription needed.
Errors: invalid_request lists the valid tags when a tag is unknown.

Use it for details the summary lacks (per-currency cash, accrued interest, segment
values with -C/-S suffixes, currency exchange rates...). Each row has the raw `value`
and, when numeric, `amount`. Values update about every 3 minutes or on change.
With `model_code` (financial advisors) the values of that model are fetched once.
Default limit 200, maximum 1000; `truncated` says whether more matched.
Errors: invalid_request lists the valid tags when a tag is unknown.

IBKR decides how far back this reaches (the current and recent sessions). Use
get_executions for fill prices and commissions. Default limit 100, maximum 1000.
Errors: ib_api_error 321, at once, when the gateway's API is read-only (get_health:
api_read_only), which refuses this request; get_executions still lists recent fills.

Covers the current trading day only (up to 7 days if the gateway's trade-log setting
allows); older trades are not available through the API. `commission` is null until
IBKR reports it (usually within seconds of the fill); realized_pnl is 0 for fills
that opened a position. Default limit 100, maximum 1000.

`modifiable` is true only for orders this server placed (same API client id): only
those can be modified or cancelled with the order tools. Orders of other API clients
and manual TWS orders are shown for information. Filled and cancelled orders are
left out; see get_completed_orders. When the gateway's API is read-only (get_health:
api_read_only), IBKR refuses the request for this server's orders alone, so
include_other_clients=false reads every client's orders and keeps this server's;
`note` says so. Errors: ib_api_error 321, at once, if IBKR refuses open orders
altogether on a read-only API.

One-shot: subscribes to IBKR's P&L feed, waits a few seconds at most for the first
update (usually about a second), and cancels, so every call is a fresh reading and
nothing needs unsubscribing. Errors: request_timeout when IBKR sends nothing (right
after login, or an account without data); retry once before giving up.

Pass the position's con_id (from get_positions) for an exact match. Waits a few
seconds at most for IBKR's first update. Errors: not_found when the account has no
position and no P&L today in that contract; ambiguous_contract lists candidates;
invalid_request for a combo (BAG: ask per leg); request_timeout when IBKR sends nothing.

Fast and always current (IBKR streams position changes). avg_cost includes
commissions and, for options and futures, the multiplier. For market value and
unrealized P&L use get_portfolio; for today's P&L of one position use
get_position_pnl. `contract.exchange` is not reported for positions; use the con_id
for follow-up calls. `model_code` (financial advisors) lists one model's positions.

For each contract: identifiers (con_id, local symbol, trading class, multiplier),
long name (`contract.description`), industry and category, stock type, the
exchange time zone, trading and liquid (regular-hours) sessions for about the next
week with closed days, min tick, size increments, valid exchanges with their market
rule ids (same order; see get_market_rule), accepted order types, ISIN and other
security ids, the underlying of a derivative, and bond terms for bonds.

The contract may be partial: symbol + sec_type FUT + exchange lists every future expiry.
Derivatives are sorted by expiry, strike and right; `limit` defaults to 20 (cap 200),
`total` and `truncated` say how many matched. Broad option specs are slow and
throttled by IBKR: use get_option_chain for expiries and strikes, then look up single
options. Futures and indexes need their listing exchange (CME, CBOE...), not SMART;
set include_expired for expired futures. Errors: not_found for an unknown
instrument; invalid_request for combos (BAG).

A contract's valid price steps can depend on the price level and exchange: each rule
lists rows of (low_edge, increment), meaning prices from low_edge up to the next row's
low_edge move in steps of increment. Get the ids from get_contract_details; its
market_rule_ids line up with valid_exchanges. Use it to round limit prices correctly.

IBKR answers each rule within a second or not at all: ids it did not answer (probably
unknown) are listed in `missing_ids`; if none was answered the call fails with
not_found.

Returns one entry per trading class (e.g. SPX monthly and SPXW weekly), with its
multiplier, the exchanges listing it, all expirations (YYYYMMDD) and all strikes.
Strikes are the union across expirations: not every strike exists for every expiry,
so qualify_contract a specific option before quoting it. This is the cheap way to
explore options; it needs no market data subscription and has no pacing concerns.
For US stock and index options pass exchange SMART: IBKR lists a chain per options
exchange, and chains that differ slightly are not merged, so the full answer can be
long. Quotes and greeks come from the options and market_data tools.

Errors: not_found when the underlying is unknown or has no listed options (or none on
`exchange`); invalid_request when `underlying` is itself an option or combo (also when
given by the con_id of one).

Quotes on SMART-routed contracts carry a `bbo_exchange` code; this lists the
exchanges it stands for, each with IBKR's single-letter code, which tells you where the
best bid and offer come from. The code only comes from market data (get_quotes needs
a market data subscription or delayed data). When IBKR returns no exchanges (e.g.
outside trading hours, or for a code not taken from a quote) the call fails with
not_found.

Use it to check a spec before quoting or ordering, or to turn a symbol into a con_id;
later calls can then pass just the con_id. The returned `description` is the long name
(e.g. APPLE INC) to confirm it is the intended instrument.

If several contracts match (e.g. a stock listed on two exchanges, or an option spec
without trading class), the call fails with ambiguous_contract and the message lists
up to 20 candidates with their con_ids: retry with the right con_id or more fields
(primary_exchange, currency, trading_class...). An unknown spec fails with not_found;
a combo (BAG) with invalid_request (qualify each leg by con_id instead).

Returns up to `limit` matches (default 16, IBKR rarely sends more): each with its
con_id, symbol, sec_type, primary exchange, currency, name (`description`) and the
derivative types listed on it (OPT, FUT, WAR...). Use it to discover a symbol or its
con_id, then call qualify_contract or get_contract_details for the exact contract.

Limits: discovery only, not exhaustive (no options or futures months in the results;
use get_option_chain or get_contract_details for those). IBKR allows about one search
per second, so back-to-back searches are spaced out. Errors: not_found when nothing
matches; request_timeout when IBKR did not answer within 4 seconds.

Deprecated by IBKR: reqFundamentalData was removed in TWS API 10.50. It still works on
IB Gateway stable (10.45); newer gateways may refuse it. Stocks only (sec_type STK).
Needs the Refinitiv (Reuters) fundamentals data subscription on the IBKR login.
Whitespace between XML tags is removed; long reports are cut at max_chars (default
50000, max 200000) with truncated=true, so prefer ReportSnapshot or ReportsFinSummary
over the large statement and ownership reports.
Errors: not_found (unknown stock, or IBKR has no such report for it, error
430), ambiguous_contract (give primary_exchange or con_id), ib_api_error 10358 (no
fundamentals subscription), invalid_request (not a stock), request_timeout (a newer
gateway may not answer at all). For key ratios without this report, use
subscribe_quotes with the fundamental_ratios generic tick.

Also shareholder and board meetings, conferences and more (get_wsh_metadata lists
the event types). Give a contract, event_types, a raw filter_json, or
fill_portfolio/fill_watchlist; narrow by start_date/end_date. Returns at most `limit`
events (default 50, max 100); each event is the JSON object WSH sends (event type
tag, dates, company, details), and `request` shows what was asked of IBKR.
truncated=true means more events may exist: narrow the dates to page through them.
The WSH metadata is requested automatically first, as IBKR requires. Needs a Wall
Street Horizon corporate event data subscription (paid) on the IBKR login; without
it IBKR answers with an ib_api_error.

Errors: not_found (no events match: widen the dates or check event_types),
invalid_request (unknown event type, bad filter_json, dates in the wrong order,
nothing to ask for), account_not_allowed (fill_portfolio on a login with accounts
outside the allowlist).

Use it to build get_wsh_events queries: `event_types` lists the event type tags
(wshe_ed is the earnings date, for example) and `metadata_json` holds the full
description, filtered by `query` and cut at max_chars (default 30000, max 200000).
The metadata is fetched once and then served from this server's cache (`cached`).
Needs a Wall Street Horizon corporate event data subscription (paid) on the IBKR
login; without it IBKR answers with an ib_api_error. not_found means nothing matched
`query`.

Use it before long get_historical_bars requests, or when they come back empty, to
learn how far back the data goes for this `what_to_show`. Needs market-data
permissions for the instrument; counts toward IBKR's historical-data limits.

Errors: not_found (no such contract, or no data of that type).

Each entry is a price and IBKR's count (traded volume) at that price, sorted by
price. Useful for volume-at-price, support/resistance and value-area questions.
Default limit 200 price levels, at most 1000; when there are more, the busiest levels
are kept and `truncated` is true. Needs market-data permissions for the instrument.

Errors: not_found (no data for the period), invalid_request (bad period).

Bars cover `duration` back from `end` (now when omitted). Intraday bar times are UTC;
daily, weekly and monthly bars carry the trading date. Default limit 1000 bars, at
most 10000; when there are more, the NEWEST are kept and `truncated` is true (request
a shorter duration or larger bars to see older ones).

Limits (IBKR): bars of 30 seconds or less reach back about 6 months, allow short
durations only (1 secs up to 1800 S, 5 secs up to 3600 S, 10/15 secs up to 14400 S,
30 secs up to 28800 S), and are paced at about 60 requests per 10 minutes, 5 per
contract and data type in 2 seconds, and no identical request within 15 s (this
server answers identical requests from a 15-second cache). Larger bars are not paced
that way; IBKR's guide for the longest duration: 1 min bars about 1 D, 3 mins 1 W,
30 mins 1 M, daily bars years. Needs market-data permissions for the instrument (the
same subscription as live quotes). IBKR keeps no data for expired options; expired
futures need include_expired in the contract.

Errors: not_found (no such contract, or no data in the range: check
what_to_show, use_rth and get_head_timestamp), invalid_request (bad duration or
bar size combination), rate_limit (pacing; retry after the stated time),
ib_api_error 162 (pacing, permissions), request_timeout (shorten the request).

Give exactly one of `start` (ticks after it) or `end` (ticks before it). IBKR sends
at most 1000 ticks per request, with one-second timestamps, and may add a few to
finish the last second. When `truncated` is true there are probably more: page on
with start set to the last tick's time (or end set to the first tick's time); ticks
in that same second can repeat.

Needs market-data permissions for the instrument. Paced like small bars (about 60
requests per 10 minutes; BID_ASK counts double), so prefer get_historical_bars for
anything longer than minutes of activity.

Errors: not_found (no ticks in the range), invalid_request (both or neither
of start/end), rate_limit, ib_api_error 162 (pacing, permissions).

Times are in the exchange's time zone with the offset included, so holidays, early
closes and overnight sessions show up as they really were. For the upcoming
sessions, get_contract_details also lists trading and liquid hours. Counts toward
IBKR's historical-data limits.

Errors: not_found (no such contract, or no sessions in the range).

Each quote also has `halted`, `market_data_type` (live, frozen, delayed or
delayed_frozen), `bbo_exchange` (expand it with get_smart_components) and, for
options, IBKR model greeks and implied volatility. Snapshots take up to about 11
seconds for quiet contracts. A contract with an open quote stream (subscribe_quotes)
is answered from the stream at no extra cost. Generic ticks (shortable shares,
fundamental ratios...) are not available as snapshots; use subscribe_quotes.

Contracts that fail are listed in `errors` (unknown or ambiguous contract, no market
data permission) while the others still get quotes; if all fail, the call fails.
Needs market data permissions for each exchange. Without them IBKR answers with
error 354, 10089 or 10168: call set_market_data_type with 'delayed' for free
15-20 minute delayed data (10089 with delayed already selected: IBKR has no delayed
data for that instrument on this login). Null prices mean IBKR sent no value.

`data` depends on `kind`: quotes → `quote` (+ `extras`); depth → `bids`/`asks`;
tick_by_tick → `ticks`; realtime_bars and bars → `bars`; scanner → `rows`; news →
`headlines`; news_bulletins → `bulletins`; display_group → `current` and `updates`.
Time series (ticks, bars, headlines, bulletins, display group updates) come oldest
first, cut to the newest `limit` (default 100, max 5000) after `since`;
`data.truncated` is true when older ones were left out.
Stream snapshots also carry `active`, `error` and `notices` (IBKR messages such as
delayed data or a lost subscription). `stale` true means the gateway connection
dropped and values may be old. Each read keeps the subscription alive; one not read
for its idle time is cancelled and this tool then reports subscription_not_found.

For each: its id, kind, key, contract, parameters, when it was created and last
read, when it will be cancelled for being idle (`idle_expires_at`), and `stale`
(true while the gateway connection is down). Also shows capacity: subscriptions
used out of the server maximum, and market depth and tick-by-tick streams used out
of IBKR's limits, plus the connection's current market data type.

Applies to every market data request made afterwards (get_quotes and new streams),
for every tool, and is kept across reconnects. Use 'delayed' when quotes fail with
error 354, 10089 or 10168 (no live market data subscription). With live selected,
IBKR still falls back to delayed data where it can (each quote says which it got).
Delayed data has no market depth and no tick-by-tick data. Open streams keep what
they had until you unsubscribe and subscribe again.

First loads `duration` of history (like get_historical_bars), then IBKR updates the
last bar and appends new ones as time passes. get_subscription_data returns the
bars oldest first (the newest 100 by default; the server keeps up to 5000). One
stream per contract and parameter set: subscribing again returns the same handle.
Counts against IBKR's historical data pacing (about 60 requests per 10 minutes;
error 162 on a violation) and needs market data permissions. Stop it with
unsubscribe.

Errors: not_found if IBKR has no bars for the period (try a longer duration or
use_rth=false), ib_api_error 321 if IBKR rejects the combination of bar size,
duration and what_to_show (the message names the field).

get_subscription_data returns `bids` and `asks` as levels (position 0 is the best
price) with price, size and market maker or venue. IBKR allows only 3 depth
streams at a time by default; this server refuses a 4th (unsubscribe one first).
One depth stream per contract: subscribing again returns the same handle with its
original rows and smart_depth. Needs live data (not available when
set_market_data_type chose delayed) and a Level II (depth of book) subscription
for the exchange; get_depth_exchanges lists exchanges that offer depth. Errors:
309 (depth limit), 10092 (no depth for this contract and exchange), 354 (no
subscription).

Returns a subscription handle. get_subscription_data(subscription_id) then returns
the current quote (bid/ask/last, sizes, OHLC, volume, greeks for options), the
requested generic tick values under `extras`, and IBKR notices. There is one quote
stream per contract: subscribing again returns the same handle (`deduplicated`
true), adding any new generic ticks to it. Each stream uses one of the login's
market data lines (100 by default); streams nobody reads for `idle_ttl_s` seconds
are cancelled, and unsubscribe frees the line at once.

Needs market data permissions (see set_market_data_type for delayed data). If IBKR
refuses the stream right away (354, 10089, 10168, 10197), the call fails with the
reason; later problems show in the data as `active: false` and `error`.

A new bar arrives every 5 seconds; get_subscription_data returns them oldest first
with open, high, low, close, volume, VWAP and trade count. Only 5-second bars exist;
for other sizes use subscribe_bars. One stream per contract, what_to_show and
use_rth: subscribing again returns the same handle. Uses a market data line and
counts against IBKR's historical data pacing. Needs market data permissions; TRADES
is not available for forex (use MIDPOINT). Errors 420 and 162 mean IBKR refused the
request (invalid for the contract, or pacing). Stop it with unsubscribe.

get_subscription_data returns the buffered ticks oldest first (use its `since` and
`limit` to page). Times are when the tick reached this server (UTC). IBKR allows
only about 3 tick-by-tick streams at a time; this server refuses more. One stream
per contract and tick_type: subscribing again returns the same handle. Needs live
data and a market data subscription for the instrument (not available with delayed
data); errors 10189 and 10190 mean IBKR refused it or its limit is reached. Stop it
with unsubscribe.

Pass either `subscription_id` or `all=true`. Works for every kind of subscription
(quotes, depth, tick-by-tick, bars, scanners, news, bulletins, display groups).
Subscriptions belong to the server, not to one client: `all=true` also stops streams
that other clients of this server opened.

Each headline has provider_code and article_id for get_news_article, plus the
publication time (UTC). Works for stocks and other instruments IBKR tags news
with. Default limit 50, at most 300 (IBKR's cap per request); for more, move `end`
back to the oldest time returned. Needs a subscription to each provider searched
(see get_news_providers).
Errors: invalid_request for a provider the login is not subscribed to; not_found
when there are no headlines in the range (widen it); request_timeout when IBKR
does not answer within 4 seconds (retry with a narrower range).

Take both from a headline (get_historical_news or a news subscription). HTML
articles are converted to plain text unless plain_text is false. Text longer than
max_chars (default 20000) is cut and truncated is true; total_chars gives the full
length. Binary articles (PDFs) are reported with article_type=binary and their
size, not returned. Needs a subscription to the provider.
Errors: ib_api_error with IBKR's message when the article is unknown or not
permitted; not_found when IBKR sends an empty article.

Use the codes with get_historical_news, get_news_article and subscribe_news. Only
subscribed providers are listed; the free API feeds (BRFG Briefing.com General
Market Columns, BRFUPDN Briefing.com Analyst Actions, DJNL Dow Jones Newsletters)
must still be enabled in IBKR's market data subscriptions. Errors: not_found when
the login has none.

Give a contract for headlines about that instrument (from provider_code, or every
subscribed provider), or only a provider_code for that provider's broad tape (all
its headlines, e.g. BRF for Briefing Trader, BZ for Benzinga, FLY for The Fly;
each needs its own subscription). Returns a handle; read the headlines (oldest
first, the newest 200 kept) with get_subscription_data(subscription_id) and fetch
a full story with get_news_article. Uses one market data line. Stop it with
unsubscribe; it is cancelled after idle_ttl_s seconds without a read.
Errors: invalid_request without a contract or provider_code, or when a contract is
given with a provider the login is not subscribed to (see get_news_providers);
ib_api_error when IBKR refuses the stream (no news permission for that provider).

Returns a handle; read the bulletins with get_subscription_data(subscription_id)
(each has type news, exchange_unavailable or exchange_available, the message and the
exchange). There is one bulletin stream per gateway connection, so calling this
again returns the same handle, and all_messages only counts the first time. Stop it
with unsubscribe; it is cancelled after idle_ttl_s seconds without a read.

Includes the negotiated server version, the API version range this client speaks,
whether open and completed orders were synced (`orders_synced`), when the session
started, and traffic counters. Works when disconnected too (the session fields are
then null).

Call this first when another tool fails with not_connected or times out. It never
fails itself. `state` is one of:
- connected: everything works.
- connecting: a connection attempt is in progress.
- not_accepting: the gateway refused or ignored the connection (it is down, logged out,
  or waiting for the user to approve 2FA). Retries run in the background.
- connectivity_lost: the gateway is up but cut off from IBKR's servers; usually heals.
- not_connected: stopped, or the connection dropped and a retry is pending.
`hint` explains what to do. `trading_enabled` says whether the trading gate is open
(order tools also need `circuit_open` false: after repeated IBKR rejections the
circuit breaker halts order submits until a human resets it). `api_read_only` means
the gateway's own settings reject orders. `is_paper` is true when the login only has
paper accounts. `market_data_type` is the data type requested for this session
(set_market_data_type changes it), and `subscriptions_used`/`subscriptions_max` show
how many streams are open. Pass probe=true to test the connection with a real
request (the state alone can lag behind a stalled socket).

The id identifies an introducing broker's white-labelled platform; it is empty for
most direct IBKR clients.

Account-scoped tools use `default_account` when called without an account. If it is
null, the login manages several accounts and you must pass one explicitly. Paper
accounts start with D. Accounts outside the server's allowlist are only counted
(`other_managed_accounts`), never named, and cannot be used.

`contract` must be one option (sec_type OPT or FOP with symbol, expiry, strike and
right, or its con_id; futures options also need their exchange, e.g. CME). Returns
`implied_vol` as a decimal (0.25 = 25%) and the greeks at that volatility (delta,
gamma, vega, theta, dividend present value). Useful for what-if pricing: pass a
hypothetical option or underlying price. Nothing is stored or streamed.

Errors: invalid_request when the contract is not an option or no volatility fits the
prices (e.g. an option price below intrinsic value); not_found or ambiguous_contract
when the option cannot be resolved (get_option_chain lists expiries and strikes);
request_timeout when IBKR does not answer within 4 seconds; ib_api_error if IBKR
refuses (it may want market data permissions for the option and its underlying).

`contract` must be one option (sec_type OPT or FOP with symbol, expiry, strike and
right, or its con_id; futures options also need their exchange, e.g. CME). Returns
`option_price` per share (multiply by the contract multiplier for the premium) and
the greeks (delta, gamma, vega, theta, dividend present value). Useful for
scenarios: vary volatility or underlying_price.

Errors: invalid_request when the contract is not an option, volatility looks like a
percent (above 10), or IBKR computed no price; not_found or ambiguous_contract when
the option cannot be resolved; request_timeout when IBKR does not answer within 4
seconds; ib_api_error if IBKR refuses (e.g. missing market data permissions).

Picks the chain for `expiration`, chooses strikes either in [strike_min, strike_max]
or the `strikes_around_atm` strikes nearest the underlying's price (taken from a
snapshot of the underlying), and returns for each option (both rights unless `right`
is set): bid/ask/last with sizes, volume, close, and IBKR's model greeks (implied_vol,
delta, gamma, vega, theta, und_price). Legs are sorted by strike, calls before puts.
`limit` caps the legs (strike and right pairs): default 20, max 40; `total` and
`truncated` say how many were selected (a range keeps the lowest strikes, ATM the
nearest). Strikes the chain lists but this expiration lacks are reported in
`skipped`, as are legs IBKR would not quote.

Market data: one snapshot per leg, using the connection's market data type (see
`market_data_type`; switch with set_market_data_type). Live quotes for US equity and
index options need IBKR's OPRA subscription for API use (plus the underlying's
exchange data; futures options need the futures exchange's data); without it, try
delayed data. Snapshots take a few seconds and up to about 11. For expiries and
strikes without quotes use get_option_chain; to stream one option use subscribe_quotes.

Errors: not_found (unknown underlying, expiration or strikes not listed, or no
underlying price: then pass strike_min/strike_max); invalid_request (bad arguments,
or several trading classes: pass trading_class); ib_api_error when no leg could be
quoted (the message names the subscription needed); subscription_limit when IBKR's
market-data lines are used up.

Sections:
- scan_codes: what a scan ranks by (e.g. TOP_PERC_GAIN, MOST_ACTIVE, HOT_BY_VOLUME),
  with the instrument types each supports.
- instruments: instrument types (e.g. STK for US stocks, IND.US, FUT.US).
- locations: markets and exchanges (e.g. STK.US.MAJOR, STK.NASDAQ), nested via parent.
- filters: filter tags for run_scanner's `filters` (e.g. avgVolumeAbove), with
  their value type and, for choice filters, the allowed values.
`query` matches codes and names (case-insensitive substring; for filters also the
filter group and category); `instrument` keeps only entries for that instrument
type. Default limit 50, at most 500; `total` says how many matched. The catalogue
is fetched once per gateway session, so the first call can take a few seconds.
Errors: not_found when nothing matches or the instrument type is unknown.

Example: top % gainers among US listed stocks above $5 is scan_code=TOP_PERC_GAIN,
instrument=STK, location_code=STK.US.MAJOR, above_price=5. Find other scan codes,
locations and filter tags with get_scanner_parameters. Each row has the rank
(1 = top) and the contract (with con_id, for quotes or orders).
Limits: at most 50 rows. IBKR allows 10 scanner subscriptions at a time; a run
uses one for a moment and always releases it. Scans need market data permissions
for the exchanges scanned.
Errors: not_found when nothing matches right now (loosen the filters, or the
market may be closed); ib_api_error with IBKR's message for an unknown scan code,
location or filter; subscription_limit when 10 scanner subscriptions are open.

Takes the same arguments as run_scanner. Read the current rows with
get_subscription_data(subscription_id): rows (best first), updated_at, no_matches
(nothing qualifies right now) and error. Stop it with unsubscribe; it is also
cancelled after the idle time in idle_ttl_s without a read. The same scan asked
for twice returns the existing handle (deduplicated=true).
Limits: at most 50 rows; IBKR allows 10 scanner subscriptions at a time.
Errors: ib_api_error when IBKR rejects the scan (check the codes with
get_scanner_parameters); subscription_limit when no slot is free.