예측시장 과거 데이터: 연구용 확률 이력과 정산 결과 가져오기

예측시장 연구에는 시간에 따른 확률과 정산된 결과가 필요합니다. Narwhal은 구간별 바이너리·스칼라 이력, 정산된 이벤트 목록, 그리고 이벤트마다 final과 거래소별 정산이 담긴 결과를 제공합니다.

정산된 이벤트 목록 보기

events 엔드포인트는 예측 이벤트를 나열하며 topic, shape, status, from, to, limit으로 필터링할 수 있습니다. 이 요청은 가장 최근에 정산된 연방준비제도 결정을 요청합니다. status 값은 upcoming, trading, closed, settled, void입니다.

curl, 정산된 이벤트
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/predictions/events?topic=usa-fed&status=settled&limit=1"
응답
{
  "events": [
    {
      "event_id": "usa-fed-2026-10",
      "question": "Federal Reserve rate decision, 28 October 2026",
      "status": "settled",
      "closes_at": "2026-10-28T17:59:00Z",
      "resolves_at": "2026-10-28T18:00:00Z",
      "release_id": "ae2a77cc-3b5b-4541-a060-3bc2ea1145d9",
      "result": {
        "final": true,
        "settled_at": "2026-10-28T20:01:40Z"
      },
      "topic_id": "usa-fed",
      "shape": "scalar"
    }
  ],
  "next_cursor": null
}

정산된 이벤트에는 result 요약이 포함됩니다. 모든 거래소의 결과가 확정되면 final은 true이고, settled_at은 거래소별 정산 시각 중 가장 늦은 시각입니다. next_cursor는 마지막 페이지에서 null이며, 그렇지 않으면 cursor로 다시 전달해 다음 페이지를 받습니다.

결과와 마지막 확률 읽기

이벤트 id로 예측 전체를 열 수 있습니다. 이 응답은 거래소 규칙 본문을 생략하고 hold 행과 거래소별 승리 마켓만 남겼습니다.

curl, 정산된 스칼라 이벤트
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/predictions/scalar/usa-fed-2026-10"
응답, 요약
{
  "event_id": "usa-fed-2026-10",
  "topic_id": "usa-fed",
  "question": "Federal Reserve rate decision, 28 October 2026",
  "status": "settled",
  "closes_at": "2026-10-28T17:59:00Z",
  "resolves_at": "2026-10-28T18:00:00Z",
  "as_of": "2026-10-28T17:58:00Z",
  "result": {
    "final": true,
    "settled_at": "2026-10-28T20:01:40Z",
    "venues": [
      {
        "venue": "kalshi",
        "final": true,
        "settled_at": "2026-10-28T18:06:30Z",
        "markets": [
          {
            "market_id": "KXFEDDECISION-26OCT-H0",
            "outcome": "yes",
            "value": "1"
          }
        ]
      },
      {
        "venue": "polymarket",
        "final": true,
        "settled_at": "2026-10-28T20:01:40Z",
        "markets": [
          {
            "market_id": "2589812",
            "outcome": "Yes",
            "value": "1"
          }
        ]
      }
    ]
  },
  "outcomes": [
    {
      "key": "hold",
      "label": "No change",
      "lower": "-12.5",
      "upper": "12.5",
      "probability": "0.9622",
      "quotes": [
        {
          "venue": "kalshi",
          "probability": "0.9602",
          "market_ids": [
            "KXFEDDECISION-26OCT-H0"
          ]
        },
        {
          "venue": "polymarket",
          "probability": "0.9686",
          "market_ids": [
            "111061902544814266207267295505639408607400625795891618462682726460921782993748"
          ]
        }
      ]
    }
  ],
  "above": []
}

as_of는 2026년 10월 28일 17:58 UTC로, 마켓이 닫히기 1분 전이며 hold 확률은 0.9622입니다. result.venues에는 각 거래소의 마켓이 정산된 outcome, value와 함께 나열됩니다. Kalshi는 KXFEDDECISION-26OCT-H0 마켓을 yes로 정산했고, 그 마켓 id는 hold 결과의 호가에 나타납니다. 정산된 이벤트에는 stale 필드가 없습니다. 이 필드는 upcoming, trading, closed 이벤트에만 전송되기 때문입니다.

확률 이력 가져오기

이력 엔드포인트는 필수인 start와 end, 선택인 interval을 받습니다. 스칼라, 바이너리, 타이밍, 극값 이벤트에서 사용할 수 있습니다. 이 요청은 경기침체 마켓의 일봉을 읽고 연속된 두 개의 봉만 남겼습니다.

curl, 바이너리 이벤트의 일별 이력
curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/predictions/binary/usa-recession-2026/history?start=2026-10-01T00:00:00Z&end=2026-10-08T00:00:00Z&interval=1d"
응답, 요약
{
  "backfill_venue": "polymarket",
  "series": [
    {
      "key": "yes",
      "active_from": "2026-10-01T00:00:00Z",
      "bars": [
        {
          "timestamp": "2026-10-04T00:00:00Z",
          "close": "0.0850"
        },
        {
          "timestamp": "2026-10-05T00:00:00Z",
          "open": "0.0750",
          "high": "0.0750",
          "low": "0.0750",
          "close": "0.0750"
        }
      ]
    }
  ],
  "next_cursor": null
}

