回填完整历史
分页读取全部历史，保存到文件，中断后可继续。
阅读指南 →所有 API
ETF 价格与共同基金的基金净值 API
获取 ETF 和共同基金的价格及价格历史，搜索和简介对所有账户开放。每个请求都需要 Bearer 密钥；REST 和 MCP 共用一个账户余额。
首次请求
获取最新价格
curl --request GET \
--url "https://api.narwhalapi.com/v1/funds/ARCX:SPY/price" \
--header "Authorization: Bearer $NARWHAL_API_KEY"响应示例
{
"id": "ARCX:SPY",
"symbol": "SPY",
"currency": "USD",
"price": "578.12",
"previous_close": "576.40",
"change": "1.72",
"change_percent": "0.30",
"volume": "61230500",
"market_session": "open",
"timestamp": "2026-10-26T15:42:00Z",
"stale": false,
"type": "etf"
}端点
GET按代码或名称搜索 ETF 和公募基金/v1/funds/search
代码或名称以 q 开头（不区分大小写）的基金：先匹配完全一致的代码，再匹配其他代码，最后匹配名称。
参数
q必填基金代码或基金名称的开头部分（不区分大小写），至少 2 个字符（例如 vf 或 vanguard 500）。排序：完全一致的代码、其他代码、名称开头，然后是名称中后续单词的开头。
country可选仅限该国家的基金，三个字母（USA）。
type可选仅 ETF 或仅公募基金。
cursor可选上一页的 next_cursor，其他参数须保持一致。
响应字段
results对象数组每页最多 50 条。
next_cursor字符串回传该值即可读取下一页。最后一页为 null。
完整参考文档 →
GET单只基金的概况/v1/funds/{id}
基金的代码、名称、类型（etf 或 mutual_fund）、交易所（仅 ETF）、国家和币种，与我们的代码列表一致。
参数
id必填基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。
响应字段
id字符串规范基金 id。
symbol字符串基金的代码。
mic字符串交易所的四字母代码。公募基金省略（无交易所）。
country字符串基金所属国家，三个字母。
完整参考文档 →
GET单只基金的最新价格/v1/funds/{id}/price
ETF 的最新价格，采用股票价格的结构并增加 type: etf；或共同基金的最新基金净值（type: mutual_fund：nav、previous_nav、change、change_percent 以及净值日期；为日终数值，从不延迟，超过下一个工作日即视为过期）。
参数
id必填基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。
主要响应字段
id字符串所请求基金返回的规范上市记录 id。
symbol字符串该基金在其交易所使用的代码。
currency字符串所有价格字段的币种，便士已换算为英镑。
price字符串ETF 最新价格，以 currency 币种的字符串形式返回。
previous_close字符串上一交易时段的收盘价，该值未知时省略。
change字符串ETF：price 减去 previous_close；共同基金：nav 减去 previous_nav。前值未知时省略。
change_percent字符串相对 ETF 的 previous_close 或共同基金的 previous_nav 的涨跌幅百分比；1.5 表示 1.5%。前值未知时省略。
volume字符串今日成交股数，未知时省略。
market_session取值之一：pre、open、post、closedtimestamp 时刻的交易所状态：pre、open、post 或 closed；只有美国交易所有 pre 和 post。
timestamp日期时间价格有效的时间，UTC 时间，精确到整秒。
完整参考文档 →
GET最多 50 只基金的最新价格/v1/funds/prices
每只列出基金的最新价格：ETF 的最新价格或共同基金的最新基金净值。
参数
ids必填以逗号分隔的基金 id，去重后最多 50 个。每个 id 的规则与单个价格路由相同。每个返回价格的 id 计一次调用。
响应字段
prices对象数组按 id 给出每个已解析 id 的价格。
errors对象数组未返回价格的 id。不计费。
完整参考文档 →
GET单只基金的价格 K 线/v1/funds/{id}/bars
每日（1d）或一分钟（1m）K 线，按时间从旧到新排列，采用股票 K 线的结构。
参数
id必填基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。
interval可选1d（每个交易日一根 K 线；共同基金的 K 线为其每日基金净值）或 1m（一分钟 K 线：仅限 ETF）。其他取值返回 400 invalid_interval。
start可选起始 K 线。1d：日期（YYYY-MM-DD），含该日；省略则表示最早的一根 K 线。1m：UTC 时间（YYYY-MM-DDTHH:MM:SSZ，或日期，表示 UTC 00:00），含该时刻；省略则表示 end 之前一天。
end可选结束 K 线。1d：日期，含该日；省略则表示已有 K 线的最近一个交易日。1m：UTC 时间，不含该时刻；省略则表示当前时间，或 start 之后五天。1m 的 start 与 end 之间最多相隔 5 天（400 range_too_large）。
cursor可选上一页的 next_cursor，其他参数须保持一致。当游标对应的价格发生变化（拆股或分红）时，游标会失效：409 cursor_expired。
响应字段
id字符串规范的标的 id。
currency字符串所有价格的币种。便士会换算为英镑。
adjusted布尔值恒为 true：价格已按拆股和分红调整。相邻两页始终一致；如果两页之间发生拆股或分红导致历史数据变化，游标会失效（409 cursor_expired），而不会把两种数据混在一起。
start字符串不会返回：start 不会被调整。
end字符串不返回：日 K线不会被截断。
bars对象数组每页最多 5,000 根 K线。
next_cursor字符串回传该值即可读取下一页。最后一页为 null。
完整参考文档 →
GET单只基金的分配记录/v1/funds/{id}/distributions
某只基金的分配记录，按除权除息日从新到旧排列，分页返回。
参数
id必填基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。
cursor可选
响应字段
id字符串规范基金 id。
start日期不返回：所有账户都能获取完整历史。
distributions对象数组按除息日从新到旧排列。
next_cursor字符串作为 cursor 传入以获取下一页；最后一页为 null。
完整参考文档 →
使用场景
相关 API
常见问题
ETF ID 怎么写？
请使用 ETF 上市记录 id，如 ARCX:SPY。当美国裸股票代码（如 SPY）只对应一个美国上市记录时，也可使用。
如何获取共同基金的净值？
共同基金请使用 FUND:VFIAX。其每日净值出现在 nav 中，并附带 previous_nav 和 date；共同基金的数值从不延迟。
价格是实时的还是延迟的？
股票、ETF 和加密货币价格对所有账户都是实时的，已知时附带当日成交量。
费用是多少？
调用按每 1,000 次 $2 的价格，从预付额度 中扣费。每个账户在前 12 个月内，每月都有 $10 的免费额度，并允许商业使用。
该 API 涵盖什么？
日线和过往分红对所有账户覆盖全部历史，并包含 ETF 的 1 分钟线。共同基金没有 1 分钟线；请求会返回 400 invalid_interval。其日线的开盘、最高、最低和收盘都使用净值，没有成交量。批量价格调用最多接受 50 个 id，每个返回价格的 id 计一次调用。
ETF 价格与共同基金净值有何不同？
ETF 返回成交价格。共同基金在 nav 中返回一个日终净值，并附带 previous_nav 和 date。通过 type 判断是 etf 还是 mutual_fund。净值从不延迟，晚于下一个工作日即视为过期。交易所休市时，ETF 价格从不视为过期。
使用了错误类型的 id 会怎样？
ETF id 使用交易所代码和股票代码，例如 ARCX:SPY；共同基金 id 使用 FUND 加冒号和代码。在基金路由上使用股票 id 会返回 404 not_found。在股票路由上使用基金 id 会以 301 重定向到基金路由。
基金历史数据可以回溯多久？
所有账户都可获得日线和过往分红的完整历史。若更早的数据不存在，start 会返回提供的第一个日期。分红的 kind 字段在数据源提供之前会被省略。
基金价格请求如何计数？
REST 和 MCP 使用同一个账户和同一份额度余额，每个请求都需要 Bearer 密钥。一次批量请求最多接受 50 个基金 id，每个返回价格的 id 计一次调用。
从免费密钥开始
12 个月内每月赠送 10 美元免费额度，无需绑卡。每月 10 美元免费额度，无需绑卡。