ETF API 參考文件：ETF 與共同基金

ETF 與共同基金的價格、NAV、歷史資料與配息

概覽

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 欄位會告訴你取得的是哪一種。

基礎網址： https://api.narwhalapi.com。 MCP 工具是 funds, with one action ，適用於下列每個路由。

每個帳戶都能取得的內容

費用	所有帳戶
ETF 最新價格	在線
共同基金 NAV	最新 NAV
日 K 線與歷史配息	完整歷史資料
一分鐘 K 線（僅限 ETF）	已包含
搜尋與公司簡介	已包含

查看定價說明每次呼叫的費用。除非路由另有說明，請求依其所屬 API 的價格計費。

共同基金 NAV 是收盤後的數值，不會延遲。超過下一個營業日仍未更新時，即視為過時。
共同基金沒有一分鐘 K 線。請求時會回傳 400 invalid_interval。
共同基金的日 K 線就是其 NAV：開、高、低、收是同一個數字，也沒有成交量。
配息的 kind 欄位在資料來源提供之前會省略。

端點

每個路由都是 GET 請求，並需要將你的金鑰放在以下請求標頭中： Authorization: Bearer 標頭。範例僅展示回應的結構，並非即時資料。

依代號或名稱搜尋 ETF 與共同基金

GET /v1/funds/search

代號或名稱以 q 開頭的基金，不分大小寫：完全相符的代號排最前，其次是其他代號，再來是名稱。可選用 type（etf 或 mutual_fund）與 country（三碼）篩選。每頁最多 50 筆，並附 next_cursor。資料來自我們自己的代號清單，所有帳號皆可使用，計為一次呼叫。

MCP：工具 funds, action search。

參數

參數	位置	必填	類型	含義
`q`	query	是	字串	代號或基金名稱的開頭，不分大小寫，至少 2 個字元（例如 `vf` 或 `vanguard 500`）。排序：完全相符的代號、其他代號、名稱開頭，最後是名稱中後續單字的開頭。
`country`	query	否	字串	僅限此國家的基金，三碼（USA）。
`type`	query	否	etf、mutual_fund 擇一	僅 ETF 或僅共同基金。
`cursor`	query	否	字串	上一頁的 `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`	path	是	字串	基金 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；或共同基金的最新 NAV（type: mutual_fund：nav、previous_nav、change、change_percent 與 NAV 的 date；為收盤後數值，不會延遲，超過下一個營業日即為 stale）。change_percent 以百分比表示。使用股票 id 會回傳 404 not_found。

MCP：工具 funds, action price。

參數

參數	位置	必填	類型	含義
`id`	path	是	字串	基金 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`	字串	選填	前一日的 NAV。未知時省略。
`date`	日期	選填	NAV 所屬的日期（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 的最新成交價，或共同基金的最新 NAV。每個回傳價格的 id 計為一次呼叫，並一次性扣款：若餘額不足以支付已解析的 id，整個請求會以 402 insufficient_credits 拒絕。未回傳價格的 id 會列在 errors，不收費。change_percent 以百分比表示。

最多可傳送 50 個 id，ETF 與共同基金可混用。批次一次性扣款：若餘額不足以支付可解析的 id，整個請求會回傳 402 insufficient_credits。

MCP：工具 funds, action prices。

參數

參數	位置	必填	類型	含義
`ids`	query	是	字串	以逗號分隔的基金 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`	字串	選填	前一日的 NAV。未知時省略。
`prices[].date`	日期	選填	NAV 所屬的日期（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 線就是其每日 NAV（開、高、低、收皆為 NAV，無成交量）；它沒有一分鐘 K 線（400 invalid_interval）。一分鐘 K 線僅限 ETF。歷史資料：全部，所有帳號皆可取得。每頁最多 5,000 根 K 線，並附 next_cursor；游標與價格不再相符時會回傳 409 cursor_expired。每頁計為一次呼叫。

若兩頁之間因股票分割或配息而使歷史資料變動，游標會失效並回傳 409 cursor_expired。

MCP：工具 funds, action bars。

參數

參數	位置	必填	類型	含義
`id`	path	是	字串	基金 id。ETF 為其標的 id：交易所的四碼代碼、冒號與代號（ARCX:SPY）。共同基金為 FUND、冒號與代號（FUND:VFIAX）。若單獨的美股代號（如 SPY）只對應一個美國標的，也可直接使用；回應會附上標準 id。
`interval`	query	否	下列其一：1d、1m	`1d`（每個交易日一根 K 線；共同基金的 K 線為其每日 NAV）或 `1m`（一分鐘 K 線，僅限 ETF）。其他值會回傳 400 invalid_interval。
`start`	query	否	字串	第一根 K 線。`1d`：日期（YYYY-MM-DD），含該日；省略時為最舊的一根。`1m`：UTC 時間（YYYY-MM-DDTHH:MM:SSZ，或以日期代表 UTC 00:00），含該時間；省略時為 `end` 的前一天。
`end`	query	否	字串	最後一根 K 線。`1d`：日期，含該日；省略時為已有 K 線的最新交易日。`1m`：UTC 時間，不含該時間；省略時為現在，或 `start` 之後五天。`1m` 的 `start` 與 `end` 相隔最多 5 天（400 range_too_large）。
`cursor`	query	否	字串	上一頁的 `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`	path	是	字串	基金 id。ETF 為其標的 id：交易所的四碼代碼、冒號與代號（ARCX:SPY）。共同基金為 FUND、冒號與代號（FUND:VFIAX）。若單獨的美股代號（如 SPY）只對應一個美國標的，也可直接使用；回應會附上標準 id。
`cursor`	query	否	字串	上一頁的 `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
}

錯誤

錯誤使用共用的問題格式，並包含 request_id。查看 API 錯誤處理：錯誤碼、額度與重試了解格式與額度標頭。失敗的請求不計費。

代碼	狀態	含義
`invalid_query`	400	參數缺漏、未知、重複，或超出範圍。
`invalid_id`	400	id 或交易對的寫法不符合此 API 的要求。
`too_many_ids`	400	批次包含超過 50 個 id。
`invalid_interval`	400	間隔不是 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	此區域目前無法回應。

此頁面對你有幫助嗎?