# Bonds API — full reference

> Sovereign bond yields, spreads, and yield curves for 60+ countries.
> Authentication: `X-API-Key: YOUR_KEY` header, or an OAuth bearer token from POST /oauth/token.
> Base URL: `https://bonds-api.com/api/v1`

## GET /latest

Most recent bond yields for one or more countries/maturities.

Parameters:
- `countries` (required) — Comma-separated ISO 3166-1 alpha-2 codes, e.g. US,DE,ES
- `maturities` (optional) — Comma-separated maturities, e.g. 2Y,10Y. Omit for all available.

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/latest?countries=US,DE,ES&maturities=2Y,10Y"
```

MCP equivalent: tools/call with name="latest"

## GET /historical

Bond yield on one specific past date.

Parameters:
- `country` (required) — ISO 3166-1 alpha-2 code
- `maturity` (required) — e.g. 10Y
- `date` (required) — Y-m-d

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/historical?country=ES&maturity=10Y&date=2025-06-15"
```

MCP equivalent: tools/call with name="historical"

## GET /timeseries

Bond yield time series over a date range.

Parameters:
- `country` (required) — ISO 3166-1 alpha-2 code
- `maturity` (required) — e.g. 10Y
- `start` (required) — Y-m-d
- `end` (required) — Y-m-d, >= start

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/timeseries?country=US&maturity=10Y&start=2025-01-01&end=2026-01-01"
```

MCP equivalent: tools/call with name="timeseries"

## GET /spread

Yield spread of a country against a benchmark (e.g. Bund, Treasury).

Parameters:
- `country` (required) — ISO 3166-1 alpha-2 code
- `benchmark` (required) — ISO 3166-1 alpha-2 code, e.g. DE for Bund
- `maturity` (optional) — Defaults to 10Y

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/spread?country=ES&benchmark=DE&maturity=10Y"
```

MCP equivalent: tools/call with name="spread"

## GET /curve

A country's full yield curve.

Parameters:
- `country` (required) — ISO 3166-1 alpha-2 code
- `date` (optional) — Defaults to the latest available date

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/curve?country=US"
```

MCP equivalent: tools/call with name="curve"

## GET /intraday

Intraday yield snapshots for one day (Professional plan).

Parameters:
- `country` (required) — ISO 3166-1 alpha-2 code
- `maturity` (required) — e.g. 10Y
- `date` (required) — Y-m-d

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/intraday?country=US&maturity=10Y&date=2026-04-06"
```

MCP equivalent: tools/call with name="intraday"

## GET /fluctuation

Change, min and max yield over a period.

Parameters:
- `countries` (required) — Comma-separated ISO 3166-1 alpha-2 codes
- `maturity` (required) — e.g. 10Y
- `start` (required) — Y-m-d
- `end` (required) — Y-m-d, >= start

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://bonds-api.com/api/v1/fluctuation?countries=IT,GR&maturity=10Y&start=2025-01-01&end=2026-01-01"
```

MCP equivalent: tools/call with name="fluctuation"