基金 API 参考

ETF 和公募基金的价格、净值、历史和分配

概览

ETF 和公募基金的价格、历史价格、分配、简介与搜索。每个请求都需要 Bearer 密钥，REST 与 MCP 共用同一个额度余额。

ETF 的 id 就是它的标的 id，例如 ARCX:SPY。公募基金的 id 由 FUND、冒号和代码组成，例如 FUND:VFIAX。当单独的美国代码（如 SPY）只对应一个美国标的时，也可以直接使用。在基金路由上传入股票 id 会返回 404 not_found，在股票路由上传入基金 id 会通过 301 跳转到这里。

ETF 有价格。公募基金每天有一个净值（NAV），分别在 nav、previous_nav 和 date 中给出。价格响应带有 type 字段，说明你拿到的是哪一种。

基础 URL： https://api.narwhalapi.com。 MCP 工具是 funds, with one action ，适用于下方每个路由。

每个账户可获得的内容

查看	所有账户
ETF 最新价格	在线
公募基金净值	最新净值
日 K 线和历史分配	完整历史数据
一分钟 K 线（仅 ETF）	已包含
搜索与简介	已包含

查看价格了解每次调用的费用。请求按其所属 API 的价格计费，除非某个路由另有说明。

公募基金净值是日终数值，从不延迟。一旦距今超过下一个工作日，即为过期。
公募基金没有一分钟 K 线。请求会返回 400 invalid_interval。
公募基金的日 K 线就是它的净值：开盘价、最高价、最低价和收盘价是同一个数，没有成交量。
在数据源提供之前，分配记录中的 kind 会被省略。

端点

每个路由都是 GET 请求，并需要在以下请求头中携带你的密钥： Authorization: Bearer 标头。示例仅展示响应的结构，并非实时数据。

按代码或名称搜索 ETF 和公募基金

GET /v1/funds/search

代码或名称以 q 开头（不区分大小写）的基金：先是完全匹配的代码，再是其他代码，最后是名称。可选筛选参数 type（etf 或 mutual_fund）和 country（三个字母）。每页最多 50 条，附带 next_cursor。数据读自我们自己的代码列表，所有账户均可使用，计一次调用。

MCP：工具 funds, action search。

参数

参数	位置	必填	类型	含义
`q`	查询参数	是	字符串	代码开头或基金名称开头，不区分大小写，至少 2 个字符（例如 `vf` 或 `vanguard 500`）。排序：完全匹配的代码、其他代码、名称开头，然后是名称中后面某个单词的开头。
`country`	查询参数	否	字符串	仅限该国家的基金，三个字母（USA）。
`type`	查询参数	否	取值之一：etf、mutual_fund	仅 ETF 或仅公募基金。
`cursor`	查询参数	否	字符串	上一页返回的 `next_cursor`，其他参数保持不变。

响应字段

字段	类型	传入	含义
`results`	对象数组	总是	每页最多 50 条。
`results[].id`	字符串	总是	规范基金 id。
`results[].symbol`	字符串	总是	基金的代码。
`results[].name`	字符串	总是	名称，与我们的代码列表一致。
`results[].type`	取值之一：etf、mutual_fund	总是	品种类型。
`results[].mic`	字符串	可选	交易所的四字母代码。公募基金省略（无交易所）。
`results[].country`	字符串	可选	基金所属国家，三个字母。
`results[].currency`	字符串	总是	价格的币种。
`next_cursor`	字符串	总是	回传该值即可读取下一页。最后一页为 null。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/search?q=vanguard&type=mutual_fund"

{
  "results": [
    {
      "id": "ARCX:SPY",
      "symbol": "SPY",
      "name": "SPDR S&P 500 ETF Trust",
      "type": "etf",
      "mic": "ARCX",
      "country": "USA",
      "currency": "USD"
    },
    {
      "id": "FUND:VFIAX",
      "symbol": "VFIAX",
      "name": "Vanguard 500 Index Fund Admiral Shares",
      "type": "mutual_fund",
      "country": "USA",
      "currency": "USD"
    }
  ],
  "next_cursor": null
}

