預測 API 參考

依主題與事件讀取預測機率，包含歷史資料、交易平台詳情與串流更新。

Narwhal 僅回傳機率，不提供官方數據或自有價格。概覽請參閱預測產品頁面。

端點

基礎 URL 為 https://api.narwhalapi.com。傳送 Authorization: Bearer $NARWHAL_API_KEY。每個 MCP 工具名稱都與其操作 ID 一致。

操作 ID	方法與路徑
`predictions_list_topics`	`GET /v1/predictions/topics`
`predictions_get_topic`	`GET /v1/predictions/topics/{topic_id}`
`predictions_list_events`	`GET /v1/predictions/events`
`predictions_get_scalar`	`GET /v1/predictions/scalar/{event_id}`
`predictions_get_extreme`	`GET /v1/predictions/extreme/{event_id}`
`predictions_get_timing`	`GET /v1/predictions/timing/{event_id}`
`predictions_get_binary`	`GET /v1/predictions/binary/{event_id}`
`predictions_get_scalar_history`	`GET /v1/predictions/scalar/{event_id}/history`
`predictions_get_extreme_history`	`GET /v1/predictions/extreme/{event_id}/history`
`predictions_get_timing_history`	`GET /v1/predictions/timing/{event_id}/history`
`predictions_get_binary_history`	`GET /v1/predictions/binary/{event_id}/history`
`predictions_get_policy_path`	`GET /v1/predictions/policy-paths/{authority}`
`predictions_get_policy_path_history`	`GET /v1/predictions/policy-paths/{authority}/history`
`predictions_stream_ticket_create`	`POST /v1/predictions/stream-ticket`
WebSocket	`/v1/predictions/stream`

請求範例

curl --request GET \
  --url "https://api.narwhalapi.com/v1/predictions/scalar/usa-cpi-yoy-2026-09" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

小數以字串表示。機率使用四位小數，例如 "0.8250"。時間使用 UTC，並帶有 Z。

主題與事件

先列出主題，再透過 topic_id 請求某個主題，讀取該主題及其事件。主題 ID 包括 usa-cpi-yoy、usa-fed 和 xau-monthly-extreme。

參數	規則
`group`	主題清單中的可選值：`central_banks`、`us_prices`、`us_jobs`、`us_activity`、`global_activity`、`global_prices`、`metals` 或 `energy`。
`topic`, `shape`, `status`, `release_id`	事件清單的選用篩選條件。
`from`, `to`	事件清單的選用 UTC 時間篩選條件。
`limit`, `cursor`	事件清單中的可選參數。`limit` 的取值範圍為1–100，預設值為50。

主題欄位

主題包含 topic_id、group、title、shape、unit、venues、resolution_kind、calendar 和 next_event_id。

venues 列出交易平台 ID，例如 ["kalshi","polymarket"]。 resolution_kind 為 release、price_fix、price_window 或 occurrence。 calendar 包含 country、family 和 variant，或為 null。

事件欄位

所有事件類型都使用這些欄位。 body 取決於類型。

欄位	內容
`event_id`, `topic_id`, `shape`, `question`	事件 ID、主題 ID、市場類型和問題。
`status`	`upcoming`、`trading`、`closed`、`settled` 或 `void`。
`closes_at`, `resolves_at`, `as_of`	交易關閉、結果確定和資料擷取時間。
`release_id`	公開日曆的發布 ID 或 `null`。
`resolution`	`description` 和 `resolves_with`，後者是 Narwhal API 路徑，例如 `/v1/economics/USA/cpi`。
`unit`, `venues`	事件單位和下文所述的交易平台市場紀錄。
`quality`	`monotone_repairs`、`rows_merged` 和 `freshness`（值為 `live`、`stale` 或 `no_live_quotes`）。
`body`	純量、極值、時間或二元類型的回應主體。

依市場類型區分的機率

透過事件所屬形態的路徑請求。純量、極值、時間和二元請求可使用選填的 at，指定過去以 UTC 記錄的某一分鐘。

以下回應本文僅供示例，數值均為虛構。

純量

scale 與 outcomes 一同傳回。每個結果都包含 key、label、lower、upper、probability 和 quotes。summary 包含 median、p10、p90、設為 bucket_upper 的 method，以及 bounds。

純量回應主體範例

{
  "scale": 1,
  "outcomes": [
    {"key": "le_3.0", "label": "3.0% or lower", "lower": null, "upper": "3.0",
     "probability": "0.8250", "quotes": [
       {"venue": "kalshi", "role": "blended", "probability": "0.8250",
        "market_ids": ["KXCPIYOY-26SEP-T3.0"]}
     ]},
    {"key": "3.0_3.2", "label": "Above 3.0% through 3.2%", "lower": "3.0", "upper": "3.2",
     "probability": "0.1500", "quotes": []},
    {"key": "gt_3.2", "label": "Above 3.2%", "lower": "3.2", "upper": null,
     "probability": "0.0250", "quotes": []}
  ],
  "summary": {"median": "3.0", "p10": "3.0", "p90": "3.2", "method": "bucket_upper", "bounds": {}}
}

極值

價格區間包含 start 和 end。最高價和最低價的機率分別顯示於 up 和 down 資料列，這些資料列包含 key、level、probability 和 quotes。observation 為 any_trade、close 或 any_release（區間內發布的任一官方數值）。

極值回應主體範例

{
  "window": {"start": "2026-10-01T00:00:00Z", "end": "2026-11-01T00:00:00Z"},
  "observation": "any_trade",
  "up": [{"key": "up:4200", "level": "4200", "probability": "0.3500", "quotes": []}],
  "down": [{"key": "down:3600", "level": "3600", "probability": "0.2000", "quotes": []}]
}

