API to Get Brazil Bond Yields

API to Get Brazil Bond Yields

You need reliable, programmatic access to Brazil government bond yields for analytics, dashboards, trading models, and research. By the end of this guide, you will be able to fetch current and historical Brazil sovereign yields, compute spreads, assemble a full yield curve, and integrate intraday snapshots into your fixed-income tools using the Bonds API.

What you get from the API and how yields are expressed

The Bonds API provides sovereign bond yields as simple JSON over HTTPS. Yields are expressed in percentage terms (for example 4.52 means 4.52%), and spreads are returned in basis points (bps), where 1 basis point = 0.01%. Dates are formatted as YYYY-MM-DD. Intraday timestamps are returned in ISO 8601 with a Z suffix and are in UTC.

Illustration: API to Get Brazil Bond Yields

Coverage includes multiple maturities across Brazil, such as 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, and 30Y, with both end-of-day and, when available, intraday snapshots. You can combine endpoints to build yield curves, compute changes over time, and benchmark Brazil vs. a reference market such as US Treasuries. Visit the homepage to learn more: bonds-api.com.

Authentication, base URL, and request patterns

All endpoints are GET requests under the same base URL: https://bonds-api.com/api/v1/. Authenticate by passing your API key in the X-API-Key request header. Example header: X-API-Key: YOUR_API_KEY.

You can test and explore endpoints in the MCP or Bonds API website, then integrate the same calls in production. When deploying, cache responses where appropriate (for example, latest end-of-day yields can be cached until the next market update; intraday snapshots should be treated as short-lived).

Endpoint: Latest yields for Brazil

Use latest to fetch the most recent available yields by country (Brazil is BR) and optional maturities.

cURL

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

Python (requests)

import requests

response = requests.get(
'https://bonds-api.com/api/v1/latest',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'BR', 'maturities': '2Y,10Y'}
)
data = response.json()
# Access yields: data['data']['BR']['2Y']['yield'], data['data']['BR']['10Y']['yield']

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(json => {
const br = json.data.BR;
console.log('BR 2Y', br['2Y'].yield, 'date', br['2Y'].date);
console.log('BR 10Y', br['10Y'].yield, 'date', br['10Y'].date);
});

PHP (file_get_contents)

<?php
$url = 'https://bonds-api.com/api/v1/latest?countries=BR&maturities=2Y,10Y';
$opts = [
'http' => [
'method' => 'GET',
'header' => "X-API-Key: YOUR_API_KEY\r\n"
]
];
$ctx = stream_context_create($opts);
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
// $data['data']['BR']['2Y']['yield'], $data['data']['BR']['10Y']['yield']
?>

Sample JSON response

{
    "success": true,
    "date": "2026-11-06",
    "rates": {
        "US_10Y": 4.834
    },
    "dates": {
        "US_10Y": "2026-11-06"
    },
    "currencies": {
        "US_10Y": "USD"
    },
    "meta": {
        "request_id": "8b593609-b1e1-4c88-9c7f-0b0062e4f3e8",
        "timestamp": "2026-11-06T01:04:04+00:00"
    }
}

How to read: yields are in percent. date is the market date in YYYY-MM-DD; source indicates the data origin. If you omit maturities, the API returns all available maturities for BR.

Endpoint: Historical yield on a specific date (Brazil)

Use historical to fetch the yield for a single maturity on a given date. The date is formatted as YYYY-MM-DD.

cURL

Python (requests)

import requests

response = requests.get(
'https://bonds-api.com/api/v1/historical',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'BR', 'maturity': '10Y', 'date': '2025-06-15'}
)
hist = response.json()
# hist['yield'] is the 10Y yield (percent) for 2025-06-15

JavaScript (fetch)

const url = new URL('https://bonds-api.com/api/v1/historical');
url.searchParams.set('country', 'BR');
url.searchParams.set('maturity', '10Y');
url.searchParams.set('date', '2025-06-15');

fetch(url.toString(), {
headers: {'X-API-Key': 'YOUR_API_KEY'}
})
.then(r => r.json())
.then(json => {
console.log('BR 10Y on', json.date, 'yield', json.yield);
});

PHP (file_get_contents)

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

Sample JSON response

How to read: yield is a percentage; date is YYYY-MM-DD. Use this endpoint for point-in-time backfills, event studies, or valuation as-of a date.

Endpoint: Time series of Brazil yields

Use timeseries to retrieve a continuous series over a date range for one maturity. Start and end are inclusive and use YYYY-MM-DD.

cURL

Python (requests)

import requests

