预测 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。详细信息会给出正确路径。