從 Alpha Vantage 遷移到 Narwhal

誰該遷移，誰該留下

團隊轉用 Narwhal 是出於授權和配額方面的原因。Alpha Vantage 將免費金鑰和進階金鑰限於個人非商業用途，除非雙方另有書面約定，而每個 Narwhal 帳戶都包含商業應用程式使用權。Alpha Vantage 免費金鑰每天允許 25 次請求；Narwhal 為每個帳戶在前 12 個月內每月提供 $10 免費額度。Alpha Vantage 的經濟序列僅涵蓋美國，而 Narwhal 可讀取 37 個國家的經濟資料。一個 Narwhal 金鑰也可透過 MCP 使用，適合代理程式專案。

技術指標、選擇權和新聞情緒請繼續使用 Alpha Vantage。它列出了 25 年以上的日線歷史，而 Narwhal 回傳每個數列的完整歷史。Narwhal 的股票涵蓋 42 家交易所，其中不包括東京。

把每個 function 對應到端點

下列每個路徑都在 2026 年 11 月 3 日用有效金鑰呼叫過。Narwhal 的 ID 帶有交易所前綴，例如 XNYS:IBM，所以請先用 /v1/equities/search 查找股票。

Narwhal 中沒有對應功能的部分

這些功能請繼續使用 Alpha Vantage 或其他資料來源。

• 技術指標：SMA、RSI、MACD 等 53 個 function。
• 選擇權，包括即時和歷史資料。
• NEWS_SENTIMENT 和 IPO_CALENDAR。
• 指數涵蓋面：INDEX_DATA 列出 200 多個指數，而 Narwhal 提供價格的有 18 個。

遷移三個呼叫

1. 設定金鑰 取得免費金鑰並存放在 NARWHAL_API_KEY 中。Narwhal 從 Authorization: Bearer 標頭讀取金鑰，因此請從每個 URL 中移除 apikey。
2. 替換 CPI 呼叫 Narwhal 的路徑寫明國家，並回傳最新值。需要歷史資料時，追加帶 start 和 end 的 /observations，回傳的指數值與 Alpha Vantage 列出的相同。
   curl，CPI 遷移前後對照

   # Ran 2026-11-03: Alpha Vantage 200 OK with the demo key, Narwhal 200 OK both calls
   # Before: Alpha Vantage, CPI
   curl "https://www.alphavantage.co/query?function=CPI&interval=monthly&apikey=demo"
   
   # After: Narwhal, latest US CPI
   curl "https://api.narwhalapi.com/v1/economics/USA/cpi" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"
   
   # After: Narwhal, CPI for July to September
   curl -G \
     --url "https://api.narwhalapi.com/v1/economics/USA/cpi/observations" \
     -d start=2026-07 -d end=2026-09 \
     -H "Authorization: Bearer $NARWHAL_API_KEY"

3. 替換報價和外匯呼叫 Narwhal 透過上市 ID 查找股票，透過基礎貨幣查詢匯率，目標貨幣放在 currencies 中。
   curl，報價和外匯遷移前後對照

   # Ran 2026-11-03: Alpha Vantage quote 200 OK (demo key), Narwhal quote and FX 200 OK
   # Before: Alpha Vantage, last price for IBM
   curl "https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=IBM&apikey=demo"
   
   # After: Narwhal, same stock (ids look like XNYS:IBM)
   curl "https://api.narwhalapi.com/v1/equities/XNYS:IBM/price" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"
   
   # Before: Alpha Vantage, USD to JPY (request taken from its documentation, not run)
   curl -G \
     --url "https://www.alphavantage.co/query" \
     -d function=CURRENCY_EXCHANGE_RATE -d from_currency=USD \
     -d to_currency=JPY -d apikey=YOUR_ALPHA_VANTAGE_KEY
   
   # After: Narwhal, USD to JPY
   curl "https://api.narwhalapi.com/v1/fx/rates/USD?currencies=JPY" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"

