Problem: you need accurate Ukraine 10-year sovereign yields you can fetch programmatically and use inside your analytics, risk tools, or dashboards. By the end of this article, you will know exactly how to query, cache, and interpret Ukraine’s 10Y yield (and the full curve) using Bonds API endpoints, including latest values, historical snapshots, intraday ticks, spreads versus benchmarks, fluctuations, and a full yield curve.
What you will build with Bonds API for Ukraine 10Y
We will focus on the Ukraine (ISO2: UA) 10Y maturity while also showing how to assemble the full curve and compute spreads versus benchmark sovereigns. The Bonds API provides yields as JSON over GET requests at https://bonds-api.com/api/v1/ with API key authentication via the X-API-Key header. You can explore the API and documentation at bonds-api.com and the MCP.
Units and conventions:
- yield: percentage (e.g., 4.52 means 4.52%)
- spread_bps: basis points (1 bp = 0.01%)
- date fields: Y-m-d (e.g., 2026-10-06) and timestamps are ISO 8601 in UTC
- source field: data provenance, such as "official" or "market"
Official sample block (verbatim)
The following official sample shows a US 10Y request and response. Copy it as-is to verify basic connectivity to the API. Note that this block uses an api_key query parameter as part of the official demonstration; in the rest of this article we will use the documented X-API-Key header for authentication. Keep both patterns in mind when testing.
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-06",
"rates": {
"US_10Y": 5.309
},
"dates": {
"US_10Y": "2026-10-06"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "5581acc2-298a-437f-8f67-72b51db4f81a",
"timestamp": "2026-10-06T00:05:39+00:00"
}
}How to read it:
- rates.US_10Y is the 10-year US yield in percent.
- date is the market date of the snapshot (Y-m-d).
- meta.timestamp is an ISO 8601 UTC timestamp when the response was generated.
Current yields for Ukraine: GET /api/v1/latest
Use this endpoint to fetch the latest available yields for one or more maturities. If you omit maturities, you receive all available tenors for UA. This is the fastest way to grab a 10Y point and, if needed, adjacent maturities for on-the-fly curve construction.
cURL
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "UA", "maturities": "2Y,10Y"}
)
data = resp.json()
# Example: access UA 10Y yield
ua_10y = data["data"]["UA"]["10Y"]["yield"]
ua_10y_date = data["data"]["UA"]["10Y"]["date"]
JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "UA");
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 ua10y = json.data.UA["10Y"].yield;
const ua10yDate = json.data.UA["10Y"].date;
console.log("UA 10Y:", ua10y, "date:", ua10yDate);
});
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=UA&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$ua10y = $data["data"]["UA"]["10Y"]["yield"];
$ua10yDate = $data["data"]["UA"]["10Y"]["date"];
echo "UA 10Y: $ua10y on $ua10yDate\n";
JSON response (official for this endpoint)
How to read it:
- data.UA.10Y.yield is the 10Y Ukraine yield in percent.
- date is the market date (Y-m-d) of that yield.
- source indicates where the value was sourced ("official").
Point-in-time 10Y yield: GET /api/v1/historical
When you need the 10Y yield on a specific date—for backtesting or event studies—use this endpoint. It returns a single point for the given date and maturity.
cURL
Python (requests)
import requests
params = {"country": "UA", "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
)
pt = r.json()
# Access fields
ua10y = pt["yield"]
pt_date = pt["date"]
JavaScript (fetch)
const params = new URLSearchParams({
country: "UA",
maturity: "10Y",
date: "2025-06-15"
});
fetch(`https://bonds-api.com/api/v1/historical?${params.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
console.log("UA 10Y on", json.date, "=", json.yield);
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "UA",
"maturity" => "10Y",
"date" => "2025-06-15"
]);
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/historical?$params";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "UA 10Y on {$data["date"]}: {$data["yield"]}\n";
JSON response (official for this endpoint)
Key fields:
- yield: 10Y yield in percent on that date.
- date: the requested Y-m-d date.
- source: data provenance.
Time series for Ukraine 10Y: GET /api/v1/timeseries
Pull a continuous time series (business days with data) for the 10Y maturity between two calendar dates. Use this for charting, modeling, and volatility studies.
cURL
Python (requests)
import requests
params = {
"country": "UA",
"maturity": "10Y",
"start": "2025-10-06",
"end": "2026-10-06"
}
r = requests.get(
"https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params
)
series = r.json()["series"]
# Example: iterate
for point in series:
d = point["date"]
y = point["yield"]
# store or plot (d, y)
JavaScript (fetch)
const sp = new URLSearchParams({
country: "UA",
maturity: "10Y",
start: "2025-10-06",
end: "2026-10-06"
});
fetch(`https://bonds-api.com/api/v1/timeseries?${sp.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
json.series.forEach(pt => {
console.log(pt.date, pt.yield);
});
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "UA",
"maturity" => "10Y",
"start" => "2025-10-06",
"end" => "2026-10-06"
]);
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/timeseries?$params";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
foreach ($data["series"] as $pt) {
echo $pt["date"] . " " . $pt["yield"] . PHP_EOL;
}
JSON response (official for this endpoint)
How to read it:
- series is an array of daily observations with Y-m-d date and yield in percent.
- Only days with data are returned (weekends/holidays may be absent).
Spread vs benchmark: GET /api/v1/spread
Compute Ukraine’s spread against a benchmark sovereign (e.g., US 10Y) for a given maturity (defaults to 10Y if omitted). Spreads are returned in basis points as spread_bps.
cURL
Python (requests)
import requests
params = { "country": "UA", "benchmark": "US", "maturity": "10Y" }
r = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params
)
spread = r.json()
bps = spread["spread_bps"] # basis points
ua_yield = spread["country_yield"] # percent
us_yield = spread["benchmark_yield"] # percent
JavaScript (fetch)
const qs = new URLSearchParams({
country: "UA",
benchmark: "US",
maturity: "10Y"
});
fetch(`https://bonds-api.com/api/v1/spread?${qs.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
console.log("Spread (bps):", json.spread_bps);
console.log("UA 10Y:", json.country_yield, "US 10Y:", json.benchmark_yield);
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "UA",
"benchmark" => "US",
"maturity" => "10Y"
]);
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/spread?$params";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "Spread (bps): {$data["spread_bps"]}\n";
JSON response (official for this endpoint)
Key fields:
- spread_bps: spread in basis points (e.g., 215 bps = 2.15%).
- country_yield and benchmark_yield: yields in percent for the same maturity.
Full Ukraine yield curve: GET /api/v1/curve
Fetch a single-date curve with multiple tenors to build a complete view including bills and long bonds. The response also flags whether the curve is inverted.
cURL
Python (requests)
import requests
r = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "UA"}
)
curve = r.json()
date = curve["date"]
tenors = curve["curve"] # dict of tenor -> yield (percent)
inverted = curve["inverted"]
JavaScript (fetch)
const p = new URLSearchParams({ country: "UA" });
fetch(`https://bonds-api.com/api/v1/curve?${p.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
console.log("Curve date:", json.date);
console.log("Inverted:", json.inverted);
Object.entries(json.curve).forEach(([tenor, y]) => {
console.log(tenor, y);
});
});
PHP (file_get_contents)
<?php
$params = http_build_query(["country" => "UA"]);
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/curve?$params";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "Curve date: {$data["date"]}, inverted: " . ($data["inverted"] ? "yes" : "no") . PHP_EOL;
foreach ($data["curve"] as $tenor => $yield) {
echo "$tenor: $yield" . PHP_EOL;
}
JSON response (official for this endpoint)
How to read it:
- curve is a map of tenor to yield in percent.
- inverted indicates whether shorter maturities exceed longer ones across the curve.
Intraday snapshots for UA 10Y: GET /api/v1/intraday
Use intraday snapshots to capture within-day yield moves for trading tools, alerting, or microstructure analysis. Timestamps are in UTC.
cURL
Python (requests)
import requests
params = {"country": "UA", "maturity": "10Y", "date": "2026-10-06"}
r = requests.get(
"https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params
)
ticks = r.json()
for snap in ticks["snapshots"]:
print(snap["fetched_at"], snap["yield"], snap["source"])
JavaScript (fetch)
const pr = new URLSearchParams({
country: "UA",
maturity: "10Y",
date: "2026-10-06"
});
fetch(`https://bonds-api.com/api/v1/intraday?${pr.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
console.log("Timezone:", json.meta.timezone);
json.snapshots.forEach(s => {
console.log(s.fetched_at, s.yield, s.source);
});
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "UA",
"maturity" => "10Y",
"date" => "2026-10-06"
]);
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/intraday?$params";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "Timezone: {$data["meta"]["timezone"]}\n";
foreach ($data["snapshots"] as $s) {
echo "{$s["fetched_at"]} {$s["yield"]} {$s["source"]}\n";
}
JSON response (official for this endpoint)
Key fields:
- snapshots[].yield is percent; fetched_at is ISO 8601 UTC.
- meta.timezone confirms timestamps are UTC.
Fluctuations over a period: GET /api/v1/fluctuation
Summarize change, min, and max for one or more countries and a fixed maturity across a given period. This is a compact alternative to pulling the entire time series.
cURL
Python (requests)
import requests
params = {
"countries": "UA",
"maturity": "10Y",
"start": "2025-10-06",
"end": "2026-10-06"
}
r = requests.get(
"https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params
)
fx = r.json()["data"]["UA"]
delta = fx["change"] # percent change (end - start)
JavaScript (fetch)
const qp = new URLSearchParams({
countries: "UA",
maturity: "10Y",
start: "2025-10-06",
end: "2026-10-06"
});
fetch(`https://bonds-api.com/api/v1/fluctuation?${qp.toString()}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const fx = json.data.UA;
console.log("Start:", fx.start_yield, "End:", fx.end_yield, "Change:", fx.change);
console.log("Min:", fx.min, "Max:", fx.max);
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"countries" => "UA",
"maturity" => "10Y",
"start" => "2025-10-06",
"end" => "2026-10-06"
]);
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/fluctuation?$params";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$ua = $data["data"]["UA"];
echo "Change: {$ua["change"]} (Start: {$ua["start_yield"]}, End: {$ua["end_yield"]})\n";
JSON response (official for this endpoint)
How to read it:
- start_yield and end_yield are percent values at the period boundaries.
- change is the arithmetic difference in percent (end - start).
- min and max are the observed extrema within [start, end].
Business days, holidays, updates, and caching
Bonds API aligns with market calendars such that weekends and market holidays typically have no new records. That means time series will skip non-trading days; do not assume a continuous calendar.
- Update cadence: latest and curve typically reflect the most recent market day with available data. Intraday snapshots provide multiple points intra-session, timestamped in UTC.
- Caching: if you poll frequently, cache by (country, maturity, date) for daily endpoints. For intraday, cache by fetched_at timestamp to avoid duplicate processing.
- Backfilling: when querying a historical date that is not a business day, expect an error (404) unless data exists for that calendar date. Use timeseries to navigate around closures.
- Symbols/maturities: you can request multiple tenors in /latest with maturities=1Y,2Y,5Y,10Y,... to build a partial curve quickly. For a complete snapshot, use /curve.
For more endpoint details and guidance, visit bonds-api.com.
Error handling and reliability
All endpoints return JSON with success=true on success. When success=false, the error field contains a diagnostic string. Handle these HTTP statuses:
- 401: Missing or invalid X-API-Key
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date
- 422: Invalid parameter (format, ISO2 code, etc.)
- 429: Rate limit exceeded
- 500: Server error
Production recommendations:
- Validate dates (Y-m-d) client-side to prevent 422s.
- Backoff and retry on 429 and 500 with jitter.
- Log error, request params, and response meta (when present) for observability.
Use cases for Ukraine 10Y and the UA curve
- Financial dashboards: display a UA 10Y tile sourced from /latest with automated refresh and market-day cache busting.
- Portfolio risk tools: calibrate duration and spread risk using /timeseries and /spread versus a benchmark like US for cross-market context.
- Economic research: assess policy transmission and term structure dynamics via /curve across dates and /fluctuation summaries for volatility windows.
- Alerts and monitoring: use /intraday to trigger notifications on yield moves beyond a threshold in percent or bps.
End-to-end: building a Ukraine 10Y curve view
For a single-page app or service:
- Query /curve?country=UA for a complete snapshot, and render a curve chart. Note inverted flag for annotation.
- Query /spread?country=UA&benchmark=US&maturity=10Y to display the on-the-run 10Y spread in bps.
- Provide a sparkline using /timeseries?country=UA&maturity=10Y over a configurable window (e.g., past 12 months).
- Enable intraday mode using /intraday for today’s date if your UI supports tick-level updates; otherwise keep to daily close data.
If you only need a couple of tenors and want minimal payloads, use /latest with maturities=2Y,5Y,10Y for a lightweight curve segment. For detailed documentation and quick start, open the MCP.
FAQ
Q1: What units should I expect for yields and spreads?
A: Yields are in percent (e.g., 4.52 means 4.52%). Spreads are in basis points (spread_bps), where 100 bps = 1.00%.
Q2: How do I handle non-trading days in time series?
A: /timeseries returns only dates with data. If you need a continuous daily index, forward-fill yields across missing calendar days at your application layer.
Q3: Can I request multiple maturities at once?
A: Yes, with /latest by passing a comma-separated maturities list (e.g., 2Y,5Y,10Y). For a single-date full curve, use /curve.
Q4: What timezone are timestamps in?
A: Dates are Y-m-d (market date). Timestamps (e.g., intraday fetched_at) are ISO 8601 in UTC, and meta.timezone confirms this.
Q5: How do I authenticate?
A: Send your API key in the X-API-Key header for all requests. You can learn more and test endpoints at bonds-api.com.
Ready to integrate Ukraine 10Y yields into your tools? Get your key and start calling the endpoints in minutes: Register. For a guided exploration of endpoints and schemas, open the MCP and browse live examples.