浏览全部文档

股票数据接口参考

上市股票的价格、历史、公司事件和估值比率

概览

上市股票的价格、历史价格、公司事件、市值和估值比率。每个请求都需要 Bearer 密钥,REST 与 MCP 共用同一个额度余额。

标的 id 由交易所的四位字母代码、冒号和股票代码组成,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时,也可以直接使用,返回结果中始终带有规范 id。价格和金额均为十进制字符串。

每个标的可以带有 company_id。它把标的关联到 Filings API 中的公司,因此价格、估值和财务报表可以通过同一个 id 对应起来。

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

A company_id 把标的关联到 披露文件 API:财务报表、申报文件和持有人。

每个账户可获得的内容

查看所有账户
最新价格在线
价格中附带的当日成交量已包含
日 K 线,以及历史分红、拆股和财报完整历史数据
1 分钟 K 线已包含
搜索与简介已包含
涨跌榜已包含
市值、P/E、P/S、P/B 和股息率已包含
估值历史完整历史数据
资本成本与 beta已包含

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

  • 估值覆盖与我们财报库中某家公司匹配的美国和韩国标的。目前韩国只提供 P/E。
  • 无法正确算出的比率会被省略,绝不会以 0 返回。
  • 财报中的 eps_actual 按市场数据口径计算,pe_ratio 所用的 EPS 来自公司财报。两者可能不同,请不要直接比较。
  • 资本成本覆盖与我们财报库中某家公司匹配的美国和韩国标的。你通过 erp 传入自己的股权风险溢价。计算方法只在资本成本方法说明中写一次,每个返回结果都链接到它。
  • 银行或保险公司会返回 422 not_applicable,因为利息对它们属于经营成本。无法算出的输入项会在 422 inputs_unavailable 中指明,绝不会自行补齐。
  • 估值历史按每个财期期末(季末或年末)给出一个数据点,而不是每天一个。每个数据点使用当日或之前最近一个交易日的收盘价(仅按拆股调整),以及该财期披露的数据。
  • 财报只包含已发布的结果,暂不包含即将发布的财报日期。
  • 日本标的的简介只包含名称、交易所、国家、币种和 company_id。

端点

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

单只股票的简介

GET /v1/equities/{id}

返回标的信息(代码、名称、类型、交易所、国家、币种)、公司的板块、行业和网站,以及标的匹配到财报库中公司时的 company_id。所有账户均可使用。日本标的只包含名称、交易所、国家、币种和 company_id。未知的字段会被省略。

MCP:工具 equities, action profile。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
symbol字符串总是该交易所上的股票代码。
name字符串总是名称,与我们的代码列表一致。
type取值之一:common_stock、preferred_stock、depositary_receipt、reit、closed_end_fund、unit、right、warrant、other总是品种类型。
mic字符串总是交易所的四位字母代码。
country字符串可选标的所属国家,三位字母。
currency字符串总是价格的币种。
sector字符串可选板块。日本标的没有简介文本,因此省略。
industry字符串可选行业。日本标的省略。
website字符串可选公司网站。日本标的省略。
logo_url字符串可选我们自己保存的公司标志图。没有时省略。
company_id字符串可选公司的财报 id,仅在标的能明确匹配到公司时返回。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT"
响应示例
{
  "id": "XNAS:MSFT",
  "symbol": "MSFT",
  "name": "Microsoft Corporation",
  "type": "common_stock",
  "mic": "XNAS",
  "country": "USA",
  "currency": "USD",
  "sector": "Technology",
  "industry": "Software",
  "website": "https://www.microsoft.com",
  "company_id": "usa:0000789019"
}

单只股票的最新价格

GET /v1/equities/{id}/price

单个标的的最新价格。change_percent 以百分比表示。未知的 id 返回 404 not_found;尚无价格数据的市场返回 404 not_covered。

MCP:工具 equities, action price。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。

响应字段

字段类型传入含义
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可选不返回:所有账户的价格都是实时的。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/price"
响应示例
{
  "id": "XNAS:MSFT",
  "symbol": "MSFT",
  "currency": "USD",
  "price": "421.35",
  "previous_close": "418.90",
  "change": "2.45",
  "change_percent": "0.58",
  "volume": "18234100",
  "market_session": "open",
  "timestamp": "2026-10-26T15:42:00Z",
  "stale": false
}

最多 50 只股票的最新价格

GET /v1/equities/prices