4. 重寫解析器 欄位不再帶編號，數列變成陣列。該腳本會執行全部三個 Narwhal 呼叫。
   Python，Narwhal 上的三個呼叫

   # Ran 2026-11-03: 200 OK for all three calls
   import os
   import requests
   
   session = requests.Session()
   session.headers["Authorization"] = f"Bearer {os.environ['NARWHAL_API_KEY']}"
   
   
   def get(path, **params):
       r = session.get("https://api.narwhalapi.com" + path, params=params, timeout=10)
       r.raise_for_status()
       return r.json()
   
   
   cpi = get("/v1/economics/USA/cpi")  # was function=CPI
   print(cpi["period"], cpi["value"])
   
   ibm = get("/v1/equities/search", q="IBM", country="USA")["results"][0]["id"]
   print(ibm, get(f"/v1/equities/{ibm}/price")["price"])  # was GLOBAL_QUOTE
   
   fx = get("/v1/fx/rates/USD", currencies="JPY")["rates"][0]  # was CURRENCY_EXCHANGE_RATE
   print(fx["currency"], fx["rate"])

5. 比對輸出 用相同的輸入執行兩個提供方。2026-09 的美國 CPI 在兩邊都是 336.940，11 月 2 日 IBM 的收盤價在兩邊都是 252.51。

回應有何不同

Alpha Vantage 把匯率巢狀放在 Realtime Currency Exchange Rate 之下，並使用帶編號的鍵。Narwhal 回傳 rates 陣列，每種貨幣一個物件。

{
  "name": "Consumer Price Index for all Urban Consumers",
  "interval": "monthly",
  "unit": "index 1982-1984=100",
  "data": [
    { "date": "2026-09-01", "value": "336.940" },
    { "date": "2026-08-01", "value": "334.980" }
  ]
}

{
  "country": "USA",
  "period": "2026-09",
  "value": "336.940",
  "index_base": "1982-84=100",
  "released_on": "2026-10-14"
}

{
  "Global Quote": {
    "01. symbol": "IBM",
    "05. price": "252.5100",
    "07. latest trading day": "2026-11-02",
    "08. previous close": "257.8100",
    "10. change percent": "-2.0558%"
  }
}

{
  "id": "XNYS:IBM",
  "symbol": "IBM",
  "currency": "USD",
  "price": "252.51",
  "previous_close": "257.81",
  "change_percent": "-2.06",
  "market_session": "closed",
  "timestamp": "2026-11-02T21:00:00Z",
  "stale": false
}

因應速率限制

Alpha Vantage 免費金鑰每天允許 25 次請求。其付費方案每分鐘 75 到 1,200 次請求，沒有每日上限，每月 $49.99 起。Narwhal 在免費額度下每分鐘允許 50 次請求，有付費額度後每分鐘 500 次，呼叫費用為每 1,000 次 $2 到 $10。

Alpha Vantage 在 200 回應內部回報問題，所以只檢查狀態碼會漏掉；對於範例之外的呼叫，示範金鑰回傳了 Information 提示。Narwhal 在你傳送過快時回傳 429 rate_limit_exceeded：等待 Retry-After 標頭給出的時間後重試。餘額用完時回傳 402 insufficient_credits：請儲值。兩者都不計費。每個成功回應都帶有 X-RateLimit-Remaining 和 X-RateLimit-Reset。快取請參閱快取回應並處理 429 錯誤。

# 200 OK on both test calls; the 402 and 429 branches follow the documented codes
import os
import time
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NARWHAL_API_KEY']}"


def get(path, **params):
    for attempt in range(4):
        r = session.get("https://api.narwhalapi.com" + path, params=params, timeout=10)
        if r.status_code == 402:
            raise RuntimeError("Out of credit; add credit in the dashboard.")
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", 2)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError(f"Gave up on {path}")

如何查找股票的 ID？

呼叫 /v1/equities/search?q=IBM&country=USA。每筆結果都有一個用於價格和 K 線的 id（如 XNYS:IBM），以及一個用於財務資料的 company_id（如 usa:0000051143）。

其餘部分可以繼續用 Alpha Vantage 嗎？

可以。每個供應商都有各自的金鑰和計費，因此只遷移表中的系列，指標、選擇權和情緒資料保留在原處。其他差異請參閱Narwhal 與 Alpha Vantage 的比較。

遷移檢查清單

• 列出程式碼呼叫的每個 function，並對照表格逐一標記。
• 將股票代碼一次性解析為上市 ID，並儲存這些 ID。
• 將金鑰移到 Bearer 標頭，並從日誌裡的 URL 中移除。
• 重寫解析器，以適配簡潔的名稱、最舊在前的陣列和字串形式的數字。
• 將對 Information 的檢查替換為對狀態碼和 code 的檢查。
• 比較數值之前，先確認 GDP 和聯邦基金利率的定義。
• 依 Retry-After 重試，遇到 insufficient_credits 時停止。
• 切換之前，讓兩個提供方並行執行並比較數值。