You need accurate Brazil government bond yields inside your own tooling. By the end of this guide, you’ll be able to fetch the latest Brazil yields, query historical and intraday values, compute spreads, and assemble a yield curve programmatically using Bonds API’s REST endpoints.
What you can build with Brazil sovereign yields
Brazil’s local sovereign curve underpins pricing for BRL fixed income, corporate bonds, swaps, and macro models. Developers and analysts typically need:
- Latest yields for dashboards and alerts.
- Historical and intraday time series for backtesting and signal generation.
- Yield curves and slope metrics across maturities.
- Cross-country spreads versus a benchmark (e.g., US Treasuries) for relative value.
All examples below use the Bonds API base URL https://bonds-api.com and the REST endpoints under https://bonds-api.com/api/v1/. Authentication is via the X-API-Key header. Learn more at bonds-api.com and explore the tools at Bonds API MCP. To begin, Register for Bonds API and Get started with Bonds API.
Data model, units, and timestamps
Unless stated otherwise:
- Yields are returned as percentages (e.g., 4.52 means 4.52%).
- Spreads use basis points (bps). 1 bps = 0.01%.
- Dates are strings formatted as Y-m-d (e.g., 2026-11-21).
- Timestamps are ISO8601 with timezone, usually UTC (e.g., 2026-11-21T12:00:00Z).
- Maturities are strings like 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y.
Brazil market data generally updates on Brazil business days; weekends and local holidays will have no new end-of-day values. If you need intraday ticks for a given market day, use the intraday endpoint. For application performance, cache responses during market closures, and set refresh intervals based on your use case (e.g., hourly for dashboards, per-request for backtests). Always check the returned date fields to confirm the effective market date of a value.
Latest Brazil yields: snapshot for chosen maturities
Use this when you need the current (most recent available) yields by maturity for Brazil (ISO2: BR). Provide countries=BR and optionally a set of maturities.
Endpoint
GET /api/v1/latest
Parameters
- countries (required): comma-separated ISO2 codes (e.g., BR)
- maturities (optional): comma-separated maturities (e.g., 2Y,10Y). Omit to get all available.
cURL
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
JSON response
{
"success": true,
"date": "2026-11-20",
"rates": {
"US_10Y": 4.92
},
"dates": {
"US_10Y": "2026-11-20"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "7076387c-43de-400c-afc5-872b27d9fe3e",
"timestamp": "2026-11-21T00:04:04+00:00"
}
}
How to read this:
- yield is a percentage value.
- date is the market date for the snapshot (Y-m-d).
- source indicates the origin (e.g., “official”).
Python
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_2y = data['data']['BR']['2Y']['yield']
br_10y = data['data']['BR']['10Y']['yield']
br_date = data['data']['BR']['10Y']['date']
print('BR 2Y:', br_2y, 'BR 10Y:', br_10y, 'Date:', br_date)
JavaScript (fetch)
const url = 'https://bonds-api.com/api/v1/latest?countries=BR&maturities=2Y,10Y';
fetch(url, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(json => {
const twoY = json.data.BR['2Y'].yield;
const tenY = json.data.BR['10Y'].yield;
const date = json.data.BR['10Y'].date;
console.log('BR 2Y', twoY, 'BR 10Y', tenY, 'Date', date);
});
PHP
<?php
$context = stream_context_create([
'http' => [
'header' => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$json = file_get_contents('https://bonds-api.com/api/v1/latest?countries=BR&maturities=2Y,10Y', false, $context);
$data = json_decode($json, true);
echo 'BR 2Y: ' . $data['data']['BR']['2Y']['yield'] . PHP_EOL;
echo 'BR 10Y: ' . $data['data']['BR']['10Y']['yield'] . PHP_EOL;
?>
Historical Brazil yield: a single date
Grab the yield for a specific Brazil maturity on a given historical date.
Endpoint
GET /api/v1/historical
Parameters
- country (required): ISO2 code (BR)
- maturity (required): e.g., 10Y
- date (required): Y-m-d
cURL
JSON response
Fields:
- yield as percent for that maturity/date.
- date is the effective market day. If the requested date is a non-business day, expect a 404 unless data exists specifically for that date.
Python
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 p = new URLSearchParams({ country: 'BR', maturity: '10Y', date: '2025-06-15' });
fetch('https://bonds-api.com/api/v1/historical?' + p.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json()).then(console.log);
PHP
<?php
$qs = http_build_query(['country' => 'BR', 'maturity' => '10Y', 'date' => '2025-06-15']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/historical?' . $qs, false, $ctx);
?>
Brazil time series: start/end window
For backtesting, charts, and factor models, request a continuous series over a date range.
Endpoint
GET /api/v1/timeseries
Parameters
- country (required): BR
- maturity (required): e.g., 10Y
- start (required): Y-m-d
- end (required): Y-m-d (greater than or equal to start)
cURL
JSON response
Each element has a date and a yield percentage. Dates reflect business days with available data.
Python
import requests
params = {'country': 'BR', 'maturity': '10Y', 'start': '2025-11-21', 'end': '2026-11-21'}
res = requests.get('https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=params)
series = res.json()['series']
# Example: compute average yield
avg_yield = sum(pt['yield'] for pt in series) / len(series) if series else None
print('Count:', len(series), 'Average:', avg_yield)
JavaScript (fetch)
const params = new URLSearchParams({
country: 'BR', maturity: '10Y', start: '2025-11-21', end: '2026-11-21'
});
fetch('https://bonds-api.com/api/v1/timeseries?' + params.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json()).then(json => {
console.log('First points:', json.series.slice(0, 3));
});
PHP
<?php
$q = http_build_query(['country' => 'BR', 'maturity' => '10Y', 'start' => '2025-11-21', 'end' => '2026-11-21']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$data = json_decode(file_get_contents('https://bonds-api.com/api/v1/timeseries?' . $q, false, $ctx), true);
echo 'Points: ' . count($data['series']) . PHP_EOL;
?>
Brazil vs. benchmark: spread in basis points
Compute the yield spread between Brazil and a benchmark country at a given maturity. By default, maturity is 10Y.
Endpoint
GET /api/v1/spread
Parameters
- country (required): BR
- benchmark (required): ISO2 code, e.g., US
- maturity (optional): default 10Y
cURL
JSON response
Interpretation:
- spread_bps is the difference in basis points (country_yield − benchmark_yield).
- country_yield and benchmark_yield are both percentages for the same maturity and date.
Python
import requests
r = requests.get('https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'BR', 'benchmark': 'US', 'maturity': '10Y'})
j = r.json()
print('Spread (bps):', j['spread_bps'], 'BR 10Y:', j['country_yield'], 'US 10Y:', j['benchmark_yield'])
JavaScript (fetch)
const p2 = new URLSearchParams({ country: 'BR', benchmark: 'US', maturity: '10Y' });
fetch('https://bonds-api.com/api/v1/spread?' + p2.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json()).then(console.log);
PHP
<?php
$params = http_build_query(['country' => 'BR', 'benchmark' => 'US', 'maturity' => '10Y']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/spread?' . $params, false, $ctx);
?>
Full Brazil yield curve
Fetch the entire curve for Brazil on the latest available market day or for a specific date. This is ideal for constructing spot curves, interpolation, and risk metrics (e.g., 2s10s slope).
Endpoint
GET /api/v1/curve
Parameters
- country (required): BR
- date (optional): Y-m-d (defaults to the latest available day)
cURL
JSON response
Fields:
- curve: maturity to yield map (percentages).
- inverted: true if short maturities exceed long maturities by internal criteria.
- date: effective market date for the curve.
Available maturities (example)
| Maturity | 1M | 3M | 6M | 1Y | 2Y | 5Y | 10Y | 30Y |
|---|---|---|---|---|---|---|---|---|
| Yield (%) | 5.31 | 5.27 | 5.18 | 4.98 | 4.25 | 4.39 | 4.52 | 4.71 |
Python
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']
slope_2s10s = curve['10Y'] - curve['2Y']
print('2s10s slope (bp):', round(slope_2s10s * 100, 1))
JavaScript (fetch)
const qp = new URLSearchParams({ country: 'BR' });
fetch('https://bonds-api.com/api/v1/curve?' + qp.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json()).then(json => {
const c = json.curve;
const slope = (c['10Y'] - c['2Y']) * 100; // bps
console.log('Curve date:', json.date, '2s10s slope (bps):', slope.toFixed(1));
});
PHP
<?php
$q = http_build_query(['country' => 'BR']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$data = json_decode(file_get_contents('https://bonds-api.com/api/v1/curve?' . $q, false, $ctx), true);
$slope = ($data['curve']['10Y'] - $data['curve']['2Y']) * 100;
echo '2s10s slope (bps): ' . number_format($slope, 1) . PHP_EOL;
?>
Intraday snapshots for Brazil
Request intraday yield snapshots for a specific maturity and date. Useful for market monitors, trade execution analysis, or intraday VaR.
Endpoint
GET /api/v1/intraday
Parameters
- country (required): BR
- maturity (required): e.g., 10Y
- date (required): Y-m-d
cURL
JSON response
Interpretation:
- snapshots: array of yield (%) points with fetched_at timestamps in UTC.
- count: number of intraday points.
- meta.timezone: timezone context for fetched_at, typically UTC.
Python
import requests
params = {'country': 'BR', 'maturity': '10Y', 'date': '2026-11-21'}
j = requests.get('https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=params).json()
snaps = j['snapshots']
if snaps:
open_y, close_y = snaps[0]['yield'], snaps[-1]['yield']
print('Open:', open_y, 'Close:', close_y, 'Change (bp):', round((close_y - open_y) * 100, 1))
JavaScript (fetch)
const q = new URLSearchParams({ country: 'BR', maturity: '10Y', date: '2026-11-21' });
fetch('https://bonds-api.com/api/v1/intraday?' + q.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json()).then(json => {
console.log('Snapshots:', json.count, 'Timezone:', json.meta.timezone);
});
PHP
<?php
$q = http_build_query(['country' => 'BR', 'maturity' => '10Y', 'date' => '2026-11-21']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$data = json_decode(file_get_contents('https://bonds-api.com/api/v1/intraday?' . $q, false, $ctx), true);
echo 'Count: ' . $data['count'] . ' Timezone: ' . $data['meta']['timezone'] . PHP_EOL;
?>
Fluctuation: min, max, and change over a period
Summarize Brazil yield behavior over a window, including start, end, change, and extrema.
Endpoint
GET /api/v1/fluctuation
Parameters
- countries (required): one or more ISO2 codes, e.g., BR
- maturity (required): e.g., 10Y
- start (required): Y-m-d
- end (required): Y-m-d
cURL
JSON response
All yields in percent. change is the absolute difference (end_yield − start_yield), not basis points. Convert to basis points by multiplying by 100.
Python
import requests
args = {'countries': 'BR', 'maturity': '10Y', 'start': '2025-11-21', 'end': '2026-11-21'}
out = requests.get('https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=args).json()
s = out['data']['BR']
print('Δ (bp):', round(s['change'] * 100, 1), 'min:', s['min'], 'max:', s['max'])
JavaScript (fetch)
const f = new URLSearchParams({ countries: 'BR', maturity: '10Y', start: '2025-11-21', end: '2026-11-21' });
fetch('https://bonds-api.com/api/v1/fluctuation?' + f.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json()).then(json => {
const s = json.data.BR;
const deltaBps = s.change * 100;
console.log('Change (bps):', deltaBps.toFixed(1), 'Range:', s.min, 'to', s.max);
});
PHP
<?php
$p = http_build_query(['countries' => 'BR', 'maturity' => '10Y', 'start' => '2025-11-21', 'end' => '2026-11-21']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$data = json_decode(file_get_contents('https://bonds-api.com/api/v1/fluctuation?' . $p, false, $ctx), true);
$s = $data['data']['BR'];
echo 'Change (bps): ' . number_format($s['change'] * 100, 1) . PHP_EOL;
?>
Error handling and common responses
Plan for error cases by inspecting success and error fields. Typical HTTP statuses include:
- 401: Missing or invalid X-API-Key
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date
- 422: Invalid parameter (e.g., wrong date format)
- 429: Rate limit exceeded
- 500: Server error
On any non-2xx response, log the URL and parameters, capture the error message, and consider retry policies for transient codes (429, 500). For 404s on non-business days, decide whether to backfill from the previous business day using your own logic.
Using multiple endpoints together for a Brazil analytics pipeline
- Dashboard: Use /latest for BR across 2Y–30Y every few minutes and highlight daily changes relative to /fluctuation start_yield.
- Backtesting: Pull /timeseries for the target maturities and compute factor exposures; supplement with /intraday for execution windows.
- Curve analytics: Fetch /curve and compute slopes (e.g., 2s10s, 5s30s). Detect inversions using the inverted flag or your own thresholds.
- Global RV: Compare /spread versus US for multiple maturities to track risk-adjusted carry or hedging basis.
You can browse, test, and monitor your calls in the MCP, and the main docs live at bonds-api.com. When you’re ready, Register for your API key.
Official sample block
The following official sample is provided as-is for reference and should be copied verbatim when you need this exact example.
Practical implementation notes
- HTTP method: All endpoints are GET.
- Auth: Send X-API-Key in the request header.
- Rate limiting: Handle 429 with exponential backoff; cache immutable historical responses aggressively.
- Timezones: End-of-day dates are business dates; intraday timestamps are UTC.
- Edge cases: Holidays and weekends return the last available date for /curve and /latest; /historical expects the exact date and will 404 if none exists.
FAQ
What units are yields and spreads in?
All yields are percentages. Spreads from /spread are in basis points (bps). To convert a percentage difference to bps, multiply by 100.
How often are Brazil yields updated?
End-of-day values update on Brazil business days. For intraday monitoring, use /intraday with snapshots timestamped in UTC.
How do I build a Brazil yield curve?
Call /curve with country=BR to get the full maturity map. You can compute slopes (e.g., 2s10s) and detect inversions via the inverted flag.
How should I handle non-trading days?
Expect no new end-of-day data; use the most recent available date from /latest or /curve. For /historical on a weekend/holiday, be prepared for 404 and implement your own prior-business-day fallback.
What’s the best way to compare Brazil with US Treasuries?
Use /spread with country=BR and benchmark=US for a maturity like 10Y to get the differential in basis points.
Build your Brazil fixed-income analytics with production-ready endpoints today. Explore the docs at bonds-api.com, test calls in the Bonds API MCP, and Register to obtain your API key.