回補完整歷史
分頁讀取全部歷史，儲存到檔案，中斷後可繼續。
閱讀指南 →所有 API
上市股票 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}
掛牌證券（代號、名稱、類型、交易所、國家、幣別）、該公司的產業類別、細分產業與網站，以及當該證券對應到我們財報資料中的公司時的 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字串price 減 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 計為一次呼叫。
回應欄位
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 股且成交金額至少 $1 million 的普通股與 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
單一美國或韓國掛牌證券的市值（最新價格乘以流通在外股數）、本益比 P/E（最新價格除以公司財報中近 12 個月稀釋後 EPS，依公司公布採 GAAP 或 IFRS）、股價營收比 P/S（市值除以近 12 個月營收）、股價淨值比 P/B（市值除以最新資產負債表的權益總額）與殖利率（近 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 之後發生分割、公司有多個股別但未提供各股別股數，或為存託憑證或外國申報公司，則省略。韓國目前尚無市值：其掛牌證券暫時只顯示 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 不同，後者採市場資料基準。
完整參考文件 →
GET單一股票的 Beta、股權成本、債務成本與 WACC/v1/equities/{id}/cost-of-capital
單一美國或韓國股票相對於基準 ETF 的 Beta（預設為兩年的週報酬率，使用已依分割與配息調整的價格）、無風險利率（該國政府殖利率曲線的 10 年期點位，或由您提供）、股權成本（無風險利率加上 Beta 乘以股權風險溢酬：可用 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選填以哪一種 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
單一美國或韓國掛牌證券在每個會計期間結束日（季末或年末）的市值、P/E、P/S、P/B 與殖利率，由舊到新排列。
參數
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 包含即將公布的財報或日本股價嗎？
財報路由只回傳過去的結果；無法取得即將公布的財報日期。日本股價無法取得；公司概況只包含 name、exchange、country、currency 與 company_id。財報的 eps_actual 採用市場資料基準，而 pe_ratio 背後的 EPS 來自公司申報文件。兩者可能不同，不應直接比較。
估值歷史資料如何運作？
估值歷史在每個財年期末給出一個資料點，按季度或按年。每個點使用該日或其之前最近的收盤價，僅按拆股調整，資料為該期間申報的數值。所有帳戶都可取得完整歷史。若更早的資料不存在，start 會給出提供的第一個日期。
資金成本需要什麼？
資金成本涵蓋已對應到我們申報文件中公司的美國與韓國上市股票，且每個回應都連結到資金成本方法說明。請在 erp 中傳入你的股權風險溢酬。銀行與保險公司會回傳 422 not_applicable，因為利息是其營業成本。無法算出的輸入值會在 422 inputs_unavailable 中指明，而不是用估計值代替。
價格如何與公司申報文件連結？
股票清單可帶有 company_id，可對應到申報文件 API 中的公司。用這個 id 將價格與估值和財務報表串連起來。無法正確計算的比率會省略，不會以 0 代替。
從免費金鑰開始
12 個月內每月贈送 10 美元免費額度，無需綁卡。每月 10 美元免費額度，無需綁卡。