You need reliable, developer-friendly access to the United States 10-year Treasury yield for dashboards, risk models, and research. By the end of this article, you will query US 10Y yields from Bonds-API, fetch intraday snapshots, build a yield curve, compute spreads, and wire everything into Python, JavaScript, and PHP with caching-aware, production-ready patterns.
What the US 10Y yield tells you
The US 10-year Treasury yield anchors global fixed-income pricing and discount rates. It drives mortgage rates, equity risk premia, and curve shape analytics (steepening, flattening, inversion). Whether you’re building a portfolio tool or running macro research, you’ll typically track:
- Level: today’s 10Y yield and its changes over time.
- Curve shape: how 10Y compares with 1Y, 2Y, 5Y, 30Y (steep or inverted).
- Cross-country spreads: US 10Y vs. German Bund 10Y in basis points.
- Intraday dynamics: snapshots around events (auctions, CPI, FOMC).
Bonds-API delivers sovereign yields as JSON over HTTPS with a simple REST surface. Explore the docs and tools on bonds-api.com and test requests in Bonds API MCP. You can Register for Bonds API or Get started with Bonds API when you’re ready.
Conventions you’ll use in production
- Base URL: https://bonds-api.com/api/v1/ (GET only).
- Authentication: supply your key in the X-API-Key header; never in the query string.
- Units: yields are percentages (for example 4.52 means 4.52%). Spreads are in basis points (bps).
- Dates and times: dates are ISO 8601 (YYYY-MM-DD). Intraday timestamps are UTC in ISO 8601 (e.g., 2026-09-28T12:00:00Z).
- Business days: sovereign yields are published on trading days; expect gaps on US federal market holidays and weekends. Use the “date” field in responses to know the effective market date of each figure.
- Caching: cache latest endpoints for a few minutes to reduce 429 rate-limit errors; cache time series longer. Always check the “date” field to detect recycled data on holidays.
All examples below focus on United States (ISO2: US) and, where relevant, the 10Y maturity.
Endpoint: Latest yields for US 10Y (and peers)
Use /latest to fetch the current day’s yields. You can request 10Y alone or multiple maturities to build a mini-curve on the fly.
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/latest?countries=US&maturities=2Y,10Y"Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "US", "maturities": "2Y,10Y"}
)
data = resp.json()
us10 = data["data"]["US"]["10Y"]["yield"]
asof = data["data"]["US"]["10Y"]["date"]
print("US 10Y:", us10, "as of", asof)JavaScript
async function fetchLatest() {
const url = "https://bonds-api.com/api/v1/latest?countries=US&maturities=2Y,10Y";
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await resp.json();
const tenY = json.data.US["10Y"].yield;
const asOf = json.data.US["10Y"].date;
console.log(`US 10Y = ${tenY}% as of ${asOf}`);
}
fetchLatest();PHP
<?php
$headers = [
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
];
$ctx = stream_context_create($headers);
$url = "https://bonds-api.com/api/v1/latest?countries=US&maturities=2Y,10Y";
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
$yield10 = $data["data"]["US"]["10Y"]["yield"];
$date10 = $data["data"]["US"]["10Y"]["date"];
echo "US 10Y: {$yield10}% on {$date10}\n";JSON response (illustrative)
{
"success": true,
"data": {
"US": {
"2Y": { "yield": 4.25, "date": "2026-09-28", "source": "official" },
"10Y": { "yield": 4.52, "date": "2026-09-28", "source": "official" }
}
}
}Fields: yield is a percent; date is market date (YYYY-MM-DD); source indicates provenance. For robustness, always check data.data.US["10Y"].date before showing “today.”
Endpoint: Historical US 10Y on a specific date
Use /historical to pin the 10Y yield to a single day, e.g., to align with portfolio valuation dates or economic releases.
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/historical?country=US&maturity=10Y&date=2025-06-15"Python
import requests
params = {"country": "US", "maturity": "10Y", "date": "2025-06-15"}
r = requests.get("https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
row = r.json()
print("US 10Y on", row["date"], "=", row["yield"], "%")JavaScript
async function onDate(date) {
const qs = new URLSearchParams({ country: "US", maturity: "10Y", date });
const resp = await fetch("https://bonds-api.com/api/v1/historical?" + qs.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const j = await resp.json();
return j.yield; // percentage
}
onDate("2025-06-15").then(v => console.log("US 10Y on 2025-06-15:", v));PHP
<?php
$params = http_build_query(["country" => "US", "maturity" => "10Y", "date" => "2025-06-15"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/historical?$params", false, $ctx);
$h = json_decode($json, true);
printf("US 10Y on %s = %.2f%%\n", $h["date"], $h["yield"]);JSON response (illustrative)
{
"success": true,
"country": "US",
"maturity": "10Y",
"date": "2025-06-15",
"yield": 4.38,
"source": "official"
}Fields: yield in percent; date in YYYY-MM-DD. If the specific date is a holiday, expect a 404; handle this by searching backward to the previous business day in your code.
Endpoint: US 10Y time series for analytics
Use /timeseries to compute rolling changes, vol, and drawdowns. Values are business-day steps between start and end inclusive (when data exists).
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/timeseries?country=US&maturity=10Y&start=2025-09-28&end=2026-09-28"Python
import requests
import statistics
p = {"country": "US", "maturity": "10Y", "start": "2025-09-28", "end": "2026-09-28"}
j = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p).json()
series = [pt["yield"] for pt in j["series"]]
chg = series[-1] - series[0]
print("Points:", len(series), "Change:", round(chg, 2), "pp")JavaScript
async function series10Y(start, end) {
const qs = new URLSearchParams({ country: "US", maturity: "10Y", start, end });
const resp = await fetch("https://bonds-api.com/api/v1/timeseries?" + qs, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const j = await resp.json();
return j.series.map(p => [p.date, p.yield]); // [YYYY-MM-DD, percent]
}
series10Y("2025-09-28", "2026-09-28").then(rows => console.log(rows.length, "rows"));PHP
<?php
$params = http_build_query([
"country" => "US", "maturity" => "10Y",
"start" => "2025-09-28", "end" => "2026-09-28"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$params", false, $ctx);
$data = json_decode($json, true);
foreach ($data["series"] as $pt) {
echo $pt["date"] . "," . $pt["yield"] . "\n";
}JSON response (illustrative)
{
"success": true,
"country": "US",
"maturity": "10Y",
"series": [
{ "date": "2025-01-02", "yield": 4.21 },
{ "date": "2025-01-03", "yield": 4.19 },
{ "date": "2025-01-06", "yield": 4.23 }
]
}Fields: series is an array of date-yield pairs; yields are percentages. Always use server dates for time alignment and holiday gaps.
Endpoint: Spread vs. benchmark (US 10Y vs. DE 10Y)
Use /spread to compute yield differentials. For US vs. Germany at 10Y, you get spread in basis points plus the underlying yields.
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/spread?country=US&benchmark=DE&maturity=10Y"Python
import requests
q = {"country": "US", "benchmark": "DE", "maturity": "10Y"}
s = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"}, params=q).json()
print("US-DE 10Y spread:", s["spread_bps"], "bps",
"| US:", s["country_yield"], "% | DE:", s["benchmark_yield"], "%")JavaScript
async function spreadUSDE() {
const qs = new URLSearchParams({ country: "US", benchmark: "DE", maturity: "10Y" });
const r = await fetch("https://bonds-api.com/api/v1/spread?" + qs.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const j = await r.json();
return j.spread_bps; // integer basis points
}
spreadUSDE().then(bps => console.log("Spread:", bps, "bps"));PHP
<?php
$params = http_build_query(["country" => "US", "benchmark" => "DE", "maturity" => "10Y"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/spread?$params", false, $ctx);
$d = json_decode($json, true);
printf("US-DE 10Y spread: %d bps (US %.2f%% vs DE %.2f%%)\n",
$d["spread_bps"], $d["country_yield"], $d["benchmark_yield"]);JSON response (illustrative)
{
"success": true,
"country": "US",
"benchmark": "DE",
"maturity": "10Y",
"spread_bps": 215,
"country_yield": 4.52,
"benchmark_yield": 2.37
}Fields: spread_bps is in basis points (1 bp = 0.01%). country_yield and benchmark_yield are percentages. You can compute approximate price sensitivity comparisons or FX-hedged carry on top.
Endpoint: Full US yield curve (build and visualize)
/curve returns multiple maturities for the latest available date (or a supplied date). This is your one-shot call for building a US Treasury curve and checking inversion.
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/curve?country=US"Python
import requests
j = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "US"}).json()
curve = j["curve"] # dict: maturity -> yield in percent
print("As of", j["date"], "| inverted:", j.get("inverted"))
print(curve)JavaScript
async function fetchCurve() {
const resp = await fetch("https://bonds-api.com/api/v1/curve?country=US", {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const j = await resp.json();
return j; // { date, inverted, curve: { "1M": 5.31, ... } }
}
fetchCurve().then(c => console.log("Curve date:", c.date, "Inverted:", c.inverted));PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/curve?country=US", false, $ctx);
$j = json_decode($json, true);
echo "Date: " . $j["date"] . " Inverted: " . ($j["inverted"] ? "true" : "false") . PHP_EOL;
foreach ($j["curve"] as $tenor => $y) { echo $tenor . ": " . $y . "%" . PHP_EOL; }JSON response (illustrative)
{
"success": true,
"country": "US",
"date": "2026-09-28",
"inverted": false,
"curve": {
"1M": 5.31, "3M": 5.27, "6M": 5.18,
"1Y": 4.98, "2Y": 4.25, "5Y": 4.39,
"10Y": 4.52, "30Y": 4.71
}
}Fields: curve is a map of maturity codes to yields in percent. inverted is a boolean derived from short vs. long slope. date is the market date of the curve.
| Maturity | Yield (%) |
|---|---|
| 1M | 5.31 |
| 3M | 5.27 |
| 6M | 5.18 |
| 1Y | 4.98 |
| 2Y | 4.25 |
| 5Y | 4.39 |
| 10Y | 4.52 |
| 30Y | 4.71 |
Endpoint: Intraday US 10Y snapshots
Use /intraday to track within-day moves (UTC timestamps). Combine with your event calendar and throttle calls with short caching (e.g., 60–120s) during calm periods.
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/intraday?country=US&maturity=10Y&date=2026-09-28"Python
import requests
from datetime import datetime
q = {"country": "US", "maturity": "10Y", "date": "2026-09-28"}
j = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"}, params=q).json()
rows = j["snapshots"]
rows.sort(key=lambda r: r["fetched_at"]) # ISO 8601 UTC
for s in rows:
t = datetime.fromisoformat(s["fetched_at"].replace("Z", "+00:00"))
print(t.isoformat(), s["yield"])JavaScript
async function intraday10Y(date) {
const qs = new URLSearchParams({ country: "US", maturity: "10Y", date });
const r = await fetch("https://bonds-api.com/api/v1/intraday?" + qs, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const j = await r.json();
return j.snapshots.map(s => ({ t: new Date(s.fetched_at), y: s.yield }));
}
intraday10Y("2026-09-28").then(rows => console.log("Points:", rows.length));PHP
<?php
$params = http_build_query(["country" => "US", "maturity" => "10Y", "date" => "2026-09-28"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/intraday?$params", false, $ctx);
$d = json_decode($json, true);
foreach ($d["snapshots"] as $s) {
echo $s["fetched_at"] . "Z," . $s["yield"] . "," . $s["source"] . PHP_EOL;
}JSON response (illustrative)
{
"success": true,
"country": "US",
"maturity": "10Y",
"date": "2026-09-28",
"snapshots": [
{ "yield": 4.51, "fetched_at": "2026-09-28T09:30:00Z", "source": "market" },
{ "yield": 4.53, "fetched_at": "2026-09-28T12:00:00Z", "source": "market" },
{ "yield": 4.52, "fetched_at": "2026-09-28T15:30:00Z", "source": "market" }
],
"count": 3,
"meta": { "timezone": "UTC" }
}Fields: snapshots[].yield is a percent; fetched_at is UTC ISO 8601. Use meta.timezone to format locally if needed.
Endpoint: Fluctuation of US 10Y over a period
/fluctuation summarizes start, end, change, min, and max for a period—ideal for sparkline annotations and risk dashboards.
Request
curl -H "X-API-Key: YOUR_API_KEY" \
"https://bonds-api.com/api/v1/fluctuation?countries=US&maturity=10Y&start=2025-09-28&end=2026-09-28"Python
import requests
p = {"countries": "US", "maturity": "10Y", "start": "2025-09-28", "end": "2026-09-28"}
j = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"}, params=p).json()
row = j["data"]["US"]
print("Δ:", row["change"], "pp | min:", row["min"], "% | max:", row["max"], "%")JavaScript
async function fluctUS(start, end) {
const qs = new URLSearchParams({ countries: "US", maturity: "10Y", start, end });
const r = await fetch("https://bonds-api.com/api/v1/fluctuation?" + qs, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const j = await r.json();
return j.data.US; // {start_yield, end_yield, change, min, max}
}
fluctUS("2025-09-28", "2026-09-28").then(s => console.log(s));PHP
<?php
$params = http_build_query([
"countries" => "US", "maturity" => "10Y",
"start" => "2025-09-28", "end" => "2026-09-28"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/fluctuation?$params", false, $ctx);
$fx = json_decode($json, true)["data"]["US"];
echo "Start: {$fx["start_yield"]}% End: {$fx["end_yield"]}% Change: {$fx["change"]}pp\n";JSON response (illustrative)
{
"success": true,
"maturity": "10Y",
"start": "2025-09-28",
"end": "2026-09-28",
"data": {
"US": {
"start_yield": 4.21,
"end_yield": 4.52,
"change": 0.31,
"min": 3.87,
"max": 4.76
}
}
}Fields: change is in percentage points (end minus start). min/max are extremes within the period.
Error handling and operational patterns
All endpoints return a standard error shape when something goes wrong: {"success": false, "error": "..."} with HTTP codes such as 401 (missing/invalid key), 403 (quota), 404 (no data for the combination), 422 (invalid parameter), 429 (rate limit), 500 (server).
- Retry policy: only retry idempotent GETs on 429 and 500 with exponential backoff; do not retry on 401/403/422 without fixing the request.
- Holiday logic: when you get 404 for a given date, step back to the previous business day or use /latest and rely on its date field.
- Caching: cache /curve and /latest for a short TTL; cache /timeseries and /fluctuation by (country, maturity, start, end) keys with long TTL.
Explore additional operational tips on bonds-api.com and experiment interactively in MCP.
One real JSON sample you may see in logs
The following is a real JSON payload you might capture in your monitoring or logging context while working with yield data. Treat it as a standalone example of JSON parsing and timestamp handling; always build against the documented endpoint contracts shown above.
{"success":true,"date":"2026-09-28","rates":{"US_10Y":5.227},"dates":{"US_10Y":"2026-09-28"},"currencies":{"US_10Y":"USD"},"meta":{"request_id":"dd03f66b-b09d-41b4-bbe5-08265f14f387","timestamp":"2026-09-28T14:08:45+00:00"}}Hints: rates.US_10Y is a percent yield; meta.timestamp is an ISO 8601 timestamp with timezone offset; currencies clarify the base currency label.
Putting it together: building a US 10Y dashboard
- Header: /latest for US 10Y and 2Y; display both with dates and a small Δ from /fluctuation over 1D/1W/1M.
- Chart: /timeseries for US 10Y over your selected horizon; sample every business day.
- Curve panel: /curve (US) for today’s curve; mark inverted state and 10Y-2Y slope.
- Cross-market: /spread vs DE at 10Y for macro context.
- Event watch: /intraday snapshots on key dates; cache briefly and annotate FOMC or CPI times.
Keep your API key in a secure store and inject it into the X-API-Key header in all calls. For more examples and SDK patterns, check bonds-api.com and the Bonds API MCP.
Troubleshooting quick reference
- 401 or 403: ensure the X-API-Key header is present and valid.
- 404 on specific date: it may be a holiday; step back to the previous business day or use /latest.
- 422: check ISO2 country and maturity codes (e.g., US and 10Y) and date format (YYYY-MM-DD).
- 429: add client-side caching and backoff; aggregate multi-maturity requests with /curve or multi-maturity query on /latest rather than separate calls.
- 500: retry with jitter; log request params for support.
FAQ
How are yields expressed across endpoints?
All yield values are percentages. For example, 4.52 in a response means 4.52%. Spread endpoints return basis points (bps), where 100 bps = 1.00%.
What timezone should I assume for dates and timestamps?
Calendar dates are trading dates in YYYY-MM-DD with no timezone offset. Intraday timestamps are UTC ISO 8601 (e.g., 2026-09-28T12:00:00Z). Always display the returned date next to the value.
How do I handle US market holidays?
Expect no new daily data on holidays and weekends. If a /historical call returns 404 for a holiday, your code can iterate backward to the most recent available business day or fall back to /latest and its date field.
Can I get a full US yield curve in one call?
Yes. Use /api/v1/curve?country=US for the latest available date (or add a date parameter). The response includes a maturity-to-yield map and an inverted flag.
What’s the best way to compute daily change for a headline?
Call /fluctuation with start as the previous business day and end as today. Use the change field (percentage points) and show the end_yield as your current level.
Ready to integrate US 10Y yields into your Finance applications? Get an API key and ship your first endpoint call in minutes: Register and explore interactive tooling in MCP.