返回所列每个 id 的最新价格。每个返回价格的 id 计 1 次调用,并一次性扣除:如果余额不足以支付已解析的 id,整个请求会被拒绝并返回 402 insufficient_credits。未返回价格的 id 列在 errors 中,不计费。change_percent 以百分比表示。

最多传入 50 个 id。批量请求一次性计费:如果余额不足以支付能解析出的 id,整个请求返回 402 insufficient_credits。

MCP:工具 equities, action prices。

参数

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

响应字段

字段类型传入含义
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可选不返回:所有账户的价格都是实时的。
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/equities/prices?ids=XNAS:MSFT,XNAS:NVDA"
响应示例
{
  "prices": [
    {
      "id": "XNAS:MSFT",
      "symbol": "MSFT",
      "currency": "USD",
      "price": "421.35",
      "previous_close": "418.90",
      "change": "2.45",
      "change_percent": "0.58",
      "volume": "18234100",
      "market_session": "open",
      "timestamp": "2026-10-26T15:42:00Z",
      "stale": false
    },
    {
      "id": "XNAS:NVDA",
      "symbol": "NVDA",
      "currency": "USD",
      "price": "188.20",
      "previous_close": "187.10",
      "change": "1.10",
      "change_percent": "0.59",
      "volume": "152003400",
      "market_session": "open",
      "timestamp": "2026-10-26T15:42:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XNAS:NOPE",
      "code": "not_found"
    }
  ]
}

美股涨跌榜

GET /v1/equities/movers

按 direction 返回前 25 只美股和 ETF:gainers、losers 或 active(当日涨幅和跌幅最大的股票中成交额最高者,不是全市场)。仅包含价格不低于 1 美元、今日成交至少 100,000 股且成交额至少 100 万美元的普通股和 ETF;由我们自行排名,缓存 10 分钟。change_percent 以百分比表示。market 目前只能是 us,其他市场返回 404 not_covered,未知的 direction 返回 400 invalid_query。计 1 次调用。

涨跌榜仅支持美国市场。其他市场返回 404 not_covered。

MCP:工具 equities, action movers。

参数

参数位置必填类型含义
market查询参数否字符串要排名的市场。目前只支持 us,其他市场返回 404 not_covered。
direction查询参数否字符串gainers(涨幅最大)、losers(跌幅最大)或 active(当日涨幅和跌幅最大的股票中成交额最高者,不是全市场)。其他值返回 400 invalid_query。

响应字段

字段类型传入含义
market恒为 "us"总是所排名的市场。
direction取值之一:gainers、losers、active总是请求的榜单类型。
movers对象数组总是最多 25 条,排名靠前者在先。仅包含价格不低于 1 美元、今日成交至少 100,000 股且成交额至少 100 万美元的普通股和 ETF。
movers[].id字符串总是规范的标的 id。
movers[].symbol字符串总是该交易所上的股票代码。
movers[].name字符串总是公司或基金名称。
movers[].price字符串总是最新价格,单位为美元。
movers[].change_percent字符串总是相对上一收盘价的涨跌幅,以百分比表示(31.4 表示 31.4%),保留 2 位小数。
movers[].volume字符串总是今日成交股数。
timestamp日期时间总是列表中最新一条价格的有效时间(UTC)。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/movers?market=us&direction=gainers"
响应示例
{
  "market": "us",
  "direction": "gainers",
  "movers": [
    {
      "id": "XNAS:NVDA",
      "symbol": "NVDA",
      "name": "NVIDIA Corporation",
      "price": "188.20",
      "change_percent": "4.12",
      "volume": "152003400"
    }
  ],
  "timestamp": "2026-10-26T15:42:00Z"
}

单只股票的价格 K线

GET /v1/equities/{id}/bars

日 K线(1d)或 1 分钟 K线(1m),按时间从早到晚排列,已按拆股和分红调整。历史范围:全部,所有账户均可获取。1 分钟 K线可追溯到 2020 年,每次调用最多覆盖 5 天(400 range_too_large)。当日的日 K线在交易所收盘后出现。每页最多 5,000 根 K线,带 next_cursor;与价格不再匹配的游标返回 409 cursor_expired。每页计 1 次调用。

K线已按拆股和分红调整。如果两次翻页之间发生拆股或分红导致历史数据变化,游标会失效并返回 409 cursor_expired。

