Yield curve inversion: what it is and how to track it by API

A yield curve inversion happens when short-term government bond yields rise above long-term yields, so the curve that normally slopes upward turns down. The most watched measure is the 2s10s spread, the 10-year Treasury yield minus the 2-year: below zero, the curve is inverted. Economists also track the 3-month to 10-year spread, which has the longer research record as a recession warning.

This explainer covers what the curve shows, why it inverts, what inversions have and have not predicted, and how to track the spreads in code from daily bond yields. It belongs to the market data API series: bonds use the same key, host and conventions as every other asset class.

The US Treasury yield curve on one chart

The yield curve plots the yield of government bonds against their time to maturity, from one month to thirty years. Normally it slopes up: lenders ask for more to tie money up for longer, because more can go wrong over thirty years than over three months.

On that date the curve sloped upward almost all the way out: 4.04% at one month, 4.81% at two years, 5.17% at ten, with a small dip between 20 and 30 years (5.54% and 5.49%). Not inverted by any of the common measures.

Normal, flat, inverted and humped curves

• NormalLong yields above short ones. Markets expect steady growth and ask a premium for time.
• FlatShort and long yields close together. Often a transition, as policy rates climb toward long-term yields.
• InvertedShort yields above long ones. Markets expect rates to fall, usually because they expect growth to slow.
• HumpedMiddle maturities highest, both ends lower. Common while a tightening cycle is peaking.

Why an inverted yield curve happens

Short and long yields answer to different forces. The short end tracks the central bank’s policy rate almost one for one. The long end reflects where investors expect short rates to be on average over the life of the bond, plus a term premium for the risk of holding it that long.

An inversion is the market saying that today’s tight policy will not last, usually because it expects the economy to weaken enough for rates to come down. Banks dislike it for a more direct reason: they borrow short and lend long, so an inverted curve squeezes their margins and can tighten credit. That is one channel through which the warning helps cause what it warns about.

The 2s10s spread and other ways to measure it

Spreads are quoted in basis points, hundredths of a percentage point, because yield differences are small. One field catches people in code: the snapshot’s change_percent is the relative move of the yield itself (−0.19% when the 10-year went from 5.18 to 5.17), not a move in percentage points. For spreads and daily changes, work with rate and change_bps.

What inversions have and have not predicted

1. 12006 to 2007The curve inverted as policy rates peaked in 2006. The recession that began at the end of 2007 followed well over a year later.
2. 22019The 3m10y spread inverted in the spring and 2s10s briefly in August. A recession arrived in early 2020, driven by the pandemic rather than the credit cycle the curve was pricing.
3. 32022 to 20242s10s inverted in July 2022 and stayed below zero for about two years, the longest stretch in decades, without the prompt recession many expected.

The research record behind the indicator is strong: an inverted 3m10y spread has preceded every US recession since the late 1960s, typically by 6 to 24 months, with few false alarms. The weakness is timing. The lead is too long and too variable to act on mechanically, and the 2022 to 2024 episode showed that other forces, such as strong household balance sheets and heavy government borrowing, can delay or soften the outcome. Treat an inversion as a change in the odds, not a countdown.

Track the yield curve by API

TickerLayer bond yields are daily observations: each one is a single published yield for a business day, carrying its date, not an intraday tick. GET /bond/last/{symbol} returns the latest observation, and GET /bond/snapshot/{symbol} adds the previous one and the change between them. Symbols combine country and tenor, such as US:2Y and US:10Y, so the same two routes serve as a Treasury API and a European government bond API.

{
  "symbol": "US:10Y",
  "rate": 5.17,1
  "unit": "percent",
  "date": "2026-09-25",2
  "timestamp": 1790294400000,
  "prev_rate": 5.18,3
  "prev_date": "2026-09-24",
  "prev_timestamp": 1790208000000,
  "change": -0.01,
  "change_bps": -1,4
  "change_percent": -0.19315
}

Because timestamp is a date at UTC midnight, a Monday-morning request returns Friday’s observation with a timestamp that is days old, and that is correct. The Unix timestamp explainer covers converting these values safely.

