免费收益率曲线 API
国债数据指南

快速结论

用户搜索免费收益率曲线 API 时要完成什么

当前中文结果更偏向官方国债收益率曲线查询、数据门户与开发文档。用户的核心需求是找到可信数据源，并通过程序获取美国国债各期限的当前或历史收益率；其次是比较 API Key、调用额度、历史范围、国家覆盖和 JSON 格式。

排名页面反复覆盖的数据与功能

反复出现的实体包括美国财政部、FRED、国债票面收益率曲线、实际收益率曲线、1 个月至 30 年期限、曲线斜率、历史观测、REST 或 XML、JSON、API Key、额度、日期、单位和出处。

票面、即期、远期与实际收益率曲线不是同一种数据

选择收益率曲线 API 前，必须先定义每个点的含义。曲线虽然都是按期限排列的利率集合，但不同提供方可能发布不同曲线概念，使用不同输入证券并采用不同插值方法。美国财政部官方名义曲线属于票面收益率曲线：固定期限数值从估计曲线读取，未必等于任何一只存量国债的真实收益率。它不是实时成交行情，也不能直接当成零息贴现曲线。

理解美国财政部官方曲线方法

美国财政部说明，当前票面曲线使用交易日美东时间约 15:30 获取的近期发行证券参考买方报价，而非实际成交。输入价格先转为收益率，再通过自举法计算各输入期限的瞬时远期利率，并用单调凸插值构建完整曲线。该方法于 2021 年 12 月 6 日取代原有的准三次 Hermite 方法。历史数据管道应保留这一方法变化的时间点，不能假设全部历史观测都采用完全相同的口径。

值得评估的免费收益率曲线数据接口

“免费”不代表条款完全相同。接入当天仍应核对各提供方文档，因为认证、额度、合理使用规则和数据集可用性可能变化。

如何用 Python 调用免费收益率曲线 API

1. 明确曲线类型、国家和期限

先明确需要名义票面曲线、实际收益率曲线、国库券利率、即期曲线还是远期曲线，再定义国家、期限、观测日期、频率、单位和历史区间。这些曲线类型不能混用。

2. 检查元数据、认证和调用限制

编写生产代码前，要确认曲线类型、期限标签、单位、复利基础、观测时间、时区、方法、API Key、限流、再使用许可和署名。看到“10Y”时只能先把它当作期限标签，必须通过文档确认它究竟是固定期限曲线点、某只具体债券，还是模型化零息利率。

3. 小范围调用并验证响应

下面的 Python 示例读取美国财政部官方 XML，提取 2 年期与 10 年期固定期限票面收益率，并计算以基点表示的 2s10s 斜率。结果保留观测日期和来源，便于审计。这是日终曲线示例，不是实时可成交报价。

import requests
import xml.etree.ElementTree as ET

url = (
    "https://home.treasury.gov/resource-center/data-chart-center/"
    "interest-rates/pages/xml"
)
params = {
    "data": "daily_treasury_yield_curve",
    "field_tdr_date_value": "2025",
}
response = requests.get(url, params=params, timeout=30)
response.raise_for_status()
root = ET.fromstring(response.content)

ns = {
    "atom": "http://www.w3.org/2005/Atom",
    "m": "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata",
    "d": "http://schemas.microsoft.com/ado/2007/08/dataservices",
}

rows = []
for entry in root.findall("atom:entry", ns):
    props = entry.find("atom:content/m:properties", ns)
    if props is None:
        continue
    date = props.findtext("d:NEW_DATE", default="", namespaces=ns)
    y2 = props.findtext("d:BC_2YEAR", default="", namespaces=ns)
    y10 = props.findtext("d:BC_10YEAR", default="", namespaces=ns)
    if date and y2 and y10:
        rows.append({
            "date": date,
            "2y_percent": float(y2),
            "10y_percent": float(y10),
            "2s10s_bp": round((float(y10) - float(y2)) * 100, 1),
            "source": "U.S. Department of the Treasury",
        })

assert rows, "No complete 2Y/10Y observations returned"
print(rows[-1])

4. 加入缓存、重试和出处记录

按发布日程缓存，遵循重试建议，记录抓取时间和序列元数据，保留来源 URL，并监控数据结构变化。

发布前验证收益率曲线 API 响应

HTTP 请求成功并不代表得到了一条有效曲线。应验证提供方、国家、币种、曲线家族、名义或实际属性、票面/即期/远期类型、期限、单位、复利约定、观测日期、发布时间与方法版本。同一条曲线的全部点必须共享同一观测日期。缺失期限应保持缺失；插值属于模型决策，必须单独标记方法。

执行整条曲线完整性检查

可使用提供方、曲线类型、国家、币种、观测日期和期限构建复合主键。重复期限、百分数与小数比例误读、期限顺序异常、未来日期以及混合不同发布日期拼成的曲线都应拒绝。还要把多个官方数值与财政部可见表格核对，并保存原始 XML/JSON、请求参数、HTTP 响应头与抓取时间。

正确计算 2s10s 及其他期限利差

期限利差通常等于同一曲线、同一观测日的长期收益率减去短期收益率。若原始单位为百分比，百分点之差乘以 100 即可得到基点。假设 10 年期为 4.20%、2 年期为 4.55%，则 2s10s 为 −35 个基点，负斜率通常称为倒挂。不能在没有说明的情况下颠倒减法方向，也不能混用实际收益率和名义收益率，或组合不同日期的收盘观测。