MCP:工具 equities, action bars。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。
interval查询参数否取值之一:1d、1m1d(每个交易日一根 K线)或 1m(1 分钟 K线)。其他值返回 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/equities/XNAS:MSFT/bars?interval=1d&start=2026-10-01"
响应示例
{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "adjusted": true,
  "bars": [
    {
      "date": "2026-10-23",
      "timestamp": "2026-10-23T13:30:00Z",
      "open": "417.10",
      "high": "420.55",
      "low": "415.80",
      "close": "418.90",
      "volume": "21034500"
    }
  ],
  "next_cursor": null
}

单只股票的分红

GET /v1/equities/{id}/dividends

单个标的的现金分红,按除息日从新到旧排列,分页返回。列表可能包含已公布的未来记录。所有账户都能获取完整历史。未来记录不会被截掉。每个请求计 1 次调用。未知的 id 返回 404 not_found;尚无数据的市场返回 404 not_covered。

MCP:工具 equities, action dividends。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。
cursor查询参数否字符串上一页返回的 next_cursor,其他参数保持不变。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
start日期可选不返回:所有账户都能获取完整历史。
dividends对象数组总是按除息日从新到旧排列。可能包含已公布的未来记录。
dividends[].ex_date日期总是股票开始不含该笔分红交易的第一天(除息日)。
dividends[].amount字符串总是每股分红,单位为 currency。
dividends[].currency字符串总是amount 的币种。便士会换算为英镑。
dividends[].pay_date日期可选发放日。未知时省略。
dividends[].record_date日期可选持有人须登记在册的日期(股权登记日)。未知时省略。
next_cursor字符串总是作为 cursor 传入即可读取下一页;最后一页为 null。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/dividends"
响应示例
{
  "id": "XNAS:MSFT",
  "dividends": [
    {
      "ex_date": "2026-08-20",
      "amount": "0.91",
      "currency": "USD",
      "pay_date": "2026-09-10",
      "record_date": "2026-08-20"
    }
  ],
  "next_cursor": null
}

单只股票的拆股

GET /v1/equities/{id}/splits

单个标的的拆股记录,从新到旧排列。所有账户都能获取完整历史。未来记录不会被截掉。每个请求计 1 次调用。未知的 id 返回 404 not_found;尚无数据的市场返回 404 not_covered。

MCP:工具 equities, action splits。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
start日期可选不返回:所有账户都能获取完整历史。
splits对象数组总是从新到旧排列。
splits[].date日期总是股票开始按拆股后口径交易的第一天。
splits[].ratio字符串总是新股对旧股的比例:10:1 表示每持有 1 股得到 10 股;1:10 为反向拆股(合股)。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:NFLX/splits"
响应示例
{
  "id": "XNAS:NFLX",
  "splits": [
    {
      "date": "2025-11-17",
      "ratio": "10:1"
    }
  ]
}

单只股票的财报

GET /v1/equities/{id}/earnings

单个标的已发布的财报(按交易所所在地日期,今天或更早),含预期值、实际值和超预期幅度,从新到旧排列,分页返回。暂不包含即将发布的财报日期。surprise_percent 以百分比表示。eps_actual 按市场数据口径计算,可能与估值中的财报 EPS 不同。当我们持有相应报告时,filing_id 指向涵盖该次财报的年报或季报。所有账户都能获取完整历史。每个请求计 1 次调用。未知的 id 返回 404 not_found;尚无数据的市场返回 404 not_covered。

此路由只返回已发布的财报,暂不包含即将发布的财报日期。

filing_id 把一份已发布的财报与涵盖它的披露文件关联起来。将它传给 Filings API 的 GET /v1/filings/{filing_id} 即可。

MCP:工具 equities, action earnings。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。
cursor查询参数否字符串上一页返回的 next_cursor,其他参数保持不变。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
start日期可选不返回:所有账户都能获取完整历史。
earnings对象数组总是只包含已发布的财报,从新到旧排列。暂不包含即将发布的财报日期。
earnings[].date日期总是财报发布日(按交易所所在地,今天或更早)。
earnings[].time取值之一:before_open、after_close、during可选当天发布的时段。未知时省略。
earnings[].eps_estimate字符串可选分析师预期的每股收益。没有时省略。
earnings[].eps_actual字符串可选按市场数据口径公布的每股收益,可能与估值中 eps_ttm 的财报 EPS 不同。公布之前省略。
earnings[].surprise字符串可选eps_actual 减去 eps_estimate,保留 2 位小数。
earnings[].surprise_percent字符串可选surprise 占预期值的百分比(8.31 表示 8.31%),保留 2 位小数。
earnings[].filing_id字符串可选我们财报库中涵盖这次财报的年报、半年报或季报:将它传给 filings 的 GET /v1/filings/{filing_id}。公司没有匹配的财报,或没有报告与该日期吻合时省略。
next_cursor字符串总是作为 cursor 传入即可读取下一页;最后一页为 null。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/earnings"
响应示例
{
  "id": "XNAS:MSFT",
  "earnings": [
    {
      "date": "2026-07-29",
      "time": "after_close",
      "eps_estimate": "3.31",
      "eps_actual": "3.45",
      "surprise": "0.14",
      "surprise_percent": "4.23",
      "filing_id": "usa:0000789019:0000950170-26-000123"
    }
  ],
  "next_cursor": null
}

