You need Taiwan government bond yields inside your own tools: build a live TW yield curve, compare 10-year spreads to the US, download history for backtests, and capture intraday snapshots for trading dashboards. By the end of this article you will pull Taiwan yields from Bonds API, handle business-day updates and caching, compute spreads, and assemble a full curve for analytics.
Scope, maturities, and units
This guide focuses on Taiwan (ISO2: TW) sovereign bond yields from bonds-api.com. The API returns yields in percentage points (for example 4.52 means 4.52%), and spreads in basis points (1 basis point = 0.01%). Dates are formatted as YYYY-MM-DD and timestamps are UTC ISO-8601.
Typical TW maturities available via Bonds API include money-market bills through long bonds. When you query the curve endpoint you’ll receive a consolidated set across short and long tenors in one response, for example 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y. The latest endpoint also supports selecting specific maturities.
Data is updated on business days for Taiwan’s market calendar. On market holidays or weekends, the “latest” will reflect the most recent available trading day. Time series omit non-trading days by design; use the series dates as the canonical trading-day calendar.
Authentication, methods, and base URL
- Base URL: https://bonds-api.com/api/v1/
- HTTP method: GET for all endpoints
- Authentication: X-API-Key header only (e.g. X-API-Key: YOUR_API_KEY)
You can Register for Bonds API and also explore endpoints interactively in the Bonds API MCP. For a fast start with an API key, Get started with Bonds API.
Reading yields, dates, and timestamps
All “yield” values are percentages. For example, "yield": 4.52 should be read as 4.52%. Fields labeled “spread_bps” are in basis points; for example 215 means a 2.15% spread.
Dates use "YYYY-MM-DD" (e.g., "2026-10-25"). Intraday “fetched_at” timestamps are UTC ISO strings (e.g., "2026-10-25T12:00:00Z"). When combining multiple endpoints, align by date fields before calculating curves or spreads.
Endpoint: Latest Taiwan yields
Use this to get the most recent available yields for Taiwan, optionally filtered by maturities. Helpful for dashboards and for initializing a TW curve snapshot at app startup.
cURL
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "TW", "maturities": "2Y,10Y"}
)
data = resp.json()
# Example access:
tw_2y = data["data"]["TW"]["2Y"]["yield"]
tw_10y = data["data"]["TW"]["10Y"]["yield"]
tw_date = data["data"]["TW"]["10Y"]["date"]
JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "TW");
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 tw = json.data.TW;
const y2 = tw["2Y"].yield; // percent
const y10 = tw["10Y"].yield; // percent
const asOf = tw["10Y"].date; // YYYY-MM-DD
console.log(y2, y10, asOf);
});
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=TW&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$y2 = $data["data"]["TW"]["2Y"]["yield"];
$y10 = $data["data"]["TW"]["10Y"]["yield"];
$asOf = $data["data"]["TW"]["10Y"]["date"];
echo "$y2 $y10 $asOf";
JSON response
{
"success": true,
"date": "2026-10-23",
"rates": {
"US_10Y": 5
},
"dates": {
"US_10Y": "2026-10-23"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "1aa87909-1d3c-4e60-b984-a9b2c8e8c22d",
"timestamp": "2026-10-25T00:04:04+00:00"
}
}
Interpretation: yields are percent; date is the trading day; source indicates the origin (e.g., official). On holidays/weekends the date will be the last open day.
Endpoint: Historical yield on a specific date
Pin a single Taiwan yield for a chosen maturity and date. Useful for point-in-time backtests and verifying past curve nodes.
cURL
Python (requests)
import requests
params = {"country": "TW", "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)
h = r.json()
ten_yield = h["yield"] # percent
as_of = h["date"] # YYYY-MM-DD
JavaScript (fetch)
const params = new URLSearchParams({
country: "TW",
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(json.yield, json.date);
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "TW",
"maturity" => "10Y",
"date" => "2025-06-15"
]);
$context = 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?$params", false, $context);
echo $json;
JSON response
Interpretation: yield is percent. If the given date is a non-trading day, expect a 404 unless that exact date exists; use the time series endpoint to locate the nearest trading day.
Endpoint: Time series between two dates
Download a continuous trading-day series for Taiwan at a single maturity between start and end (inclusive). Ideal for charts, regressions, and backtesting.
cURL
Python (requests)
import requests
params = {"country": "TW", "maturity": "10Y",
"start": "2025-10-25", "end": "2026-10-25"}
res = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
series = res.json()["series"]
# series is a list of {"date": "YYYY-MM-DD", "yield": float}
JavaScript (fetch)
const p = new URLSearchParams({
country: "TW",
maturity: "10Y",
start: "2025-10-25",
end: "2026-10-25"
});
fetch("https://bonds-api.com/api/v1/timeseries?" + p.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
json.series.forEach(pt => {
// pt.date is YYYY-MM-DD, pt.yield is percent
});
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "TW",
"maturity" => "10Y",
"start" => "2025-10-25",
"end" => "2026-10-25"
]);
$ctx = stream_context_create([
"http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]
]);
echo file_get_contents("https://bonds-api.com/api/v1/timeseries?$params", false, $ctx);
JSON response
Interpretation: the series contains only trading days. Values are percentages; to compute daily changes, take first-differences of adjacent yields.
Endpoint: Intraday yield snapshots
Capture same-day snapshots for a Taiwan maturity with UTC timestamps. Useful for monitoring moves during the session or reconciling EOD marks.
cURL
Python (requests)
import requests
p = {"country": "TW", "maturity": "10Y", "date": "2026-10-25"}
j = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p).json()
snapshots = j["snapshots"] # list of {yield, fetched_at, source}
tz = j["meta"]["timezone"] # "UTC"
JavaScript (fetch)
const params = new URLSearchParams({
country: "TW",
maturity: "10Y",
date: "2026-10-25"
});
fetch("https://bonds-api.com/api/v1/intraday?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
json.snapshots.forEach(s => {
// s.yield is percent; s.fetched_at is UTC ISO timestamp
});
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"country" => "TW", "maturity" => "10Y", "date" => "2026-10-25"
]);
$ctx = stream_context_create([
"http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]
]);
echo file_get_contents("https://bonds-api.com/api/v1/intraday?$params", false, $ctx);
JSON response
Interpretation: all yields are percentages. Timestamps are UTC. Use “count” for quick sanity checks and “source” to understand whether the tick comes from intraday market quotes.
Endpoint: Spread vs benchmark
Compare Taiwan yields to a benchmark, such as US Treasuries. The API reports spreads in basis points (bps). Default maturity is 10Y if none is supplied.
cURL
Python (requests)
import requests
p = {"country": "TW", "benchmark": "US", "maturity": "10Y"}
j = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p).json()
spread_bps = j["spread_bps"] # integer bps
tw = j["country_yield"] # percent
us = j["benchmark_yield"] # percent
JavaScript (fetch)
const qp = new URLSearchParams({country: "TW", benchmark: "US", maturity: "10Y"});
fetch("https://bonds-api.com/api/v1/spread?" + qp.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
console.log(json.spread_bps); // basis points
});
PHP (file_get_contents)
<?php
$params = http_build_query(["country" => "TW", "benchmark" => "US", "maturity" => "10Y"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents("https://bonds-api.com/api/v1/spread?$params", false, $ctx);
JSON response
Interpretation: spread_bps=215 means Taiwan’s 10Y yield is 2.15% higher than the US 10Y. Both country_yield and benchmark_yield are percentages.
Endpoint: Full Taiwan yield curve
Fetch the Taiwan curve across standard tenors on a single date. This is the simplest way to assemble a multi-maturity snapshot for valuation, bootstrapping, or scenario analysis.
cURL
Python (requests)
import requests
j = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "TW"}).json()
curve_date = j["date"]
tw_curve = j["curve"] # dict: tenor -> percent yield
is_inverted = j["inverted"] # boolean
JavaScript (fetch)
fetch("https://bonds-api.com/api/v1/curve?country=TW", {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
// json.curve = {"1M": 5.31, ...}, values are percent
// json.inverted indicates short rates > long rates
});
PHP (file_get_contents)
<?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=TW", false, $ctx);
echo $json;
JSON response
Interpretation: yields are percent. The inverted flag is a quick diagnostic; you can also check slope directly (e.g., 10Y minus 2Y). If you need only a subset, use the latest endpoint with maturities to fetch selected nodes.
Endpoint: Fluctuation over a period
Obtain start/end yields, absolute change, and min/max across a date window for Taiwan. This saves you from computing these from a raw series.
cURL
Python (requests)
import requests
p = {"countries": "TW", "maturity": "10Y",
"start": "2025-10-25", "end": "2026-10-25"}
j = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p).json()
tw = j["data"]["TW"]
delta = tw["change"] # percent points
low = tw["min"] # percent
high = tw["max"] # percent
JavaScript (fetch)
const s = new URLSearchParams({
countries: "TW", maturity: "10Y", start: "2025-10-25", end: "2026-10-25"
});
fetch("https://bonds-api.com/api/v1/fluctuation?" + s.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const tw = json.data.TW;
// tw.start_yield, tw.end_yield, tw.change, tw.min, tw.max all in percent
});
PHP (file_get_contents)
<?php
$params = http_build_query([
"countries" => "TW",
"maturity" => "10Y",
"start" => "2025-10-25",
"end" => "2026-10-25"
]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents("https://bonds-api.com/api/v1/fluctuation?$params", false, $ctx);
JSON response
Interpretation: all values are in percent (not bps). “change” is end_yield minus start_yield in percentage points.
Error handling and rate safety
All endpoints return a consistent error shape when unsuccessful:
- 401: Missing or invalid X-API-Key (check header exactness)
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date
- 422: Invalid parameter (e.g., date format must be YYYY-MM-DD)
- 429: Rate limit exceeded
- 500: Server error
Implement retries only for 429 and 500 with exponential backoff and jitter. For 404 and 422, correct the parameters. Cache stable data aggressively: historical, curve-by-date, and time series do not change after publication; cache latest intraday snapshots for short intervals (e.g., 30–60 seconds) in UI layers.
Building and using a Taiwan yield curve
There are two primary ways to build a TW curve:
- Single-call curve: GET /curve?country=TW returns a multi-tenor snapshot with an “inverted” flag and common money-market through long-bond tenors.
- Selected nodes via latest: GET /latest?countries=TW&maturities=2Y,5Y,10Y,30Y returns just the nodes you need, which you can then interpolate for pricing.
For daily valuation, call /curve once per business day and store by date. For intraday monitoring, use /intraday on key nodes (e.g., 2Y and 10Y) and compute slopes (10Y–2Y, 30Y–10Y) and curvature (butterfly trades) in real time.
Caching, business days, and holidays
- Business days: Series and latest reflect Taiwan’s trading days. On holidays/weekends, expect latest to carry the last open day’s date.
- Update frequency: Latest and intraday update during trading hours; historical/curve-by-date are static once published.
- Caching strategy:
- Historical/time series: Cache indefinitely by (country, maturity, start, end) or page segment.
- Latest: Cache per country and tenor for short TTLs (e.g., 60s–300s) to reduce request load.
- Intraday: If you poll, use ETag/If-Modified-Since equivalents at the application layer by memoizing last snapshot timestamp per maturity.
Sovereign bond fundamentals (applied to Taiwan)
Government bond yields reflect the cost of funding and market expectations for inflation and policy rates. Taiwan’s short-dated instruments (1M–1Y) closely track policy conditions, while longer tenors (5Y–30Y) embed growth and inflation risk premia. Analysts often monitor:
- Level: Absolute 10Y yield for valuation anchors
- Slope: 10Y minus 2Y for growth expectations
- Spread to US: Cross-market risk premium and FX-hedged carry considerations
All of these can be computed directly from the endpoints shown above.
Official live sample block
The following live sample block is provided as-is.
Putting it to work: common Taiwan analytics
- Financial dashboards: Call /curve for TW each morning, plot the curve, and refresh /latest intraday for 2Y/5Y/10Y.
- Portfolio risk tools: Use /timeseries for 5Y and 10Y to compute rolling vol and beta to benchmarks; persist /fluctuation to summarize recent extremes.
- Economic research: Benchmark TW 10Y vs US 10Y from /spread, and correlate to macro variables. Use /historical for key dates around policy events.
- Alerting: Poll /intraday for TW 10Y and alert when moves exceed N bps within M minutes.
Explore the API catalog and schema details at bonds-api.com, or try requests in the MCP.
FAQ
Q: How are yields and spreads expressed?
A: Yields are percentages (e.g., 4.52 means 4.52%). Spreads returned by /spread are in basis points (e.g., 215 means +2.15%).
Q: What timezone are timestamps in?
A: All timestamps in the API are UTC. Dates are YYYY-MM-DD and represent the trading day.
Q: How do I handle non-trading days for Taiwan?
A: Latest endpoints return the most recent available trading day. Time series skip non-trading days. For exact dates, use /historical; if a date is a holiday, you may get 404.
Q: Can I fetch multiple Taiwan maturities at once?
A: Yes. Use /curve for a full curve snapshot or /latest with the maturities parameter (e.g., 2Y,5Y,10Y,30Y) for selected nodes.
Q: What’s the best caching strategy for production apps?
A: Cache historical and curve-by-date indefinitely; cache latest and spread for short TTLs (60s–300s); de-duplicate intraday polling by memoizing the most recent snapshot time per maturity.
Ready to ship Taiwan yield analytics? Get an API key and start integrating today: Register. You can also explore interactively in the MCP and the documentation on bonds-api.com.