Bond Universe
Retrieves thousands of individual US dollar bonds with their price, yield to maturity, modified duration and spread over Treasuries, read from the holdings of bond ETFs.
Individual bond prices are not published for free, but bond ETFs publish their holdings every day: each bond’s coupon and maturity (in its name), its par amount and its market value, from which the price follows. By default this reads the iShares iBoxx $ Investment Grade Corporate Bond ETF (LQD), the iShares 0-5 Year Investment Grade Corporate Bond ETF (IGSB) and the iShares Broad USD High Yield Corporate Bond ETF (USHY): together about 8,000 investment grade and high yield corporate bonds. A bond held by several funds is listed once, with the funds that hold it.
The formula is as follows:
\[\text{Price} = \text{Market Value} / \text{Par Amount} \cdot 100 (a \;\text{clean price per}\; 100 \;\text{of par})\] \[\text{Yield to Maturity:}\;\; \text{the rate y at which the coupons and principal},\;\; \text{discounted at} (1 + y / 2) \text{per half year},\;\; \text{are worth the clean price plus accrued interest (see get\_yield\_to\_maturity)}\] \[\text{Modified Duration} = \text{Macaulay Duration} / (1 + y / 2) (\text{see}\; \text{get\_duration})\] \[\text{G-Spread} = \text{Yield to Maturity} - \text{Treasury Par Yield at the bond's maturity}\]Coupons are semi-annual, the US convention for corporate bonds, and the yield is a nominal annual rate compounded twice a year (bond-equivalent), like the Treasury par yields it is compared with. The coupon periods fall on the bond’s actual coupon dates, counted back from maturity, and the time in the current period is counted in actual days. The Treasury par yield at a maturity is interpolated linearly between the maturities of the US Treasury par yield curve on the price date (held at the 1-month and 30-year yield beyond them).
Also known as: corporate bond prices, bond yields, bond screener, credit spreads per bond, G-spread.
Bond Universe in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_bond_universe as shown below.
from financetoolkit import FixedIncome
fixedincome = FixedIncome(api_key="FINANCIAL_MODELING_PREP_KEY")
bonds = fixedincome.get_bond_universe(issuer="APPLE INC")
bonds[["Coupon", "Maturity", "Price", "Yield to Maturity", "Modified Duration", "G-Spread"]].head()
Or, after setting up the Finance Toolkit MCP, ask:
What did Apple's bonds maturing by the end of 2028 yield, and at which spread over Treasuries did they trade?
Which returns:
| ISIN | Coupon | Maturity | Price | Yield to Maturity | Modified Duration | G-Spread |
|---|---|---|---|---|---|---|
| US037833EC07 | 0.012 | 2028-02-08 | 95.96 | 0.0454 | 1.2213 | 0.0021 |
| US037833ET32 | 0.04 | 2028-05-10 | 99.12 | 0.0461 | 1.4224 | 0.0024 |
| US037833EY27 | 0.04 | 2028-05-12 | 99.09 | 0.0463 | 1.4275 | 0.0025 |
| US037833EH93 | 0.014 | 2028-08-05 | 94.67 | 0.046 | 1.6896 | 0.0019 |
| US037833FD70 | 0.0465 | 2028-11-09 | 99.95 | 0.0468 | 1.8564 | 0.0022 |
Parameters
get_bond_universe accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
etfs | list[str] | str | None | The bond ETFs to read the holdings of, as a list or a comma-separated string. The holdings must name each bond as “ISSUER COUPON% MM/DD/YYYY” with a par amount, as iShares funds do. Defaults to None, which uses LQD, IGSB and USHY. | None, which uses LQD, IGSB and USHY |
issuer | list[str] | str | None | Keeps the bonds whose issuer contains this text (case-insensitive), e.g. “APPLE” or “JPMORGAN”, or any of several. Defaults to None, every issuer. | None, every issuer |
maturity_start | str | None | Keeps the bonds maturing on or after this date (YYYY-MM-DD). Defaults to None. | None |
maturity_end | str | None | Keeps the bonds maturing on or before this date (YYYY-MM-DD). Defaults to None. | None |
bonds | list[str] | str | None | Keeps the bonds with these ISINs or CUSIPs, as a list or a comma-separated string. Defaults to None, every bond. | None, every bond |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the class. | 2 |