Brazil Yield Curve

Brazil Yield Curve

You need clean, reliable Brazil sovereign yield data inside your own tools, with enough flexibility to pull the latest levels, build curves, compute spreads, and analyze changes over time. By the end of this article, you will be able to query Brazil’s yield curve, retrieve intraday and historical data, compute US–Brazil spreads, and embed everything in dashboards or research pipelines using Bonds API’s REST endpoints.

Brazil sovereign yields with Bonds API: data model, units, and calendars

Bonds API provides sovereign bond yields as JSON over HTTPS at https://bonds-api.com. For Brazil (ISO2: BR), you can query specific maturities (for example 2Y, 10Y) or request the full curve. Yields are returned as percentages (for example 4.52 means 4.52%), while spreads are returned in basis points (for example 215 means 2.15%).

Illustration: Brazil Yield Curve

Dates in daily endpoints use the YYYY-MM-DD format and represent the business date for which the yield is published. Intraday snapshots include an ISO-8601 UTC timestamp (for example 2026-10-23T12:00:00Z). Update frequency follows market hours and official publication cycles; on local market holidays or weekends you should expect no new values. For production, cache responses by date and maturity to avoid re-fetching immutable daily data, and respect rate limits with client-side retries and backoffs on 429.

Authentication uses an API key via the X-API-Key header. All endpoints use HTTP GET at the base URL: https://bonds-api.com/api/v1/. You can find more documentation and tooling at bonds-api.com and the MCP.

Endpoint: Latest yields for Brazil

Use /latest to pull the most recent yields for selected maturities. This is ideal for dashboards and quote tickers. The maturities parameter is optional; omit it to receive all available maturities for the specified country.

cURL

curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"

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()
# data["data"]["BR"]["10Y"]["yield"] is a percentage (e.g., 4.52)
# data["data"]["BR"]["10Y"]["date"] is "YYYY-MM-DD"

JavaScript (fetch)

const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "BR");
url.searchParams.set("maturities", "2Y,10Y");

const res = await fetch(url, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const json = await res.json();
// json.data.BR["2Y"].yield is a float percent
// json.data.BR["2Y"].date is "YYYY-MM-DD"

PHP (file_get_contents)

<?php
$ctx = 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, $ctx);
$data = json_decode($json, true);
// $data["data"]["BR"]["2Y"]["yield"] is a percent value
?>

JSON response

{
    "success": true,
    "date": "2026-10-23",
    "rates": {
        "US_10Y": 4.949
    },
    "dates": {
        "US_10Y": "2026-10-23"
    },
    "currencies": {
        "US_10Y": "USD"
    },
    "meta": {
        "request_id": "87befe1b-a760-4bdd-8d1a-ded434351f9c",
        "timestamp": "2026-10-23T00:04:04+00:00"
    }
}

Fields: yield is a percentage; date is the market date in YYYY-MM-DD; source indicates the data origin. Use this endpoint to quickly display Brazil 2Y and 10Y in your UI, or to compute simple level-based risk metrics.

Official sample (verbatim)

The following sample is provided verbatim from the official documentation for illustration:

Endpoint: Historical yield for a specific date

Use /historical to retrieve Brazil’s yield on a single date for a given maturity. This is useful for point-in-time backtests and valuation checkpoints.

cURL

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)
hist = r.json()
# hist["yield"] is a percent; hist["date"] is "YYYY-MM-DD"

JavaScript (fetch)

const res = await fetch(
"https://bonds-api.com/api/v1/historical?country=BR&maturity=10Y&date=2025-06-15",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const json = await res.json();
// json.yield is a float (percent), json.source denotes data origin

PHP (file_get_contents)

<?php
$ctx = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/historical?country=BR&maturity=10Y&date=2025-06-15";
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
// $data["yield"] is the percent yield for the given date/maturity
?>

JSON response

Interpretation: yield is a percentage for the given Brazil maturity and date; source notes origin. If the date falls on a weekend/holiday, you may receive no data (404) or the series may have the previous business day as the latest date depending on the endpoint design—handle 404 and 422 errors defensively.

Endpoint: Time series for Brazil yields

Use /timeseries to pull a continuous series between two dates for a specific maturity. This powers charts, regressions, and analytics like realized volatility or beta estimates.

cURL

Python (requests)

import requests, pandas as pd

q = {
"country": "BR",
"maturity": "10Y",
"start": "2025-10-23",
"end": "2026-10-23"
}
resp = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
series = resp.json()
# Convert to DataFrame if needed:
df = pd.DataFrame(series["series"]) # columns: date (YYYY-MM-DD), yield (percent)

JavaScript (fetch)

const url = new URL("https://bonds-api.com/api/v1/timeseries");
url.searchParams.set("country", "BR");
url.searchParams.set("maturity", "10Y");
url.searchParams.set("start", "2025-10-23");
url.searchParams.set("end", "2026-10-23");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" }});
const json = await res.json();
// json.series is an array of { date: "YYYY-MM-DD", yield: float percent }

PHP (file_get_contents)

<?php
$params = http_build_query([
"country" => "BR",
"maturity" => "10Y",
"start" => "2025-10-23",
"end" => "2026-10-23"
]);
$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);
// $data["series"] holds daily observations

