發起你的第一個 Narwhal API 請求

通過REST或MCP使用一個密鑰存取經濟數據、FX、股票、SEC申報、棕櫚油價格和日曆。

本指南從 CPI 開始，然後在以下位置連結到六個 API 各自可用的參考文件 api.narwhalapi.com.

經濟數據覆蓋範圍

AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP 和 USA 均已上線。每次數據請求都需要 Narwhal API 密鑰。

免費測試版限制： 3,000 每個 UTC 月的成功請求數，加上 30 每分鐘請求數，突發容量為 5。REST 和 MCP 共用相同限額。

設置你的 API 密鑰

在其中將密鑰作為 Bearer 令牌發送 Authorization 標頭——絕不放在 URL 中。創建帳戶以獲取免費密鑰，然後閱讀身份驗證指南，再儲存密鑰。

終端

export NARWHAL_API_KEY="nw_live_..."

請求官方 CPI

在路徑中傳入 ISO 三字母國家代碼。省略 period 返回最新的完整已接受發布版本。

請求

curl --request GET \
  --url https://api.narwhalapi.com/v1/economics/USA/cpi \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

回應範例

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "base_period": "1982-84",
  "base_value": "100",
  "released_on": "2026-08-12"
}

Python 和 JavaScript 示例

在應用中使用相同的環境變量和端點。這些示例使用內置庫。

Python 3

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.narwhalapi.com/v1/economics/USA/cpi",
    headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data)

JavaScript · Node.js 18+

const key = process.env.NARWHAL_API_KEY;
if (!key) throw new Error("Set NARWHAL_API_KEY first");
const response = await fetch(
  "https://api.narwhalapi.com/v1/economics/USA/cpi",
  { headers: { Authorization: "Bearer " + key }, signal: AbortSignal.timeout(30000) }
);
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);

選擇你的 API

API	開始帶有
經濟數據 API	十個國家官方發布機構提供的 CPI、通脹、勞動力、GDP 和貿易數據。
FX API	當前匯率、轉換和分頁歷史記錄，每個匯率都帶有時間戳記。
股票 API	發現普通股工具並獲取經拆股調整的日線數據。
公開假日日曆 API	已發布的官方數據和文件說明來源、範圍、期間與限制。
棕櫚油鮮果串（FFB）API	按地區和樹齡提供的印度尼西亞官方 FFB 排程。
SEC 申報文件 API	公司搜尋、身份和 SEC 申報元數據。

選擇國家和指標

每個已上線國家都提供九個最新發布操作和九個對應的歷史操作。 Economics API 參考列出每條路徑和回應結構。

指標	路徑後綴
CPI	`/cpi`
通脹	`/inflation`
失業率	`/unemployment`
勞動力參與率	`/labour-force-participation`
GDP 與增長率	`/gdp` · `/gdp-growth`
貿易、出口、進口	`/trade` · `/trade/exports` · `/trade/imports`

通過 MCP 連接

使用 MCP 客戶端時沿用同一個密鑰和架構。工具發現會列出你帳戶在全部六個 API 中可用的操作。請參見該 MCP 指南.

與客戶端無關的欄位映射

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

通過 MCP 客戶端的安全密鑰設置替換佔位符。普通 JSON 不會自行展開環境變量。

首次 tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

初始化與 tools/list 不會消耗額度。每次成功的 tools/call 消耗一次請求。

閱讀回應

讀取每項操作的回應架構。Economics 返回領域對象；Equities 使用 meta/values 適用於時間序列和 count/data 適用於金融工具。

規則	這意味著什麼
`period`	官方發布版本所返回的確切月份、季度或年份。
`released_on`	官方發布日期。
十進位字串	數值表示可避免二進位浮點數帶來的意外誤差。
缺失數據	不完整或不可用的發布會安全失敗；缺失值絕不會變成零。

讀取 Narwhal 如何儲存和更新官方發布版本.

成功回應中的配額標頭

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

按狀態和錯誤代碼處理錯誤

先檢查 HTTP 狀態，然後使用 code 在應用邏輯中。 detail 用於日誌和調試。該錯誤和配額指南列出所有公開狀態。

RFC 9457 問題回應

{
  "ok": false,
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "The request parameters are not valid for this operation.",
  "code": "invalid_query",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50",
  "instance": "/v1/economics/USA/cpi"
}

需要密鑰幫助嗎？聯繫 Narwhal API.

查看其中的新內容更新日誌。

LLM？讀取llms.txt.