单只股票的市值、P/E、P/S、P/B 和股息率

GET /v1/equities/{id}/valuation

单个美国或韩国标的的市值(最新价格乘以流通股数)、P/E(最新价格除以公司财报中的近 12 个月稀释后 EPS,按 GAAP 或 IFRS 原样披露)、P/S(市值除以近 12 个月营收)、P/B(市值除以最新资产负债表的总权益)和股息率(近 12 个月每股分红除以价格,以百分比表示),并附带输入项及其对应日期。目前韩国只提供 P/E;市值、P/S、P/B 和股息率需要股本数和分红数据。无法正确算出的数值会被省略,绝不会以 0 返回:股本数之后发生拆股时的市值、有多个股份类别但各自没有股本数时的市值、存托凭证或外国申报公司的市值;EPS 为负数或小于 0.01、以其他币种披露、或为存托凭证时的 P/E。公司的其他股份类别(如优先股)没有自己的数值,也不显示。美国和韩国以外的标的,或无法明确匹配到公司的标的,返回 404 not_covered。计 1 次调用。

每个比率都附带其输入项及对应日期:shares_as_of、eps_period_end、revenue_period_end、equity_as_of 和 dividends_period_end。

MCP:工具 equities, action valuation。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
currency字符串总是market_cap 以及 pe_ratio 所用价格的币种。
market_cap字符串可选最新价格乘以 shares_outstanding,单位为 currency 的整数单位。在 shares_as_of 之后发生拆股、公司有多个股份类别但各自没有股本数、或为存托凭证或外国申报公司时省略。韩国暂无市值:其标的目前只显示 P/E。
pe_ratio字符串可选最新价格除以 eps_ttm,保留 2 位小数。eps_ttm 为负数或小于 0.01、披露币种不是 currency、在 eps_period_end 之后发生拆股,以及存托凭证时省略。
ps_ratio字符串可选市销率:market_cap 除以 revenue_ttm,保留 2 位小数。market_cap 省略时它也省略;营收不大于 0,或营收币种不是 currency 时同样省略。
pb_ratio字符串可选市净率:market_cap 除以 total_equity,保留 2 位小数。market_cap 省略时它也省略;总权益为 0 或负数,或币种不是 currency 时同样省略。
dividend_yield字符串可选近 12 个月每股分红除以最新价格,以百分比表示(0.71 表示 0.71%),保留 2 位小数。这 12 个月没有分红记录(包括不分红的公司)、在 dividends_period_end 之后发生拆股、分红币种不是 currency,以及存托凭证时省略。
shares_outstanding字符串可选公司主要普通股类别的流通股数。若标的属于其他类别(如优先股),此处没有股本数,则省略。
shares_as_of日期可选shares_outstanding 的统计日期。只要有股本数就会显示。
eps_ttm字符串可选来自公司财报的近 12 个月稀释后 EPS(按 GAAP 或 IFRS 原样披露);第四季度为全年数据减去前三个季度。只要能算出就会显示;若标的是公司的其他股份类别则省略。它可能与股票财报中的 eps_actual 不同,后者按市场数据口径计算。
eps_period_end日期可选eps_ttm 中最新一个季度的截止日。只要显示 eps_ttm 就会显示。
revenue_ttm字符串可选来自公司财报的近 12 个月营收,单位为披露币种的整数单位(第四季度为全年数据减去前三个季度)。没有连续四个季度或完整年度数据,以及标的是公司的其他股份类别时省略。
revenue_period_end日期可选revenue_ttm 中最新一个季度的截止日。只要显示 revenue_ttm 就会显示。
total_equity字符串可选最新资产负债表的总权益,含少数股东权益,单位为披露币种的整数单位。可能为负数。
equity_as_of日期可选total_equity 对应的资产负债表日期。只要显示 total_equity 就会显示。
dividend_per_share_ttm字符串可选主要普通股类别近 12 个月宣告的每股分红,以披露币种计。只要能算出就会显示。
dividends_period_end日期可选dividend_per_share_ttm 中最新一个季度的截止日。只要显示 dividend_per_share_ttm 就会显示。
company_id字符串总是该标的在我们财报库中匹配到的公司。
timestamp日期时间总是结果所用价格的有效时间(UTC)。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/valuation"
响应示例
{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "market_cap": "3130000000000",
  "pe_ratio": "33.50",
  "ps_ratio": "11.40",
  "pb_ratio": "10.20",
  "dividend_yield": "0.86",
  "shares_outstanding": "7430000000",
  "shares_as_of": "2026-07-24",
  "eps_ttm": "12.58",
  "eps_period_end": "2026-06-30",
  "revenue_ttm": "274500000000",
  "revenue_period_end": "2026-06-30",
  "total_equity": "307000000000",
  "equity_as_of": "2026-06-30",
  "dividend_per_share_ttm": "3.64",
  "dividends_period_end": "2026-06-30",
  "company_id": "usa:0000789019",
  "timestamp": "2026-10-26T15:42:00Z"
}

