Peru Bond Yield MCP

Peru Bond Yield MCP

You're trying to programmatically track Peru’s sovereign bond yields, build a real-time curve, compute US–Peru spreads, and embed all of it into a dashboard or quant research workflow. By the end of this article you’ll be able to query Peru (PE) yields from Bonds API, retrieve daily and intraday updates, assemble a full curve, compute fluctuations and spreads versus benchmarks, and productionize these calls with caching and error handling.

What this guide covers

This is a hands-on, Peru-focused walkthrough for the Bonds API MCP audience. We’ll cover all seven REST GET endpoints exposed by bonds-api.com and show complete examples (cURL, Python, JavaScript, PHP), then explain how to interpret yields, dates, timestamps, spreads, and curves in fixed-income workflows.

Illustration: Peru Bond Yield MCP
  • Peru sovereign yields across standard maturities (e.g., 1M–30Y)
  • Daily latest, historical single-day, and multi-day time series
  • Intraday snapshots for trading-day monitoring
  • Curve construction, inversion detection, and benchmark spreads
  • Practical concerns: business days, holidays, caching, and update cadence

Every request uses GET and requires an API key. To obtain an API key, visit Register. You can also explore the MCP entry point for experimentation.

Authentication, base URL, and conventions

All endpoints live under the same base URL and require the X-API-Key header. Only GET is supported.

  • Base URL: https://bonds-api.com/api/v1/
  • Auth: X-API-Key header containing your key
  • Countries: ISO2 codes (Peru is PE)
  • Maturities: strings like 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y

Yields are expressed in percent (e.g., 4.52 means 4.52%). Spreads are expressed in basis points (bps). Dates are in Y-m-d. Intraday timestamps are ISO 8601 with Z for UTC.

Availability notes:

  • Business days: Data updates on local business days; weekends and local market holidays will not produce new daily values.
  • Update frequency: Daily endpoints reflect the latest available day; intraday captures snapshots during the trading session where supported.
  • Caching: Cache daily endpoints by country+maturity+date. For intraday, cache by snapshot timestamp and maturity. Always respect country holidays to avoid unnecessary polling.

Useful links: the homepage bonds-api.com and the MCP are helpful starting points.

Endpoint: Latest yields for Peru

Use this to fetch the most recent daily yields for one or more maturities in Peru. If you omit maturities, the API returns all available tenors for the country.

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": "PE", "maturities": "2Y,10Y"}
)
resp.raise_for_status()
data = resp.json()
# Example: read PE 10Y yield and date
pe_10y = data["data"]["PE"]["10Y"]["yield"]
pe_10y_date = data["data"]["PE"]["10Y"]["date"]
print(pe_10y, pe_10y_date)

JavaScript (fetch)

const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "PE");
url.searchParams.set("maturities", "2Y,10Y");