单只基金的概况

GET /v1/funds/{id}

基金的代码、名称、类型（etf 或 mutual_fund）、交易所（仅 ETF）、国家和币种，与我们的代码列表一致。所有账户均可使用。未知的字段会被省略。

MCP：工具 funds, action profile。

参数

参数	位置	必填	类型	含义
`id`	路径参数	是	字符串	基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。

响应字段

字段	类型	传入	含义
`id`	字符串	总是	规范基金 id。
`symbol`	字符串	总是	基金的代码。
`name`	字符串	总是	名称，与我们的代码列表一致。
`type`	取值之一：etf、mutual_fund	总是	品种类型。
`mic`	字符串	可选	交易所的四字母代码。公募基金省略（无交易所）。
`country`	字符串	可选	基金所属国家，三个字母。
`currency`	字符串	总是	价格的币种。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/ARCX:SPY"

{
  "id": "ARCX:SPY",
  "symbol": "SPY",
  "name": "SPDR S&P 500 ETF Trust",
  "type": "etf",
  "mic": "ARCX",
  "country": "USA",
  "currency": "USD"
}

单只基金的最新价格

GET /v1/funds/{id}/price

ETF 返回最新成交价，格式同股票价格并附加 type: etf；公募基金返回最新净值（type: mutual_fund：nav、previous_nav、change、change_percent 和净值对应的 date；为日终数值，从不延迟，超过下一个工作日则为 stale）。change_percent 以百分比表示。传入股票 id 会返回 404 not_found。

MCP：工具 funds, action price。

参数

参数	位置	必填	类型	含义
`id`	路径参数	是	字符串	基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。

响应字段

字段	类型	传入	含义
`id`	字符串	总是	规范的标的 id。
`symbol`	字符串	总是	该交易所上的股票代码。
`currency`	字符串	总是	所有价格字段的币种。便士会换算为英镑。
`price`	字符串	可选	最新成交价，单位为 `currency`。
`previous_close`	字符串	可选	上一交易日的收盘价。未知时省略。
`change`	字符串	可选	`price` 减去 `previous_close`。`previous_close` 省略时它也省略。
`change_percent`	字符串	可选	相对 `previous_close` 的涨跌幅，以百分比表示（1.5 表示 1.5%）。
`volume`	字符串	可选	今日成交股数。未知时省略，延迟数据中一律省略。
`market_session`	取值之一：pre、open、post、closed	可选	标的所在交易所在 `timestamp` 时的状态：pre、open、post 或 closed。只有美国交易所有 pre 和 post。
`timestamp`	日期时间	可选	价格的有效时间（UTC，精确到整秒）。
`stale`	布尔值	总是	交易所开盘期间价格超过 15 分钟未更新，或无法刷新时为 true。休市期间不会被视为过期。
`delayed`	恒为 true	可选	不返回：所有账户的价格都是实时的。
`type`	取值之一：etf、mutual_fund	总是	ETF 为 etf，公募基金为 mutual_fund。
`nav`	字符串	可选	每份净值，币种为 `currency`。
`previous_nav`	字符串	可选	前一日的净值。未知时省略。
`date`	日期	可选	净值对应的日期（YYYY-MM-DD）。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/ARCX:SPY/price"

{
  "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"
}

最多 50 只基金的最新价格

GET /v1/funds/prices

返回所列每只基金的最新价格：ETF 的最新成交价或公募基金的最新净值。每个返回价格的 id 计一次调用，一次性扣费：如果你的余额不足以支付已解析的 id，整个请求会被拒绝并返回 402 insufficient_credits。未返回价格的 id 列在 errors 中，不收费。change_percent 以百分比表示。

最多发送 50 个 id，ETF 和公募基金可以混合。批量请求一次性扣费：如果你的余额不足以支付能解析的 id，整个请求返回 402 insufficient_credits。

MCP：工具 funds, action prices。

参数

参数	位置	必填	类型	含义
`ids`	查询参数	是	字符串	以逗号分隔的基金 id，去重后最多 50 个。每个 id 的规则与单个价格路由相同。每个返回价格的 id 计一次调用。