单只股票的 beta、股权成本、债务成本和 WACC

GET /v1/equities/{id}/cost-of-capital

单只美国或韩国股票相对基准 ETF 的 beta(默认使用两年的周收益率,价格已按拆股和分红调整)、无风险利率(该国国债收益率曲线的 10 年期点位,或由你提供)、股权成本(无风险利率加 beta 乘以股权风险溢价:由你通过 erp 传入,默认使用我们公布的该股票所在国家的总溢价)、债务成本(公司财报中的利息费用除以平均总债务;无法使用时,取无风险利率加上公开表中按公司利息保障倍数查得的违约利差;分别给出税前和税后,除非你传入 tax_rate,否则税率取自公开表中该国的企业所得税率),以及按市值和总债务加权的 WACC。每个输入项都在结果中附带数值、依据和日期。银行和保险公司返回 422 not_applicable;无法正确算出的输入项会在 422 inputs_unavailable 中指明,绝不会自行修补;已显示但需谨慎对待的数字会附带一条 warnings。计 1 次调用。

erp 为必填。这里没有韩国的收益率曲线,因此韩国股票需要传入 risk_free。每个输入项都附带数值和日期,warnings 列出了在使用前需要核对的数字。

MCP:工具 equities, action cost_of_capital。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。
erp查询参数否字符串你的股权风险溢价,以百分比表示(5 表示 5%)。省略时使用我们公布的该股票所在国家的总股权风险溢价(结果中会注明其日期和依据)。我们没有公布该国溢价时,不传此参数会返回 400 erp_required。须大于 0 且不超过 25。
benchmark查询参数否字符串计算 beta 时作为市场代表的标的 id:与该股票币种相同的 ETF、基金或股票。省略时,美国股票用 ARCX:SPY,韩国股票用 XKRX:069500,日本股票用 XTKS:1306;其他市场必须传入。
window查询参数否取值之一:2y、5y收益率回溯的时间跨度:2y(默认)或 5y。
frequency查询参数否取值之一:weekly、monthly收益率的计算间隔:weekly(默认;取每个 ISO 周内最后一个共同交易日)或 monthly。
beta查询参数否取值之一:raw、adjusted用哪个 beta 计算股权成本:raw(默认)或 adjusted(0.67 乘以 raw 再加 0.33)。结果中始终同时包含两者。
risk_free查询参数否字符串你自己的无风险利率,以百分比表示。省略时使用该国国债收益率曲线的 10 年期点位。没有曲线的地区(韩国)必须传入:不传则返回 422 risk_free_unavailable。
tax_rate查询参数否字符串你自己用于债务税盾的税率,以百分比表示。省略时使用 Damodaran 公开表中(PwC 税率)该股票所在国家的企业所得税率。范围为 0 到 60。
period查询参数否取值之一:ttm、annual利息费用所取的期间:近 12 个月(ttm,默认)或最近一个完整财年(annual)。韩国和日本只有年度数据,因此只能使用 annual。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
currency字符串总是金额字段的币种。
company_id字符串总是该标的在我们财报库中匹配到的公司。
beta对象总是
beta.benchmark对象总是
beta.benchmark.id字符串总是基准的标的 id。
beta.benchmark.default恒为 true可选当基准是我们为该股票所在市场设定的默认基准时出现,值为 true。
beta.window取值之一:2y、5y总是
beta.frequency取值之一:weekly、monthly总是
beta.start日期总是第一个收益率所用的第一个价格的日期。
beta.end日期总是最后一个收益率所用的最后一个价格的日期。
beta.observations整数总是回归中使用的收益率个数。
beta.raw字符串总是股票收益率对基准收益率回归的斜率,两者所用价格均已按拆股和分红调整。
beta.adjusted字符串总是0.67 乘以 raw 再加 0.33。
beta.used取值之一:raw、adjusted总是用于 cost_of_equity 的 beta。
beta.r_squared字符串总是所解释的股票方差占比。
beta.std_error字符串总是raw 的标准误差。
risk_free对象总是
risk_free.rate字符串总是无风险利率,以百分比表示(4.25 表示 4.25%)。
risk_free.source取值之一:yield_curve、caller总是
risk_free.basis取值之一:ours、caller总是ours:我们发布的官方国债收益率曲线。caller:由你提供。
risk_free.country字符串可选收益率曲线所属国家。caller 时不返回。
risk_free.maturity恒为 "10y"可选曲线上的期限点位。caller 时不返回。
risk_free.tenor恒为 "P10Y"可选maturity 对应的 ISO 8601 时长。caller 时不返回。
risk_free.curve_type字符串可选曲线的报价方式(平价、零息、Svensson、到期收益率):各国之间略有不同。caller 时不返回。
risk_free.as_of日期可选曲线的日期。caller 时不返回。
equity_risk_premium对象总是
equity_risk_premium.rate字符串总是股权风险溢价,以百分比表示(4.25 表示 4.25%)。
equity_risk_premium.source取值之一:narwhal、caller总是由谁设定:narwhal 表示我们公布的该股票所在国家的总股权风险溢价,caller 表示你传入的 erp。
equity_risk_premium.country字符串可选我们溢价所属的国家,ISO 3166-1 alpha-3 代码。仅 narwhal 时返回。
equity_risk_premium.as_of日期可选我们溢价所对应的日期。仅 narwhal 时返回。
equity_risk_premium.basis取值之一:observed、modelled、table可选我们的总溢价如何得出:observed 来自我们自己的数据,modelled 由我们的利差模型得出,table 的国家部分取自公开表。仅 narwhal 时返回。
cost_of_equity字符串总是无风险利率加 beta 乘以股权风险溢价,以百分比表示(4.25 表示 4.25%)。
cost_of_debt对象可选没有债务记录的公司省略。
cost_of_debt.pre_tax字符串总是利息费用除以平均总债务,以百分比表示(4.25 表示 4.25%)。无法使用该方法时(利息不为正,或结果低于 0.1% 或高于 30%),若有 EBIT 记录:取无风险利率加上公开表中该公司利息保障倍数对应的违约利差;basis 会说明使用了哪一种。
cost_of_debt.basis取值之一:ours、table总是ours:公司财报中的利息费用除以平均债务。table:无风险利率加上表中的违约利差。
cost_of_debt.interest_coverage字符串可选EBIT 除以利息费用。仅 table 时返回;没有利息时省略。
cost_of_debt.default_spread字符串可选该利息保障倍数对应的违约利差,以百分比表示(4.25 表示 4.25%)。仅 table 时返回。
cost_of_debt.table字符串可选利差表的名称。仅 table 时返回。
cost_of_debt.table_update字符串可选该表的更新期次,例如 January 2026。仅 table 时返回。
cost_of_debt.table_url字符串可选该表的发布位置。仅 table 时返回。
cost_of_debt.after_tax字符串可选pre_tax 乘以(1 减税率)。税率未知时省略。
cost_of_debt.period取值之一:ttm、annual总是
cost_of_debt.period_end日期总是利息所含最新季度或年度的截止日。
cost_of_debt.interest_expense字符串总是该期间的利息费用,单位为 currency 的整数单位。
cost_of_debt.average_debt字符串总是期初和期末总债务的平均值;没有期初数据时只用期末余额。单位为 currency 的整数单位;不含租赁。
cost_of_debt.opening_debt字符串可选period_end 一年前的总债务。没有记录时省略。
cost_of_debt.closing_debt字符串总是period_end 时的总债务。
tax_rate对象可选该国在表中没有税率时省略。传入 tax_rate 可自行设定。
tax_rate.rate字符串总是债务适用的税率,以百分比表示(4.25 表示 4.25%)。
tax_rate.basis取值之一:table、caller总是table:取自公开表的该国税率。caller:由你提供。
tax_rate.source取值之一:country_table、caller总是country_table:取自公开表的该股票所在国家的企业所得税率。caller:你传入的 tax_rate。
tax_rate.country字符串可选税率所属国家的 ISO 3166-1 alpha-3 代码。仅表中税率返回。
tax_rate.table字符串可选表的名称,含其发布方和来源。仅表中税率返回。
tax_rate.table_update字符串可选税率所取自表的更新期次,例如 January 2026。
tax_rate.table_url字符串可选该表的发布位置。仅表中税率返回。
weights对象总是
weights.equity字符串总是市值除以(市值加债务),以百分比表示(4.25 表示 4.25%)。
weights.debt字符串总是债务除以(市值加债务),以百分比表示(4.25 表示 4.25%)。
weights.market_cap字符串总是最新价格乘以流通股数,单位为 currency 的整数单位。
weights.market_cap_as_of日期时间总是market_cap 所用价格的有效时间。
weights.total_debt字符串总是记录中最新的总债务,单位为 currency 的整数单位;不含租赁。
weights.total_debt_as_of日期总是total_debt 对应的资产负债表日期。
wacc字符串可选加权平均资本成本,以百分比表示(4.25 表示 4.25%)。没有债务的公司等于 cost_of_equity。存在债务但税率未知时省略。
warnings对象数组总是使用这些数字之前需要核对的事项。没有时为空。
warnings[].code字符串总是稳定的机器可读代码。
warnings[].message字符串总是用通俗语言说明其含义。
methodology_url字符串总是每个数值是如何算出的。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/cost-of-capital?erp=5"
响应示例
{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "company_id": "usa:0000789019",
  "beta": {
    "benchmark": {
      "id": "ARCX:SPY",
      "default": true
    },
    "window": "2y",
    "frequency": "weekly",
    "start": "2024-10-25",
    "end": "2026-10-16",
    "observations": 103,
    "raw": "1.0842",
    "adjusted": "1.0564",
    "used": "raw",
    "r_squared": "0.5731",
    "std_error": "0.0894"
  },
  "risk_free": {
    "rate": "4.1200",
    "source": "yield_curve",
    "basis": "ours",
    "country": "USA",
    "maturity": "10y",
    "curve_type": "nominal_par",
    "as_of": "2026-10-22"
  },
  "equity_risk_premium": {
    "rate": "5.0000",
    "source": "caller"
  },
  "cost_of_equity": "9.5410",
  "cost_of_debt": {
    "pre_tax": "3.9100",
    "basis": "ours",
    "after_tax": "2.9078",
    "period": "ttm",
    "period_end": "2026-06-30",
    "interest_expense": "2900000000",
    "average_debt": "74200000000",
    "opening_debt": "72000000000",
    "closing_debt": "76400000000"
  },
  "tax_rate": {
    "rate": "25.6300",
    "source": "country_table",
    "basis": "table",
    "country": "USA",
    "table": "Damodaran, corporate marginal tax rates by country (PwC, January 2026 update)",
    "table_update": "January 2026",
    "table_url": "https://pages.stern.nyu.edu/~adamodar/New_Home_Page/datafile/countrytaxrates.html"
  },
  "weights": {
    "equity": "98.0000",
    "debt": "2.0000",
    "market_cap": "3893412000000",
    "market_cap_as_of": "2026-10-26T15:42:00Z",
    "total_debt": "76400000000",
    "total_debt_as_of": "2026-06-30"
  },
  "wacc": "9.4083",
  "warnings": [],
  "methodology_url": "https://narwhalapi.com/methodology/cost-of-capital"
}

