Predictions API reference

Endpoints

The base URL is https://api.narwhalapi.com. Send Authorization: Bearer $NARWHAL_API_KEY. Each MCP tool name matches its operation id.

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

Decimals are strings. Probabilities use four decimal places, such as "0.8250". Times are UTC with Z.

Topics and events

List topics, then request a topic by topic_id to read the topic and its events. Topic ids include usa-cpi-yoy, usa-fed, and xau-monthly-extreme.

Topic fields

A topic has topic_id, group, title, shape, unit, venues, resolution_kind, calendar, and next_event_id.

venues lists venue ids such as ["kalshi","polymarket"]. resolution_kind is release, price_fix, price_window, or occurrence. calendar contains country, family, and variant, or is null.

Event fields

Every event shape uses these fields. The body depends on the shape.

Odds by market shape

Request the event through its shape path. Scalar, extreme, timing, and binary requests accept an optional at for a past captured minute in UTC.

The following bodies are illustrative. Values are made up.

Scalar

scale accompanies outcomes. Each outcome has key, label, lower, upper, probability, and quotes. The summary contains median, p10, p90, method set to bucket_upper, and 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": {}}
}

Extreme

A price window has start and end. Its high and low probabilities appear in up and down rows with key, level, probability, and quotes. observation is any_trade, close, or any_release (any official figure published in the window).

{
  "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": []}]
}

Timing

Each step gives the chance that something has happened by by. Steps have key, by, kind (meeting for a decision meeting, date for the end of that day), label, probability, and quotes. The body also includes 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"
}

Binary

The body contains labels with yes and no, a deadline, probability, and quotes.

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

Policy path

Request authority as federal-reserve, european-central-bank, bank-of-england, bank-of-japan, bank-of-canada, reserve-bank-of-australia, or bank-indonesia.

The response contains authority, unit set to bps, as_of, method, and meetings. It returns changes only, never the current rate.

{
  "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"}
  ]
}

History

Use /v1/predictions/{shape}/{event_id}/history for scalar, extreme, timing, and binary events.

The response contains event_id, interval, and series. Each series has key, active_from, active_to, and bars. Bars contain start, end, open, high, low, and close. They record closing probabilities per interval.

{
  "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"}
     ]}
  ]
}

Policy path history is available at /v1/predictions/policy-paths/{authority}/history.

Venues and blending

Kalshi and Polymarket venue markets appear in venues, one record per venue market found for the question. A blended role means the market is in the numbers. An excluded role means it is shown for reference.

Each quotes entry contains venue, role (blended or excluded), probability, and market_ids.

Freshness and plans

Every venue is read every 60 seconds. REST returns the latest minute with as_of. Use at to read any captured minute, subject to the plan delay.

Free sees everything 15 minutes delayed, including latest views, history ends, and policy paths. An at newer than that cutoff returns 403 plan_upgrade_required. Basic and Pro are live.

The stream and prediction webhooks are available on Basic and Pro only. See the Webhooks API reference for prediction webhooks.

Stream

Send POST /v1/predictions/stream-ticket to get a short-lived ticket. Connect to /v1/predictions/stream, then send a subscription:

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

A connection supports up to 200 events. Reconnecting gives fresh snapshots with no replay.

Errors

Errors use NarwhalProblem: 400 invalid_query, 403 plan_upgrade_required, or 404 event_not_found.

Requesting an event under the wrong shape returns 404 event_not_found. The detail gives the right path.