Check if the yield curve is inverted

Do it with the API

Subtract the shorter maturity's yield from the longer maturity's yield. For the usual test, keep the order as 10-year minus 2-year: a negative result means the 2-year yield is higher. The Python script also calculates the 10-year minus 3-month spread so you can read both comparisons from the same curve.

The US curve includes maturities 1m, 1.5m, 2m, 3m, 4m, 6m, 1y, 2y, 3y, 5y, 7y, 10y, 20y and 30y. Use the maturity labels to select the yields for your calculation. The response contains both the shorter and longer maturities used in the common inversion tests, as well as the other points on the US curve.

1. Get your API key Get a free key and keep it in the environment variable NARWHAL_API_KEY. Requests use Authorization: Bearer YOUR_KEY; REST and MCP share the same key.
2. Fetch the US curve and calculate the spreads Use GET /v1/economics/USA/yield-curve to read the curve's date, curve_type and yields. The script reads each maturity and yield_percent, then prints the date, both spreads in basis points and the result of comparing the 2-year yield with the 10-year yield.
   Python, the 10-year minus 2-year spread

   import os
   import requests
   
   curve = requests.get("https://api.narwhalapi.com/v1/economics/USA/yield-curve",
                        headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}, timeout=10).json()
   y = {row["maturity"]: float(row["yield_percent"]) for row in curve["yields"]}
   print("curve date", curve["date"])
   print("10y - 2y  =", round((y["10y"] - y["2y"]) * 100), "bp")
   print("10y - 3m  =", round((y["10y"] - y["3m"]) * 100), "bp")
   print("inverted (2y > 10y):", y["2y"] > y["10y"])

3. Read the sign alongside the date A spread below zero means the selected pair is inverted. Keep the printed curve date with the result, and name the maturities you compared when you describe it. The final line uses 2y > 10y, which is the same condition as a negative 10-year minus 2-year spread.
4. Select a day or maturity when needed Use date to select a day, or the optional maturity filter to return one maturity. Leave the maturity filter out when you want both yields in the same response, as the script does. The US response has curve_type set to nominal_par. For a historical range, use the history endpoint with each maturity you need. A range that ends entirely before the plan window returns 403 plan_upgrade_required. Reading a single date or period outside the window also returns that error. A range that starts before the window and reaches into it begins at the window’s first day without an error.

Do it in a sheet or without code

The Narwhal bond yields pages show the curve and spread. Open economics for the page route, or use a spreadsheet if you want to subtract the yields yourself. Keep the curve date with the values you copy so the result refers to a named published day.

Put the 10-year yield in B10 and the 2-year yield in B8, using the yield numbers as returned by the API. Subtract with the formula below. Its result is in percentage points; multiply that result by 100 to express the spread in basis points. Preserve the subtraction order when you move the values to other cells.

=B10-B8

Which option to use when

History uses GET /v1/economics/USA/yield-curve/history?start=...&end=...&maturity=..., subject to the history window in plans and limits. A start before that window moves up to its first day, so the response begins later than requested.

Which spread is the inversion test?

The common tests are 10-year minus 2-year and 10-year minus 3-month, and they can disagree. Name the pair alongside the result because the phrase "the curve is inverted" leaves the shorter maturity unspecified. Each test compares the 10-year yield with its own shorter maturity.

On 23 October 2026, the US 10-year minus 2-year spread was +31 bp and the 10-year minus 3-month spread was +78 bp. Both were positive. Other countries have different maturities: the UK curve starts at 0.5y and has half-year steps, so read the maturity labels returned for the country you request.

How fresh is the yield curve?

The response's date is the latest published day, and weekends and holidays have no new curve. The US example is dated Friday, 23 October 2026. Use the date in the response when you label a spread; the day you request the data can differ from the curve's published day.

Is a basis point a hundredth of a percentage point?

Yes, a basis point is a hundredth of a percentage point. Subtracting yields expressed in percent gives a difference in percentage points. Multiply that difference by 100 for basis points, keeping its sign. On 23 October 2026, the US 10-year minus 2-year difference of 0.31 percentage points equalled 31 bp.

Worked example: 23 October 2026

On 23 October 2026, the US curve had a 10-year yield of 5.00%, a 2-year yield of 4.69% and a 3-month yield of 4.22%. Start with the 10-year yield for each subtraction. Use the 2-year yield for the usual test, then repeat with the 3-month yield for the other common comparison.

For 23 October 2026, subtract 4.69% from 5.00% to get 0.31 percentage points. Multiply 0.31 by 100 to get 31 bp. The positive sign means the 10-year yield was higher than the 2-year yield, so that pair was not inverted. For the same date, subtract 4.22% from 5.00% to get 0.78 percentage points, then multiply by 100 to get 78 bp for the 10-year minus 3-month spread.

On 23 October 2026, the US 20-year yield was 5.37% and the 30-year yield was 5.33%. Those maturities are also part of the returned curve. The calculations here use the 10-year yield with the 2-year and 3-month yields for the common inversion tests.