JSON response

Each element includes date in YYYY-MM-DD and yield in percent. Missing dates correspond to weekends and holidays; there is no filler data for those days. Cache series responses on the (country, maturity, start, end) tuple for reproducibility and speed.

Endpoint: Spread vs benchmark (US or DE)

Use /spread to compute Brazil’s yield spread versus a benchmark such as US Treasuries (US) or German Bunds (DE). Spreads return in basis points (bps), while the accompanying yields are in percent.

cURL

Python (requests)

import requests

p = {"country": "BR", "benchmark": "US", "maturity": "10Y"}
res = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p)
spread = res.json()
# spread["spread_bps"] is integer/float in basis points
# spread["country_yield"] and ["benchmark_yield"] are percents

JavaScript (fetch)

const res = await fetch(
"https://bonds-api.com/api/v1/spread?country=BR&benchmark=US&maturity=10Y",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const s = await res.json();
// s.spread_bps (bps), s.country_yield (percent), s.benchmark_yield (percent)

PHP (file_get_contents)

<?php
$ctx = stream_context_create([
"http" => [ "method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n" ]
]);
$url = "https://bonds-api.com/api/v1/spread?country=BR&benchmark=US&maturity=10Y";
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
// $data["spread_bps"] is the BR vs US 10Y spread in basis points
?>

JSON response

Interpretation: a positive spread_bps means Brazil yields are higher than the benchmark by that many basis points at the specified maturity.

Endpoint: Full Brazil yield curve

Use /curve to fetch the entire Brazil yield curve on the latest available date (or a specified date). This is the fastest way to draw curve charts or bootstrap analytics across maturities.

cURL

Python (requests)

import requests

res = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "BR"} # Optional: "date": "YYYY-MM-DD"
)
curve = res.json()
# curve["curve"] maps maturity strings (e.g., "1M","10Y") to percent yields
# curve["inverted"] is a boolean flag

JavaScript (fetch)