响应字段

字段	类型	传入	含义
`prices`	对象数组	总是	按 id 给出每个已解析 id 的价格。
`prices[].id`	字符串	总是	规范的标的 id。
`prices[].symbol`	字符串	总是	该交易所上的股票代码。
`prices[].currency`	字符串	总是	所有价格字段的币种。便士会换算为英镑。
`prices[].price`	字符串	可选	最新成交价，单位为 `currency`。
`prices[].previous_close`	字符串	可选	上一交易日的收盘价。未知时省略。
`prices[].change`	字符串	可选	`price` 减去 `previous_close`。`previous_close` 省略时它也省略。
`prices[].change_percent`	字符串	可选	相对 `previous_close` 的涨跌幅，以百分比表示（1.5 表示 1.5%）。
`prices[].volume`	字符串	可选	今日成交股数。未知时省略，延迟数据中一律省略。
`prices[].market_session`	取值之一：pre、open、post、closed	可选	标的所在交易所在 `timestamp` 时的状态：pre、open、post 或 closed。只有美国交易所有 pre 和 post。
`prices[].timestamp`	日期时间	可选	价格的有效时间（UTC，精确到整秒）。
`prices[].stale`	布尔值	总是	交易所开盘期间价格超过 15 分钟未更新，或无法刷新时为 true。休市期间不会被视为过期。
`prices[].delayed`	恒为 true	可选	不返回：所有账户的价格都是实时的。
`prices[].type`	取值之一：etf、mutual_fund	总是	ETF 为 etf，公募基金为 mutual_fund。
`prices[].nav`	字符串	可选	每份净值，币种为 `currency`。
`prices[].previous_nav`	字符串	可选	前一日的净值。未知时省略。
`prices[].date`	日期	可选	净值对应的日期（YYYY-MM-DD）。
`errors`	对象数组	总是	未返回价格的 id。不计费。
`errors[].id`	字符串	总是	请求时传入的原始 id。
`errors[].code`	取值之一：not_found、not_covered、upstream_busy	总是	not_found：没有这个标的。not_covered：该交易所暂无价格数据。upstream_busy：当前无法获取价格，请稍后重试。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/prices?ids=ARCX:SPY,FUND:VFIAX"

{
  "prices": [
    {
      "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"
    },
    {
      "id": "FUND:VFIAX",
      "symbol": "VFIAX",
      "currency": "USD",
      "type": "mutual_fund",
      "nav": "551.07",
      "previous_nav": "549.80",
      "change": "1.27",
      "change_percent": "0.23",
      "date": "2026-10-23",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "FUND:NOPE",
      "code": "not_found"
    }
  ]
}

单只基金的价格 K 线

GET /v1/funds/{id}/bars

日线（1d）或一分钟（1m）K 线，按时间从早到晚排列，格式同股票 K 线。公募基金的日 K 线就是其每日净值（开盘价、最高价、最低价和收盘价均为净值，无成交量）；它没有一分钟 K 线（400 invalid_interval）。一分钟 K 线仅限 ETF。历史范围：全部，所有账户均可获取。每页最多 5,000 根 K 线，附带 next_cursor；游标与价格不再匹配时返回 409 cursor_expired。每页计一次调用。

如果拆股或分配改变了两页之间的历史数据，游标将失效并返回 409 cursor_expired。

MCP：工具 funds, action bars。

参数

