You need to fetch, chart, and analyze the China 10-year government bond yield inside your own tools. By the end of this guide you will query the China 10Y (and adjacent maturities), build a daily time series, compute spreads versus benchmarks, assemble a yield curve, and troubleshoot responses from the Bonds API — all with reproducible cURL, Python, JavaScript, and PHP examples.
Why China’s 10Y matters and what you can build
The 10-year sovereign point is the anchor for discount curves, macro views, and duration targeting. With China (ISO2: CN), the 10Y yield is central to:
- Risk dashboards that monitor cross-market rates moves and value-at-risk.
- Macro research that studies monetary cycles, curves, and growth-inflation regimes.
- Trading tools that plot intraday snapshots and end-of-day closes.
- Portfolio systems that compute spreads to the US 10Y and track carry/roll.
All data in this article is served by bonds-api.com over a REST interface. Every request is a GET to https://bonds-api.com/api/v1/, authenticated via the X-API-Key header.
Data conventions, maturities, time, and caching
Yields are expressed in percent (for example, 4.52 means 4.52%). When spreads are returned, they are expressed in basis points (bps), where 1 bp = 0.01%.
Dates in response bodies follow Y-m-d (for example, 2026-10-18). Intraday snapshot timestamps use ISO-8601 with timezone offsets; Bonds API returns UTC in intraday metadata and snapshot timestamps (for example, 2026-10-18T12:00:00Z).
China coverage includes money-market points (1M, 3M, 6M), on-the-run tenors (1Y, 2Y, 5Y, 10Y), and long bonds (30Y). Trading days follow China business days; weekends and mainland holidays are excluded. Latest values generally reflect the most recent business day close for daily endpoints. For intraday snapshots, frequency is multiple times per day while markets are active.
To minimize load and stay within rate limits, implement HTTP caching on your side for end-of-day endpoints (latest, curve, historical). Cache bust only when the relevant market session is expected to update or when you detect a new date in responses. Time series endpoints are deterministic for a fixed date range and cache well.
Official sample block (verbatim)
The following official sample block is provided verbatim and demonstrates a live /latest call format. Note this block uses a US example and includes an api_key query parameter. Your production China integration should use the X-API-Key header as shown in the China endpoint sections below.
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-16",
"rates": {
"US_10Y": 5.09
},
"dates": {
"US_10Y": "2026-10-16"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "4fb12ff6-8648-450a-99df-2fa3866ddf13",
"timestamp": "2026-10-18T00:04:43+00:00"
}
}Authentication
All China examples below use:
- Base URL: https://bonds-api.com/api/v1/
- HTTP method: GET only
- Header: X-API-Key: YOUR_API_KEY
Explore the API interactively via the MCP, and consult docs on bonds-api.com. When you are ready to build, you can Register for an API key.
Endpoint: /latest — Get the current China 10Y (and nearby tenors)
Use /latest to fetch the most recent available yields. For the China 10Y, you can request it alone or alongside other CN tenors for context (for example, 2Y and 10Y to check curve slope).
cURL
JSON response
Interpretation: yield is in percent; date is the effective market date (Y-m-d). source indicates the origin (for example, official). On weekends/holidays, the latest will reflect the last trading day.
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "CN", "maturities": "2Y,10Y"}
)
data = resp.json()
cn_10y = data["data"]["CN"]["10Y"]["yield"]
cn_10y_date = data["data"]["CN"]["10Y"]["date"]
print("CN 10Y:", cn_10y, "on", cn_10y_date)JavaScript (fetch)
async function getLatestCN() {
const url = new URL("https://bonds-api.com/api/v1/latest");
url.search = new URLSearchParams({ countries: "CN", maturities: "2Y,10Y" });
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await resp.json();
const tenY = json.data.CN["10Y"].yield;
const dt = json.data.CN["10Y"].date;
console.log(`CN 10Y: ${tenY}% on ${dt}`);
}
getLatestCN();PHP (file_get_contents)
<?php
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$query = http_build_query(["countries" => "CN", "maturities" => "2Y,10Y"]);
$json = file_get_contents("https://bonds-api.com/api/v1/latest?$query", false, $context);
$data = json_decode($json, true);
echo "CN 10Y: " . $data["data"]["CN"]["10Y"]["yield"] . "%\n";
?>Endpoint: /historical — Yield on a given date (China 10Y)
Use /historical to retrieve a specific calendar day for a single maturity. If you request a non-business day, expect either no data (404) or the nearest available trading day only when documented; otherwise, request the previous business day explicitly.
cURL
JSON response
Interpretation: yield is percent; date is the requested day (Y-m-d). If you see a 404 error with error text indicating “No data,” adjust to the nearest previous China business day.
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "CN", "maturity": "10Y", "date": "2025-06-15"}
)
row = resp.json()
print(row["maturity"], row["yield"], row["date"])JavaScript
async function getHistoricalCN10Y(date) {
const url = new URL("https://bonds-api.com/api/v1/historical");
url.search = new URLSearchParams({ country: "CN", maturity: "10Y", date });
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
return resp.json();
}
getHistoricalCN10Y("2025-06-15").then(console.log);PHP
<?php
$params = ["country" => "CN", "maturity" => "10Y", "date" => "2025-06-15"];
$q = http_build_query($params);
$context = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$res = file_get_contents("https://bonds-api.com/api/v1/historical?$q", false, $context);
echo $res;
?>Endpoint: /timeseries — Daily China 10Y time series
Use /timeseries to fetch a continuous daily history over a date window. The series typically includes only trading days. Store and cache locally for backtesting and charting.
cURL
JSON response
Interpretation: series is an array of daily observations with date (Y-m-d) and yield in percent, typically for business days only. Join across maturities by calling /timeseries separately per tenor, or use /curve per date to reconstruct cross-sections.
Python
import requests
import pandas as pd
resp = requests.get(
"https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "CN", "maturity": "10Y", "start": "2025-10-18", "end": "2026-10-18"}
)
ts = pd.DataFrame(resp.json()["series"])
ts["date"] = pd.to_datetime(ts["date"])
ts = ts.set_index("date").sort_index()
print(ts.tail())JavaScript
async function getCN10YSeries(start, end) {
const url = new URL("https://bonds-api.com/api/v1/timeseries");
url.search = new URLSearchParams({ country: "CN", maturity: "10Y", start, end });
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await resp.json();
return json.series; // [{date, yield}...]
}PHP
<?php
$params = ["country" => "CN", "maturity" => "10Y", "start" => "2025-10-18", "end" => "2026-10-18"];
$q = http_build_query($params);
$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?$q", false, $ctx);
?>Endpoint: /spread — China vs. benchmark (US) at 10Y
Use /spread to compute a cross-country spread in basis points. By default, the maturity is 10Y; you can override with the maturity parameter.
cURL
JSON response
Interpretation: spread_bps is in basis points (for example, 215 bps = 2.15%). country_yield and benchmark_yield are both in percent. Use spreads in dashboards and risk models to track relative value.
Python
import requests
r = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "CN", "benchmark": "US", "maturity": "10Y"}
)
s = r.json()
print(f"CN-US 10Y spread: {s['spread_bps']} bps")JavaScript
async function cnUs10ySpread() {
const url = new URL("https://bonds-api.com/api/v1/spread");
url.search = new URLSearchParams({ country: "CN", benchmark: "US", maturity: "10Y" });
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
return resp.json();
}PHP
<?php
$p = ["country" => "CN", "benchmark" => "US", "maturity" => "10Y"];
$q = http_build_query($p);
$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?$q", false, $ctx);
?>Endpoint: /curve — Full China yield curve
Use /curve for a cross-section of CN yields on the latest available trading day, or specify a date. This is ideal for pricing tools, interpolations, and risk term structures.
cURL
JSON response
Interpretation: inverted indicates whether the curve is globally inverted per Bonds API’s heuristic. curve contains yields per tenor in percent. Use this in applications that need multiple CN points at once.
Quick look at CN curve points
| Maturity | Yield (%) |
|---|---|
| 1M | 5.31 |
| 3M | 5.27 |
| 6M | 5.18 |
| 1Y | 4.98 |
| 2Y | 4.25 |
| 5Y | 4.39 |
| 10Y | 4.52 |
| 30Y | 4.71 |
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "CN"}
)
curve = resp.json()["curve"]
ten_y = curve["10Y"]
print("Curve 10Y:", ten_y)JavaScript
async function getCNYieldCurve(date) {
const url = new URL("https://bonds-api.com/api/v1/curve");
const params = { country: "CN" };
if (date) params.date = date;
url.search = new URLSearchParams(params);
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await resp.json();
return json.curve;
}PHP
<?php
$p = ["country" => "CN"];
$q = http_build_query($p);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$body = file_get_contents("https://bonds-api.com/api/v1/curve?$q", false, $ctx);
echo $body;
?>Endpoint: /intraday — China 10Y snapshots on a date
Use /intraday to collect multiple snapshots during a single trading date. Combine with /latest for a “live vs. close” view and alerting.
cURL
JSON response
Interpretation: snapshots is an array with yield (percent), fetched_at (ISO-8601 UTC), and source. count is the number of snapshots included for that date; meta.timezone clarifies timestamps are UTC.
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": "CN", "maturity": "10Y", "date": "2026-10-18"}
)
intraday = r.json()
for s in intraday["snapshots"]:
t = datetime.fromisoformat(s["fetched_at"].replace("Z", "+00:00"))
print(t, s["yield"])JavaScript
async function getCN10YIntraday(date) {
const url = new URL("https://bonds-api.com/api/v1/intraday");
url.search = new URLSearchParams({ country: "CN", maturity: "10Y", date });
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const json = await resp.json();
return json.snapshots;
}PHP
<?php
$p = ["country" => "CN", "maturity" => "10Y", "date" => "2026-10-18"];
$q = http_build_query($p);
$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?$q", false, $ctx);
?>Endpoint: /fluctuation — CN 10Y change, min, max over a period
Use /fluctuation for summary statistics across a date range, handy for dashboards and risk signposts.
cURL
JSON response
Interpretation: change is end_yield - start_yield in percentage points. min and max are the range extrema across the window. These are not bps; they are in percent.
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "CN", "maturity": "10Y", "start": "2025-10-18", "end": "2026-10-18"}
)
fl = resp.json()["data"]["CN"]
print(f"CN 10Y Δ: {fl['change']} pct, min: {fl['min']}, max: {fl['max']}")JavaScript
async function cn10yFluctuation(start, end) {
const url = new URL("https://bonds-api.com/api/v1/fluctuation");
url.search = new URLSearchParams({ countries: "CN", maturity: "10Y", start, end });
const r = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const j = await r.json();
return j.data.CN;
}PHP
<?php
$p = ["countries" => "CN", "maturity" => "10Y", "start" => "2025-10-18", "end" => "2026-10-18"];
$q = http_build_query($p);
$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?$q", false, $ctx);
?>Error handling and retries
Common error responses share the shape success=false and error=message. Handle notable cases:
- 401: Missing or invalid X-API-Key — confirm header and re-issue with a valid key.
- 403: Account quota exceeded — throttle or wait before retrying.
- 404: No data for requested country/maturity/date — adjust to a business day or supported tenor.
- 422: Invalid parameter — ensure ISO2=CN, maturity in the documented set, and Y-m-d dates.
- 429: Rate limit exceeded — back off with exponential retry; prefer caching.
- 500: Server error — brief retry with jitter; log request_id when available.
Putting it together: build a live CN 10Y panel
Combine endpoints to deliver a robust panel:
- Topline: /latest for CN 10Y and 2Y (slope check).
- Chart: /timeseries for the last 12 months.
- Cross-market: /spread vs US 10Y in bps.
- Curve context: /curve for the full tenor set.
- Intraday tape: /intraday snapshots to show session dynamics.
- Weekly wrap: /fluctuation to summarize change, min, max.
Roll up results into your cache keyed by endpoint + parameters + date. Refresh at reasonable intervals: end-of-day for daily endpoints; hourly or on-demand for intraday. Always annotate yields as percent and spreads as bps in UI labels.
For more details on capabilities and coverage, visit bonds-api.com.
FAQ
What units are yields and spreads in?
Yields are percent (for example, 4.52). Spreads returned by /spread use basis points (integer or float, for example, 215 bps = 2.15%).
How are dates and timestamps formatted?
Daily dates use Y-m-d (for example, 2026-10-18). Intraday fetched_at timestamps are ISO-8601 in UTC (for example, 2026-10-18T12:00:00Z). The intraday meta.timezone field confirms UTC.
What happens on weekends and China market holidays?
Daily endpoints (latest, curve, timeseries, historical) reflect China business days. On weekends or holidays, the “latest” date remains the most recent trading day. If /historical has no data for a non-trading day, request the previous business day.
Can I request multiple maturities at once?
Yes. Use /latest with maturities=2Y,10Y (omit maturities to fetch all available). For a full cross-section on a single date, use /curve, which returns many maturities at once.
How should I cache results?
Cache /latest and /curve for a given date and refresh when you detect a new date from the API. Cache /timeseries and /historical indefinitely for fixed date ranges. For /intraday, cache with shorter TTLs (for example, minutes) and coalesce frequent refreshes.
Build your CN 10Y analytics now using the endpoints above. Use the MCP to explore requests and responses quickly, and bonds-api.com for docs and coverage. When you are ready to integrate, get an API key via the Register link above.