params = {
'country': 'BR',
'maturity': '10Y',
'start': '2025-11-06',
'end': '2026-11-06'
}
r = requests.get('https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=params)
series = r.json()['series']
# series is a list of { 'date': 'YYYY-MM-DD', 'yield': float }

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-11-06');
url.searchParams.set('end', '2026-11-06');

fetch(url, { headers: {'X-API-Key': 'YOUR_API_KEY'} })
.then(r => r.json())
.then(json => {
json.series.forEach(pt => {
// pt.date in YYYY-MM-DD, pt.yield in percent
});
});

PHP (file_get_contents)

<?php
$params = http_build_query([
'country' => 'BR',
'maturity' => '10Y',
'start' => '2025-11-06',
'end' => '2026-11-06'
]);
$url = 'https://bonds-api.com/api/v1/timeseries?' . $params;
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$resp = file_get_contents($url, false, $ctx);
$data = json_decode($resp, true);
// Iterate $data['series']
?>

Sample JSON response

How to read: series is an array of date/yield pairs. Use the range for rolling analytics, risk models, and charting.

Endpoint: Brazil vs. benchmark spread

Use spread to compute the spread of Brazil vs. a benchmark country (e.g., US). By default maturity is 10Y; you can specify another maturity if supported.

cURL

Python (requests)

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'}
)
spread = r.json()
# spread['spread_bps'] is in basis points
# spread['country_yield'] and ['benchmark_yield'] are in percent

JavaScript (fetch)

const url = new URL('https://bonds-api.com/api/v1/spread');
url.searchParams.set('country', 'BR');
url.searchParams.set('benchmark', 'US');
url.searchParams.set('maturity', '10Y');

fetch(url, { headers: {'X-API-Key': 'YOUR_API_KEY'} })
.then(r => r.json())
.then(json => {
console.log('Spread (bps):', json.spread_bps);
console.log('BR 10Y:', json.country_yield, 'US 10Y:', json.benchmark_yield);
});

PHP (file_get_contents)

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

Sample JSON response

How to read: spread_bps is the yield difference in basis points. Use it to track Brazil’s relative value vs. US Treasuries or other benchmarks.

Endpoint: Full Brazil yield curve

Use curve to fetch all available maturities for a single date. If date is omitted, the API returns the latest available curve.

cURL

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['curve'] is a dict of { '1M': percent, '3M': percent, ... }
# curve['inverted'] is a boolean flag

JavaScript (fetch)

const url = new URL('https://bonds-api.com/api/v1/curve');
url.searchParams.set('country', 'BR');

fetch(url, { headers: {'X-API-Key': 'YOUR_API_KEY'} })
.then(r => r.json())
.then(json => {
console.log('Curve date:', json.date, 'Inverted:', json.inverted);
console.log('Points:', json.curve);
});

PHP (file_get_contents)

<?php
$url = 'https://bonds-api.com/api/v1/curve?country=BR';
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$resp = file_get_contents($url, false, $ctx);
$data = json_decode($resp, true);
// $data['curve'] contains maturity: yield pairs
?>

Sample JSON response

How to read: curve contains maturity keys mapped to yield percentages. inverted indicates if shorter maturities exceed longer ones (a classic inversion signal). Use this endpoint to build Brazil yield curves with a single call.

Endpoint: Intraday Brazil snapshots

Use intraday to get multiple yield snapshots for the same date and maturity. All timestamps are in UTC and returned as fetched_at. The date is the market date in YYYY-MM-DD.

cURL

Python (requests)

import requests

params = {'country': 'BR', 'maturity': '10Y', 'date': '2026-11-06'}
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': ISO8601 Z, 'source': str }

JavaScript (fetch)

const url = new URL('https://bonds-api.com/api/v1/intraday');
url.searchParams.set('country', 'BR');
url.searchParams.set('maturity', '10Y');
url.searchParams.set('date', '2026-11-06');

fetch(url, { headers: {'X-API-Key': 'YOUR_API_KEY'} })
.then(r => r.json())
.then(json => {
console.log('Count:', json.count, 'TZ:', json.meta.timezone);
console.table(json.snapshots);
});

PHP (file_get_contents)

<?php
$q = http_build_query(['country' => 'BR', 'maturity' => '10Y', 'date' => '2026-11-06']);
$url = 'https://bonds-api.com/api/v1/intraday?' . $q;
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$resp = file_get_contents($url, false, $ctx);
$data = json_decode($resp, true);
// Iterate $data['snapshots']; timestamps are UTC (ISO 8601)
?>

Sample JSON response

How to read: yield is a percent; fetched_at is UTC time for the snapshot. Use intraday for real-time monitoring and VWAP-like analytics.

Endpoint: Fluctuation over a Brazil period

Use fluctuation to compute start/end yields, absolute change, and within-period min/max for one or more countries over a window.

cURL

Python (requests)

import requests

