予測市場の研究には、オッズの時間推移と決済済みの結果が必要です。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 で、マーケットが閉じる 1 分前です。hold の確率は 0.9622 です。result.venues には、各取引所のマーケットが、決済された outcome と value とともに並びます。Kalshi は KXFEDDECISION-26OCT-H0 マーケットを yes で決済し、そのマーケット ID は hold アウトカムの気配に現れます。決済済みイベントには stale フィールドがありません。このフィールドは upcoming、trading、closed のイベントにだけ送られるためです。
オッズ履歴を取得する
履歴エンドポイントは、必須の start と end、任意の interval を受け取ります。スカラー、バイナリ、タイミング、極値の各イベントに対応しています。このリクエストは、景気後退マーケットの日足を取得し、連続する 2 本だけを残しています。
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 もあります。4 つの値がそろった足はリアルタイムで取得したもので、close だけの足は取引所からのバックフィルです。backfill_venue はその取引所を示し、active_from は系列がいつ始まったかを示します。スカラーイベントでは、アウトカムの key ごとに 1 本の系列があります。
最後のオッズを結果と照らし合わせる
スクリプトは決済済みの連邦準備制度イベントを読み、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 と一致します。これでキャリブレーション表の 1 行ができます。市場は決定の直前に、勝ったアウトカムを 0.9622 と値付けしていました。
サンプルを作るには、/v1/predictions/events を status=settled、topic、そして決済時刻に対する from と to の期間でページ送りします。event_id ごとにスクリプトを実行し、締め切り前の最後の確率を決済済みのアウトカムと並べて保存します。数か月にわたる調査には interval=1d、決定前の最後の数日には 1h を使います。
as_of と stale は研究者に何を伝えますか?
as_of は、取引所を最後に確認した時刻です。stale は、オープン中のイベントで取引所の確認が 3 分を超えて途絶えたときに true になります。30 分を超えると、レスポンスは確率を返さず、quotes リストはすべて空になり、すべての取引所が除外されます。そうした時点は調査から外すか、欠測として扱ってください。決済済みと void のイベントには stale フィールドがありません。
結果はいつ確定しますか?
result.final は、すべての取引所の結果が確定した時点で true になります。取引所が判定したものの確定していない結果は、まだ変わることがあります。確定した結果のアウトカムが、異議申し立てや修正のあとで変わったことを Narwhal が見つけた場合、結果に amended_at が付きます。ラベルを固定する前に、final と amended_at を確認してください。
void イベントはどのように見えますか?
void イベントは、イベント一覧で status が void になります。取引所がマーケットを決済または無効にすると、venues のその取引所の項目に、値が settled または void の settlement が付きます。上の連邦準備制度のレスポンスでは、両方の取引所が settled です。status=void で絞り込むと無効になったイベントが見つかります。キャリブレーション用のサンプルでは、決済済みイベントとは分けて扱ってください。
どこまで遡れて、どの刻みで取得できますか?
interval は 1m、5m、1h、1d で、デフォルトは 1h です。1 回のリクエストでカバーできるのは、1m で最大 2 日、5m で 7 日、1h で 92 日、1d で 3,660 日です。1 ページには約 5,000 本の足が入ります。next_cursor が null でなくてもページが空になることがあるため、カーソルを追い続けてください。パラメータの全一覧は予測市場のドキュメントを参照してください。
公開。