You need the United States 10 Year Treasury yield in your own models, dashboards, and risk tools—updated reliably, queryable by date, and easy to combine with other tenors for a full curve. By the end of this guide, you’ll know exactly how to pull US 10Y yields (and related maturities) from the Bonds API, cache and interpret results, compute spreads, and assemble a curve suitable for fixed-income analytics and backtesting.
What the API returns and how to interpret it
The Bonds API serves sovereign bond yields as JSON over HTTPS. Yields are expressed as percentages (for example, 4.52 means 4.52%). When a field is named spread_bps, it is a spread in basis points (1 bp = 0.01%). Dates are returned as ISO 8601 calendar dates (YYYY-MM-DD), and timestamps in the meta object—where present—are ISO 8601 with timezone (UTC).
- Latest yields: most recent business day with an official close. On US market holidays or weekends, the latest date will be the most recent business day.
- Intraday snapshots: time-stamped, UTC-based observations collected during the trading day.
- Historical and time series endpoints: business-day calendaring; if a requested date is a holiday with no official close, you’ll receive a 404 for that specific date query (use the timeseries endpoint to navigate around non-trading days).
- Update frequency: intraday as snapshots; latest/historical/curve as daily official closes. Cache intraday responses more lightly (e.g., minutes), and daily endpoints by the trading day (e.g., until the next official close).
For documentation and environment details, visit bonds-api.com. If you want a ready-to-use sandbox and schema explorer, see the MCP. To obtain an API key and start testing, Register.
Quick sanity check: US 10Y via the official sample
The following sample is provided as-is to verify connectivity and shape. Copy it to quickly confirm the endpoint responds and to familiarize yourself with the JSON fields you’ll parse in your application.
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
{
"success": true,
"date": "2026-11-06",
"rates": {
"US_10Y": 4.834
},
"dates": {
"US_10Y": "2026-11-06"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "28f601ac-5a2b-4be1-8e0a-cf07edfb1c4e",
"timestamp": "2026-11-06T00:04:05+00:00"
}
}
How to read it:
rates.US_10Yis the US 10-year yield as a percentage.dateanddates.US_10Yshow the calendar date for the latest observation.currencies.US_10Yindicates the currency of the underlying bond (USD for US Treasuries).meta.timestampis an ISO timestamp (UTC) for when this payload was generated.
Latest US yields: single tenor or multiple maturities
Use /api/v1/latest to fetch the most recent yields for the United States across one or several maturities. This is the fastest path to the United States 10 Year Treasury when you just need the current close.
Endpoint
GET https://bonds-api.com/api/v1/latest
- Required:
countries(ISO2 comma-separated; e.g., US) - Optional:
maturities(comma-separated; e.g., 2Y,10Y). Omit to fetch all available US maturities.
cURL
Python (requests)
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()
us_10y = data["data"]["US"]["10Y"]["yield"] # percentage, e.g., 4.52
us_10y_date = data["data"]["US"]["10Y"]["date"] # "YYYY-MM-DD"
JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.search = new URLSearchParams({ countries: "US", maturities: "2Y,10Y" }).toString();
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await res.json();
const tenY = json.data.US["10Y"].yield; // percent
const tenYDate = json.data.US["10Y"].date; // YYYY-MM-DD
PHP (file_get_contents)
<?php
$context = stream_context_create([
"http" => [
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/latest?countries=US&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$us10y = $data["data"]["US"]["10Y"]["yield"]; // percent
$asof = $data["data"]["US"]["10Y"]["date"]; // YYYY-MM-DD
echo $us10y;
Response example
Notes:
yieldis a percentage, not basis points.dateis the observation date (official daily close). On weekends or holidays, it points to the prior business day.sourceindicates the data provenance for the observation.
Historical US 10Y: a specific calendar date
Use /api/v1/historical to target the 10-year yield on a single date. This is essential for point-in-time portfolio analytics, day-over-day changes, or event studies.
Endpoint
GET https://bonds-api.com/api/v1/historical
- Required:
country(US),maturity(e.g., 10Y),date(YYYY-MM-DD)
cURL
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "US", "maturity": "10Y", "date": "2025-06-15"}
)
h = resp.json()
ten_yield = h["yield"] # percent
JavaScript
const params = new URLSearchParams({ country: "US", maturity: "10Y", date: "2025-06-15" });
const res = await fetch(`https://bonds-api.com/api/v1/historical?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const hist = await res.json();
const y = hist.yield; // percent
PHP
<?php
$params = http_build_query([
"country" => "US",
"maturity" => "10Y",
"date" => "2025-06-15"
]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/historical?$params", false, $context);
$data = json_decode($json, true);
echo $data["yield"]; // percent
Response example
If the date falls on a holiday without an official close, you’ll receive a 404. Use the time series endpoint to locate the nearest available business day.
Time series for the United States 10 Year
Use /api/v1/timeseries to retrieve an array of daily observations across a period. This is useful for charting, backtests, and computing rolling measures like duration-adjusted risk or realized volatility.
Endpoint
GET https://bonds-api.com/api/v1/timeseries
- Required:
country(US),maturity(e.g., 10Y),start(YYYY-MM-DD),end(YYYY-MM-DD)
cURL
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "US", "maturity": "10Y", "start": "2025-11-06", "end": "2026-11-06"}
)
ts = resp.json()
series = ts["series"] # list of { "date": "YYYY-MM-DD", "yield": float }
JavaScript
const params = new URLSearchParams({
country: "US",
maturity: "10Y",
start: "2025-11-06",
end: "2026-11-06"
});
const res = await fetch(`https://bonds-api.com/api/v1/timeseries?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const ts = await res.json();
const points = ts.series; // array of { date, yield }
PHP
<?php
$params = http_build_query([
"country" => "US",
"maturity" => "10Y",
"start" => "2025-11-06",
"end" => "2026-11-06"
]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$params", false, $context);
$data = json_decode($json, true);
foreach ($data["series"] as $row) {
// $row["date"], $row["yield"]
}
Response example
Interpretation tips:
- All yields are percentages. If you compute daily bps changes, multiply percentage deltas by 100.
- Missing days (weekends/holidays) are absent from the array; do not forward-fill unless your analysis requires it.
Yield spread: US vs. benchmark
Use /api/v1/spread to compute a cross-country spread for a given maturity. For the US 10Y versus the German 10Y Bund, request the 10Y maturity. The response includes both country yields and the spread in basis points.
Endpoint
GET https://bonds-api.com/api/v1/spread
- Required:
country(US),benchmark(e.g., DE) - Optional:
maturity(defaults to 10Y)
cURL
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "US", "benchmark": "DE", "maturity": "10Y"}
)
sp = resp.json()
bps = sp["spread_bps"] # integer/float in basis points
us_y = sp["country_yield"] # percent
de_y = sp["benchmark_yield"] # percent
JavaScript
const params = new URLSearchParams({ country: "US", benchmark: "DE", maturity: "10Y" });
const res = await fetch(`https://bonds-api.com/api/v1/spread?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const sp = await res.json();
const spreadBps = sp.spread_bps;
const us = sp.country_yield;
const de = sp.benchmark_yield;
PHP
<?php
$params = http_build_query(["country" => "US", "benchmark" => "DE", "maturity" => "10Y"]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/spread?$params", false, $context);
$data = json_decode($json, true);
echo $data["spread_bps"]; // basis points
Response example
Interpretation:
spread_bps= US 10Y yield minus German 10Y yield, in basis points.- Use spreads to normalize relative value across markets without mixing percent and bps internally.
Full US yield curve for curve analytics
Use /api/v1/curve to obtain the entire US curve on the latest day (or a specified date). This is ideal for bootstrapping, duration/convexity approximations, or curve-shape diagnostics like inversion checks.
Endpoint
GET https://bonds-api.com/api/v1/curve
- Required:
country(US) - Optional:
date(YYYY-MM-DD). If omitted, returns the latest available day with data.
cURL
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "US"}
)
curve = resp.json()
asof = curve["date"] # YYYY-MM-DD
ten_y = curve["curve"]["10Y"] # percent
JavaScript
const params = new URLSearchParams({ country: "US" });
const res = await fetch(`https://bonds-api.com/api/v1/curve?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const cv = await res.json();
const inverted = cv.inverted;
const us10y = cv.curve["10Y"];
PHP
<?php
$params = http_build_query(["country" => "US"]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/curve?$params", false, $context);
$data = json_decode($json, true);
$us10y = $data["curve"]["10Y"];
$inv = $data["inverted"] ? "yes" : "no";
Response example
Interpretation:
curvemaps maturities to yields in percentages. The 10Y node is your US 10Y yield for that date.invertedindicates whether the short end (e.g., 2Y) exceeds the long end (e.g., 10Y/30Y) by the API’s inversion heuristic.
Comparing US maturities on the curve date
| Maturity | Yield (%) |
|---|---|
| 2Y | 4.25 |
| 5Y | 4.39 |
| 10Y | 4.52 |
| 30Y | 4.71 |
Intraday snapshots for the United States 10 Year
Use /api/v1/intraday for time-stamped yield observations within a specific day. This is useful for monitoring session dynamics, alerting, and live dashboards. Timestamps are UTC.
Endpoint
GET https://bonds-api.com/api/v1/intraday
- Required:
country(US),maturity(10Y),date(YYYY-MM-DD)
cURL
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "US", "maturity": "10Y", "date": "2026-11-06"}
)
intra = resp.json()
snaps = intra["snapshots"] # list; each has yield, fetched_at, source
# Example: mid-session change in bps
bps_change = (snaps[-1]["yield"] - snaps[0]["yield"]) * 100
JavaScript
const params = new URLSearchParams({ country: "US", maturity: "10Y", date: "2026-11-06" });
const res = await fetch(`https://bonds-api.com/api/v1/intraday?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const intra = await res.json();
const last = intra.snapshots.at(-1);
PHP
<?php
$params = http_build_query(["country" => "US", "maturity" => "10Y", "date" => "2026-11-06"]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/intraday?$params", false, $context);
$data = json_decode($json, true);
$count = $data["count"]; // number of snapshots
Response example
Interpretation:
yieldvalues are in percentages.fetched_atis an ISO timestamp in UTC for the snapshot collection time.- In intraday contexts, implement short cache lifetimes and expect more frequent updates during market hours.
Fluctuation over a period for the US 10Y
Use /api/v1/fluctuation to retrieve the start and end yields, absolute change, and the min/max over a period. This reduces client-side aggregation and is convenient for overview widgets and risk reporting.
Endpoint
GET https://bonds-api.com/api/v1/fluctuation
- Required:
countries(US),maturity(10Y),start(YYYY-MM-DD),end(YYYY-MM-DD)
cURL
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "US", "maturity": "10Y", "start": "2025-11-06", "end": "2026-11-06"}
)
fl = resp.json()
us = fl["data"]["US"]
delta_bps = us["change"] * 100 # convert percent to bps
JavaScript
const params = new URLSearchParams({
countries: "US",
maturity: "10Y",
start: "2025-11-06",
end: "2026-11-06"
});
const res = await fetch(`https://bonds-api.com/api/v1/fluctuation?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const fl = await res.json();
const stats = fl.data.US;
PHP
<?php
$params = http_build_query([
"countries" => "US",
"maturity" => "10Y",
"start" => "2025-11-06",
"end" => "2026-11-06"
]);
$context = stream_context_create(["http" => ["header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/fluctuation?$params", false, $context);
$data = json_decode($json, true);
$us = $data["data"]["US"];
// $us["start_yield"], $us["end_yield"], $us["change"], $us["min"], $us["max"]
Response example
Interpretation:
changeis in percentage points (not bps). Multiply by 100 for basis points.- Use
min/maxfor range analysis and VaR scenario scaffolding.
Practical notes: maturities, holidays, update cadence, and caching
- Maturities: For the US curve, common nodes include bills (1M, 3M, 6M), notes (1Y, 2Y, 5Y, 10Y) and bonds (30Y). The curve endpoint returns a map keyed by these maturities; the 10Y node is your US 10 Year yield for that date.
- Business days and market holidays: Daily endpoints reflect the most recent business day with an official close. If your requested
historicaldate is a holiday, you will receive a 404; use thetimeseriesendpoint to navigate around non-trading days. - Update frequency: Intraday snapshots arrive during market hours with UTC timestamps, while official daily closes populate the latest/historical/curve endpoints once per business day.
- Caching:
- Intraday: cache for minutes (or disable if you need near-real-time behavior) and revalidate during market hours.
- Daily: cache by date key (e.g.,
US:10Y:2026-11-06) and refresh after the next official close.
- Building a multi-maturity curve: Use
/api/v1/latest?countries=US&maturities=...for a subset, or/api/v1/curve?country=USfor the full set on a single as-of date.
Explore more on bonds-api.com and the MCP for structured metadata.
Error handling and retries
All error responses share a common shape: {"success": false, "error": "message"}. You should branch logic on success and HTTP status codes:
- 401: Missing or invalid X-API-Key. Ensure the header is present and correct.
- 403: Account quota exceeded. Back off and notify ops or queue for later.
- 404: No data for the requested country/maturity/date. Check dates (business day) and maturity codes.
- 422: Invalid parameter (date format must be YYYY-MM-DD; ISO2 country code must be US for the United States).
- 429: Rate limit exceeded. Implement exponential backoff with jitter.
- 500: Server error. Retry with a capped backoff; implement circuit-breakers in production.
Real-world use cases centered on the US 10Y
- Financial dashboards: Show the latest US 10Y with daily change, plus intraday ticks for session context.
- Portfolio risk tools: Compute historical beta of asset returns to changes in US 10Y via the time series endpoint; use fluctuation for quick risk summaries.
- Economic research: Compare US 10Y to German Bund 10Y with the spread endpoint; analyze curve inversion using the curve endpoint’s
invertedflag. - Fixed-income analytics: Construct and persist daily curves; compute tenor spreads (2s10s, 5s30s) from the curve or the latest endpoint with multiple maturities.
Putting it together: assembling a US curve and a 2s10s spread
For many analytics, you’ll want a compact set of nodes and an intra-curve spread. You can either call /api/v1/curve for a complete map or call /api/v1/latest with maturities=2Y,10Y to populate a 2s10s chart. Always treat yields as percentages and convert to basis points for spread visualizations if that’s your house style.
Complete endpoint recap
- /api/v1/latest — get the current US 10Y and other nodes.
- /api/v1/historical — fetch US 10Y on a given calendar date.
- /api/v1/timeseries — daily series for the US 10Y across a window.
- /api/v1/spread — basis point spread versus a benchmark country (e.g., DE).
- /api/v1/curve — full US curve with inversion flag.
- /api/v1/intraday — intraday US 10Y snapshots with UTC timestamps.
- /api/v1/fluctuation — start/end, change, min, max over a period.
All endpoints use GET. Authentication is supplied with an API key. See bonds-api.com for more details and register to obtain your key.
FAQ
How are yields expressed?
All yield values in payloads are percentages. For example, 4.52 means 4.52%. When you see spread_bps, that is a spread in basis points (e.g., 25 = 0.25%).
What timezone are timestamps in?
Dates appear as YYYY-MM-DD (calendar dates). Intraday timestamps are ISO 8601 with a UTC offset and the intraday meta.timezone field confirms UTC.
Why do I get 404 for some historical dates?
If the requested date is a non-trading day with no official close, /api/v1/historical returns 404. Use /api/v1/timeseries over a window that includes that date to locate the nearest business day.
How often does US 10Y update?
The daily endpoints update once per business day with the official close. The intraday endpoint provides multiple snapshots during market hours for session tracking.
How should I cache?
Cache intraday requests for minutes (or revalidate frequently). Cache daily endpoints by their as-of date and refresh after the next official close. Always key caches by country and maturity, e.g., US:10Y:2026-11-06.
Ready to integrate the United States 10 Year yield into your stack? Get your API key and start building in minutes: Register. For schema exploration and testing, open the MCP.