曲线倒挂是信号，不是独立预测结论

2s10s、3m10y 和 10s30s 衡量不同的曲线区间，可能给出不同信息。它们与未来增长的关系取决于样本、政策环境、市场预期和观察期限。看板必须注明两端期限、减法方向、单位与观测日期；Agent 可以描述变化并引用数据，但不应把某一次倒挂写成经济将在特定日期衰退的证明。

构建无前视偏差的历史收益率曲线

对齐交易日历并保存当时可获得的数据

收益率曲线通常只在工作日发布，因此周末和节假日不是零值。回测必须明确缺失日期是保持缺失，还是沿用最近一次已发布曲线；两种选择都要记录。观测时间与抓取时间应分开保存。如果提供方后来更正历史或改变方法，研究管道可能同时需要最新修订序列和策略当时真正可见的快照。FRED 观测接口对适用序列支持实时区间和历史版本参数，但仍需仔细记录；这些参数并不能自动保证所有衍生利差都满足历史时点安全要求。

不要伪造历史上不存在的期限

美国财政部公布的期限集合会随时间变化，部分期限开始较晚，30年固定期限序列也经历过停发与恢复。使用现代固定列集会在历史区间产生大量缺口。应保留可用性元数据，不得把期限回填到官方开始时间之前；任何插值或代理值都要标记。方法发生变化时，应分段分析或加入方法指示变量，避免把结构性口径变化误判为市场信号。

官方财政部数据源与收益率曲线聚合 API 怎么选

最重视权威性与直接出处时，美国财政部数据源是首选。它提供曲线观测与定义，但 XML 解析不如标准化 JSON 方便。聚合 API 可简化曲线快照、期限利差、跨国覆盖和 Agent 接入，但必须检查其转换逻辑和免费套餐条款。

什么时候更适合使用聚合 API

需要统一查询多个国家或提供方时，聚合 API 更适合原型、跨国看板和 Agent 工具，但不会取代原始机构的权威性。应保存提供方、数据集与序列 ID、单位、频率、抓取时间和来源 URL，并检查数值转换、更新延迟和许可；重要结果仍需与官方门户核对。

使用前验证元数据、修订与数据质量

不要把序列名称当作完整定义

两个“10年期美国国债”字段可能分别表示固定期限票面曲线点、某只最新发行债券报价、月度均值、TIPS 实际收益率或衍生利差的一端。必须保存名称、曲线家族、输入样本、方法、单位、复利约定、频率、时区、估值时间与发布日程，并把维度代码与可读标签一起保留，不能只依赖 10Y 这样的简写。

显式处理修订值与缺失观测

提供方可能更正观测、增加新发行期限、调整曲线输入或改变插值方法。产品必须明确展示最新官方历史，还是保留每天抓取到的曲线快照。空值绝不能转成零；同时要检测重复日期、期限集合异常、单位变化、曲线类型混用、无法解释的跳变，以及超过官方发布时间窗口仍未更新的最新观测。

构建可靠的生产级数据接入

分离发现、抓取、标准化与交付

数据管道应分离发现、抓取、标准化和交付。抓取阶段保存原始响应、HTTP 状态、请求参数和时间；标准化阶段统一日期、单位和缺失值，但保留原始表达；交付阶段再向看板、数据库、API 或 Agent 提供已验证数据。保留原始响应便于重新处理。

让轮询、缓存和重试匹配发布日程

美国财政部说明，交易日曲线通常在美东时间 18:00 前发布，但也可能延迟。应围绕官方时间窗口轮询，而不是持续请求。按提供方、曲线类型和观测日期缓存，只更新最新分区，避免重复重建全部历史。临时故障可有限退避重试，无效参数不能无限请求，API Key 不能写入客户端。还要监控曲线陈旧、期限缺失、数据结构变化，以及单位从百分比突然变成小数。备用来源必须代表同一曲线概念，不能只因为期限标签相似就替换。

收益率曲线 API 的常见应用场景

研究、看板、提醒与 AI Agent

开发者可把曲线用于固定收益看板、期限比较、2 年/10 年或 10 年/30 年利差监控、衰退研究输入、贴现率背景、回测和数据型 Agent。历史研究需要可复现快照，运营看板则要分别展示观测日期与抓取时间。

面向 AI Agent 时，应把“获取最新名义票面曲线”“读取某一观测日曲线”或“使用匹配期限计算指定利差”等任务封装成范围明确的操作，并说明国家、曲线类型、单位、支持期限、错误状态与出处。Agent 必须引用发布机构和观测日期，区分来源数值与自行计算的利差，并避免把远期利率或曲线倒挂写成确定预测。QVeris 可帮助查找、检查和调用这些能力，并保留审计记录；原始机构仍是数值与方法的权威来源。

QVeris 如何帮助接入收益率曲线 API

• 先在 QVeris 中查看 Alpha Vantage 提供商详情，再按照 QVeris REST API 参考完成集成。
• 在 Agent 调用前检查操作参数和响应结构。
• 在下游记录中保留提供方 URL、时间戳、序列 ID 和许可信息。

FAQ

外部参考链接