回填完整历史
分页读取全部历史，保存到文件，中断后可继续。
阅读指南 →所有 API
面向上市股票的股票数据接口
获取上市股票的价格和公司事件，市值和估值比率均已包含。每个请求都要使用 Bearer 密钥；REST 和 MCP 共用一个账户余额。
首次请求
获取最新价格
curl --request GET \
--url "https://api.narwhalapi.com/v1/equities/XNAS:MSFT/price" \
--header "Authorization: Bearer $NARWHAL_API_KEY"响应示例
{
"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
}端点
GET按股票代码或名称搜索股票/v1/equities/search
代码或名称以 q 开头（不区分大小写）的上市证券：先匹配完全一致的代码，再匹配其他代码，最后匹配名称。
参数
q必填股票代码或公司名称的开头部分（不区分大小写），至少 2 个字符（例如 ms 或 micro）。排序：完全一致的代码、其他代码、名称开头，然后是名称中后续单词的开头；每一档内美国主要上市证券排在前面。
country可选只返回该国家的标的，三位字母（USA、KOR）。
type可选只返回该类型的标的。
cursor可选上一页的 next_cursor，其他参数须保持一致。
响应字段
results对象数组每页最多 50 条。
next_cursor字符串回传该值即可读取下一页。最后一页为 null。
完整参考文档 →
GET单只股票的简介/v1/equities/{id}
该上市证券（symbol、name、type、exchange、country、currency）、公司所属的板块、行业和网站，以及当该上市证券与我们备案文件中的某家公司匹配时的 company_id。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
响应字段
id字符串规范的标的 id。
symbol字符串该交易所上的股票代码。
mic字符串交易所的四位字母代码。
country字符串标的所属国家，三位字母。
sector字符串板块。日本标的没有简介文本，因此省略。
industry字符串行业。日本标的省略。
website字符串公司网站。日本标的省略。
logo_url字符串我们自己保存的公司标志图。没有时省略。
company_id字符串公司的财报 id，仅在标的能明确匹配到公司时返回。
完整参考文档 →
GET单只股票的最新价格/v1/equities/{id}/price
某个上市证券的最新价格。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
主要响应字段
id字符串所请求股票返回的规范上市记录 id。
symbol字符串该股票在其交易所使用的代码。
currency字符串所有价格字段的币种，便士已换算为英镑。
price字符串股票最新价格，以 currency 币种的十进制字符串形式返回。
previous_close字符串上一交易时段的收盘价，该值未知时省略。
change字符串价格减去 previous_close，只要省略 previous_close 就一并省略。
change_percent字符串相对 previous_close 的涨跌幅百分比；1.5 表示 1.5%。
volume字符串今日成交股数，未知时省略。
market_session取值之一：pre、open、post、closedtimestamp 时刻的交易所状态：pre、open、post 或 closed；只有美国交易所有 pre 和 post。
timestamp日期时间价格有效的时间，UTC 时间，精确到整秒。
完整参考文档 →
GET最多 50 只股票的最新价格/v1/equities/prices
每个列出 id 的最新价格。
参数
ids必填以逗号分隔的标的 id，去重后最多 50 个。每个 id 的规则与单个价格路由相同。每个返回价格的 id 计 1 次调用。
响应字段
prices对象数组按 id 给出每个已解析 id 的价格。
errors对象数组未返回价格的 id。不计费。
完整参考文档 →
GET美股涨跌榜/v1/equities/movers
按涨跌方向排列的美国前 25 只股票和 ETF：gainers、losers 或 active（在当日涨幅和跌幅最大的证券中按成交额最高排序，并非全市场）。
参数
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。
timestamp日期时间列表中最新一条价格的有效时间（UTC）。
完整参考文档 →
GET单只股票的价格 K线/v1/equities/{id}/bars
每日（1d）或一分钟（1m）K 线，按时间从旧到新排列，已针对拆股和分红调整。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
interval可选每session) or 1m (one-minute bars).1d (one bar Anything else is 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/equities/{id}/dividends
某个上市证券的现金股息，按除权除息日从新到旧排列，分页返回。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
cursor可选
响应字段
id字符串规范的标的 id。
start日期不返回：所有账户都能获取完整历史。
dividends对象数组按除息日从新到旧排列。可能包含已公布的未来记录。
next_cursor字符串作为 cursor 传入以获取下一页；最后一页为 null。
完整参考文档 →
GET单只股票的拆股/v1/equities/{id}/splits
某个上市证券的拆股记录，按时间从新到旧排列。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
响应字段
id字符串规范的标的 id。
start日期不返回：所有账户都能获取完整历史。
splits对象数组从新到旧排列。
完整参考文档 →
GET单只股票的财报/v1/equities/{id}/earnings
某个上市证券过去的财报发布记录（在交易所的日期为今天或更早），包含预期值、实际值和意外幅度，按时间从新到旧排列，分页返回。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
cursor可选
响应字段
id字符串规范的标的 id。
start日期不返回：所有账户都能获取完整历史。
earnings对象数组只包含已发布的财报，从新到旧排列。暂不包含即将发布的财报日期。
next_cursor字符串作为 cursor 传入以获取下一页；最后一页为 null。
完整参考文档 →
GET单只股票的市值、P/E、P/S、P/B 和股息率/v1/equities/{id}/valuation
某个美国或韩国上市证券的市值（最新价格乘以流通股数）、市盈率（最新价格除以公司备案文件中的过去 12 个月摊薄每股收益，按报告采用的 GAAP 或 IFRS）、市销率（市值除以过去 12 个月收入）、市净率（市值除以最新资产负债表的总权益）和股息率（过去 12 个月每股股息除以价格，以百分比表示），以及所用的输入数据和对应日期。
参数
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 之后发生拆股、公司有多个股份类别但没有各自的股数，以及存托凭证或外国申报公司的情况下省略。韩国暂无市值：其上市证券目前只显示市盈率。
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 个月摊薄每股收益（按报告采用的 GAAP 或 IFRS）；第四季度为全年数值减去前三个季度。只要能够计算就会显示；对于公司另一股份类别的上市证券则省略。它可能与股票财报中的 eps_actual 不同，后者采用市场数据口径。
完整参考文档 →
GET单只股票的 beta、股权成本、债务成本和 WACC/v1/equities/{id}/cost-of-capital
某只美国或韩国股票相对于基准 ETF 的贝塔（默认为两年的周收益率，使用经拆股和分红调整的价格）、无风险利率（该国政府收益率曲线上的 10 年期点位，或你自行提供的值）、权益成本（无风险利率加贝塔乘以股权风险溢价：由你在 erp 中提供，或默认采用我们发布的该股票所在国的总溢价）、债务成本（利息支出除以公司备案文件中的平均总债务；若无法使用，则为无风险利率加上公开表中按公司利息保障倍数对应的默认利差；分税前和税后，国家公司税率取自公开表，除非你传入 tax_rate）以及 WACC，按市值和总债务加权。
参数
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。
frequency可选收益率区间：weekly（默认；每个 ISO 周最后一个共同交易日）或 monthly。
beta可选用哪个贝塔计算权益成本：raw（默认）或 adjusted（0.67 倍原始值加 0.33）。两者始终都会返回。
risk_free可选你自己的无风险利率，以百分比表示。省略时使用该国国债收益率曲线的 10 年期点位。没有曲线的地区（韩国）必须传入：不传则返回 422 risk_free_unavailable。
tax_rate可选你自己用于债务税盾的税率，以百分比表示。省略时使用 Damodaran 公开表中（PwC 税率）该股票所在国家的企业所得税率。范围为 0 到 60。
period可选利息支出的期间：过去 12 个月（ttm，默认）或最近一个完整财年（annual）。韩国和日本只有年度数据，因此采用 annual。
响应字段
id字符串规范的标的 id。
currency字符串金额字段的币种。
company_id字符串该标的在我们财报库中匹配到的公司。
cost_of_equity字符串无风险利率加 beta 乘以股权风险溢价，以百分比表示（4.25 表示 4.25%）。
cost_of_debt对象没有债务记录的公司省略。
tax_rate对象当表中没有该国税率时省略。传入 tax_rate 即可设置。
wacc字符串加权平均资本成本，以百分比表示（4.25 表示 4.25%）。无负债公司等于 cost_of_equity。存在负债但税率未知时省略。
warnings对象数组使用这些数字之前需要核对的事项。没有时为空。
methodology_url字符串每个数值是如何算出的。
完整参考文档 →
GET单只股票的估值历史/v1/equities/{id}/valuation/history
某个美国或韩国上市证券在每个财务期末（季末或年末）的市值、市盈率、市销率、市净率和股息率，按时间从旧到新排列。
参数
id必填标的 id：交易所的四位字母代码、冒号和股票代码，例如 XNAS:MSFT 或 XNYS:BRK.B。当单独的美股代码（如 MSFT）只对应一个美国标的时也可使用，返回结果带有规范 id。股份类别用点号表示（BRK.B），也接受 BRK-B。
响应字段
id字符串规范的标的 id。
currency字符串所有价格和市值的币种。
company_id字符串该标的在我们财报库中匹配到的公司。
start日期不返回：所有账户都能获取完整历史。
points对象数组公司每个财期期末一个数据点，按时间从早到晚排列。每个数据点由该财期披露的数据和当日价格算出，而不是当时已知的数据：后来的重述也会体现在内。没有价格或没有任何数值的财期没有数据点。
完整参考文档 →
使用场景
相关 API
常见问题
股票 ID 怎么写？
上市记录 id 由四位交易所代码和股票代码组合而成，例如微软为 XNAS:MSFT。唯一的美国裸股票代码同样可用；返回结果会给出规范 id。
费用是多少？
调用按每 1,000 次 $2 的价格，从预付额度 中扣费。每个账户在前 12 个月内，每月都有 $10 的免费额度，并允许商业使用。
价格是实时的还是延迟的？
股票、ETF 和加密货币价格对所有账户都是实时的。批量调用最多接受 50 个 id，每返回一个价格计一次调用。
包含哪些估值数据？
仅限美国的涨跌幅榜、估值历史以及含 beta 的资本成本，所有账户都可使用。估值将美国和韩国上市公司与申报文件匹配；韩国只有市盈率。
该 API 涵盖什么？
搜索和公司简介对所有账户开放。日线和过往财报覆盖全部历史，股息和拆股也遵循同一范围。已包含 1 分钟线。当日成交量未知时会省略。市值以及市盈率、市销率、市净率和股息率均已包含。价格和金额为十进制字符串。
股票 API 是否包含即将发布的财报或日本股价？
财报路由只返回过往业绩；即将发布的财报日期不可用。日本股价不可用；公司简介仅包含名称、交易所、国家、币种和 company_id。财报中的 eps_actual 采用市场数据口径，而 pe_ratio 所依据的每股收益来自公司披露文件。两者可能不同，不应直接比较。
估值历史是如何运作的？
估值历史在每个财年期末给出一个数据点，按季度或按年。每个点使用该日或其之前最近的收盘价，仅按拆股调整，数据为该期间申报的数值。所有账户都可获得完整历史。若更早的数据不存在，start 会给出提供的第一个日期。
资本成本需要什么？
资本成本涵盖在我们的披露文件中已匹配到公司的美国和韩国上市记录，每个返回结果都链接到资本成本方法说明。请在 erp 中传入你的股权风险溢价。银行和保险公司会返回 422 not_applicable，因为利息属于其经营成本。无法算出的输入项会在 422 inputs_unavailable 中指明，而不是进行估算。
价格如何与公司披露文件关联？
一条上市记录可带有 company_id，用于关联披露文件 API 中的公司。使用该 id 可将价格和估值与财务报表联系起来。无法正确计算的比率会被省略，而不会用 0 代替。
从免费密钥开始
12 个月内每月赠送 10 美元免费额度，无需绑卡。每月 10 美元免费额度，无需绑卡。