单只股票的估值历史

GET /v1/equities/{id}/valuation/history

单个美国或韩国标的在每个财期期末(季末或年末)的市值、P/E、P/S、P/B 和股息率,按时间从早到晚排列。每个数据点使用当日或之前最近一个交易日的收盘价(仅按拆股调整),以及该财期披露的数据(近 12 个月 EPS、营收和分红、总权益、最近的股本数),因此后来的重述也会体现在内。无法算出的数值会被省略,绝不会以 0 返回,规则与估值接口相同。历史范围:全部,所有账户均可获取。美国和韩国以外的标的,或无法明确匹配到公司的标的,返回 404 not_covered。计 1 次调用。

MCP:工具 equities, action valuation_history。

参数

参数位置必填类型含义
id路径参数是字符串标的 id:交易所的四位字母代码、冒号和股票代码,例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码(如 MSFT)只对应一个美国标的时也可使用,返回结果带有规范 id。股份类别用点号表示(BRK.B),也接受 BRK-B。

响应字段

字段类型传入含义
id字符串总是规范的标的 id。
currency字符串总是所有价格和市值的币种。
company_id字符串总是该标的在我们财报库中匹配到的公司。
start日期可选不返回:所有账户都能获取完整历史。
points对象数组总是公司每个财期期末一个数据点,按时间从早到晚排列。每个数据点由该财期披露的数据和当日价格算出,而不是当时已知的数据:后来的重述也会体现在内。没有价格或没有任何数值的财期没有数据点。
points[].date日期总是公司的一个财期期末(季末或年末):该数据点中的所有数值都以这一天为准。
points[].price字符串可选price_date 当日的收盘价,单位为 currency,仅按拆股调整(从不按分红调整),因此与当前股本口径一致。当前无法读取该期间的价格时,它和下面所有数值都会省略,请稍后重试。
points[].price_date日期可选价格所取自的、date 当日或之前的最近一个交易日(最多提前 7 天)。
points[].market_cap字符串可选price 乘以最接近 date 的股本数(在其前 130 天到后 45 天之间统计),按当前股本口径,单位为 currency 的整数单位。没有这样的股本数、有多个股份类别但各自没有股本数,以及存托凭证或外国申报公司时省略。
points[].pe_ratio字符串可选price 除以截至 date 的四个季度稀释后 EPS,保留 2 位小数。EPS 为负数或小于 0.01、披露币种不是 currency、没有截至 date 的四个季度(或全年)记录,以及存托凭证时省略。
points[].ps_ratio字符串可选market_cap 除以截至 date 的四个季度营收,保留 2 位小数。market_cap 省略时它也省略;营收没有记录、不大于 0 或币种不是 currency 时同样省略。
points[].pb_ratio字符串可选market_cap 除以 date 当日资产负债表的总权益,保留 2 位小数。market_cap 省略时它也省略;权益没有记录、不大于 0 或币种不是 currency 时同样省略。
points[].dividend_yield字符串可选截至 date 的四个季度每股分红除以 price,以百分比表示(0.71 表示 0.71%),保留 2 位小数。这几个季度没有分红记录、分红币种不是 currency,以及存托凭证时省略。
请求
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/valuation/history"
响应示例
{
  "id": "XNAS:MSFT",
  "currency": "USD",
  "company_id": "usa:0000789019",
  "points": [
    {
      "date": "2026-06-30",
      "price": "497.40",
      "price_date": "2026-06-30",
      "market_cap": "3697000000000",
      "pe_ratio": "39.54",
      "ps_ratio": "13.47",
      "pb_ratio": "12.04",
      "dividend_yield": "0.73"
    }
  ]
}

错误

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

代码状态含义
invalid_query400参数缺失、未知、重复或超出范围。
invalid_id400id 或交易对的写法不符合此 API 的要求。
too_many_ids400批量请求包含的 id 超过 50 个。
invalid_interval400interval 不是 1d 或 1m,或该品种不支持。
range_too_large400时间窗口超过该路由允许的长度。
not_found404没有这个标的、基金或交易对。
not_covered404尚未涵盖该市场、国家或公司。
invalid_cursor400该游标不是本请求返回的,或来自另一个请求。
cursor_expired409游标对应的价格已变化。请不带游标重新开始。
insufficient_credits402您的额度余额低于该请求的费用。
upstream_busy503目前无法获取价格。在批量请求中会列在 errors 中。请稍后重试。
area_unavailable503该区域目前无法响应。
erp_required400请发送 erp,即你的股权风险溢价(百分比)。
insufficient_history422该股票与其基准共有的收益率不足时间窗口的 80%。
risk_free_unavailable422该国家没有收益率曲线。请发送 risk_free。
not_applicable422WACC 对银行或保险公司没有意义。
currency_mismatch422基准或财报与价格的币种不同。
inputs_unavailable422某个输入无法正确计算。详情中指明了它。

此页面对你有帮助吗?