모든 봉에는 봉의 시작 시각인 timestamp와 close가 있습니다. 10월 4일 봉에는 close만 있고, 10월 5일 봉에는 open, high, low도 있습니다. 네 값이 모두 있는 봉은 실시간으로 수집된 것이고, close만 있는 봉은 거래소에서 가져온 백필입니다. backfill_venue는 그 거래소를 나타내고 active_from은 시리즈가 시작된 시점을 나타냅니다. 스칼라 이벤트에는 결과 key마다 시리즈가 하나씩 있습니다.

마지막 확률을 결과와 대조하기

스크립트는 정산된 연방준비제도 이벤트를 읽고, Kalshi 마켓이 yes로 정산된 결과를 찾은 뒤, 그 결과의 일별 이력을 따라갑니다. 마지막 페이지까지 next_cursor를 따라가며 start, end, interval은 매번 같은 값을 반복합니다.

python, 정산된 이벤트의 확률 이력
import json
import os
import urllib.parse
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 history(event_id, start, end, interval="1d"):
    bars, cursor = {}, None
    while True:
        query = {"start": start, "end": end, "interval": interval}
        if cursor:
            query["cursor"] = cursor
        page = get(f"/v1/predictions/scalar/{event_id}/history?" + urllib.parse.urlencode(query))
        for series in page["series"]:
            bars.setdefault(series["key"], []).extend(series["bars"])
        cursor = page["next_cursor"]
        if not cursor:
            return bars

event = get("/v1/predictions/scalar/usa-fed-2026-10")
print(event["status"], "final:", event["result"]["final"])

# The winning outcome: the Kalshi market that settled to yes.
yes = {m["market_id"] for v in event["result"]["venues"] if v["venue"] == "kalshi"
       for m in v["markets"] if m["outcome"] == "yes"}
winner = [o["key"] for o in event["outcomes"] for q in o["quotes"]
          if yes & set(q["market_ids"])]
print("winner:", winner)

bars = history("usa-fed-2026-10", "2026-10-21T00:00:00Z", "2026-10-29T00:00:00Z")
for bar in bars[winner[0]]:
    print(bar["timestamp"][:10], bar["close"])

스크립트는 settled final: True, 이어서 winner: ['hold'], 그리고 hold 결과의 2026년 10월 21일부터 10월 28일까지 일별 종가를 출력합니다. 값은 0.8707에서 0.9622까지 이어지고, 마지막 종가는 이벤트의 hold 행에 있는 probability와 같습니다. 이렇게 보정 표의 한 행이 만들어집니다. 시장은 결정 직전에 승리한 결과를 0.9622로 평가했습니다.

표본을 만들려면 /v1/predictions/events를 status=settled, topic, 그리고 결과 확정 시각에 대한 from과 to 기간으로 페이지 단위로 가져옵니다. event_id마다 스크립트를 실행하고, 마감 직전의 마지막 확률을 정산된 결과 옆에 저장합니다. 여러 달에 걸친 연구에는 interval=1d를, 결정 직전 마지막 며칠에는 1h를 사용하세요.

as_of와 stale은 연구자에게 무엇을 알려 주나요?

as_of는 거래소를 마지막으로 확인한 시각입니다. stale은 진행 중인 이벤트에서 3분이 넘도록 거래소 확인이 없으면 true가 됩니다. 30분이 넘으면 응답은 확률을 보내지 않고, 모든 quotes 목록이 비며, 모든 거래소가 제외됩니다. 이런 시점은 연구에서 빼거나 결측으로 표시하세요. 정산된 이벤트와 void 이벤트에는 stale 필드가 없습니다.

결과는 언제 확정되나요?

result.final은 모든 거래소의 결과가 확정되면 true가 됩니다. 거래소가 결정했지만 아직 확정하지 않은 결과는 바뀔 수 있습니다. 확정된 결과의 결과값이 분쟁이나 정정 뒤에 바뀐 것을 Narwhal이 발견하면 결과에 amended_at이 붙습니다. 라벨을 고정하기 전에 final과 amended_at을 확인하세요.

void 이벤트는 어떻게 보이나요?

void 이벤트는 이벤트 목록에서 상태가 void입니다. 거래소가 마켓을 정산하거나 무효 처리하면 venues의 해당 항목에 값이 settled 또는 void인 settlement가 붙습니다. 위의 연방준비제도 응답에서는 두 거래소 모두 settled입니다. status=void로 필터링하면 무효 처리된 이벤트를 찾을 수 있으며, 보정 표본에서는 정산된 이벤트와 따로 다루세요.

얼마나 과거까지, 어떤 간격으로 가져올 수 있나요?

interval은 1m, 5m, 1h, 1d이며 기본값은 1h입니다. 한 번의 요청으로 1m은 최대 2일, 5m은 7일, 1h는 92일, 1d는 3,660일을 다룰 수 있습니다. 한 페이지에는 약 5,000개의 봉이 담기며, next_cursor가 null이 아닌데도 페이지가 비어 있을 수 있으므로 커서를 계속 따라가세요. 전체 파라미터 목록은 예측 문서를 참고하세요.

에 게시되었습니다.

다음 단계