거시경제 확률 대시보드에는 토픽 목록과 타일마다 한 번의 이벤트 읽기가 필요합니다. Narwhal은 CPI, 고용, 실업률, 경기 침체, 중앙은행 결정에 대한 시장 확률을 scalar, binary, timing, extreme이라는 이름의 네 가지 형태로 제공합니다.
대시보드에 쓸 토픽 목록 가져오기
대시보드의 각 타일은 토픽 하나입니다. 토픽 엔드포인트가 이를 나열하며 선택 사항인 group을 받습니다. 거시경제 그룹은 central_banks, us_prices, us_jobs, us_activity, global_activity, global_prices입니다. 이 요청은 us_jobs를 지정하고 처음 두 토픽만 남깁니다.
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/topics?group=us_jobs"{
"topics": [
{
"topic_id": "usa-payrolls",
"group": "us_jobs",
"title": "US nonfarm payrolls change",
"shape": "scalar",
"unit": "jobs",
"unit_key": "job",
"venues": [
"kalshi"
],
"resolution_kind": "release",
"calendar": {
"country": "USA",
"family": "labour"
},
"next_event_id": "usa-payrolls-2026-10"
},
{
"topic_id": "usa-unemployment",
"group": "us_jobs",
"title": "US unemployment rate",
"shape": "scalar",
"unit": "percent",
"unit_key": "percent",
"venues": [
"kalshi",
"polymarket"
],
"resolution_kind": "release",
"calendar": {
"country": "USA",
"family": "labour"
},
"next_event_id": "usa-unemployment-2026-10"
}
]
}shape는 어느 엔드포인트를 호출할지 알려 줍니다. scalar, binary, timing, extreme 중 하나입니다. unit은 답의 단위, venues는 그 뒤에 있는 시장 목록, resolution_kind는 토픽이 어떻게 확정되는지를 나타냅니다. next_event_id는 지금 보여 줄 이벤트입니다. deu-gdp-yoy처럼 next_event_id가 없는 토픽도 있으며, 스크립트는 이를 건너뜁니다.
이벤트 하나 읽기: 경기 침체 확률
binary 이벤트는 예 또는 아니오로 답하는 질문입니다. 이 요청은 경기 침체 시장을 읽습니다. 응답에는 시장별 규정 문구가 들어 있지 않습니다.
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/binary/usa-recession-2026"{
"event_id": "usa-recession-2026",
"topic_id": "usa-recession-2026",
"question": "US recession by end of 2026?",
"status": "trading",
"closes_at": "2026-12-31T00:00:00Z",
"resolves_at": "2026-12-31T00:00:00Z",
"as_of": "2026-11-03T02:21:00Z",
"stale": false,
"resolution": "Two consecutive negative quarters of US real GDP from Q2 2025 to Q4 2026, or an NBER recession call for 2025 or 2026",
"venues": [
{
"venue": "kalshi",
"url": "https://kalshi.com/markets/kxrecssnber/kxrecssnber-26",
"rules_url": "https://assets.kalshi.com/contract_terms/NBERRECSS.pdf",
"settlement_source": "Bureau of Economic Analysis",
"excluded_reason": "rules",
"match": {
"differences": [
"rules"
],
"note": "Kalshi resolves on two negative GDP quarters only; Polymarket also counts an NBER recession call"
},
"volume_24h_usd": "123.64",
"open_interest_usd": "17994.22"
},
{
"venue": "polymarket",
"url": "https://polymarket.com/event/us-recession-by-end-of-2026",
"settlement_source": "Bureau of Economic Analysis; NBER",
"weight": "1.0000",
"volume_24h_usd": "2090.24"
}
],
"probability": "0.0550",
"quotes": [
{
"venue": "kalshi",
"probability": "0.0250",
"market_ids": [
"KXRECSSNBER-26"
]
},
{
"venue": "polymarket",
"probability": "0.0550",
"market_ids": [
"100379208559626151022751801118534484742123694725746262280150222742563282755057"
]
}
]
}probability는 예에 대한 시장 확률로 여기서는 0.0550이며, quotes에는 시장별 가격이 나열됩니다. Kalshi 항목에는 excluded_reason: rules와 match 메모가 있는데, 그 규정은 GDP가 두 분기 연속 마이너스일 때만 인정하는 반면 Polymarket은 연구 기관의 경기 침체 판정도 인정합니다. Kalshi의 0.0250은 참고용으로 quotes에 남아 있고, 대표 probability는 Polymarket 호가와 같습니다. as_of는 호가 시각이며, 호가가 유효한 동안 stale은 false입니다.
API가 정의한 네 가지 형태
| 형태 | 답하는 질문 | 읽을 필드 | 이벤트 예시 |
|---|---|---|---|
scalar | 발표나 결정이 어느 값 또는 범위에 속할지 | outcomes, 각 항목에 key, label, lower, upper, probability가 있음 | usa-cpi-yoy-2026-11 |
binary | 일어날지 여부 | probability, quotes | usa-recession-2026 |
timing | 언제까지 일어날지 | steps, 각 항목에 by, label, probability가 있음 | usa-fed-next-cut-to-2028-12-31 |
extreme | 계열이 얼마나 높아지거나 낮아질지 | level과 probability를 가진 up, down 목록과 window | usa-unemployment-peak-2026 |
scalar 이벤트는 거시경제 대시보드가 보여 주는 발표를 다룹니다. CPI의 12개월 변화, 실업률, 비농업 고용, 중앙은행의 금리 결정입니다. CPI나 실업률 이벤트의 resolves_with 필드는 이를 확정하는 Narwhal 계열(예: /v1/economics/USA/cpi)을 가리킵니다. 따라서 이벤트가 확정되면 타일에서 확률뿐 아니라 발표된 수치로도 연결할 수 있습니다.
scalar 이벤트는 구간의 경계에도 이름을 붙입니다. outcome에서 lower와 upper가 범위를 한정하고, 경계가 null이면 그쪽은 열린 범위입니다. 3.0% 이하를 뜻하는 le_3.0 행이 그 예입니다. 이 페이지를 위해 읽은 CPI, 실업률, 연방준비제도 이벤트에서는 모든 행의 probability 합이 1이므로, outcomes를 막대 차트로 그리면 전체 분포를 보여 줄 수 있습니다.
대시보드 행 구성하기
스크립트는 세 그룹을 차례로 돌며 각 토픽의 다음 이벤트를 그 형태가 가리키는 엔드포인트로 읽고, 타일마다 헤드라인 한 줄을 출력합니다. scalar는 가장 가능성이 높은 결과, binary는 예 확률, timing은 첫 번째 단계, extreme은 첫 번째 수준을 보여 줍니다. 쓸 수 있는 호가가 없는 타일은 그렇다고 표시합니다.
import json
import os
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 headline(shape, e):
if shape == "binary":
if "probability" not in e:
return "no usable quote"
return f"yes {float(e['probability']):.1%}"
if shape == "scalar":
priced = [o for o in e["outcomes"] if "probability" in o]
if not priced:
return "no usable quote"
top = max(priced, key=lambda o: float(o["probability"]))
return f"{top['label']} {float(top['probability']):.1%}"
if shape == "timing":
step = e["steps"][0]
if "probability" not in step:
return "no usable quote"
return f"by {step['label']} {float(step['probability']):.1%}"
if shape == "extreme":
if not e["up"] or "probability" not in e["up"][0]:
return "no usable quote"
step = e["up"][0]
return f"reach {step['level']} {float(step['probability']):.1%}"
for group in ("us_prices", "us_jobs", "us_activity"):
for topic in get("/v1/predictions/topics?group=" + group)["topics"]:
if not topic.get("next_event_id") or topic["shape"] == "scalar" and topic["unit"] == "count":
continue
e = get(f"/v1/predictions/{topic['shape']}/{topic['next_event_id']}")
print(group, e["event_id"], topic["shape"], headline(topic["shape"], e),
"stale" if e["stale"] else "live")
| 이벤트 | 형태 | 헤드라인 |
|---|---|---|
usa-cpi-yoy-2026-11 | 스칼라 | 3.9%, 20.0% |
usa-unemployment-2026-10 | 스칼라 | 4.2%, 37.1% |
usa-unemployment-peak-2026 | 극값 | 5.0 도달, 3.1% |
usa-recession-2026 | 이진 | 예 5.5% |
usa-gdp-2026-q4 | 스칼라 | 쓸 수 있는 호가 없음 |
이 줄들은 한 번 실행한 출력입니다. 확률은 시장에 따라 움직이므로 모든 타일에서 as_of를 확인하고 API에서 페이지를 새로 고치세요.
쓸 수 있는 호가가 없는 타일은 무슨 뜻인가요?
이벤트 응답은 stale: true이고 확률 필드가 없습니다. emu-ecb-cut-2026의 binary 응답은 quotes 목록이 비어 있고 Polymarket 시장 항목에 excluded_reason: thin이 붙어 있습니다. 응답에 표시할 확률이 없으므로 이런 타일은 0이 아니라 사용 불가로 표시하세요.
CPI, 고용, 실업률은 어느 토픽에 있나요?
usa-cpi-yoy, usa-cpi-mom, usa-core-cpi-yoy, usa-core-cpi-mom은 us_prices에 있습니다. usa-payrolls와 usa-unemployment는 us_jobs에 있습니다. usa-recession-2026은 us_activity에, 금리 결정은 central_banks에 있습니다. 그룹을 조회한 다음 각 토픽의 next_event_id를 읽으세요.
토픽마다 하나가 아니라 예정된 이벤트를 나열하려면 어떻게 하나요?
/v1/predictions/events를 topic과 status=trading으로 호출합니다. usa-cpi-yoy에서는 2026년 12월 10일 13:30 UTC에 확정되는 2026년 11월 이벤트 usa-cpi-yoy-2026-11과 2026년 12월 이벤트 usa-cpi-yoy-2026-12가 반환됩니다. 각 행에는 question, closes_at, resolves_at, shape가 있습니다. 이미 시장이 있는 발표의 캘린더 보기에 쓰고, 각 이벤트는 그 형태의 엔드포인트로 여세요.
같은 목록은 shape, from, to, limit, cursor도 받으며, status=settled를 쓰면 이미 확정된 이벤트가 반환됩니다.
금리 결정 타일은 어떻게 보여 주나요?
central_banks 그룹을 쓰거나 한 중앙은행의 정책 경로를 호출하면, 가격이 매겨진 모든 회의에 대한 인하, 동결, 인상 확률을 한 응답으로 얻습니다. 연방준비제도의 사례는 Fed 금리 확률 읽는 법에서 보여 줍니다.
에 게시되었습니다.