fetch(url, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const pe10y = json.data.PE["10Y"].yield;
const asOf = json.data.PE["10Y"].date; // Y-m-d
console.log(pe10y, 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=PE&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$yield10 = $data["data"]["PE"]["10Y"]["yield"];
$date10 = $data["data"]["PE"]["10Y"]["date"];
echo $yield10 . " " . $date10;

Sample JSON

{
    "success": true,
    "date": "2026-10-22",
    "rates": {
        "US_10Y": 5.115
    },
    "dates": {
        "US_10Y": "2026-10-22"
    },
    "currencies": {
        "US_10Y": "USD"
    },
    "meta": {
        "request_id": "4e9ec116-6df3-478a-b389-d0f23470e5c3",
        "timestamp": "2026-10-22T00:06:36+00:00"
    }
}

Fields:

  • yield: Percent value (e.g., 4.52 means 4.52%).
  • date: The daily as-of date in Y-m-d, local market day aligned.
  • source: “official” identifies the primary source lineage.

Note: Official live sample (US)

The following live-format sample is provided as-is. It uses a different parameter for the API key and returns a different response shape. Copy it verbatim if you need to test the live sample call.

In this live example, rates are still in percent, the date is Y-m-d, and meta.timestamp is an ISO 8601 UTC timestamp.

Endpoint: Historical yield (single date)

Retrieve Peru’s yield for a specific maturity on a given date (useful for backtests or point-in-time analytics).

cURL

Python

import requests

params = {"country": "PE", "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()
print(hist["yield"], hist["date"])

JavaScript

const params = new URLSearchParams({
country: "PE",
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(j => {
// j.yield is percent; j.date is Y-m-d
console.log(j.country, j.maturity, j.yield, j.date);
});

PHP (Guzzle)

<?php
require "vendor/autoload.php";

$client = new \GuzzleHttp\Client([
"base_uri" => "https://bonds-api.com/api/v1/"
]);

$res = $client->request("GET", "historical", [
"headers" => ["X-API-Key" => "YOUR_API_KEY"],
"query" => ["country" => "PE", "maturity" => "10Y", "date" => "2025-06-15"]
]);

$data = json_decode($res->getBody(), true);
echo $data["yield"] . " on " . $data["date"];

Sample JSON

Fields:

  • yield: Percent on that calendar day.
  • date: Y-m-d; if the requested date is a non-business day and no value exists, expect a 404.

Endpoint: Time series (range)

Pull a date-indexed Peru yield series for a maturity between two dates. Ideal for charts, regressions, and risk factor modeling.

cURL

Python

import requests

params = {
"country": "PE",
"maturity": "10Y",
"start": "2025-10-22",
"end": "2026-10-22"
}
r = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
r.raise_for_status()
series = r.json()["series"]
# Each item: {"date": "Y-m-d", "yield": float}
for row in series[:3]:
print(row["date"], row["yield"])

JavaScript

const p = new URLSearchParams({
country: "PE",
maturity: "10Y",
start: "2025-10-22",
end: "2026-10-22"
});
fetch("https://bonds-api.com/api/v1/timeseries?" + p.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
j.series.forEach(pt => {
// pt.date is Y-m-d; pt.yield is percent
console.log(pt.date, pt.yield);
});
});

PHP (file_get_contents)

<?php
$q = http_build_query([
"country" => "PE",
"maturity" => "10Y",
"start" => "2025-10-22",
"end" => "2026-10-22"
]);
$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/timeseries?$q", false, $context);
$data = json_decode($json, true);
foreach ($data["series"] as $row) {
echo $row["date"] . " " . $row["yield"] . PHP_EOL;
}

Sample JSON

Interpretation: A list of date-yield points in percent. Series respects business days; gaps align with weekends/holidays.

Endpoint: Intraday snapshots

For trading-day monitoring, this endpoint returns multiple snapshots captured during the specified date for a maturity.

cURL

Python

import requests

params = {"country": "PE", "maturity": "10Y", "date": "2026-10-22"}
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"]:
# fetched_at is ISO 8601 UTC
print(s["fetched_at"], s["yield"], s["source"])

JavaScript

const intradayParams = new URLSearchParams({
country: "PE",
maturity: "10Y",
date: "2026-10-22"
});
fetch("https://bonds-api.com/api/v1/intraday?" + intradayParams.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
console.log("Count:", j.count, "TZ:", j.meta.timezone);
j.snapshots.forEach(s => console.log(s.fetched_at, s.yield));
});

PHP (Guzzle)

<?php
require "vendor/autoload.php";
$client = new \GuzzleHttp\Client(["base_uri" => "https://bonds-api.com/api/v1/"]);
$res = $client->request("GET", "intraday", [
"headers" => ["X-API-Key" => "YOUR_API_KEY"],
"query" => ["country" => "PE", "maturity" => "10Y", "date" => "2026-10-22"]
]);
$data = json_decode($res->getBody(), true);
echo "Snapshots: " . $data["count"] . PHP_EOL;
foreach ($data["snapshots"] as $s) {
echo $s["fetched_at"] . " " . $s["yield"] . PHP_EOL;
}

Sample JSON

Fields:

  • yield: Percent at snapshot time.
  • fetched_at: ISO 8601 UTC timestamp (Z).
  • count: Number of snapshots included.

Endpoint: Full yield curve

Fetch the entire Peru curve for the latest available date, or a specified date, in one call. Use this to compute curve slopes, interpolations, and to check inversion.

cURL

Python

import requests

r = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "PE"})
r.raise_for_status()
curve = r.json()
print("As of:", curve["date"], "Inverted:", curve["inverted"])
for tenor, yld in curve["curve"].items():
print(tenor, yld)

JavaScript

const q = new URLSearchParams({ country: "PE" });
fetch("https://bonds-api.com/api/v1/curve?" + q.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
console.log("Date:", j.date, "Inverted:", j.inverted);
Object.entries(j.curve).forEach(([tenor, y]) => console.log(tenor, y));
});

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=PE", false, $ctx);
$data = json_decode($json, true);
echo "As of " . $data["date"] . " inverted=" . ($data["inverted"] ? "yes" : "no") . PHP_EOL;
foreach ($data["curve"] as $tenor => $y) {
echo $tenor . " " . $y . PHP_EOL;
}

