fixed_income
Calculate bond and derivative valuations from bond terms and yield curves: duration, present value, yield to maturity, Z-spread, key rate duration, default probability, and option-adjusted spread.
Instructions
Bond and derivative valuation calculations (bond duration, present value, yield to maturity, derivative pricing, par yield, forward rate, breakeven inflation rate, key rate duration, yield curve spread, Z-spread, bond-equivalent yield, Taylor-series price change estimate). No tickers or countries needed — pass the bond's terms directly, e.g. par_value=1000, coupon_rate=0.05, years_to_maturity=10 with bond_price or yield_to_maturity. A bond's price is get_present_value. The curve-based calculations (par yield, forward rate, yield curve spread, Z-spread, key rate duration, breakeven inflation) take the curve as spot_rates (nominal_rates and real_rates for breakeven inflation), the decimal rate per maturity in years as a number (a curve column '10Y' becomes '10', '6M' becomes '0.5'), e.g. {'1': 0.042, '2': 0.040, '5': 0.041, '10': 0.043}; without it they use a fixed sample curve for illustration. Pass a zero-coupon (spot) curve, not a par curve: from the rates tool get_zero_coupon_curve (annually compounded), get_bank_of_england_yield_curve (UK, continuously compounded), the Euro Area and Germany curves of get_government_bond_yield_curve (continuously compounded zero curves; its other countries are par curves), get_hqm_corporate_bond_yield_curve with rate='spot' (US corporate, semi-annual bond-equivalent) or get_eiopa_risk_free_rate (annually compounded); get_treasury_rates is a par curve (semi-annual bond-equivalent) and only approximates one. Compounding assumed: par yield, Z-spread and key rate duration read the curve as nominal rates compounded frequency times a year, forward rate as annually compounded rates, and yield curve spread and breakeven inflation subtract the rates as given. Bond prices are clean prices; a maturity between coupon dates (2.5 years) discounts each cash flow over its fractional period. get_option_adjusted_spread values a callable bond on a Ho-Lee tree (bond_price, coupon_rate, years_to_maturity, call_price, years_to_first_call, volatility=0.01) and returns the OAS, the straight bond price, the option value and the effective duration and convexity; without spot_rates it uses the current US Treasury zero-coupon curve. get_implied_default_probability turns credit spreads (spreads=0.012 or 'BBB:0.011, B:0.031', recovery_rate=0.4, horizons='1,5,10') into hazard rates and default probabilities; without spreads it uses the latest ICE BofA spread per rating, which needs a FRED API key.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| guess | No | For get_yield_to_maturity: The initial guess for the yield to maturity. For get_z_spread: The initial guess for the Z-spread. Leave unset to use the default of the indicator you selected. Defaults are 0.01 for get_z_spread; 0.05 for get_yield_to_maturity. | |
| limit | No | The rows to return, like head and tail: 5 for the first five, -5 for the last five (the most recent of a time series). A table with its periods as columns (financial statements, ratios) keeps its first or last periods instead. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. | |
| model | No | The type of model to use for calculating the derivative price. | black |
| tenor | No | The tenor (length in years) of the underlying swap. | |
| spreads | No | The credit spread as a decimal (0.01 for 100 basis points), or several by name as a dictionary, Series or string such as "BBB:0.011, B:0.031". | |
| end_date | No | End of the date range in YYYY-MM-DD format. | 2026-10-27 |
| horizons | No | The horizons in years, as a list or a comma-separated string. | |
| maturity | No | The maturity (or maturities), in years, to calculate the breakeven inflation rate for. If not provided, a range of maturities will be used. | |
| notional | No | The notional amount of the derivative. | |
| countries | No | Country names, comma-separated or as a list, e.g. 'United States,Germany,Japan'. | |
| frequency | No | For get_duration, get_present_value: The frequency of coupon payments per year. For get_yield_to_maturity, get_par_yield, get_key_rate_duration, get_z_spread, get_taylor_price_change: The number of coupon payments per year. For get_option_adjusted_spread: The coupon payments per year. Leave unset to use the default of the indicator you selected. Defaults are 1 for get_duration, get_key_rate_duration, get_par_yield, get_present_value, get_taylor_price_change, get_yield_to_maturity, get_z_spread; 2 for get_option_adjusted_spread. | |
| indicator | Yes | Name of the specific metric to calculate, one of the listed values. Required — search_metrics finds the indicator (and its tool) for a metric by name. | |
| par_value | No | The par value of the bond. Leave unset to use the default of the indicator you selected. Defaults are 100 for get_duration, get_key_rate_duration, get_par_yield, get_present_value, get_taylor_price_change, get_yield_to_maturity, get_z_spread; 100.0 for get_option_adjusted_spread. | |
| quarterly | No | Return quarterly data instead of annual when True. | |
| tolerance | No | The tolerance level for convergence. | |
| bond_price | No | Clean price of the bond per 100 face value. Leave unset to use the default of the indicator you selected. Defaults are None for get_yield_to_maturity, get_z_spread; 100.0 for get_option_adjusted_spread. | |
| call_price | No | The price at which the issuer can call the bond, None for a bond without a call. | |
| real_rates | No | The real (inflation-protected) yield curve in decimals, indexed by maturity in years (a number, or a label such as '6M' or '10Y'). | |
| spot_rates | No | The zero-coupon curve (annually compounded) by maturity in years. | |
| start_date | No | Start of the date range in YYYY-MM-DD format. | 2021-10-28 |
| volatility | No | For get_derivative_price: The volatility of the underlying swap rate, quoted on the basis given by `volatility_type`. For get_option_adjusted_spread: The volatility of the short rate in absolute terms. | |
| coupon_rate | No | Annual coupon rate as a decimal, e.g. 0.05 for 5 %. Leave unset to use the default of the indicator you selected. Defaults are 0.05 for get_key_rate_duration, get_option_adjusted_spread, get_yield_to_maturity, get_z_spread; None for get_duration, get_present_value, get_taylor_price_change. | |
| is_receiver | No | True if the holder is the receiver of the derivative, False if the holder is the payer. | |
| strike_rate | No | Option strike price. | |
| far_maturity | No | The further maturity (or maturities), in years. If not provided, a range of far maturities will be used. | |
| forward_rate | No | The forward rate as derived from the swap curve. | |
| show_columns | No | Comma-separated names to filter the output. For historical data use the key names visible in any response record (e.g. 'Close,Volume,Return'). For financial statements use the 'metric' field values from the response (e.g. 'Revenue,Net Income,EBITDA'). Call the tool once without this parameter to see all available names, then repeat with show_columns to reduce response size and token usage. | |
| yield_change | No | For get_key_rate_duration: The size of the shock applied to each key rate, up and down (in decimal). For get_taylor_price_change: The hypothetical change in yield to maturity, e.g. 0.01 for a 100 basis point increase. Leave unset to use the default of the indicator you selected. Defaults are 0.0001 for get_key_rate_duration; 0.01 for get_taylor_price_change. | |
| duration_type | No | The type of duration to calculate. | modified |
| long_maturity | No | The longer maturity (or maturities), in years. If not provided, a range of long maturities will be used. | |
| near_maturity | No | The nearer maturity (or maturities), in years. If not provided, a range of near maturities will be used. | |
| nominal_rates | No | The nominal (non-inflation-protected) yield curve in decimals, indexed by maturity in years (a number, or a label such as '6M' or '10Y'). | |
| recovery_rate | No | The share of the face value recovered on default. | |
| discount_yield | No | The money-market discount yield of the instrument (in decimal). If not provided, a range of discount yields will be used. | |
| include_payoff | No | True to include the payoff in the output, False otherwise. | |
| max_iterations | No | The maximum number of iterations for convergence. | |
| risk_free_rate | No | The risk-free interest rate used to discount the swap's payment dates, read as a continuously compounded rate on a flat curve (discount factor exp(-r * t)). | |
| short_maturity | No | The shorter maturity (or maturities), in years. If not provided, a range of short maturities will be used. | |
| show_input_info | No | For get_derivative_price: True to display input information, False otherwise. For get_duration, get_present_value, get_yield_to_maturity, get_par_yield, get_forward_rate, get_breakeven_inflation_rate, get_key_rate_duration, get_yield_curve_spread, get_z_spread, get_bond_equivalent_yield, get_taylor_price_change: Whether to display input information. | |
| volatility_type | No | The convention `volatility` is quoted on, either 'lognormal' (relative to the forward rate) or 'normal' (absolute, in rate units). | |
| days_to_maturity | No | The number of days until the instrument matures. If not provided, a range of typical T-bill maturities will be used. | |
| key_rate_maturity | No | The maturity (or maturities), in years, of the curve point(s) to shock. Must be present in the index of `spot_rates`. | |
| payment_frequency | No | Number of fixed-leg payments per year on the underlying swap (e.g. 1 for annual, 2 for semi-annual, 4 for quarterly). | |
| years_to_maturity | No | Years remaining until the bond matures. Leave unset to use the default of the indicator you selected. Defaults are None for get_derivative_price, get_duration, get_key_rate_duration, get_par_yield, get_present_value, get_taylor_price_change, get_yield_to_maturity, get_z_spread; 10.0 for get_option_adjusted_spread. | |
| yield_to_maturity | No | For get_duration, get_present_value: The yield to maturity of the bond. For get_taylor_price_change: The current yield to maturity of the bond. | |
| years_to_first_call | No | The years until the bond can first be called. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |