Initiate a Flex query. Returns a reference_code to use with flex_get_statement.

Args: query_id: Flex Query ID (overrides IBKR_FLEX_QUERY_ID env var). token: Flex API token (overrides IBKR_FLEX_TOKEN env var).

Returns JSON: {"reference_code": "...", "status": "..."}

Download a completed Flex report using its reference code.

Polls automatically until the report is ready or the timeout is reached.

Args: reference_code: Reference code returned by flex_send_request. token: Flex API token (overrides IBKR_FLEX_TOKEN env var). poll_interval_seconds: Seconds between polling attempts (default 5). max_wait_seconds: Maximum seconds to wait for the report (default 120).

Returns JSON: {"xml_content": "<FlexQueryResponse...>..."}

Send a Flex query and wait for the complete XML report.

Combines flex_send_request + flex_get_statement in one call.

Args: query_id: Flex Query ID (overrides IBKR_FLEX_QUERY_ID env var). token: Flex API token (overrides IBKR_FLEX_TOKEN env var). poll_interval_seconds: Seconds between polling attempts (default 5). max_wait_seconds: Maximum seconds to wait for the report (default 120).

Returns JSON: {"xml_content": "<FlexQueryResponse...>..."}

Extract account metadata from a Flex XML report.

Args: xml_content: Raw Flex XML string (from flex_run_query or flex_get_statement).

Returns JSON array of account info objects, one per FlexStatement in the report.

Extract trade records from a Flex XML report.

Args: xml_content: Raw Flex XML string. symbol: Filter by ticker symbol (case-insensitive, optional). asset_category: Filter by asset category e.g. STK, OPT, FUT (optional). from_date: Earliest trade date to include, YYYY-MM-DD (optional). to_date: Latest trade date to include, YYYY-MM-DD (optional).

Returns JSON: {"count": N, "trades": [...]}

Extract open position records from a Flex XML report.

Args: xml_content: Raw Flex XML string. symbol: Filter by ticker symbol (case-insensitive, optional). asset_category: Filter by asset category e.g. STK, OPT, FUT (optional).

Returns JSON: {"count": N, "positions": [...]}

Extract cash transaction records from a Flex XML report.

Common transaction_type values: Dividends, "Withholding Tax", "Broker Interest Paid", "Broker Interest Received", "Other Fees".

Args: xml_content: Raw Flex XML string. transaction_type: Filter by transaction type substring (case-insensitive, optional). symbol: Filter by symbol (optional). from_date: Earliest date, YYYY-MM-DD (optional). to_date: Latest date, YYYY-MM-DD (optional).

Returns JSON: {"count": N, "total_amount": "...", "transactions": [...]}

Extract daily NAV / equity summary rows from a Flex XML report.

Args: xml_content: Raw Flex XML string. from_date: Earliest report date, YYYY-MM-DD (optional). to_date: Latest report date, YYYY-MM-DD (optional).

Returns JSON: {"count": N, "equity_summary": [...]}

Extract FIFO realized/unrealized P&L summary from a Flex XML report.

Args: xml_content: Raw Flex XML string. symbol: Filter by ticker symbol (case-insensitive, optional). asset_category: Filter by asset category e.g. STK, OPT, FUT (optional).

Returns JSON: {"count": N, "total_realized": "...", "total_unrealized": "...", "rows": [...]}

Aggregate realized P&L from trade records in a Flex XML report.

Only closing trades (open_close contains 'C') contribute to realized P&L.

Args: xml_content: Raw Flex XML string. group_by: Dimension to aggregate by — "symbol", "month", "year", "asset_category", or "buy_sell" (default "symbol"). asset_category: Filter by asset category e.g. STK, OPT, FUT (optional). from_date: Earliest trade date, YYYY-MM-DD (optional). to_date: Latest trade date, YYYY-MM-DD (optional).

Returns JSON with totals and a breakdown list sorted by realized_pnl descending.

Summarize dividend income and withholding taxes from cash transactions.

Args: xml_content: Raw Flex XML string.

Returns JSON with total gross dividends, total withholding tax, net dividends, and a per-symbol breakdown.

Calculate free cash as a percentage of Net Liquidation Value (Net Liq), after deducting cash reserved for short (sold) put obligations.

When a put is sold, the seller must be able to purchase the underlying if assigned. The worst-case cash reservation per contract is:

strike × multiplier × |quantity|

This tool answers: "Of my total Net Liq, how much of my cash is actually free — not spoken for by open short-put assignments?"

Uses the most recent equity-summary row for Net Liq and cash, and the current open-positions snapshot for short puts.

Returns JSON: net_liq — total portfolio value in base currency gross_cash — cash balance from equity summary reserved_for_puts — worst-case assignment obligation of all short puts free_cash — gross_cash − reserved_for_puts free_cash_pct_net_liq — free_cash / net_liq × 100 (the headline %) cash_pct_net_liq — gross_cash / net_liq × 100 (for reference) currency — base currency of the account as_of_date — equity summary report date used short_puts — per-position breakdown of the reservation

Show how the portfolio NAV changed over time and compute a return figure.

Return methods

twr (default) — Time-Weighted Return via daily chain-linking. Eliminates the timing/size effect of external cash flows. Use this to evaluate the strategy independent of cash-flow decisions.

mwr — Money-Weighted Return via Modified Dietz. Reflects the investor's actual experience: large deposits before a rally boost the return; large withdrawals before a rally reduce it. Use this to evaluate overall portfolio performance.

Args: xml_content: Raw Flex XML string. metric: Which equity component to track — "total", "cash", "stock", "options", "futures", "bonds" (default "total"). return_method: "twr" (default) or "mwr".

Returns JSON with a time-series, annualised and period returns, and the total net external cash flow over the period.