Sample JSON

Fields:

  • curve: Mapping tenor → yield (percent). Use to compute spreads across tenors.
  • inverted: Boolean flag that indicates whether shorter maturities exceed longer ones in a typical inversion sense.

Endpoint: Spread vs benchmark

Compute Peru’s yield spread versus a benchmark country (e.g., US for Treasuries) for a specific maturity. Returns spreads in basis points (1 bp = 0.01%).

cURL

Python

import requests

p = {"country": "PE", "benchmark": "US", "maturity": "10Y"}
r = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p)
r.raise_for_status()
s = r.json()
print(s["spread_bps"], s["country_yield"], s["benchmark_yield"])

JavaScript

fetch("https://bonds-api.com/api/v1/spread?country=PE&benchmark=US&maturity=10Y", {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
// spread_bps is in basis points (e.g., 215 means 2.15%)
console.log(j.spread_bps, j.country_yield, j.benchmark_yield);
});

PHP (Guzzle)

<?php
require "vendor/autoload.php";
$client = new \GuzzleHttp\Client(["base_uri" => "https://bonds-api.com/api/v1/"]);
$res = $client->request("GET", "spread", [
"headers" => ["X-API-Key" => "YOUR_API_KEY"],
"query" => ["country" => "PE", "benchmark" => "US", "maturity" => "10Y"]
]);
$j = json_decode($res->getBody(), true);
echo $j["spread_bps"] . " bps";

Sample JSON

Fields:

  • spread_bps: Difference in basis points (country − benchmark) × 100.
  • country_yield, benchmark_yield: Percent yields for context and display.

Endpoint: Fluctuation (change, min, max)

Summarize the Peru yield move over a period for a given maturity: start, end, absolute change, and the min–max range.

cURL

Python

import requests

params = {
"countries": "PE",
"maturity": "10Y",
"start": "2025-10-22",
"end": "2026-10-22"
}
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"]["PE"]
print(fl["start_yield"], fl["end_yield"], fl["change"], fl["min"], fl["max"])

JavaScript

const f = new URLSearchParams({
countries: "PE",
maturity: "10Y",
start: "2025-10-22",
end: "2026-10-22"
});
fetch("https://bonds-api.com/api/v1/fluctuation?" + f.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
const s = j.data.PE;
console.log(s.start_yield, s.end_yield, s.change, s.min, s.max);
});

PHP (file_get_contents)

<?php
$q = http_build_query([
"countries" => "PE",
"maturity" => "10Y",
"start" => "2025-10-22",
"end" => "2026-10-22"
]);
$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/fluctuation?$q", false, $ctx);
$d = json_decode($json, true)["data"]["PE"];
echo "Δ=" . $d["change"] . " (" . $d["min"] . "," . $d["max"] . ")";

Sample JSON

Fields:

  • change: End minus start, expressed in percentage points.
  • min, max: Extremes over the interval, useful for stress testing.

Building a Peru yield curve, spreads, and dashboard

For a practical MCP workflow, you can combine endpoints as follows:

  1. Get the full daily curve with /curve (country=PE). This gives you tenors from bills to bonds for the current day.
  2. Overlay intraday 10Y with /intraday on the same date to show real-time movements against the daily close.
  3. Compute US–Peru 10Y spread via /spread (country=PE, benchmark=US, maturity=10Y). The spread_bps can be plotted alongside the 10Y yield.
  4. Render historical panels using /timeseries for 10Y (and optionally 2Y, 5Y) to examine slope dynamics.
  5. Summarize the prior year’s volatility with /fluctuation to display min–max bands and net change.

