回補完整歷史
分頁讀取全部歷史，儲存到檔案，中斷後可繼續。
閱讀指南 →所有 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 美元免費額度，無需綁卡。