예측 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"처럼 소수점 이하 네 자리로 표시됩니다. 시간은 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에 표시되며, 해당 질문에 대해 찾은 각 거래 플랫폼의 시장마다 레코드 하나가 포함됩니다. 역할이 blended이면 해당 시장이 수치 계산에 포함됩니다. 역할이 excluded이면 참고용으로 표시됩니다.

각 quotes 항목에는 venue, role(blended 또는 excluded), probability, market_ids가 포함됩니다.

데이터 최신성과 요금제

각 거래 플랫폼의 데이터를 60초마다 조회합니다. REST는 최신 분의 데이터를 as_of와 함께 반환합니다. at를 사용하여 수집된 임의의 분 단위 데이터를 조회하며, 요금제의 지연 시간이 적용됩니다.

Free 요금제에서는 최신 조회, 과거 데이터의 끝 시점, 정책금리 경로를 포함한 모든 데이터가 15분 지연됩니다. 해당 기준보다 최신인 at를 지정하면 403 plan_upgrade_required가 반환됩니다. Basic과 Pro는 실시간 데이터를 제공합니다.

스트림과 예측 웹훅은 Basic과 Pro에서만 사용할 수 있습니다. 예측 웹훅에 대해서는 웹훅 API 레퍼런스를 참고하세요.

스트림

POST /v1/predictions/stream-ticket를 전송하여 유효기간이 짧은 티켓을 받습니다. /v1/predictions/stream에 연결한 다음 구독을 전송합니다:

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

연결 하나당 최대 200개의 이벤트를 지원합니다. 재연결 시 리플레이 없이 최신 스냅샷이 제공됩니다.

오류

오류는 NarwhalProblem을 사용하며, 400 invalid_query, 403 plan_upgrade_required, 404 event_not_found 중 하나입니다.

잘못된 유형으로 이벤트를 요청하면 404 event_not_found가 반환됩니다. 상세 정보에 올바른 경로가 표시됩니다.