The script below fetches the three legs, refuses to build a spread from observations with different dates, prints 2s10s and 3m10y for the latest and the previous day, and upserts one row per observation date into a CSV. Run it once a day from cron or any scheduler and the CSV becomes your 2s10s history. It needs Python 3.9 or newer and pip install requests.

import csv
import os
from pathlib import Path

import requests

API = "https://api.tickerlayer.com"
HEADERS = {"x-api-key": os.environ["TICKERLAYER_API_KEY"]}
HISTORY = Path("us_curve.csv")


def snapshot(symbol: str) -> dict:
    r = requests.get(f"{API}/bond/snapshot/{symbol}", headers=HEADERS, timeout=10)
    if r.status_code == 403:
        raise SystemExit("Bond yields are a data add-on: enable it for this key first.")
    r.raise_for_status()
    return r.json()


def spread_bps(long_leg: dict, short_leg: dict, field: str = "rate"):
    """Long yield minus short yield, in basis points (None if a leg is missing)."""
    if long_leg.get(field) is None or short_leg.get(field) is None:
        return None
    return round((long_leg[field] - short_leg[field]) * 100)


m3, y2, y10 = snapshot("US:3M"), snapshot("US:2Y"), snapshot("US:10Y")
if not (m3["date"] == y2["date"] == y10["date"]):
    raise SystemExit("Legs carry different observation dates; wait for all three to update.")

s2s10s, s3m10y = spread_bps(y10, y2), spread_bps(y10, m3)
print(f"Observation date {y10['date']} (previous {y10['prev_date']})")
print(f"3M {m3['rate']:.2f}%  2Y {y2['rate']:.2f}%  10Y {y10['rate']:.2f}%")
print(f"2s10s {s2s10s:+d} bps (previous {spread_bps(y10, y2, 'prev_rate'):+d})")
print(f"3m10y {s3m10y:+d} bps (previous {spread_bps(y10, m3, 'prev_rate'):+d})")
print("Inverted" if s2s10s < 0 else "Not inverted on 2s10s")

# One row per observation date: re-running on the same day overwrites, never duplicates.
rows = {}
if HISTORY.exists():
    with HISTORY.open() as f:
        rows = {row["date"]: row for row in csv.DictReader(f)}
rows[y10["date"]] = {"date": y10["date"], "us3m": m3["rate"], "us2y": y2["rate"],
                     "us10y": y10["rate"], "s2s10s_bps": s2s10s, "s3m10y_bps": s3m10y}
with HISTORY.open("w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=list(rows[y10["date"]].keys()))
    writer.writeheader()
    writer.writerows(rows[d] for d in sorted(rows))
print(f"{len(rows)} observation(s) stored in {HISTORY}")

Observation date 2026-09-25 (previous 2026-09-24)
3M 4.24%  2Y 4.81%  10Y 5.17%
2s10s +36 bps (previous +31)
3m10y +93 bps (previous +94)
Not inverted on 2s10s
1 observation(s) stored in us_curve.csv

The date check is the part people skip. Legs can publish at slightly different times, and a spread built from a Thursday 2-year and a Friday 10-year is wrong by a day’s move. Upserting by date also makes the job safe to repeat: running it twice on the same day overwrites the row instead of duplicating it.

Or subscribe once and let new observations arrive

On the WebSocket side, bonds.quotes replays the latest observation right after you subscribe, then sends one rate frame per symbol whenever a new observation is published. The frame format is in the WebSocket message reference.

Bond yields are a data add-on, priced at $39 a month on Individual and $349 on Business, and without it the bond routes answer 403. It covers the US curve from 1 month to 30 years and the German, Spanish, French, Italian and UK curves from 1 to 30 years; the bonds docs list every tenor and the data add-ons page the terms. Point the script at DE:2Y and DE:10Y and it tracks the German 2s10s (the European curves start at one year, so drop the 3-month leg), and IT:10Y minus DE:10Y gives the classic gauge of stress in euro-area bond markets.

A stored curve becomes more useful next to other series. Line it up with daily index or stock bars from the historical stock data guide to see how equities behaved around past inversions, or add the spreads to a correlation matrix.