const res = await fetch(
"https://bonds-api.com/api/v1/curve?country=BR",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// data.curve is an object: { "1M": 5.31, ..., "30Y": 4.71 } (percents)

PHP (file_get_contents)

<?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=BR", false, $ctx);
$data = json_decode($json, true);
// $data["inverted"] indicates if short yields exceed long yields overall
?>

JSON response

Fields: curve is a maturity-to-yield map (percent values). inverted indicates whether the curve is generally inverted across key points. Use the curve map directly for charting or to compute slope metrics like 2s10s (2Y vs 10Y) and 5s30s.

Endpoint: Intraday snapshots

Use /intraday for time-stamped snapshots within a market date for a given maturity. Snapshots are useful for monitoring live moves and computing intraday VaR or PnL impacts.

cURL

Python (requests)

import requests, datetime as dt

params = {"country": "BR", "maturity": "10Y", "date": "2026-10-23"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
snap = r.json()
# snap["snapshots"] is a list of { yield: percent, fetched_at: ISO-8601 UTC }

JavaScript (fetch)

const res = await fetch(
"https://bonds-api.com/api/v1/intraday?country=BR&maturity=10Y&date=2026-10-23",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Timestamps are UTC; convert to local time in your UI if needed

PHP (file_get_contents)

<?php
$ctx = stream_context_create([
"http" => [ "method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n" ]
]);
$url = "https://bonds-api.com/api/v1/intraday?country=BR&maturity=10Y&date=2026-10-23";
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
// $data["meta"]["timezone"] will indicate the reference timezone (UTC)
?>

JSON response

Interpretation: yields are percentages; fetched_at is an ISO-8601 UTC timestamp. When plotting intraday, resample to your desired interval and localize to user timezone.

Endpoint: Fluctuation over a period

Use /fluctuation to summarize change, min, and max over a period for one or more countries at a given maturity. This is great for screening, alerts, and summary panels.

cURL

Python (requests)

import requests

p = {
"countries": "BR",
"maturity": "10Y",
"start": "2025-10-23",
"end": "2026-10-23"
}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p)
fl = r.json()
# fl["data"]["BR"]["change"] is the percent change in yield over the window

JavaScript (fetch)

const url = new URL("https://bonds-api.com/api/v1/fluctuation");
url.searchParams.set("countries", "BR");
url.searchParams.set("maturity", "10Y");
url.searchParams.set("start", "2025-10-23");
url.searchParams.set("end", "2026-10-23");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" }});
const json = await res.json();
// Use json.data.BR to render start_yield, end_yield, min, max, change

PHP (file_get_contents)

<?php
$params = http_build_query([
"countries" => "BR",
"maturity" => "10Y",
"start" => "2025-10-23",
"end" => "2026-10-23"
]);
$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);
$data = json_decode($json, true);
// Render $data["data"]["BR"] stats

JSON response

All yield fields are percentages. change equals end_yield - start_yield (in percentage points). Use min and max to quickly highlight extremes in your UI.

Building and using the Brazil yield curve

You can build a yield curve in two ways:

  • Request a full country curve via /curve (single request, includes key points from bills to long bonds).
  • Request targeted maturities with /latest by passing maturities=1M,3M,6M,1Y,2Y,5Y,10Y,30Y if you only need a subset or must mix with other countries in one call.

When plotting curves, label yields in percent and ensure the x-axis uses maturity order (1M to 30Y). To compute slopes (for example 2s10s), subtract yields in percentage points. For spreads vs US or DE, use the /spread endpoint for direct basis-point results. For day-over-day curve changes, fetch /curve on two dates or compute diffs from /latest daily snapshots cached by date.

Error handling, rate limits, and caching

Common error responses share a uniform shape with success=false and an error message. Handle these statuses:

  • 401: Missing or invalid X-API-Key. Ensure the header is present on all requests.
  • 403: Account quota exceeded. Implement backoff and show a discrete UI message.
  • 404: No data for the requested country/maturity/date. This can occur on holidays or for unsupported combinations; consider falling back to previous business day in your logic where appropriate.
  • 422: Invalid parameter (date format must be YYYY-MM-DD; ISO2 must be valid).
  • 429: Rate limit exceeded. Retry with exponential backoff; cache immutable daily responses.
  • 500: Server error. Retry with jitter and alert if persistent.

Production tips: cache by endpoint parameters. Daily endpoints (/latest by date, /historical, /timeseries) are immutable for published days; intraday snapshots can change within the day and should be refreshed on a timer. Always normalize timestamps to UTC when stitching data across countries/timezones.

Sovereign bond fundamentals in practice

Sovereign yields reflect the borrowing costs and policy outlook of an issuer. Short maturities (for example 1M–1Y) often track policy rate expectations; long maturities (for example 10Y–30Y) incorporate growth, inflation, and risk premia. With the Bonds API:

  • Risk tools: compute DV01 exposure by mapping portfolio maturities to /curve yields and pricing shifts.
  • Dashboards: show BR 2Y, 5Y, 10Y, 30Y from /latest, plus 2s10s slope and US–BR 10Y spread from /spread.
  • Research: run panel regressions on /timeseries for multiple maturities, and summarize moves with /fluctuation.
  • Intraday monitoring: alert on threshold moves using /intraday snapshots.

To explore interactively and integrate quickly, visit bonds-api.com or use the MCP to test queries.

End-to-end example: construct, plot, and compare Brazil 2Y–10Y

Steps

  • Get the latest BR 2Y and 10Y with /latest.
  • Compute slope = 10Y - 2Y (percentage points).
  • Get the US–BR 10Y spread with /spread to contextualize international risk premium (in bps).
  • Optionally, retrieve the full BR curve with /curve and render a chart for today vs a past date from /curve?date=YYYY-MM-DD, or construct two curves from /latest snapshots cached by date.

In a production UI, cache the curve by date, refresh /latest at a fixed interval during local market hours, and use /intraday for finer granularity when the market is open.

Business days, local holidays, and timestamps

Brazil’s sovereign market observes local business days. Over weekends and holidays, /latest will not advance to a new date until the next trading day. The /timeseries endpoint will skip non-business days without filling. For intraday, timestamps are provided in UTC; convert to your user’s timezone for display. When reconciling daily close data with intraday snapshots, anchor on the published date field and use the last intraday snapshot of that date as the provisional close if your workflow requires it.

Security, performance, and environment setup

Store YOUR_API_KEY securely (for example, environment variables or a secret manager). Do not hardcode keys in client-side applications; proxy requests through a secure backend if you must build browser apps. Compress responses via standard HTTP negotiation (most clients do this automatically). Paginate or window your /timeseries requests by date ranges to keep payloads manageable. Use HTTP caching headers in your clients and ETags where supported; on your side, memoize responses by parameter combination to cut latency and costs.

FAQ

How are yields expressed? All yield fields are percentages (for example 4.52 equals 4.52%). Spread fields (spread_bps) are basis points (for example 215 equals 2.15%).

What date format and timezone should I expect? Daily endpoints use YYYY-MM-DD for the market date. Intraday timestamps are ISO-8601 in UTC (for example 2026-10-23T12:00:00Z). Convert UTC to your local timezone for UI display.

How often do values update? /latest and /curve reflect the latest available business day; during market hours they may update according to the underlying sources. /intraday provides multiple snapshots within the specified date. On weekends/holidays, expect no new daily values.

What symbols/maturities can I request? Use BR with maturities like 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y, as returned by /curve and /latest. Omit the maturities parameter to get all available for the country.

How should I handle errors and missing data? Check success in the JSON. Handle 401/403/429 with retries or user prompts, 404 when a country/maturity/date combination has no data, and 422 for invalid parameters. Cache immutable daily responses to avoid re-fetching.

Ready to plug Brazil’s yield curve into your analytics stack? Get your key and start testing now: Register. For hands-on exploration and quick prototyping, try the MCP. You can always find the docs and service status at bonds-api.com.

Start building with bond data today

Get your API key and access sovereign bond yields across 60+ countries. 7-day free trial, no credit card required.

Related posts

All posts →