تحتاج أبحاث أسواق التنبؤ إلى الاحتمالات عبر الزمن والنتيجة المسوّاة. توفّر Narwhal سجلًا للأحداث الثنائية والقياسية حسب الفاصل الزمني، وقائمة بالأحداث المسوّاة، ونتيجة لكل حدث تتضمن final وتسوية كل منصة.
عرض الأحداث التي تمت تسويتها
تعرض نقطة events الأحداث التنبؤية ويمكن تصفيتها بـ topic وshape وstatus وfrom وto وlimit. يطلب هذا الطلب أحدث قرار للاحتياطي الفيدرالي تمت تسويته. قيم status هي upcoming وtrading وclosed وsettled وvoid.
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 للحصول على الصفحة التالية.
قراءة النتيجة وآخر الاحتمالات
يفتح معرّف الحدث التنبؤ الكامل. تحذف هذه الاستجابة نص قواعد المنصات وتُبقي صف hold والسوق الفائز في كل منصة.
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 هي 17:58 بالتوقيت العالمي المنسق في 28 أكتوبر 2026، أي قبل إغلاق السوق بدقيقة، واحتمال hold هو 0.9622. تسرد result.venues أسواق كل منصة مع outcome وvalue المسوّيين. سوّت Kalshi سوق KXFEDDECISION-26OCT-H0 على yes، ويظهر معرّف السوق في أسعار النتيجة hold. لا يحتوي الحدث المسوّى على الحقل stale، لأن هذا الحقل يُرسل فقط مع أحداث upcoming وtrading وclosed.
جلب سجل الاحتمالات
تتطلب نقاط السجل start وend، وتقبل interval اختياريًا. وهي متاحة للأحداث القياسية والثنائية والتوقيتية والقصوى. يقرأ هذا الطلب الشموع اليومية لسوق الركود ويُبقي شمعتين متتاليتين.
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. شمعة 4 أكتوبر فيها close فقط، أما شمعة 5 أكتوبر ففيها أيضًا open وhigh وlow. الشمعة ذات القيم الأربع التُقطت مباشرة، والشمعة التي فيها الإغلاق فقط هي بيانات مُعبَّأة لاحقًا من منصة. يسمّي backfill_venue هذه المنصة، ويحدّد active_from متى بدأت السلسلة. وفي الحدث القياسي توجد سلسلة واحدة لكل نتيجة key.
مطابقة آخر الاحتمالات مع النتيجة
يقرأ السكربت حدث الاحتياطي الفيدرالي المسوّى، ويجد النتيجة التي سوّى سوق Kalshi فيها على yes، ثم يمرّ على السجل اليومي لتلك النتيجة. ويتبع next_cursor حتى الصفحة الأخيرة مع تكرار start وend وinterval نفسها.
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 من 21 أكتوبر 2026 إلى 28 أكتوبر 2026. تتدرج من 0.8707 إلى 0.9622، ويساوي آخر إغلاق قيمة probability في صف hold داخل الحدث. وهذا يعطي صفًا واحدًا لجدول المعايرة: سعّر السوق النتيجة الفائزة عند 0.9622 قبيل القرار.
لبناء عيّنة، تصفّح /v1/predictions/events صفحةً صفحةً مع status=settled وtopic ونافذة from وto على وقت الحسم. شغّل السكربت لكل event_id واحفظ آخر احتمال قبل الإغلاق بجانب النتيجة المسوّاة. استخدم interval=1d لدراسة تمتد أشهرًا عدة، و1h للأيام الأخيرة قبل القرار.
ماذا يخبر as_of وstale الباحث؟
as_of هو آخر وقت جرى فيه فحص المنصات. تكون stale هي true في الحدث المفتوح بعد أكثر من 3 دقائق دون فحص أي منصة. وبعد أكثر من 30 دقيقة لا ترسل الاستجابة أي احتمالات، وتكون كل قوائم quotes فارغة، وتُستبعد كل المنصات. أسقط هذه اللحظات من دراستك أو علّمها كمفقودة. ولا يوجد الحقل stale في الأحداث المسوّاة وvoid.
متى تصبح النتيجة نهائية؟
تصبح result.final هي true عندما تكون نتيجة كل منصة نهائية. أما نتيجة المنصة التي حدّدتها دون أن تعتمدها نهائيًا فقد تتغير. وإذا وجدت Narwhal أن مخرج نتيجة نهائية تغيّر بعد نزاع أو تعديل، تحمل النتيجة الحقل amended_at. تحقق من final وamended_at قبل أن تثبّت التصنيف.
كيف يبدو الحدث void؟
للحدث void الحالة void في قائمة الأحداث. وبمجرد أن تسوّي المنصة سوقها أو تلغيه، يحمل إدخالها في venues الحقل settlement بقيمة settled أو void. وفي استجابة الاحتياطي الفيدرالي أعلاه تُظهر المنصتان settled. صفِّ بـ status=void لإيجاد الأحداث الملغاة، وعاملها بشكل منفصل عن الأحداث المسوّاة في عيّنة المعايرة.
إلى أي مدى يمكن الرجوع في السجل وبأي فواصل؟
قيمة interval هي 1m أو 5m أو 1h أو 1d، والافتراضي 1h. يمكن للطلب الواحد أن يغطي 2 أيام على الأكثر مع 1m، و7 أيام مع 5m، و92 يومًا مع 1h، و3,660 يومًا مع 1d. تحتوي الصفحة على نحو 5,000 شمعة، وقد تكون الصفحة فارغة بينما next_cursor ليست null، لذا واصل اتباع المؤشر. راجع وثائق التنبؤات للاطلاع على قائمة المعاملات الكاملة.
نُشر في .