预测市场研究需要赔率随时间的变化和已结算的结果。Narwhal 按时间间隔提供二元和标量事件的历史、已结算事件列表，以及每个事件包含 final 和各交易平台结算信息的结果。
列出已结算的事件
events 端点列出预测事件，可按 topic、shape、status、from、to 和 limit 过滤。这个请求获取最近一次已结算的美联储决议。status 的取值有 upcoming、trading、closed、settled 和 void。
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/events?topic=usa-fed&status=settled&limit=1"{
"events": [
{
"event_id": "usa-fed-2026-10",
"question": "Federal Reserve rate decision, 28 October 2026",
"status": "settled",
"closes_at": "2026-10-28T17:59:00Z",
"resolves_at": "2026-10-28T18:00:00Z",
"release_id": "ae2a77cc-3b5b-4541-a060-3bc2ea1145d9",
"result": {
"final": true,
"settled_at": "2026-10-28T20:01:40Z"
},
"topic_id": "usa-fed",
"shape": "scalar"
}
],
"next_cursor": null
}已结算的事件带有 result 摘要。当所有交易平台的结果都已最终确定时,final 为 true,settled_at 是各平台结算时间中最晚的一个。最后一页的 next_cursor 为 null,否则把它作为 cursor 传回即可获取下一页。
读取结果和最后的赔率
用事件 id 可以打开完整的预测。这个响应省略了各交易平台的规则文本，只保留 hold 行和每个平台的获胜市场。
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/scalar/usa-fed-2026-10"{
"event_id": "usa-fed-2026-10",
"topic_id": "usa-fed",
"question": "Federal Reserve rate decision, 28 October 2026",
"status": "settled",
"closes_at": "2026-10-28T17:59:00Z",
"resolves_at": "2026-10-28T18:00:00Z",
"as_of": "2026-10-28T17:58:00Z",
"result": {
"final": true,
"settled_at": "2026-10-28T20:01:40Z",
"venues": [
{
"venue": "kalshi",
"final": true,
"settled_at": "2026-10-28T18:06:30Z",
"markets": [
{
"market_id": "KXFEDDECISION-26OCT-H0",
"outcome": "yes",
"value": "1"
}
]
},
{
"venue": "polymarket",
"final": true,
"settled_at": "2026-10-28T20:01:40Z",
"markets": [
{
"market_id": "2589812",
"outcome": "Yes",
"value": "1"
}
]
}
]
},
"outcomes": [
{
"key": "hold",
"label": "No change",
"lower": "-12.5",
"upper": "12.5",
"probability": "0.9622",
"quotes": [
{
"venue": "kalshi",
"probability": "0.9602",
"market_ids": [
"KXFEDDECISION-26OCT-H0"
]
},
{
"venue": "polymarket",
"probability": "0.9686",
"market_ids": [
"111061902544814266207267295505639408607400625795891618462682726460921782993748"
]
}
]
}
],
"above": []
}as_of 为 2026 年 10 月 28 日 17:58 UTC,即市场关闭前一分钟,hold 的概率为 0.9622。result.venues 列出各交易平台的市场，以及已结算的 outcome 和 value。Kalshi 将 KXFEDDECISION-26OCT-H0 市场结算为 yes,该市场 id 出现在 hold 结果的报价中。已结算的事件没有 stale 字段，因为该字段只会在 upcoming、trading 和 closed 事件上发送。
获取赔率历史
历史端点需要 start 和 end,并可选 interval,适用于标量、二元、时点和极值事件。这个请求读取衰退市场的日线，并保留连续的两根。
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/binary/usa-recession-2026/history?start=2026-10-01T00:00:00Z&end=2026-10-08T00:00:00Z&interval=1d"{
"backfill_venue": "polymarket",
"series": [
{
"key": "yes",
"active_from": "2026-10-01T00:00:00Z",
"bars": [
{
"timestamp": "2026-10-04T00:00:00Z",
"close": "0.0850"
},
{
"timestamp": "2026-10-05T00:00:00Z",
"open": "0.0750",
"high": "0.0750",
"low": "0.0750",
"close": "0.0750"
}
]
}
],
"next_cursor": null
}每根线都有表示起始时间的 timestamp 和 close。10 月 4 日的那根只有 close,而 10 月 5 日的那根还有 open、high 和 low。四个值齐全的线是实时采集的，只有收盘价的线则是来自交易平台的回填数据。backfill_venue 指明该平台,active_from 说明序列从何时开始。标量事件的每个结果 key 对应一条序列。
用结果核对最后的赔率
脚本读取已结算的美联储事件，找出 Kalshi 市场结算为 yes 的结果，再遍历该结果的每日历史。它会一直跟随 next_cursor 直到最后一页，每次都重复相同的 start、end 和 interval。
import json
import os
import urllib.parse
import urllib.request
def get(path):
req = urllib.request.Request(
"https://api.narwhalapi.com" + path,
headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urllib.request.urlopen(req, timeout=30) as r:
return json.load(r)
def history(event_id, start, end, interval="1d"):
bars, cursor = {}, None
while True:
query = {"start": start, "end": end, "interval": interval}
if cursor:
query["cursor"] = cursor
page = get(f"/v1/predictions/scalar/{event_id}/history?" + urllib.parse.urlencode(query))
for series in page["series"]:
bars.setdefault(series["key"], []).extend(series["bars"])
cursor = page["next_cursor"]
if not cursor:
return bars
event = get("/v1/predictions/scalar/usa-fed-2026-10")
print(event["status"], "final:", event["result"]["final"])
# The winning outcome: the Kalshi market that settled to yes.
yes = {m["market_id"] for v in event["result"]["venues"] if v["venue"] == "kalshi"
for m in v["markets"] if m["outcome"] == "yes"}
winner = [o["key"] for o in event["outcomes"] for q in o["quotes"]
if yes & set(q["market_ids"])]
print("winner:", winner)
bars = history("usa-fed-2026-10", "2026-10-21T00:00:00Z", "2026-10-29T00:00:00Z")
for bar in bars[winner[0]]:
print(bar["timestamp"][:10], bar["close"])
它会打印 settled final: True,然后是 winner: ['hold'],再是 hold 结果从 2026 年 10 月 21 日到 10 月 28 日的每日收盘价。数值从 0.8707 升到 0.9622,最后一个收盘价等于事件中 hold 行的 probability。这样就得到校准表中的一行:决议前夕，市场给获胜结果的定价是 0.9622。
要构建样本，可用 status=settled、一个 topic,以及针对结算时间的 from 和 to 窗口，对 /v1/predictions/events 逐页取数。对每个 event_id 运行脚本，把收盘前最后的概率和已结算的结果一起保存。跨越多个月的研究用 interval=1d,决议前最后几天用 1h。
as_of 和 stale 对研究者意味着什么?
as_of 是上次检查各交易平台的时间。对进行中的事件，如果超过 3 分钟没有检查平台,stale 为 true。超过 30 分钟后，响应不再发送概率，每个 quotes 列表都为空，所有平台都被排除。研究中应剔除这些时刻，或标记为缺失。已结算和 void 的事件没有 stale 字段。
结果何时最终确定?
当所有交易平台的结果都最终确定后,result.final 为 true。平台已经裁定但尚未最终确定的结果仍可能变化。如果 Narwhal 发现某个最终结果在争议或修订后发生了变化，该结果会带有 amended_at。冻结标签之前，请检查 final 和 amended_at。
void 事件是什么样的?
void 事件在事件列表中的状态为 void。当某个平台结算或作废了它的市场后,venues 中该平台的条目会带有 settlement,值为 settled 或 void。在上面的美联储响应中，两个平台都显示 settled。用 status=void 过滤可以找到被作废的事件，在校准样本中要把它们与已结算事件分开处理。
最多能回溯多久，步长是多少?
interval 可选 1m、5m、1h 或 1d,默认是 1h。单次请求最多可覆盖:1m 为 2 天,5m 为 7 天,1h 为 92 天,1d 为 3,660 天。一页约有 5,000 根线，而且即使 next_cursor 不为 null,该页也可能是空的，所以要一直跟随游标。完整的参数列表见预测市场文档。
发布于。