予測APIリファレンス

エンドポイント

ベースURLは https://api.narwhalapi.com です。 Authorization: Bearer $NARWHAL_API_KEY を送信してください。 各MCPツールの名前は、その操作IDと一致します。

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

小数は文字列です。 確率は "0.8250" のように小数点以下4桁で表します。 時刻は Z 付きのUTCです。

トピックとイベント

トピックの一覧を取得し、次に topic_id でトピックをリクエストすると、そのトピックとイベントを取得できます。 トピックIDには usa-cpi-yoy、usa-fed、xau-monthly-extreme などがあります。

トピックのフィールド

トピックには topic_id、group、title、shape、unit、venues、resolution_kind、calendar、next_event_id が含まれます。

venues は ["kalshi","polymarket"] のような取引プラットフォームIDの一覧です。 resolution_kind は release、price_fix、price_window、occurrence のいずれかです。 calendar には country、family、variant が含まれるか、null が設定されます。

イベントのフィールド

すべてのイベント形式でこれらのフィールドを使用します。 body は形式によって異なります。

市場形式別の確率

イベントは対応する形状別のパスからリクエストしてください。スカラー、極値、タイミング、二値のリクエストでは、過去に取得されたUTCの分を指定する任意のatを使用できます。

以下のレスポンス本文は説明用です。値は架空のものです。

スカラー

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があります。高値・安値の確率は、key、level、probability、quotesを含むupとdownの行に表示されます。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 を使用します。

レスポンスには 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 に表示され、その質問に対応する市場が見つかるごとに、取引プラットフォームの市場単位で1件のレコードが含まれます。 役割が blended の場合、その市場は数値の計算に含まれます。 役割が excluded の場合、その市場は参考として表示されます。

quotes の各エントリには venue、role（blended または excluded）、probability、market_ids が含まれます。

データの鮮度とプラン

各取引プラットフォームから60秒ごとにデータを取得します。 RESTは最新の分のデータを as_of とともに返します。 at を使用すると、プランの遅延に従って、取得済みの任意の分のデータを読み取れます。

Freeプランでは、最新表示、履歴の末尾、政策金利の経路を含むすべてのデータに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":[]}

1つの接続で最大200件のイベントに対応します。 再接続すると最新のスナップショットが提供され、リプレイは行われません。

エラー

エラーは NarwhalProblem を使用し、400 invalid_query、403 plan_upgrade_required、404 event_not_found のいずれかです。

誤った形式でイベントをリクエストすると、404 event_not_found が返されます。 詳細に正しいパスが示されます。