You're building a fixed-income dashboard or backtest and need reliable, programmatic access to Brazil’s 10-year government bond yield. By the end of this guide, you’ll know how to pull the latest BR 10Y yield, query specific historical dates, stream intraday snapshots, compute spreads versus a benchmark, and construct a full Brazil yield curve—all via simple GET requests to the Bonds API.
What you get from the Bonds API for Brazil (BR) 10Y
The Bonds API at bonds-api.com serves sovereign bond yields as JSON over HTTPS, with consistent symbols and a predictable response schema. Yields are returned as percentages (for example, 4.52 means 4.52%) unless otherwise noted, and dates use the Y-m-d format. When timestamps appear (for intraday), they are in UTC ISO 8601.
Key capabilities you will use for Brazil’s 10-year bond (“10Y”):
- Fetch the latest yields across multiple maturities (including 10Y) for BR.
- Request the BR 10Y yield on a specific historical date.
- Pull a BR 10Y daily time series between two dates.
- Calculate the 10Y spread of Brazil versus a benchmark country (e.g., US).
- Download the full BR yield curve on a chosen date (e.g., 1M to 30Y) and detect inversion.
- Request intraday snapshots for the BR 10Y with UTC timestamps.
- Compute fluctuations (change, min, max) for BR 10Y across any range.
All endpoints use GET and the base URL is https://bonds-api.com/api/v1/. Authentication is via the X-API-Key request header. If you do not have an API key yet, visit Register for Bonds API or Register to get started.
How yields, dates, and snapshots are represented
- Yield units: percentage values (e.g., 4.52 = 4.52%).
- Spread units (spread_bps): basis points (1 bp = 0.01%).
- Date fields: Y-m-d (e.g., 2026-10-08). These correspond to market business days.
- Intraday timestamps: UTC ISO 8601 (e.g., 2026-10-08T12:00:00Z).
Brazil’s bond market observes local business days. On weekends and Brazilian market holidays, you should expect no new daily observations. The latest endpoints will provide data for the most recent day with an official or market source. For application performance, consider caching stable daily endpoints for several minutes and intraday endpoints for shorter intervals depending on your refresh strategy.
Endpoint 1: Latest Brazil yields (including 10Y)
Use this endpoint to pull the most recent available yield prints for Brazil across selected maturities. If you omit “maturities”, the API returns all available tenors for the country.
cURL (GET /latest)
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"JSON response (sample)
{
"success": true,
"date": "2026-10-08",
"rates": {
"US_10Y": 5.29
},
"dates": {
"US_10Y": "2026-10-08"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "499b9d01-030f-47ae-8ce0-64d95bba9de2",
"timestamp": "2026-10-08T00:04:44+00:00"
}
}How to read it:
- data.BR.10Y.yield is the latest BR 10Y yield as a percent.
- data.BR.10Y.date is the market date (Y-m-d) for the observation.
- source indicates whether it’s from an “official” or “market” source.
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "BR", "maturities": "2Y,10Y"}
)
data = resp.json()
br_10y = data["data"]["BR"]["10Y"]["yield"]
br_10y_date = data["data"]["BR"]["10Y"]["date"]
print("BR 10Y:", br_10y, "on", br_10y_date)JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "BR");
url.searchParams.set("maturities", "2Y,10Y");
fetch(url.toString(), {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json()).then(data => {
const tenY = data.data.BR["10Y"].yield;
const d = data.data.BR["10Y"].date;
console.log("BR 10Y", tenY, "as of", d);
});PHP (file_get_contents)
<?php
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/latest?countries=BR&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "BR 10Y: " . $data["data"]["BR"]["10Y"]["yield"] . " on " . $data["data"]["BR"]["10Y"]["date"];
Endpoint 2: Historical BR 10Y on a specific date
Pull a single-day observation by country, maturity, and date (Y-m-d). This is useful for backfills, end-of-month snapshots, or valuation dates.
cURL (GET /historical)
JSON response (sample)
Yield is a percent. If the requested date is a non-business day with no official print, the API may return an error if no observation is available for that specific date.
Python (requests)
import requests
params = {"country": "BR", "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
)
print(r.json())JavaScript (fetch)
const u = new URL("https://bonds-api.com/api/v1/historical");
u.searchParams.set("country", "BR");
u.searchParams.set("maturity", "10Y");
u.searchParams.set("date", "2025-06-15");
fetch(u.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(res => res.json())
.then(console.log);PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "BR",
"maturity" => "10Y",
"date" => "2025-06-15"
]);
$ctx = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
echo file_get_contents("https://bonds-api.com/api/v1/historical?$params", false, $ctx);
Endpoint 3: Time series for BR 10Y between two dates
Get a daily series for the BR 10Y between start and end dates (inclusive). Great for charts, regressions, and risk models.
cURL (GET /timeseries)
JSON response (sample)
Each series element has a date and yield (percent). Expect no gaps for business days with available data; weekends/holidays will be absent.
Python (requests)
import requests
q = {"country": "BR", "maturity": "10Y", "start": "2025-10-08", "end": "2026-10-08"}
res = requests.get(
"https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q
)
series = res.json()["series"]
print("Observations:", len(series))JavaScript (fetch)
const ts = new URL("https://bonds-api.com/api/v1/timeseries");
ts.searchParams.set("country", "BR");
ts.searchParams.set("maturity", "10Y");
ts.searchParams.set("start", "2025-10-08");
ts.searchParams.set("end", "2026-10-08");
fetch(ts, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(d => console.log(d.series));PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "BR",
"maturity" => "10Y",
"start" => "2025-10-08",
"end" => "2026-10-08"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents("https://bonds-api.com/api/v1/timeseries?$params", false, $ctx);
Endpoint 4: BR 10Y spread vs benchmark (e.g., US)
Compute the 10Y spread between Brazil and a benchmark country in basis points (bps). For example, BR vs US indicates the premium (or discount) of Brazil’s 10Y yield relative to the US 10Y.
cURL (GET /spread)
JSON response (sample)
Interpretation:
- spread_bps is basis points. 215 bps equals 2.15% spread.
- country_yield and benchmark_yield are percentage yields used for the calculation.
Python (requests)
import requests
args = {"country": "BR", "benchmark": "US", "maturity": "10Y"}
r = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=args
)
print(r.json())JavaScript (fetch)
const s = new URL("https://bonds-api.com/api/v1/spread");
s.searchParams.set("country", "BR");
s.searchParams.set("benchmark", "US");
s.searchParams.set("maturity", "10Y");
fetch(s, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(console.log);PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "BR",
"benchmark" => "US",
"maturity" => "10Y"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents("https://bonds-api.com/api/v1/spread?$params", false, $ctx);
Endpoint 5: Full Brazil yield curve
Pulls all supported BR maturities for a given date (or latest) to build a curve and detect inversion.
cURL (GET /curve)
JSON response (sample)
Interpretation:
- curve contains tenor-to-yield mappings in percent.
- inverted indicates whether the curve shows inversion (short yields above long yields in aggregate).
- Use these points to interpolate a zero curve or construct duration/convexity analytics.
Python (requests)
import requests
r = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "BR"}
)
curve = r.json()["curve"]
tenors = ["1M","3M","6M","1Y","2Y","5Y","10Y","30Y"]
points = [(t, curve.get(t)) for t in tenors]
print(points)JavaScript (fetch)
const c = new URL("https://bonds-api.com/api/v1/curve");
c.searchParams.set("country", "BR");
fetch(c, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(d => console.log("Inverted:", d.inverted, "10Y:", d.curve["10Y"]));PHP (file_get_contents)
<?php
$params = http_build_query(["country" => "BR"]);
$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?$params", false, $ctx);
echo $json;
Endpoint 6: Intraday snapshots for BR 10Y
Get multiple BR 10Y observations across a specific market date, each with a UTC timestamp. Ideal for intraday monitoring or market-open/close deltas.
cURL (GET /intraday)
JSON response (sample)
Interpretation:
- snapshots[i].yield is the instantaneous 10Y level (percent) at fetched_at (UTC).
- count provides the number of intraday snapshots in the response.
Python (requests)
import requests
p = {"country": "BR", "maturity": "10Y", "date": "2026-10-08"}
r = requests.get(
"https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p
)
snapshots = r.json()["snapshots"]
print("First snapshot UTC:", snapshots[0]["fetched_at"], "yield", snapshots[0]["yield"])JavaScript (fetch)
const iurl = new URL("https://bonds-api.com/api/v1/intraday");
iurl.searchParams.set("country", "BR");
iurl.searchParams.set("maturity", "10Y");
iurl.searchParams.set("date", "2026-10-08");
fetch(iurl, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(d => console.log("Intraday count:", d.count));PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "BR",
"maturity" => "10Y",
"date" => "2026-10-08"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents("https://bonds-api.com/api/v1/intraday?$params", false, $ctx);
Endpoint 7: Fluctuation (change, min, max) for BR 10Y
Summarize BR 10Y behavior across a date range, including start and end yields, absolute change, and extrema.
cURL (GET /fluctuation)
JSON response (sample)
Fields are percents. change is end_yield - start_yield.
Python (requests)
import requests
q = {"countries": "BR", "maturity": "10Y", "start": "2025-10-08", "end": "2026-10-08"}
res = requests.get(
"https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q
)
print(res.json()["data"]["BR"])JavaScript (fetch)
const f = new URL("https://bonds-api.com/api/v1/fluctuation");
f.searchParams.set("countries", "BR");
f.searchParams.set("maturity", "10Y");
f.searchParams.set("start", "2025-10-08");
f.searchParams.set("end", "2026-10-08");
fetch(f, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(d => console.log(d.data.BR));PHP (file_get_contents)
<?php
$params = http_build_query([
"countries" => "BR",
"maturity" => "10Y",
"start" => "2025-10-08",
"end" => "2026-10-08"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents("https://bonds-api.com/api/v1/fluctuation?$params", false, $ctx);
Building a Brazil 10Y-centric dashboard
To power a practical dashboard for Brazil’s 10-year bond, combine endpoints as follows:
- Header tile: GET /latest with countries=BR,maturities=10Y to show the current yield.
- Sparkline: GET /timeseries for the past 1–12 months of BR 10Y to render a chart.
- Intraday watch: GET /intraday on the current market date to track movement across the session (store UTC timestamps; render in user’s local timezone).
- Spread lens: GET /spread with benchmark=US to visualize BR-UST 10Y differential in bps.
- Curve context: GET /curve for BR to show where 10Y sits relative to 2Y, 5Y, 30Y, etc.
- Range stats: GET /fluctuation to display change/min/max since a chosen anchor date.
For caching, consider:
- Daily endpoints (/latest, /curve, /historical, /timeseries, /fluctuation): cache for a few minutes or until the next expected official refresh window.
- Intraday (/intraday): short TTL (e.g., 15–60 seconds) depending on UI responsiveness needs.
Comparing Brazil maturities to frame the 10Y
When the endpoint supports multiple maturities (e.g., /latest or /curve), request enough points to contextualize the 10Y. Here’s a quick view of BR tenors found in the sample curve:
| Maturity | Purpose | Endpoint example |
|---|---|---|
| 2Y | Short end, policy-sensitive | /latest?countries=BR&maturities=2Y,10Y |
| 5Y | Intermediate tenor | /curve?country=BR |
| 10Y | Benchmark long tenor | /historical?country=BR&maturity=10Y&date=YYYY-MM-DD |
| 30Y | Long end, convexity-sensitive | /curve?country=BR |
Error handling and robustness
Common error responses share a consistent JSON shape: {"success": false, "error": "message"}. Handle these cases:
- 401: Missing/invalid X-API-Key. Ensure the header is set and the key is active.
- 403: Account quota exceeded. Back off and alert; review usage.
- 404: No data for requested country/maturity/date. Consider fallback logic or user messaging.
- 422: Invalid parameter (date format, ISO2, or tenor). Validate inputs before calling.
- 429: Rate limit exceeded. Implement retry with exponential backoff.
- 500: Server error. Retry or show a temporary error notice.
Official US 10Y sample for quick connectivity check
The following is an official sample you can run to confirm connectivity and see a working response shape. Note: this sample shows an inline api_key parameter and a US 10Y symbol. For production Brazil workflows, use the endpoints and header-based authentication demonstrated above.
cURL (official sample)
JSON (official sample)
Fields here illustrate a consolidated shape with a per-symbol map keyed by US_10Y and a UTC timestamp in meta.timestamp. Yields are again in percent.
Use cases: how teams apply BR 10Y via API
- Portfolio risk and hedging: Drive scenario shocks using BR 10Y levels, spreads to US, and curve shifts from /curve.
- Macro research: Correlate BR 10Y time series with inflation surprises, policy moves, or commodity prices via /timeseries.
- Trading dashboards: Blend /latest and /intraday to monitor BR 10Y moves across the session; add /spread for cross-market context.
- Valuation pipelines: Retrieve specific end-of-day BR 10Y via /historical to lock valuation inputs; use /fluctuation to report risk metrics.
Explore more at bonds-api.com and the Bonds API MCP or MCP for tools that help you inspect and validate requests.
Practical integration notes for Brazil 10Y
- Timezones: Treat all intraday timestamps as UTC; convert to user locale in the UI.
- Business days: Expect gaps on weekends and Brazilian holidays; do not forward-fill unless your analytics require it.
- Caching: Cache daily resources for minutes; intraday for seconds. Invalidate when you detect new data timestamps.
- Input validation: Enforce ISO2 (“BR”), tenor format (“10Y”), and date format (“YYYY-MM-DD”) before calling.
- Graceful degradation: If /intraday fails or empties, display /latest as a fallback and note the timestamp.
Sovereign bond fundamentals, briefly
Sovereign bonds are issued by national governments. The 10-year tenor is a focal point for macro analysis, discount rates, and policy expectations. Yields reflect prevailing interest rate expectations, inflation outlook, fiscal risk, and global risk appetite. When comparing Brazil’s 10Y to US Treasuries via /spread, the result in basis points provides a fast read on relative risk premia and carry.
Putting it all together: a minimal BR 10Y workflow
- On load: call /latest for BR 10Y and display yield and date.
- For chart: call /timeseries for the desired window (e.g., 1Y) and render a line.
- Context: call /spread with benchmark=US and show BR-UST 10Y in bps.
- Curve: call /curve and position the 10Y relative to 2Y/5Y/30Y for slope analysis.
- Intraday: if market is open, call /intraday every N seconds for live tiles.
- Analytics: call /fluctuation from month/quarter start to now for change, min, max.
FAQ
Q: Are yields returned as decimals or percents?
A: Percents. For example, 4.52 represents a 4.52% yield. Spreads from /spread are in basis points.
Q: What timezone are “fetched_at” timestamps in for /intraday?
A: UTC ISO 8601 (e.g., 2026-10-08T12:00:00Z). Convert to your user’s local time for display.
Q: How do I request multiple BR maturities at once?
A: Use /latest with countries=BR and a comma-separated maturities list (e.g., 2Y,5Y,10Y). For a full curve, use /curve with country=BR.
Q: What happens on weekends and Brazilian market holidays?
A: There will be no new daily observations. /latest returns the most recent available date with data, and /intraday typically has no snapshots for closed days.
Q: How should I handle errors or empty results?
A: Check the "success" flag and “error” message. For 404 or empty series, inform the user and consider fallbacks (e.g., last-known good daily value) based on your business logic.
Ready to integrate the Brazil 10-Year into your analytics and dashboards? Get started with Bonds API. For tooling and request validation, visit the Bonds API MCP. If you need an API key, you can also Get started with Bonds API.