거시경제 예측시장 대시보드: 이벤트별 시장 확률 보기

거시경제 확률 대시보드에는 토픽 목록과 타일마다 한 번의 이벤트 읽기가 필요합니다. Narwhal은 CPI, 고용, 실업률, 경기 침체, 중앙은행 결정에 대한 시장 확률을 scalar, binary, timing, extreme이라는 이름의 네 가지 형태로 제공합니다.

대시보드에 쓸 토픽 목록 가져오기

대시보드의 각 타일은 토픽 하나입니다. 토픽 엔드포인트가 이를 나열하며 선택 사항인 group을 받습니다. 거시경제 그룹은 central_banks, us_prices, us_jobs, us_activity, global_activity, global_prices입니다. 이 요청은 us_jobs를 지정하고 처음 두 토픽만 남깁니다.

curl, 미국 고용 토픽
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, 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, quotesusa-recession-2026
timing언제까지 일어날지steps, 각 항목에 by, label, probability가 있음usa-fed-next-cut-to-2028-12-31
extreme계열이 얼마나 높아지거나 낮아질지level과 probability를 가진 up, down 목록과 windowusa-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은 첫 번째 수준을 보여 줍니다. 쓸 수 있는 호가가 없는 타일은 그렇다고 표시합니다.

python, 토픽마다 헤드라인 한 줄
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 금리 확률 읽는 법에서 보여 줍니다.

에 게시되었습니다.

다음 단계