時間

每個步驟給出事件截至 by 已發生的機率。步驟包含 key、by、kind（決策會議為 meeting，當日結束時為 date）、label、probability 和 quotes。回應本文還包含 not_within_window。

時間類型回應主體範例

{
  "steps": [
    {"key": "2026-10-28", "by": "2026-10-28T18:00:00Z", "kind": "meeting", "label": "28 Oct 2026 meeting",
     "probability": "0.6000", "quotes": []}
  ],
  "not_within_window": "0.4000"
}

二元

回應主體包含帶有 yes 和 no 的 labels，以及 deadline、probability 和 quotes。

二元回應主體範例

{
  "labels": {"yes": "Yes", "no": "No"},
  "deadline": "2026-12-31T23:59:00Z",
  "probability": "0.8250",
  "quotes": []
}

政策利率路徑

請求時將 authority 設為 federal-reserve、european-central-bank、bank-of-england、bank-of-japan、bank-of-canada、reserve-bank-of-australia 或 bank-indonesia。

回應包含 authority、設為 bps 的 unit、as_of、method 和 meetings。僅傳回利率變動，不傳回目前利率。

政策利率路徑回應範例

{
  "authority": "federal-reserve",
  "unit": "bps",
  "as_of": "2026-10-08T12:00:00Z",
  "method": "Probability-weighted decision rows; cut 50+ and hike 50+ count as 50 bps; meetings add up.",
  "meetings": [
    {"event_id": "usa-fed-2026-10-28", "resolves_at": "2026-10-28T18:00:00Z",
     "p_cut": "0.6000", "p_hold": "0.4000", "p_hike": "0.0000",
     "expected_change_bps": "-15.00", "cumulative_change_bps": "-15.00"}
  ]
}

歷史

純量、極值、時間和二元類型的事件使用 /v1/predictions/{shape}/{event_id}/history。

參數	規則
`interval`	`1m`、`5m`、`1h`（預設）或 `1d`。
`start`, `end`	UTC 時間。時間視窗上限為：`1m` 最多 2 天，`5m` 最多 7 天，`1h` 最多 92 天，`1d` 最多 3,660 天。

回應包含 event_id、interval 和 series。每個序列包含 key、active_from、active_to 和 bars。每個柱包含 start、end、open、high、low 和 close。它們記錄每個時間間隔的收盤機率。

歷史回應範例，僅顯示一個序列

{
  "event_id": "usa-cpi-yoy-2026-09",
  "interval": "1h",
  "series": [
    {"key": "le_3.0", "active_from": "2026-10-01T00:00:00Z", "active_to": null,
     "bars": [
       {"start": "2026-10-08T11:00:00Z", "end": "2026-10-08T12:00:00Z",
        "open": "0.8000", "high": "0.8400", "low": "0.7900", "close": "0.8250"}
     ]}
  ]
}

政策利率路徑歷史可透過 /v1/predictions/policy-paths/{authority}/history 取得。

交易平台與資料整合

Kalshi 和 Polymarket 的市場列在 venues 中，每個針對該問題找到的交易平台市場對應一筆紀錄。 blended 角色表示該市場已計入數值。 excluded 角色表示該市場僅供參考。

每個 quotes 項目包含 venue、role（blended 或 excluded）、probability 和 market_ids。

交易平台欄位	內容
`venue`, `role`, `venue_event_id`	交易平台 ID、整合角色和交易平台事件 ID。
`url`, `rules_url`, `rules_text`, `settlement_source`	市場連結、規則連結及文字，以及結算來源。
`weight`, `depth_usd`, `volume_24h_usd`, `open_interest_usd`, `fetched_at`	權重、深度、成交量、未平倉合約量和擷取時間。
`match`	`differences` 和 `note`。
`excluded_reason`	對於目前分鐘：`stale`（3 分鐘內沒有報價）、`thin`（深度低於該主題的最低要求），或下列差異值之一。
`settlement`	僅包含 `status`：`pending`、`settled`、`void` 或 `disputed`。不包含獲勝結果。

差異	處理方式
`outcome_set`	各列無法一一對應。使用共有列進行整合；若剩餘不足 3 列，則排除。
`timing`	結果確定時間不同；予以排除。
`source`	依據不同來源結算；予以排除。
`rules`	使用不同條件；予以排除。

資料時效與方案

每 60 秒讀取一次各交易平台的資料。 REST 回傳最新一分鐘的資料，並附帶 as_of。使用 at 讀取已擷取的任意一分鐘的資料，但須遵守方案延遲限制。

免費方案的所有資料均延遲 15 分鐘，包括最新檢視、歷史資料末端和政策利率路徑。若 at 晚於該截止時間，則回傳 403 plan_upgrade_required。 Basic 和 Pro 提供即時資料。

串流和預測 Webhook 僅適用於 Basic 和 Pro。預測 Webhook 請參閱 Webhook API 參考。

串流

傳送 POST /v1/predictions/stream-ticket 以取得短期有效的票證。連線至 /v1/predictions/stream，然後傳送訂閱：

訂閱訊息

{"action":"subscribe","topics":["usa-fed"],"event_ids":[]}

訊息	內容或頻率
`subscribed`	符合條件的事件 ID。
`snapshot`	完整事件。
`update`	變更時的完整事件，每個事件每分鐘最多一次。
`status`	狀態訊息。
`heartbeat`	每 30 秒一次。

一個連線最多支援 200 個事件。重新連線會提供最新快照，不進行重播。

錯誤

錯誤使用 NarwhalProblem：400 invalid_query、403 plan_upgrade_required 或 404 event_not_found。

使用錯誤的類型請求事件會回傳 404 event_not_found。詳細資訊會提供正確路徑。