参数	位置	必填	类型	含义
`id`	路径参数	是	字符串	基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。
`interval`	查询参数	否	取值之一：1d、1m	`1d`（每个交易日一根 K 线；公募基金的 K 线是其每日净值）或 `1m`（一分钟 K 线：仅限 ETF）。其他值返回 400 invalid_interval。
`start`	查询参数	否	字符串	第一根 K线。`1d`：日期（YYYY-MM-DD），包含该日；省略表示取最早的一根。`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线。
`bars[].date`	字符串	可选	交易日日期（YYYY-MM-DD）。仅日 K线有此字段，1 分钟 K线省略。
`bars[].timestamp`	日期时间	总是	K线所在时段的起点（UTC）：日 K线为交易所开盘时刻，1 分钟 K线为该分钟。
`bars[].open`	字符串	总是	周期的第一个价格。
`bars[].high`	字符串	总是	周期内最高价。
`bars[].low`	字符串	总是	周期内最低价。
`bars[].close`	字符串	总是	周期的最后一个价格。
`bars[].volume`	字符串	可选	该时段内的成交股数。未知时省略。
`next_cursor`	字符串	总是	回传该值即可读取下一页。最后一页为 null。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/ARCX:SPY/bars?interval=1d&start=2026-10-01"

{
  "id": "ARCX:SPY",
  "currency": "USD",
  "adjusted": true,
  "bars": [
    {
      "date": "2026-10-23",
      "timestamp": "2026-10-23T13:30:00Z",
      "open": "575.10",
      "high": "577.60",
      "low": "573.90",
      "close": "576.40",
      "volume": "48210300"
    }
  ],
  "next_cursor": null
}

单只基金的分配记录

GET /v1/funds/{id}/distributions

单只基金的分配记录，按除息日从新到旧排列，分页返回。所有账户均可获取完整历史。每次请求计一次调用。未知 id 返回 404 not_found。

MCP：工具 funds, action distributions。

参数

参数	位置	必填	类型	含义
`id`	路径参数	是	字符串	基金 id。ETF 即其标的 id：交易所的四字母代码、冒号和代码（ARCX:SPY）。公募基金由 FUND、冒号和代码组成（FUND:VFIAX）。当单独的美国代码（如 SPY）只对应一个美国标的时，也可直接使用；响应中会返回规范 id。
`cursor`	查询参数	否	字符串	上一页返回的 `next_cursor`，其他参数保持不变。

响应字段

字段	类型	传入	含义
`id`	字符串	总是	规范基金 id。
`start`	日期	可选	不返回：所有账户都能获取完整历史。
`distributions`	对象数组	总是	按除息日从新到旧排列。
`distributions[].ex_date`	日期	总是	基金开始不含该分配交易的第一天。
`distributions[].amount`	字符串	总是	每份分配金额，币种为 `currency`。
`distributions[].currency`	字符串	总是	`amount` 的币种。
`distributions[].pay_date`	日期	可选	发放日。未知时省略。
`distributions[].record_date`	日期	可选	持有人须登记在册的日期（股权登记日）。未知时省略。
`distributions[].kind`	取值之一：income、capital_gain	可选	分配的类型。数据源未说明时省略。
`next_cursor`	字符串	总是	作为 `cursor` 传入即可读取下一页；最后一页为 null。

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/funds/ARCX:SPY/distributions"

{
  "id": "ARCX:SPY",
  "distributions": [
    {
      "ex_date": "2026-09-18",
      "amount": "1.78",
      "currency": "USD",
      "pay_date": "2026-10-30",
      "record_date": "2026-09-18"
    }
  ],
  "next_cursor": null
}

错误

错误使用通用的 problem 结构，并带有 request_id。查看 API 错误码与额度了解该结构和额度相关的响应头。失败的请求不计费。

代码	状态	含义
`invalid_query`	400	参数缺失、未知、重复或超出范围。
`invalid_id`	400	id 或交易对的写法不符合此 API 的要求。
`too_many_ids`	400	批量请求包含的 id 超过 50 个。
`invalid_interval`	400	interval 不是 1d 或 1m，或该品种不支持。
`range_too_large`	400	时间窗口超过该路由允许的长度。
`not_found`	404	没有这个标的、基金或交易对。
`invalid_cursor`	400	该游标不是本请求返回的，或来自另一个请求。
`cursor_expired`	409	游标对应的价格已变化。请不带游标重新开始。
`insufficient_credits`	402	您的额度余额低于该请求的费用。
`upstream_busy`	503	目前无法获取价格。在批量请求中会列在 errors 中。请稍后重试。
`area_unavailable`	503	该区域目前无法响应。

此页面对你有帮助吗?