params = {'countries': 'BR', 'maturity': '10Y', 'start': '2025-11-06', 'end': '2026-11-06'}
r = requests.get('https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
fl = r.json()
# fl['data']['BR'] contains start_yield, end_yield, change, min, max (all percents)

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-11-06');
url.searchParams.set('end', '2026-11-06');

fetch(url, { headers: {'X-API-Key': 'YOUR_API_KEY'} })
.then(r => r.json())
.then(json => {
const br = json.data.BR;
console.log('Change:', br.change, 'from', br.start_yield, 'to', br.end_yield);
});

PHP (file_get_contents)

<?php
$q = http_build_query([
'countries' => 'BR',
'maturity' => '10Y',
'start' => '2025-11-06',
'end' => '2026-11-06'
]);
$url = 'https://bonds-api.com/api/v1/fluctuation?' . $q;
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$resp = file_get_contents($url, false, $ctx);
$data = json_decode($resp, true);
// Use $data['data']['BR']['min'|'max'|'change']
?>

Sample JSON response

How to read: All values are percents. change is end_yield - start_yield. Use this for performance summaries and risk reports.

Business days, market holidays, updates, and caching

Yields generally update on Brazil business days. Intraday snapshots are available during trading hours and are timestamped in UTC. On weekends and Brazil market holidays, expect no intraday snapshots and the latest endpoint to reflect the most recent business day’s close. For robust apps, treat end-of-day values as cacheable until the next trading session and set short cache lifetimes for intraday calls.

When querying specific dates (historical, intraday), if the date has no data (for example a holiday), you may receive an error indicating no data. You can implement a fallback by stepping to the nearest prior business day where appropriate for your use case.

Building a Brazil yield curve and spreads in practice

You can build a curve with one call using the curve endpoint. If you need a custom curve across selected points or want to include off-the-run maturities, call latest with multiple maturities and stitch the results. Then compute spreads vs. benchmarks using the spread endpoint to monitor relative value and stress testing scenarios.

Maturity Use Case Endpoint
1M, 3M, 6MShort-term policy expectations, funding/latest, /curve
1Y, 2Y, 5YMacro regime shifts, belly of the curve/latest, /timeseries, /curve
10Y, 30YTerm premium, benchmark duration risk/latest, /curve, /spread

Error handling and response semantics

Error responses have the same shape across endpoints with success=false and error set to a message. Common HTTP statuses include 401 (missing/invalid API key), 403 (quota exceeded), 404 (no data for country/maturity/date), 422 (invalid parameter), 429 (rate limit), and 500 (server error). In all clients, check success before accessing fields, and implement retries with backoff for transient 429/500 statuses.

Official sample

The following official sample demonstrates a latest call and response format that you can run as-is. It uses a 10Y US example and includes a timestamp and currency metadata.

How to read: rates are percentages; date is YYYY-MM-DD; meta.timestamp is an ISO 8601 UTC timestamp; currencies indicates the base currency of the underlying instrument.

Real-world integration patterns

  • Financial dashboards: Use latest for tiles showing Brazil 2Y/5Y/10Y; call curve for a chart, and spread for BR vs. US.
  • Portfolio risk: Pull timeseries for DV01-sensitive points (e.g., 2Y/10Y) to run historical shocks and compute factor exposures.
  • Economics research: Use historical to anchor event windows and fluctuation to summarize regime changes.
  • Trading tools: Ingest intraday for monitoring moves around Brazil macro releases; alert on spread thresholds in basis points.

Get an API key and start integrating today: Register. You can also explore requests interactively in the MCP. For general product info, visit bonds-api.com or Get started with Bonds API.

FAQ

Q: What units are used for yields and spreads?
A: Yields are percentages (for example 4.52 means 4.52%). Spread values are in basis points (bps), where 100 bps equals 1 percentage point.

Q: What timezone are dates and timestamps in?
A: Dates are returned as YYYY-MM-DD (market date). Intraday fetched_at timestamps are UTC in ISO 8601 (e.g., 2026-11-06T12:00:00Z). Treat them as UTC when storing and displaying.

Q: How should I handle Brazil market holidays and weekends?
A: Expect no intraday snapshots on non-trading days. latest returns the most recent available business day. If you query a holiday with historical or intraday, handle 404 responses by stepping to the previous business day if needed.

Q: Can I build a Brazil yield curve with one request?
A: Yes. Use the curve endpoint for country=BR. It returns an object mapping maturities like 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y to yield percentages, plus an inverted flag.

Q: How often should I refresh data?
A: For end-of-day analytics, refresh after market close for Brazil. For monitoring during the session, use intraday and set shorter cache TTLs (minutes). For spreads, refresh at the same cadence as the underlying country and benchmark feeds.

Ready to integrate Brazil sovereign bond yields into your application? Generate your API key and start building in minutes: Register.

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.