Z-Spread
Calculates the zero-volatility spread (Z-spread) of individual bonds over the Treasury zero-coupon curve. The Z-spread is the constant spread that, when added uniformly to every point of the curve, makes the present value of the bond’s cash flows equal to its price.
Unlike a simple yield spread (the bond’s yield to maturity minus a Treasury yield of the same maturity, the G-spread of get_bond_universe), the Z-spread is measured against the entire curve rather than a single point, which makes it a more accurate measure of the compensation an investor receives for a bond’s credit and liquidity risk. For a Treasury it shows how far the issue trades off the curve, typically a few basis points.
The formula is as follows, solved for the Z-Spread with the secant method:
\[\text{Price} = \operatorname{SUM}(\text{Cash Flow} (t) / (1 + (\text{Spot Rate} (t) + \text{Z-Spread}) / 2) ^{2t}) - \text{Accrued Interest}\]Where each coupon is 100 * Coupon / 2, the principal is repaid with the last coupon, t is each remaining payment time in years on the bond’s actual coupon dates and Spot Rate(t) is the Treasury zero-coupon rate of the price date (get_zero_coupon_curve), restated from annual to semi-annual compounding, interpolated linearly between its maturities and held flat beyond its first and last maturity.
The bonds are selected as in collect_bond_statistics. TIPS have no Z-spread on the nominal curve. For a bond with an embedded option the Z-spread includes the option’s value, which an option-adjusted spread removes: the ICE BofA option-adjusted spreads of bond indices are in get_ice_bofa_option_adjusted_spread, and short_rate_model.get_option_adjusted_spread calculates one for a call schedule of your own. For terms of your own, use bond_model.get_z_spread.
Also known as: zero-volatility spread, static spread, credit spread.
Z-Spread in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_z_spread as shown below.
from financetoolkit import FixedIncome
fixedincome = FixedIncome(api_key="FINANCIAL_MODELING_PREP_KEY")
z_spreads = fixedincome.get_z_spread(
issuer="Apple", maturity_start="2030-01-01", maturity_end="2035-12-31"
)
z_spreads[["Issuer", "Coupon", "Maturity", "Price", "Price Date", "Z-Spread"]]
Or, after setting up the Finance Toolkit MCP, ask:
What Z-spread over the Treasury curve did Apple's bonds maturing from 2030 to 2035 trade at?
Which returns:
| Issuer | Coupon | Maturity | Price | Price Date | Z-Spread | |
|---|---|---|---|---|---|---|
| US037833EU05 | APPLE INC | 0.0415 | 2030-05-10 | 97.95 | 2026-11-05 | 0.0024 |
| US037833DU14 | APPLE INC | 0.0165 | 2030-05-11 | 89.69 | 2026-11-05 | 0.0033 |
| US037833EZ91 | APPLE INC | 0.042 | 2030-05-12 | 98.25 | 2026-11-05 | 0.002 |
| US037833DY36 | APPLE INC | 0.0125 | 2030-08-20 | 87.72 | 2026-11-05 | 0.0027 |
| US037833ED89 | APPLE INC | 0.0165 | 2031-02-08 | 87.78 | 2026-11-05 | 0.0029 |
| US037833EJ59 | APPLE INC | 0.017 | 2031-08-05 | 86.74 | 2026-11-05 | 0.0027 |
| US037833FG02 | APPLE INC | 0.049 | 2031-11-09 | 99.83 | 2026-11-05 | 0.0035 |
| US037833FA32 | APPLE INC | 0.045 | 2032-05-12 | 98.35 | 2026-11-05 | 0.0022 |
| US037833EP10 | APPLE INC | 0.0335 | 2032-08-08 | 92.53 | 2026-11-05 | 0.0022 |
| US037833EV87 | APPLE INC | 0.043 | 2033-05-10 | 95.84 | 2026-11-05 | 0.0038 |
| US037833FH84 | APPLE INC | 0.051 | 2033-11-09 | 99.77 | 2026-11-05 | 0.0044 |
| US037833FB15 | APPLE INC | 0.0475 | 2035-05-12 | 97.91 | 2026-11-05 | 0.0028 |
Parameters
get_z_spread accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
bonds | list[str] | str | None | CUSIPs or ISINs, see collect_bond_statistics. Defaults to None. | None |
issuer | list[str] | str | None | Part of an issuer’s name, such as “Apple”. Defaults to None. | None |
etfs | list[str] | str | None | The bond ETFs to select bonds from, see get_bond_universe. Defaults to None. | None |
maturity_start | str | None | The earliest maturity (YYYY-MM-DD). Defaults to None. | None |
maturity_end | str | None | The latest maturity (YYYY-MM-DD). Defaults to None. | None |
date | str | None | The day of the Treasury prices (YYYY-MM-DD). Defaults to None, the latest day with prices. | "2025-03-31" |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the class. | 2 |