You need reliable, programmatic access to the Vietnam 10-year government bond yield and related curve analytics, and you want that data inside your models, dashboards, and trading tools. By the end of this guide, you’ll be able to query, cache, and interpret Vietnam’s sovereign yields (with a focus on the 10Y), compute spreads, fetch intraday snapshots, and assemble a full curve using the Bonds API over simple GET requests returning JSON.
What the Vietnam 10Y yield represents and how Bonds API expresses it
Sovereign bond yields are quoted as annualized percentages. The Vietnam 10-year (VN 10Y) yield is the market-implied return for lending to the Government of Vietnam for a decade, incorporating expectations for inflation, monetary policy, and credit risk over the term. In the Bonds API:
- Yield values are expressed as decimal percentages (for example 4.52 means 4.52% per annum).
- Dates use the Y-m-d format (for example 2026-11-03).
- Timestamps, when present (for example fetched_at), are ISO-8601 in UTC (for example 2026-11-03T12:00:00Z).
- Spreads are returned in basis points (bps), where 1 bps = 0.01%.
All endpoints are GET requests to https://bonds-api.com/api/v1/ with authentication via the X-API-Key header. See documentation and service details at bonds-api.com. To start building, you’ll need an API key: Register for Bonds API and Get started with Bonds API. For component integrations and toolchains, also see Bonds API MCP.
Latest Vietnam yields: query the VN 10Y in real time
Use the latest endpoint when you need the most recently published yields. You can request one or multiple maturities. For the VN 10Y specifically, you can include 10Y in the maturities list; you can also add 2Y to build a mini-curve or spread.
Endpoint
GET /api/v1/latest with countries and optional maturities.
cURL example
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
Python (requests) example
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "VN", "maturities": "2Y,10Y"}
)
resp.raise_for_status()
data = resp.json()
# Access VN 10Y yield and date
vn10y = data["data"]["VN"]["10Y"]["yield"] # decimal percent, e.g., 4.52
vn10y_date = data["data"]["VN"]["10Y"]["date"] # "YYYY-MM-DD"
JavaScript (fetch) example
const url = "https://bonds-api.com/api/v1/latest?countries=VN&maturities=2Y,10Y";
fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(json => {
const vn10y = json.data.VN["10Y"].yield;
const date = json.data.VN["10Y"].date;
console.log("VN 10Y", vn10y, "on", date);
});
PHP (file_get_contents) example
<?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=VN&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$vn10y = $data["data"]["VN"]["10Y"]["yield"];
$date = $data["data"]["VN"]["10Y"]["date"];
echo "VN 10Y $vn10y% on $date\n";
JSON response (official sample for this endpoint)
{
"success": true,
"date": "2026-11-03",
"rates": {
"US_10Y": 4.909
},
"dates": {
"US_10Y": "2026-11-03"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "adc52648-b288-4937-b225-b245e16663cf",
"timestamp": "2026-11-03T00:05:50+00:00"
}
}
How to read it: success indicates the request status. data.VN.10Y.yield is the latest Vietnam 10Y yield as a percentage. date is the observation date (YYYY-MM-DD, local market date). source signals the provenance (for example official market or authority feed).
Live sample (as-is)
The following live-form sample block is provided as-is for demonstration purposes:
Point-in-time VN 10Y: historical on a specific date
When you need the VN 10Y yield for a particular date (for example for valuation, backtesting, or compliance checks), use the historical endpoint with a single country, maturity, and date.
Endpoint
GET /api/v1/historical with country, maturity, and date (Y-m-d).
cURL example
Python (requests) example
import requests
params = {"country": "VN", "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)
r.raise_for_status()
hist = r.json()
point_yield = hist["yield"] # decimal percent
point_date = hist["date"] # "YYYY-MM-DD"
JavaScript (fetch) example
const p = new URLSearchParams({ country: "VN", 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(json => console.log("VN 10Y on", json.date, "=", json.yield));
PHP (Guzzle) example
<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client();
$res = $client->get('https://bonds-api.com/api/v1/historical', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'VN', 'maturity' => '10Y', 'date' => '2025-06-15']
]);
$body = json_decode($res->getBody(), true);
echo $body['yield'];
JSON response
Interpretation: yield is the VN 10Y rate (percentage) for the specified date; source identifies where the rate originated.
VN 10Y time series: daily values over a range
To plot or model the VN 10Y over time, use the timeseries endpoint with start and end dates. Business-day gaps and holidays are naturally reflected as missing calendar dates where no observations exist.
Endpoint
GET /api/v1/timeseries with country, maturity, start, and end.
cURL example
Python (requests) example
import requests
q = {
"country": "VN",
"maturity": "10Y",
"start": "2025-11-03",
"end": "2026-11-03"
}
res = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
res.raise_for_status()
series = res.json()["series"] # list of {date, yield}
# Example: compute average yield
avg = sum(pt["yield"] for pt in series) / len(series)
JavaScript (fetch) example
const params = new URLSearchParams({
country: "VN",
maturity: "10Y",
start: "2025-11-03",
end: "2026-11-03"
});
fetch("https://bonds-api.com/api/v1/timeseries?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
json.series.forEach(pt => {
// pt.date = "YYYY-MM-DD"; pt.yield = decimal percent
});
});
PHP (file_get_contents) example
<?php
$q = http_build_query([
'country' => 'VN',
'maturity' => '10Y',
'start' => '2025-11-03',
'end' => '2026-11-03'
]);
$opts = ['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]];
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$q", false, stream_context_create($opts));
$data = json_decode($json, true);
$series = $data['series'];
JSON response
Interpretation: series is an ordered list of date/yield points; each yield is a percentage value. Non-trading days will not appear with a value unless the market published on those dates.
VN vs US spread: quantify relative value in bps
Relative value screens often compare Vietnam’s yields to a benchmark like the US Treasury. Use the spread endpoint to compute the 10Y spread in basis points. The response includes both legs for transparency.
Endpoint
GET /api/v1/spread with country, benchmark, and optional maturity (default 10Y).
cURL example
Python (requests) example
import requests
params = {"country": "VN", "benchmark": "US", "maturity": "10Y"}
res = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
res.raise_for_status()
sp = res.json()
bps = sp["spread_bps"] # integer or float, basis points
vn = sp["country_yield"] # percent
us = sp["benchmark_yield"]
JavaScript (fetch) example
const params = new URLSearchParams({ country: "VN", benchmark: "US", maturity: "10Y" });
fetch("https://bonds-api.com/api/v1/spread?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => console.log(`Spread ${j.spread_bps} bps (VN=${j.country_yield}%, US=${j.benchmark_yield}%)`));
PHP (Guzzle) example
<?php
$client = new \GuzzleHttp\Client();
$res = $client->get('https://bonds-api.com/api/v1/spread', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'VN', 'benchmark' => 'US', 'maturity' => '10Y']
]);
$body = json_decode($res->getBody(), true);
echo $body['spread_bps'];
JSON response
Interpretation: spread_bps is the VN 10Y minus US 10Y, in basis points. Positive values mean Vietnam yields higher than the benchmark; negative values indicate tighter yields than the benchmark.
Full Vietnam yield curve: build and inspect shape
To construct analytics like duration ladders or to value multi-maturity exposures, request the full Vietnam government curve for a given date. This returns short bills through long bonds when available.
Endpoint
GET /api/v1/curve with country and optional date (Y-m-d). If date is omitted, the latest available day is returned.
cURL example
Python (requests) example
import requests
res = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "VN"})
res.raise_for_status()
curve = res.json()
by_tenor = curve["curve"] # dict: tenor -> yield (percent)
inverted = curve["inverted"]
JavaScript (fetch) example
fetch("https://bonds-api.com/api/v1/curve?country=VN", {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
// j.date is "YYYY-MM-DD"
// j.curve has keys like "1M","3M","6M","1Y","2Y","5Y","10Y","30Y"
console.log("Inverted:", j.inverted);
});
PHP (file_get_contents) example
<?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=VN", false, $ctx);
$data = json_decode($json, true);
$tenors = $data['curve'];
JSON response
Interpretation: curve is a mapping from tenor to yield (percent). inverted is a boolean that flags if the curve slopes downward from short to long in a way that meets the service’s inversion test. date is the market date for the curve snapshot.
Intraday VN 10Y: snapshots across the trading day
When you need sub-daily granularity (for example for alerting or dashboard tiles), use the intraday endpoint. Intraday snapshots include an ISO-8601 fetched_at timestamp in UTC and a source field.
Endpoint
GET /api/v1/intraday with country, maturity, and date (Y-m-d).
cURL example
Python (requests) example
import requests
params = {"country": "VN", "maturity": "10Y", "date": "2026-11-03"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
r.raise_for_status()
snap = r.json()
for s in snap["snapshots"]:
# s["yield"] in percent, s["fetched_at"] in UTC
pass
JavaScript (fetch) example
const qs = new URLSearchParams({ country: "VN", maturity: "10Y", date: "2026-11-03" });
fetch("https://bonds-api.com/api/v1/intraday?" + qs, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => console.log("Count:", j.count, "TZ:", j.meta.timezone));
PHP (Guzzle) example
<?php
$client = new \GuzzleHttp\Client();
$res = $client->get('https://bonds-api.com/api/v1/intraday', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'VN', 'maturity' => '10Y', 'date' => '2026-11-03']
]);
$data = json_decode($res->getBody(), true);
echo $data['count'];
JSON response
Interpretation: snapshots is an array of intraday observations with UTC timestamps. Use meta.timezone to align with your application’s time zone, and count for quick checks on completeness.
Fluctuation analysis: period change, min, and max
For risk summaries or period-end reporting, quickly compute the VN 10Y change over a date range as well as observed min and max.
Endpoint
GET /api/v1/fluctuation with countries (one or more), maturity, start, and end.
cURL example
Python (requests) example
import requests
params = {
"countries": "VN",
"maturity": "10Y",
"start": "2025-11-03",
"end": "2026-11-03"
}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
r.raise_for_status()
fl = r.json()["data"]["VN"]
delta = fl["change"] # percentage points (end - start)
JavaScript (fetch) example
const q = new URLSearchParams({
countries: "VN",
maturity: "10Y",
start: "2025-11-03",
end: "2026-11-03"
});
fetch("https://bonds-api.com/api/v1/fluctuation?" + q, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => console.log(j.data.VN));
PHP (file_get_contents) example
<?php
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = "https://bonds-api.com/api/v1/fluctuation?countries=VN&maturity=10Y&start=2025-11-03&end=2026-11-03";
$data = json_decode(file_get_contents($url, false, $ctx), true);
print_r($data['data']['VN']);
JSON response
Interpretation: change is the absolute percentage-point change between start_yield and end_yield (not basis points). min and max are the observed extrema over the period.
Practical details: maturities, business days, holidays, and caching
Maturities: Vietnam coverage includes common on-the-run maturities across bills and bonds (for example 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y). Availability depends on market publication for a given day. You can discover the set via the curve endpoint or by omitting maturities in the latest endpoint for VN.
Business days and holidays: Sovereign yields typically update on local trading days. If the Vietnam market is closed (local public holidays or weekends), daily endpoints will reflect the last published date; timeseries naturally skips non-publication days.
Update frequency: latest updates as the underlying sources publish. For intraday, snapshots carry fetched_at timestamps in UTC. Use them to assess staleness in real time.
Caching strategy:
- Cache latest VN 10Y for a short TTL (for example 1–5 minutes) during trading hours; extend TTL outside trading hours and on weekends/holidays.
- Cache historical and timeseries responses aggressively (hours to days), as backfills for past dates don’t change.
- Include E2E monitoring around error shapes (see below) to degrade gracefully when quota or rate limits are hit.
Building a multi-tenor curve for analysis: call /api/v1/curve once per country to get all available tenors and avoid stitching multiple latest calls. If you need a two-point curve (for example 2Y and 10Y only) for a lightweight widget, use /api/v1/latest with maturities=2Y,10Y. For cross-sectional analytics across countries, use /api/v1/latest with countries=VN,US and a shared maturities list, then compute spreads or interpolations in your app.
Error handling: all error responses use success=false and an error message string. Common statuses: 401 (missing or invalid API key), 403 (quota exceeded), 404 (no data for the requested combination), 422 (invalid parameter or date format), 429 (rate limit exceeded), 500 (server error). Always check HTTP status and then success in the parsed JSON. For more resources, visit bonds-api.com and explore integration patterns in the MCP.
Field definitions and units at a glance
- yield: decimal percentage (for example 4.52 means 4.52% per annum).
- date: observation date, Y-m-d, local market date of the yield.
- fetched_at: ISO-8601 timestamp in UTC for intraday snapshots.
- spread_bps: basis points (1 bps = 0.01%).
- inverted: boolean flag indicating curve inversion based on the provider’s check.
- source: string label for the data source (for example official, market).
Developer use cases for the Vietnam 10Y
- Financial dashboards: show the VN 10Y tile with period change from /api/v1/fluctuation and a mini-sparkline from /api/v1/timeseries.
- Portfolio risk: compute DV01 or spread-based stress by combining /api/v1/curve for VN with /api/v1/spread against a benchmark.
- Economic research: perform event studies around policy announcements using /api/v1/intraday snapshots and pre/post day /api/v1/historical points.
- Alerting: trigger notifications when VN 10Y exceeds a threshold or when intraday change surpasses N bps using /api/v1/intraday combined with cached latest.
Common error responses
The API returns structured errors you can parse for robust handling:
- 401: Missing or invalid X-API-Key
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date combination
- 422: Invalid parameter (wrong date format, unknown ISO2 code, etc.)
- 429: Rate limit exceeded
- 500: Server error
Pattern: success=false and error is a message string. Inspect HTTP status and JSON body to branch retries, backoffs, or fallbacks.
Quick links and next steps
Start integrating with a free API key: Register. Explore SDKs, components, and workflows in the MCP. General docs and product info live at bonds-api.com. You can also bookmark Get started with Bonds API for later.
FAQ
How are VN yields quoted in the API?
As decimal percentages (for example 4.52 represents 4.52% per annum). Spreads from the spread endpoint are in basis points.
What timezone should I assume for intraday timestamps?
All intraday fetched_at fields are ISO-8601 UTC. Daily dates (date fields) use Y-m-d in the local market context.
How can I build a Vietnam yield curve without multiple calls?
Use /api/v1/curve?country=VN to retrieve all available tenors and an inversion flag for the given date.
How do I compare Vietnam to the US 10Y?
Call /api/v1/spread?country=VN&benchmark=US&maturity=10Y to get the spread in bps plus both leg yields for transparency.
What should I cache?
Cache historical and timeseries responses aggressively. Cache latest with a short TTL during trading hours and longer off-hours. Always propagate error JSON to logs for diagnosis.
Ready to ship your integration? Grab an API key and start pulling the Vietnam 10-year yield into your stack today: Register. If you need modular building blocks and workflows, visit the MCP.