# US Treasury Yields — Par & Real Yield Curves, T-Bills, Spreads (`yadroo/us-treasury-yields`) Actor

Official US Treasury rates for macro, trading and finance agents: daily par yield curve 1M–30Y with 2s10s/3m10y spreads, inversion flags and breakeven inflation, real (TIPS) curve, T-bill rates with CUSIPs, long-term rates, average interest on the debt and debt-to-the-penny.

- **URL**: https://apify.com/yadroo/us-treasury-yields.md
- **Developed by:** [Samat Makatov](https://apify.com/yadroo) (community)
- **Categories:** AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Official US Treasury interest-rate data as clean JSON for macro, trading, treasury and research agents: the daily **par yield curve** (1 month – 30 years) with 2s10s / 3m10y spreads, inversion flags and curve shape, the **real (TIPS) curve** and breakeven inflation, **T-bill rates** with CUSIPs and maturities, **long-term rates**, plus **average interest rates on the federal debt** and **debt to the penny** from the Treasury Fiscal Data API. Any month or date range back to 1990. No API key, no proxy, no browser.

### Use cases

- **Recession / curve monitoring** — daily run with `latestOnly` + `includeChanges`; alert when `inverted2s10s` flips or the 10Y moves more than 10 bps.
- **Discount rates for valuation models** — pull the 10Y/20Y/30Y par yields for a valuation date (`startDate`/`endDate`).
- **Cash management** — compare 4- to 52-week bill coupon-equivalent yields with your bank's offer; get CUSIPs and maturity dates for orders.
- **Inflation expectations** — `includeBreakevens` gives 5Y/10Y/30Y breakevens (nominal − TIPS) per day.
- **Backtests & research** — multi-year daily history in one run (one request per year), oldest-first, only the fields you need.
- **Sovereign-debt dashboards** — monthly average interest rate by security type and daily total public debt outstanding.

### Input

| Field | Type | Default | Allowed values / notes |
|---|---|---|---|
| `series` | string | `parYield` | `parYield`, `realYield`, `billRates`, `longTermRates`, `realLongTerm`, `avgInterestRates`, `debtToPenny` |
| `months` | string\[] | current month | `YYYYMM` values from `199001`, e.g. `["202608","202609"]`; ignored when a date range is set |
| `startDate` | string | — | `YYYY-MM-DD`; with `endDate` selects a range (one request per calendar year); a start before 1990 is moved to `1990-01-01` |
| `endDate` | string | today | `YYYY-MM-DD`, inclusive |
| `latestOnly` | boolean | `false` | Only the newest day in the window, whatever `sortOrder` says (avgInterestRates: every security type of the newest month) |
| `includeSpreads` | boolean | `true` | parYield: spreads, `…Bps`, `inverted2s10s`, `inverted3m10y`, `curveShape` |
| `includeBreakevens` | boolean | `false` | parYield: adds real curve fetch and `breakeven5y/7y/10y/20y/30y` |
| `includeChanges` | boolean | `false` | `<field>ChangeBps` vs the previous business day for the key fields of the series — also on the first day of a month or year (the run reads the month before when needed); not for `avgInterestRates`/`debtToPenny` |
| `securities` | string\[] | all | avgInterestRates filter — names from Reference; case does not matter, short forms `T-Bills`, `T-Notes`, `T-Bonds`, `TIPS`, `FRN`, `FFB`, `SLGS`, `GAS` work; an unknown name stops the run before any row is billed, with a "did you mean" |
| `fields` | string\[] | all | Output columns in your order; `id`, `series`, `date`, `sourceUrl`, `fetchedAt` are always kept and come first unless you list them. Case does not matter; a column the series does not have is skipped with a warning; a list with no usable column stops the run before any row is billed |
| `sortOrder` | string | `desc` | `desc` (newest first) or `asc` (oldest first); only these two values are accepted |
| `maxItems` | integer | `500` | 1 – 20 000; keeps the first rows in `sortOrder` (newest with `desc`, oldest with `asc`) |

### Reference

#### Series

| `series` | Source | One row = | Key fields | History from |
|---|---|---|---|---|
| `parYield` | treasury.gov *Daily Treasury Par Yield Curve Rates* | business day | `m1 m1_5 m2 m3 m4 m6 y1 y2 y3 y5 y7 y10 y20 y30` (% p.a.) | 1990 (short tenors added later: 1M 2001, 2M 2018, 4M 2022, 1.5M 2025) |
| `realYield` | *Daily Treasury Par Real Yield Curve Rates* | business day | `r5 r7 r10 r20 r30` | 2003 |
| `billRates` | *Daily Treasury Bill Rates* | business day | `w4/w6/w8/w13/w17/w26/w52` × `BankDiscount`, `CouponEquivalent`, `Maturity`, `Cusip` | 2001 |
| `longTermRates` | *Daily Treasury Long-Term Rates* | business day | `lt20yConstantMaturity`, `ltAverageOver10y`, `ltRealRate`, `extrapolationFactor` | 2000 |
| `realLongTerm` | *Daily Treasury Real Long-Term Rate Averages* | business day | `realLongTermAverage` | 2000 |
| `avgInterestRates` | Fiscal Data *Average Interest Rates on U.S. Treasury Securities* | month × security type | `securityType`, `security`, `avgInterestRate`, `fiscalYear`, `fiscalQuarter` | 2001 |
| `debtToPenny` | Fiscal Data *Debt to the Penny* | business day | `debtHeldByPublic`, `intragovernmentalHoldings`, `totalPublicDebtOutstanding` (USD) | 1993 |

#### Computed fields (parYield)

| Field | Formula |
|---|---|
| `spread2s10s` / `spread2s10sBps` | `y10 − y2` (pp / bps) |
| `spread3m10y` | `y10 − m3` |
| `spread5s30s`, `spread2s30s`, `spread1y10y` | `y30 − y5`, `y30 − y2`, `y10 − y1` |
| `inverted2s10s`, `inverted3m10y` | spread < 0 |
| `curveShape` | `inverted` if either spread < 0, `flat` if |2s10s| < 0.10 pp, else `normal` |
| `breakevenNy` | `yN − rN` (requires `includeBreakevens`) |
| `<field>ChangeBps` | `(day − previous business day) × 100` (requires `includeChanges`); the previous business day may lie before the window |

#### `securities` values (avgInterestRates)

Marketable: `Treasury Bills`, `Treasury Notes`, `Treasury Bonds`, `Treasury Inflation-Protected Securities (TIPS)`, `Treasury Floating Rate Notes (FRN)`, `Federal Financing Bank`, `Total Marketable`.
Non-marketable: `Domestic Series`, `Special Purpose Vehicle`, `State and Local Government Series`, `United States Savings Securities`, `United States Savings Inflation Securities`, `Government Account Series`, `Government Account Series Inflation Securities`, `Total Non-marketable`.
Total: `Total Interest-bearing Debt`.
Used in earlier years (still matched): `Treasury Inflation-Indexed Notes` and `Treasury Inflation-Indexed Bonds` (the TIPS lines before 2005), `Foreign Series` (to 2025), `R.E.A. Series` (to 2011), `Hope Bonds` (2009–2016).
`series` and `sortOrder` are lists: Apify refuses any other value before the run starts.

### Examples

**Daily curve alert (latest day, changes and breakevens)**

```json
{ "series": "parYield", "latestOnly": true, "includeChanges": true, "includeBreakevens": true }
```

**Two years of 2Y/10Y history for a backtest, oldest first**

```json
{ "startDate": "2024-06-01", "endDate": "2025-06-30", "fields": ["y2", "y10", "spread2s10s", "inverted2s10s"], "sortOrder": "asc", "maxItems": 1000 }
```

**T-bill ladder shopping list**

```json
{ "series": "billRates", "latestOnly": true }
```

**Real yields for August 2026**

```json
{ "series": "realYield", "months": ["202608"] }
```

**What does the government pay on its debt? (year to date, bills vs total)**

```json
{ "series": "avgInterestRates", "startDate": "2026-01-01", "securities": ["Treasury Bills", "Total Marketable", "Total Interest-bearing Debt"] }
```

### Output

Par-curve row (trimmed):

```json
{
  "id": "parYield:2026-09-11",
  "series": "parYield",
  "date": "2026-09-11",
  "m1": 3.93, "m3": 4.07, "m6": 4.12, "y1": 4.35, "y2": 4.63, "y5": 4.78, "y10": 4.96, "y20": 5.38, "y30": 5.35,
  "spread2s10s": 0.33, "spread2s10sBps": 33, "spread3m10y": 0.89, "spread5s30s": 0.57,
  "inverted2s10s": false, "inverted3m10y": false, "curveShape": "normal",
  "breakeven5y": 2.4, "breakeven10y": 2.36, "breakeven30y": 2.28,
  "y10ChangeBps": 1, "spread2s10sChangeBps": -6,
  "sourceUrl": "https://home.treasury.gov/resource-center/data-chart-center/interest-rates/pages/xml?data=daily_treasury_yield_curve&field_tdr_date_value_month=202609",
  "fetchedAt": "2026-09-12T23:37:42.109Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | `<series>:<date>` (`avgInterestRates`: `<series>:<date>|<security>`) — stable across runs |
| `series` | string | Input series |
| `date` | string | Business day (`YYYY-MM-DD`) |
| tenor fields | number | null | Percent per annum; `null` when Treasury did not publish that tenor on that day |
| spreads / flags / breakevens / changes | number | boolean | null | See Computed fields |
| `sourceUrl` | string | The exact treasury.gov feed or Fiscal Data API request the row was read from |
| `fetchedAt` | string | ISO timestamp |

Every column has a title, a description and an example in the dataset schema, so agents can see the shape before a run. The key-value store record `SUMMARY` holds the window, the row count (`items`, `delivered`), every request URL, the newest row, warnings, failed requests and, when a run was cut short, why (`stoppedBy`) — handy for one-call agents.

### Use it from code / agents

```bash
curl -X POST "https://api.apify.com/v2/acts/yadroo~us-treasury-yields/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'content-type: application/json' -d '{"latestOnly":true,"includeChanges":true}'
```

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('yadroo/us-treasury-yields').call({ startDate: '2025-01-01', fields: ['y2', 'y10', 'spread2s10s'] });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

```python
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("yadroo/us-treasury-yields").call(run_input={"series": "billRates", "latestOnly": True})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

MCP: connect your agent to `https://mcp.apify.com` and call the `yadroo/us-treasury-yields` tool with the same JSON.

### Pricing

Pay per event: **$0.001 per run start + $0.001 per row**. Latest day ≈ $0.002; one month (~21 rows) ≈ $0.022; a full year of daily curves (~250 rows) ≈ $0.25; ten years ≈ $2.5.
Store discounts: Bronze −10 %, Silver −20 %, Gold and above −30 % on the row price; the start event is the same on every plan; platform usage is included.
Your **maximum cost per run** is respected: the run writes only the rows it pays for and ends with "Stopped at your spending limit: N rows delivered".

### Limits & FAQ

- **Freshness** — treasury.gov posts each day's rates after the close (~4:30–6 pm ET); weekends and federal holidays have no rows. `avgInterestRates` is monthly (published a few days after month end); `debtToPenny` daily with a one-day lag.
- **Turn of the month** — with the default window (current month) nothing is published yet on the 1st until the close, and `avgInterestRates` lags by days. Such a run steps back up to two months, so you always get the latest available rows; the window used is in the log, the run status and `SUMMARY`. A window you set yourself (`months`, `startDate`/`endDate`) is never widened — an empty month stays empty.
- **Speed** — treasury.gov XML is slow (5–30 s per request); a month is one request, a date range is one request per calendar year, breakevens double it, and `includeChanges` may add one month request. Rows are written page by page as they arrive. 1990→today is ~37 year requests: allow 15–35 minutes, or split the range. Retries with back-off on 429/5xx (honouring Retry-After); a 4xx answer is not retried. Malformed dates, reversed ranges, unknown securities or unusable `fields` stop the run at once with a clear message.
- **Timeout** — a run close to its timeout stops starting new requests, keeps every row it has written and ends SUCCEEDED with "Stopped before the run timeout: N rows saved". Raise the run timeout (default 900 s) or split the date range for more.
- **Failures** — if a page cannot be read after the retries, the other pages are still written and the status names the page that failed; a run that could read nothing fails with Treasury's error.
- **Missing tenors** — older years lack short tenors (`m1` before 2001, `m2` before 2018, `m4` before 2022, `m1_5` before 2025): they are `null`, spreads that need them are `null` too.
- **Are these "risk-free rates"?** — They are Treasury's official constant-maturity par yields (the same numbers as the Daily Treasury Par Yield Curve page); TIPS real yields come from the real curve feed.
- **Roadmap** — FRED-style monthly averages and a "curve on date X vs date Y" diff mode on request.

Made by **Yadroo** — see also [fx-rates](https://apify.com/yadroo/fx-rates), [world-bank-indicators](https://apify.com/yadroo/world-bank-indicators), [sec-company-financials](https://apify.com/yadroo/sec-company-financials), [sec-edgar-filings](https://apify.com/yadroo/sec-edgar-filings), [kalshi-markets](https://apify.com/yadroo/kalshi-markets).

# Actor input Schema

## `series` (type: `string`):

Which official dataset to pull. The first five come from treasury.gov XML feeds (business days, published ~end of day ET, history back to 1990). `avgInterestRates` and `debtToPenny` come from the Treasury Fiscal Data API.

## `months` (type: `array`):

Months to fetch, e.g. \["202608","202609"] (from 199001). Default: the current month — if Treasury has not published any day of it yet (the 1st of a month before the close; avgInterestRates lags by days), the run steps back up to two months and says so in the status. Ignored when `startDate`/`endDate` is set.

## `startDate` (type: `string`):

YYYY-MM-DD. With `endDate` defines a date range (one treasury.gov request per calendar year covered). Overrides `months`. A start before 1990-01-01 is moved there (no data earlier). Par curve data starts 1990-01-02, real yields 2003, bills 2001, debt to the penny 1993, average interest rates 2001.

## `endDate` (type: `string`):

YYYY-MM-DD, inclusive. Default: today when `startDate` is given.

## `latestOnly` (type: `boolean`):

Return only the newest day in the window, whatever `sortOrder` says (for `avgInterestRates`: every security type of the newest month). Combine with `includeChanges` for a daily alert.

## `includeSpreads` (type: `boolean`):

Adds `spread2s10s`, `spread3m10y`, `spread5s30s`, `spread2s30s`, `spread1y10y` (percentage points and `…Bps`), `inverted2s10s`, `inverted3m10y` and `curveShape` (normal | flat | inverted) to each par-curve row.

## `includeBreakevens` (type: `boolean`):

Also fetches the real (TIPS) curve and adds `breakeven5y/7y/10y/20y/30y` = nominal par − real yield, the market-implied inflation expectation.

## `includeChanges` (type: `boolean`):

Adds `<field>ChangeBps` = change versus the previous business day, in basis points, for the key fields of the series (par: 3M, 2Y, 5Y, 10Y, 30Y and 2s10s/3m10y; real: 5Y/10Y/30Y; bills: 13/26/52-week; long-term: all three rates; real long-term: the average). The previous business day is read even when it falls before the window (one extra month request), so the first day of a month has its change too. Not available for `avgInterestRates` and `debtToPenny`.

## `securities` (type: `array`):

Filter `avgInterestRates` by security description, e.g. \["Treasury Bills","TIPS","Total Marketable"]. Case does not matter; the short forms T-Bills, T-Notes, T-Bonds, TIPS, FRN, FFB, SLGS and GAS are accepted. Any other unknown name stops the run before any row is billed, with a "did you mean". Empty = all security types. Full list (including names used before 2026) in the README.

## `fields` (type: `array`):

Optional list of output columns, in the order you want them (e.g. \["y2","y10","spread2s10s"]). `id`, `series`, `date`, `sourceUrl` and `fetchedAt` are always kept and come first unless you list them. Case does not matter; a name the series does not have is skipped with a warning, and a list with no usable column stops the run before any row is billed.

## `sortOrder` (type: `string`):

Order of rows by date. `maxItems` keeps the first rows in this order: the newest with `desc`, the oldest with `asc`.

## `maxItems` (type: `integer`):

Cap on rows (the first rows in `sortOrder`). One year ≈ 250 business days per series; avgInterestRates: about 16 rows per month.

## Actor input object example

```json
{
  "series": "parYield",
  "latestOnly": false,
  "includeSpreads": true,
  "includeBreakevens": false,
  "includeChanges": false,
  "sortOrder": "desc",
  "maxItems": 500
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("yadroo/us-treasury-yields").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("yadroo/us-treasury-yields").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call yadroo/us-treasury-yields --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yadroo/us-treasury-yields"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AYtmv5JvP8FWYbAU7/builds/Ryu46b4k3G1fGIFXQ/openapi.json