股權風險溢酬 API 參考文件

各國的股權風險溢酬與國家風險溢酬

概覽

Narwhal 對股權風險溢酬的估計：投資人持有股票相對於無風險公債所預期的額外報酬。每個請求都需要 Bearer 金鑰，且 REST 與 MCP 共用同一個額度餘額。

國家以其 ISO 3166 alpha-3 代碼表示，例如 USA 或 IDN。合計等於成熟市場溢酬加上國家風險溢酬，而國家風險溢酬等於國家違約利差乘以波動率比。除了比率是一般數字之外，每項數據都是以十進位字串表示的百分比，含四位小數。

每項數據都附有其依據：由市場或官方數據觀測而得、模型估算，或取自方法頁面所引用的公開國家風險表。方法、輸入與限制請見股權風險溢酬計算方法頁面，每個回應都附有連結。

基礎網址： https://api.narwhalapi.com。下列每條路由都是各自獨立的 MCP 工具，參數相同。

每個帳戶都能取得的內容

費用	所有帳戶
一個國家的最新數據	已包含
所有國家的最新數據	已包含
歷史	完整歷史資料

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

A country appears only when we hold a row for it. Without a row the route returns 404 series_not_found; nothing is filled in or carried forward.
成熟市場沒有國家溢酬：對美國而言，違約利差為 0，波動率比為空值，合計等於成熟市場溢酬。作為歐元區基準的德國，其國家溢酬同樣為 0。
數據以美元計價。換算成其他貨幣的折現率，需要再加上兩種貨幣間的通膨差。
歷史資料依日期分頁：傳入一頁的 next_cursor，並搭配相同的其他參數，即可讀取下一頁。
這些數據是供分析的估計值，不構成財務、投資、法律或稅務建議。

端點

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

取得一個國家的股權風險溢酬

GET /v1/economics/{country}/equity-risk-premium

一個國家的最新股權風險溢酬，或 date 當天或之前的最新數據：成熟市場溢酬、國家違約利差、波動率比、國家風險溢酬與合計，並各附其依據。

傳入 date 可讀取該日當天或之前的最新數據。

MCP：工具 economics_get_equity_risk_premium。

參數

參數	位置	必填	類型	含義
`country`	path	是	字串
`date`	query	否	字串

回應欄位

欄位	類型	傳送
`country`	字串	固定回傳
`as_of`	日期	固定回傳
`unit`	always "percent"	固定回傳
`mature_erp`	字串	固定回傳
`country_default_spread`	字串	固定回傳
`volatility_ratio`	字串	固定回傳
`country_risk_premium`	字串	固定回傳
`total_erp`	字串	固定回傳
`basis`	對象	固定回傳
`basis.mature_erp`	下列其一：observed、modelled、table	固定回傳
`basis.country_default_spread`	下列其一：observed、modelled、table	固定回傳
`basis.volatility_ratio`	下列其一：observed、modelled、table	固定回傳
`basis.country_risk_premium`	下列其一：observed、modelled、table	固定回傳
`basis.total_erp`	下列其一：observed、modelled、table	固定回傳
`methodology_url`	always "https://narwhalapi.com/methodology/equity-risk-premium"	選填

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/ITA/equity-risk-premium"

{
  "country": "ITA",
  "as_of": "2026-10-28",
  "unit": "percent",
  "mature_erp": "3.2230",
  "country_default_spread": "0.8881",
  "volatility_ratio": "2.0310",
  "country_risk_premium": "1.8037",
  "total_erp": "5.0267",
  "basis": {
    "mature_erp": "observed",
    "country_default_spread": "observed",
    "volatility_ratio": "modelled",
    "country_risk_premium": "modelled",
    "total_erp": "modelled"
  },
  "methodology_url": "https://narwhalapi.com/methodology/equity-risk-premium"
}

取得股權風險溢酬歷史資料

GET /v1/economics/{country}/equity-risk-premium/history

一個國家依日期排列的股權風險溢酬，由舊到新，以 next_cursor 分頁。

MCP：工具 economics_get_equity_risk_premium_history。

參數

參數	位置	必填	類型	含義
`country`	path	是	字串
`start`	query	否	字串
`end`	query	否	字串
`limit`	query	否	整數
`cursor`	query	否	字串	上一頁的 `next_cursor`，其他參數須與上一頁相同。

回應欄位

欄位	類型	傳送	含義
`country`	字串	固定回傳
`observations`	物件陣列	固定回傳
`observations[].country`	字串	固定回傳
`observations[].as_of`	日期	固定回傳
`observations[].unit`	always "percent"	固定回傳
`observations[].mature_erp`	字串	固定回傳
`observations[].country_default_spread`	字串	固定回傳
`observations[].volatility_ratio`	字串	固定回傳
`observations[].country_risk_premium`	字串	固定回傳
`observations[].total_erp`	字串	固定回傳
`observations[].basis`	對象	固定回傳
`observations[].basis.mature_erp`	下列其一：observed、modelled、table	固定回傳
`observations[].basis.country_default_spread`	下列其一：observed、modelled、table	固定回傳
`observations[].basis.volatility_ratio`	下列其一：observed、modelled、table	固定回傳
`observations[].basis.country_risk_premium`	下列其一：observed、modelled、table	固定回傳
`observations[].basis.total_erp`	下列其一：observed、modelled、table	固定回傳
`observations[].methodology_url`	always "https://narwhalapi.com/methodology/equity-risk-premium"	選填
`next_cursor`	字串	固定回傳	Pass as cursor to read the next page. Always sent; null on the last page.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/ITA/equity-risk-premium/history?start=2026-01-01"