Available maturities in the sample curve

Maturity How to request Common use
1Mmaturity=1MShort-end funding proxy
3Mmaturity=3MQuarterly horizon
6Mmaturity=6MHalf-year outlook
1Ymaturity=1YLocal policy expectations
2Ymaturity=2YFront-end duration risk
5Ymaturity=5YIntermediate term
10Ymaturity=10YBenchmark duration, discounting
30Ymaturity=30YLong-tail liability matching

Units, dates, and timezones recap

  • Yield fields: Percent (not decimal fractions). For example, 4.52 means 4.52%.
  • Spread fields: Basis points (e.g., 215 bps equals 2.15%).
  • Dates in daily endpoints: Y-m-d (local market business days).
  • Intraday timestamps: ISO 8601 with Z (UTC), suitable for direct charting in most time-aware libraries.

Handling business days and market holidays

  • Daily endpoints return the latest available date. On holidays or weekends there may be no new values.
  • When requesting a historical date that is a non-business day, a 404 may be returned if no official fixing exists.
  • Time series align to business days; gaps represent weekends/holidays. Consider forward-filling for analytics that require contiguous series.

Caching and retries

  • Cache keys: Include endpoint + country + maturity + date/range, and invalidate by next business day or when new intraday snapshots arrive.
  • Rate limits and network issues: Implement exponential backoff on 429 and retry on 500 with jitter. Respect 403 or 401 without automatic retries.
  • Idempotency: All requests are GET and safe to retry idempotently.

Error handling

Standardized error responses help you branch logic quickly in clients and backends.

  • 401: Missing or invalid X-API-Key — ensure the header is present and correct.
  • 403: Account quota exceeded — halt requests and alert the operator.
  • 404: No data for requested country/maturity/date — confirm business day and tenor availability.
  • 422: Invalid parameter — check ISO2 country codes, date format (Y-m-d), or maturity string.
  • 429: Rate limit exceeded — retry with backoff.
  • 500: Server error — retry with backoff; log request context for support.

Sovereign-bond fundamentals (quick refresher)

Peru’s sovereign curve summarizes the term structure of local-currency government debt. The short end (1M–1Y) is sensitive to immediate policy signals and liquidity, while the belly (2Y–5Y) and long end (10Y–30Y) reflect growth, inflation, and term premia. Spreads versus US Treasuries express relative risk and currency/term premia differences, often monitored in basis points.

For quant teams, these endpoints support:

  • Risk dashboards: real-time 10Y intraday overlays with daily close.
  • Curve analytics: slope calculations (e.g., 10Y–2Y), inversion flags, PCA on time series.
  • Macro research: regime detection via fluctuation min–max and rolling volatility.
  • Portfolio tooling: spread curves versus benchmark for relative-value screens.

FAQ

How are yields expressed?
All yield values are in percent (e.g., 4.52 means 4.52%). Spread values are in basis points (bps).

What timezones are timestamps in?
Daily dates use Y-m-d (as-of market day). Intraday snapshots include ISO 8601 UTC timestamps with Z (e.g., 2026-10-22T12:00:00Z).

How do I request multiple Peru maturities at once?
Use /latest with countries=PE and maturities as a comma-separated list (e.g., 2Y,5Y,10Y). Or use /curve to fetch the full tenor set for a single day.

What happens on local holidays?
No new daily value is published; the latest endpoint returns the most recent available day. Historical requests for holiday dates may return 404 if no fixing exists.

Can I compare Peru to another market?
Yes. Use /spread with country=PE and benchmark=US (or another supported ISO2) and an optional maturity (defaults to 10Y).

If you’re ready to integrate Peru’s curve and spreads into your analytics, get an API key now: Register. Explore more developer resources at bonds-api.com and experiment via the MCP.

Start building with bond data today

Get your API key and access sovereign bond yields across 60+ countries. 7-day free trial, no credit card required.