You need reliable, programmatic access to Hungary’s sovereign bond yields so you can build yield curves, monitor spreads, and power risk models. By the end of this guide, you will be able to fetch current and historical Hungarian government bond yields, assemble a complete HU yield curve, calculate spreads versus benchmarks, and integrate all seven Bonds-API endpoints into production code with caching and holiday-aware logic.
What this article covers and who it’s for
This deep dive focuses on Hungary (ISO2: HU) and the Bonds API endpoints you will use to query Hungarian government bond yields across maturities. It is written for fixed-income analysts, quantitative developers, and fintech teams who need HU yield data in dashboards, risk engines, or research notebooks.
All requests are GET, the base URL is https://bonds-api.com/api/v1/, and authentication is via the X-API-Key header. Yields are expressed in percent (for example, 4.52 means 4.52%) unless otherwise noted. Timestamps in intraday data are UTC. For API reference and account setup, visit bonds-api.com or use these quick links: Register for Bonds API, Bonds API MCP, and Get started with Bonds API.
Authentication and environment basics
All endpoints below require your API key in the X-API-Key header. Do not pass the key as a query parameter. Sample header:
X-API-Key: YOUR_API_KEY
Base URL for all endpoints:
https://bonds-api.com/api/v1/
Recommended practices:
- Cache the latest endpoint for a few minutes to absorb minor fluctuations and reduce rate usage.
- Align historical/time series requests to business days; if a requested date is a market holiday or weekend, data will correspond to the latest available prior business day.
- Handle error responses consistently (401 for auth, 403 for quota, 404 for no data, 422 for invalid params, 429 for rate limiting, 500 for server errors).
Endpoint: Latest yields (current levels by maturity)
Use GET /latest to retrieve current Hungarian sovereign bond yields. You can request specific maturities or omit them to get all available points. Yields are percentages.
cURL
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
JSON response (example)
{
"success": true,
"date": "2026-10-28",
"rates": {
"US_10Y": 4.994
},
"dates": {
"US_10Y": "2026-10-28"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "e0d801dc-3f3b-4376-81a8-0d1b7756ef1d",
"timestamp": "2026-10-28T00:04:45+00:00"
}
}
How to read:
- yield: Percent level (4.52 means 4.52%).
- date: ISO date (YYYY-MM-DD) of the observation, aligned to market days.
- source: Origin of data (e.g., “official”).
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/latest',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'HU', 'maturities': '2Y,10Y'}
)
resp.raise_for_status()
data = resp.json()
hu_2y = data['data']['HU']['2Y']['yield']
hu_10y = data['data']['HU']['10Y']['yield']
obs_date = data['data']['HU']['10Y']['date']
print('HU 2Y:', hu_2y, 'HU 10Y:', hu_10y, 'as of', obs_date)
JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/latest');
url.search = new URLSearchParams({ countries: 'HU', maturities: '2Y,10Y' }).toString();
fetch(url, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(json => {
const twoY = json.data.HU['2Y'].yield;
const tenY = json.data.HU['10Y'].yield;
console.log('HU 2Y:', twoY, 'HU 10Y:', tenY);
});
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=HU&maturities=2Y,10Y';
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo 'HU 10Y: ' . $data['data']['HU']['10Y']['yield'] . PHP_EOL;
Endpoint: Historical (yield on a specific date)
Use GET /historical for the HU yield on a single date. If the date is a weekend/holiday, the API serves the nearest prior business day if available.
cURL
JSON response (example)
Fields:
- yield: Percent yield for the given date/maturity.
- date: ISO date requested (or the effective observation, per exchange calendar).
Python
import requests
r = requests.get(
'https://bonds-api.com/api/v1/historical',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'HU', 'maturity': '10Y', 'date': '2025-06-15'}
)
r.raise_for_status()
hist = r.json()
print(hist['date'], hist['maturity'], hist['yield'])
JavaScript
const params = { country: 'HU', maturity: '10Y', date: '2025-06-15' };
const urlH = 'https://bonds-api.com/api/v1/historical?' + new URLSearchParams(params);
fetch(urlH, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(d => console.log(`${d.country} ${d.maturity} on ${d.date}: ${d.yield}%`));
PHP
<?php
$q = http_build_query(['country' => 'HU', 'maturity' => '10Y', 'date' => '2025-06-15']);
$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/historical?' . $q, false, $ctx);
echo $json;
Endpoint: Time series (yield series between two dates)
Use GET /timeseries to retrieve a continuous series for HU at a single maturity between start and end dates. The series respects business days.
cURL
JSON response (example)
Note: Each entry carries a date and yield in percent.
Python
import requests
import pandas as pd
r = requests.get(
'https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'HU', 'maturity': '10Y', 'start': '2025-10-28', 'end': '2026-10-28'}
)
r.raise_for_status()
ts = r.json()['series']
df = pd.DataFrame(ts) # columns: date, yield
print(df.head())
JavaScript
const tsParams = { country: 'HU', maturity: '10Y', start: '2025-10-28', end: '2026-10-28' };
const tsUrl = 'https://bonds-api.com/api/v1/timeseries?' + new URLSearchParams(tsParams);
fetch(tsUrl, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(d => {
const series = d.series.map(pt => [pt.date, pt.yield]);
console.log(series.slice(0, 5));
});
PHP
<?php
$params = http_build_query([
'country' => 'HU', 'maturity' => '10Y',
'start' => '2025-10-28', 'end' => '2026-10-28'
]);
$ctx = 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, $ctx);
$data = json_decode($json, true);
foreach ($data['series'] as $row) {
echo $row['date'] . ' ' . $row['yield'] . PHP_EOL;
}
Endpoint: Spread (HU vs benchmark)
Use GET /spread to compute the yield differential between Hungary and a benchmark market (for example, US or DE) at a chosen maturity. Spread is in basis points (1 bp = 0.01%).
cURL
JSON response (example)
Fields:
- spread_bps: Basis point difference (positive if HU > benchmark).
- country_yield, benchmark_yield: Percent yields used in the calculation.
Python
import requests
r = requests.get(
'https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'HU', 'benchmark': 'US', 'maturity': '10Y'}
)
spread = r.json()
print('Spread (bps):', spread['spread_bps'])
JavaScript
const spParams = { country: 'HU', benchmark: 'US', maturity: '10Y' };
const spUrl = 'https://bonds-api.com/api/v1/spread?' + new URLSearchParams(spParams);
fetch(spUrl, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(s => console.log(`HU vs ${s.benchmark} at ${s.maturity}: ${s.spread_bps} bps`));
PHP
<?php
$q = http_build_query(['country' => 'HU', 'benchmark' => 'US', 'maturity' => '10Y']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents('https://bonds-api.com/api/v1/spread?' . $q, false, $ctx);
echo $json;
Endpoint: Curve (full HU yield curve)
Use GET /curve to retrieve the full Hungarian yield curve for the most recent available date (or a specified date). This endpoint returns multiple maturity points in one response, which is convenient for plotting, bootstrapping, or calculating curve factors.
cURL
JSON response (example)
Fields:
- curve: Map of maturity to percent yield.
- inverted: Boolean flag indicating if the short end exceeds the long end overall.
- date: ISO observation date for the entire curve.
Maturities at a glance
| Maturity | Comment |
|---|---|
| 1M, 3M, 6M | Short bills; useful for liquidity and policy rate expectations. |
| 1Y, 2Y | Short notes; sensitive to policy path and front-end inflation. |
| 5Y, 10Y | Benchmark curve segment; duration risk and macro expectations. |
| 30Y | Long duration exposure; term premium signals. |
Python
import requests
r = requests.get(
'https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'HU'}
)
curve = r.json()
print('Curve date:', curve['date'])
for mat, yld in curve['curve'].items():
print(mat, yld)
JavaScript
fetch('https://bonds-api.com/api/v1/curve?country=HU', {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(c => {
console.log('Inverted?', c.inverted);
Object.entries(c.curve).forEach(([mat, y]) => console.log(mat, y));
});
PHP
<?php
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents('https://bonds-api.com/api/v1/curve?country=HU', false, $ctx);
$data = json_decode($json, true);
echo 'Date: ' . $data['date'] . PHP_EOL;
Endpoint: Intraday (snapshots throughout a trading day)
Use GET /intraday for multiple yield snapshots during a specific date. Timestamps are in UTC.
cURL
JSON response (example)
Fields:
- snapshots[].yield: Percent yields at each capture time.
- snapshots[].fetched_at: ISO 8601 UTC timestamp.
- count: Number of snapshots for the day.
Python
import requests
from datetime import datetime
r = requests.get(
'https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'HU', 'maturity': '10Y', 'date': '2026-10-28'}
)
intraday = r.json()
for s in intraday['snapshots']:
t = datetime.fromisoformat(s['fetched_at'].replace('Z', '+00:00'))
print(t, s['yield'])
JavaScript
const iParams = { country: 'HU', maturity: '10Y', date: '2026-10-28' };
const iUrl = 'https://bonds-api.com/api/v1/intraday?' + new URLSearchParams(iParams);
fetch(iUrl, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(d => d.snapshots.forEach(s => console.log(s.fetched_at, s.yield)));
PHP
<?php
$q = http_build_query(['country' => 'HU', 'maturity' => '10Y', 'date' => '2026-10-28']);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/intraday?' . $q, false, $ctx);
Endpoint: Fluctuation (change/min/max over a period)
Use GET /fluctuation to summarize HU yield change, min, and max over a date range. This is ideal for dashboards and alerting.
cURL
JSON response (example)
Fields:
- start_yield/end_yield: Percent yields at the endpoints.
- change: Difference in percentage points (end - start).
- min/max: Extremes over the period.
Python
import requests
r = requests.get(
'https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'HU', 'maturity': '10Y', 'start': '2025-10-28', 'end': '2026-10-28'}
)
fl = r.json()['data']['HU']
print('Change (pp):', fl['change'], 'Range:', fl['min'], '-', fl['max'])
JavaScript
const fParams = { countries: 'HU', maturity: '10Y', start: '2025-10-28', end: '2026-10-28' };
const fUrl = 'https://bonds-api.com/api/v1/fluctuation?' + new URLSearchParams(fParams);
fetch(fUrl, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(d => {
const s = d.data.HU;
console.log(`Δ: ${s.change} pp, min: ${s.min}%, max: ${s.max}%`);
});
PHP
<?php
$q = http_build_query([
'countries' => 'HU',
'maturity' => '10Y',
'start' => '2025-10-28',
'end' => '2026-10-28'
]);
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/fluctuation?' . $q, false, $ctx);
Building, reading, and caching the Hungary yield curve
When you need multiple maturities at once, prefer GET /curve to minimize requests and ensure all points are synchronized to the same date. If you need bespoke points not returned by /curve, you can call GET /latest with maturities specified, but cache the full result and extract what you need locally. For time-dependent analytics (DV01, key-rate durations, or Nelson-Siegel fits), use the curve’s observation date to align derived outputs, and store it alongside the vector of yields.
Caching suggestions:
- Latest/curve endpoints: cache 1–5 minutes intraday; refresh on market events.
- Historical/timeseries: cache permanently after first retrieval for a given (country, maturity, date).
- Intraday: cache until the next polling cycle; keep timestamps in UTC.
Business days and holidays: The API aligns yields to available market days. If you query a non-trading day with /historical or /intraday, handle a potential 404 for unsupported combos or rely on time series for continuous sequences without guessing missing dates. Always log 422 to catch malformed parameters (e.g., wrong date format).
Sovereign bond fundamentals (Hungary context)
Hungarian government bonds reflect the market’s expectations for inflation, policy rate path, and sovereign risk. Front-end maturities (1M–2Y) are highly sensitive to central bank communication, while intermediates (5Y–10Y) incorporate medium-term macro outlook and term premium. The long end (30Y) is driven by long-horizon inflation and growth expectations, liability hedging demand, and supply dynamics.
Typical workflows:
- Real-time monitoring: Use /latest for HU 2Y/10Y and /intraday for intra-session tracking.
- Backtesting: Retrieve /timeseries for HU 10Y and compute rolling volatility, drawdowns, or factor loadings.
- Relative value: Use /spread with benchmark=DE or US to track HU-Bund or HU-UST spread in bps.
- Curve analytics: Pull /curve for all points, check inverted=false/true for curve shape, and fit a curve model.
Explore more capabilities at bonds-api.com and the developer console in the Bonds API MCP. For a step-by-step start and an API key, see Register and the MCP.
Error handling and operational guidance
- 401 Unauthorized: Ensure X-API-Key is present and valid.
- 403 Quota exceeded: Back off and alert internally.
- 404 Not found: No data for the requested combination; validate country ISO2 (HU) and maturity codes.
- 422 Validation: Check date formatting (YYYY-MM-DD) and parameter names.
- 429 Rate limit: Implement exponential backoff and client-side caching.
- 500 Server error: Retry with jitter; avoid tight loops.
Deployment tips:
- Set explicit timeouts in HTTP clients.
- Normalize all dates to UTC and store as YYYY-MM-DD for dailies; use ISO 8601 with timezone for intraday.
- Log the endpoint, query params, and response status for observability.
Official sample
The following official sample shows a latest-yield request and response shape.
In this structure: rates are percentages; date fields use YYYY-MM-DD; timestamp is ISO 8601 with UTC offset.
End-to-end example: assembling a Hungary curve, spread, and change
Steps
- Get the full HU curve using GET /curve to populate your curve vector and the observation date.
- Compute HU vs US 10Y spread with GET /spread (maturity=10Y) and store spread_bps for dashboards.
- Pull a year of HU 10Y with GET /timeseries and a 1-year fluctuation summary via GET /fluctuation to display Δ, min, and max alongside the chart.
- Optionally, refresh HU 10Y throughout the day with GET /intraday to power tick charts.
Production checklist
- Use X-API-Key header for all requests.
- Backoff on 429; cache latest/curve responses to reduce load.
- Standardize units: yields in percent; spreads in basis points.
- Normalize times to UTC; watch for local holidays affecting availability.
- Persist the observation date with each stored yield vector for reproducibility.
FAQ
Q: What units are used for yields and spreads?
A: Yields are in percent (e.g., 4.52 means 4.52%). Spreads from /spread are in basis points (bps), where 100 bps = 1 percentage point.
Q: How should I handle weekends and holidays for Hungary?
A: For /historical and /timeseries, the API provides data for business days. If you request a non-trading day and receive 404 or an adjusted date, align your logic to prior business days or rely on /timeseries for continuous sequences.
Q: Can I request multiple maturities for Hungary at once?
A: Yes. Use /curve for a synchronized set of maturities, or /latest with a comma-separated maturities list if you need a subset. Both return yields in percent.
Q: What timezone are intraday timestamps?
A: Intraday timestamps use UTC in ISO 8601 format (e.g., 2026-10-28T12:00:00Z).
Q: How frequently are HU yields updated?
A: Updates follow market availability. Use /intraday for within-day snapshots, and /latest or /curve for the most recent daily levels. Cache results to smooth minor refresh intervals.
Start integrating Hungarian sovereign yields into your analytics in minutes. Get your API key and explore the developer console: Register or open the MCP. For documentation and platform overview, visit bonds-api.com.