{
  "country": "ITA",
  "observations": [
    {
      "country": "ITA",
      "as_of": "2026-09-01",
      "unit": "percent",
      "mature_erp": "3.2230",
      "country_default_spread": "0.8881",
      "volatility_ratio": "2.0310",
      "country_risk_premium": "1.8037",
      "total_erp": "5.0267",
      "basis": {
        "mature_erp": "observed",
        "country_default_spread": "observed",
        "volatility_ratio": "modelled",
        "country_risk_premium": "modelled",
        "total_erp": "modelled"
      },
      "methodology_url": "https://narwhalapi.com/methodology/equity-risk-premium"
    },
    {
      "country": "ITA",
      "as_of": "2026-10-28",
      "unit": "percent",
      "mature_erp": "3.2230",
      "country_default_spread": "0.8881",
      "volatility_ratio": "2.0310",
      "country_risk_premium": "1.8037",
      "total_erp": "5.0267",
      "basis": {
        "mature_erp": "observed",
        "country_default_spread": "observed",
        "volatility_ratio": "modelled",
        "country_risk_premium": "modelled",
        "total_erp": "modelled"
      },
      "methodology_url": "https://narwhalapi.com/methodology/equity-risk-premium"
    }
  ],
  "next_cursor": null
}

列出所有國家的股權風險溢酬

GET /v1/economics/equity-risk-premium

每個有數據的國家的最新股權風險溢酬，依國家排序。

MCP：工具 economics_list_equity_risk_premium。

參數

此路由不接受任何參數。

回應欄位

欄位	類型	傳送
`countries`	物件陣列	固定回傳
`countries[].country`	字串	固定回傳
`countries[].as_of`	日期	固定回傳
`countries[].unit`	always "percent"	固定回傳
`countries[].mature_erp`	字串	固定回傳
`countries[].country_default_spread`	字串	固定回傳
`countries[].volatility_ratio`	字串	固定回傳
`countries[].country_risk_premium`	字串	固定回傳
`countries[].total_erp`	字串	固定回傳
`countries[].basis`	對象	固定回傳
`countries[].basis.mature_erp`	下列其一：observed、modelled、table	固定回傳
`countries[].basis.country_default_spread`	下列其一：observed、modelled、table	固定回傳
`countries[].basis.volatility_ratio`	下列其一：observed、modelled、table	固定回傳
`countries[].basis.country_risk_premium`	下列其一：observed、modelled、table	固定回傳
`countries[].basis.total_erp`	下列其一：observed、modelled、table	固定回傳
`countries[].methodology_url`	always "https://narwhalapi.com/methodology/equity-risk-premium"	選填

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/equity-risk-premium"

{
  "countries": [
    {
      "country": "DEU",
      "as_of": "2026-10-28",
      "unit": "percent",
      "mature_erp": "3.2230",
      "country_default_spread": "0.0000",
      "volatility_ratio": "2.5462",
      "country_risk_premium": "0.0000",
      "total_erp": "3.2230",
      "basis": {
        "mature_erp": "observed",
        "country_default_spread": "observed",
        "volatility_ratio": "observed",
        "country_risk_premium": "observed",
        "total_erp": "observed"
      },
      "methodology_url": "https://narwhalapi.com/methodology/equity-risk-premium"
    },
    {
      "country": "ITA",
      "as_of": "2026-10-28",
      "unit": "percent",
      "mature_erp": "3.2230",
      "country_default_spread": "0.8881",
      "volatility_ratio": "2.0310",
      "country_risk_premium": "1.8037",
      "total_erp": "5.0267",
      "basis": {
        "mature_erp": "observed",
        "country_default_spread": "observed",
        "volatility_ratio": "modelled",
        "country_risk_premium": "modelled",
        "total_erp": "modelled"
      },
      "methodology_url": "https://narwhalapi.com/methodology/equity-risk-premium"
    }
  ]
}

錯誤

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

代碼	狀態	含義
`invalid_query`	400	參數缺漏、未知、重複，或超出範圍。
`series_not_found`	404	我們沒有這個國家的股權風險溢酬資料。
`invalid_cursor`	400	此游標不是這個請求所回傳的，或來自不同的請求。
`insufficient_credits`	402	您的額度餘額不足以支付此請求的費用。
`economics_unavailable`	503	經濟資料目前無法回應。請稍後再試。

此頁面對你有幫助嗎?