مرجع API التوقعات

نقاط النهاية

عنوان URL الأساسي هو https://api.narwhalapi.com. أرسل Authorization: Bearer $NARWHAL_API_KEY. يطابق اسم كل أداة MCP معرّف عمليتها.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/predictions/scalar/usa-cpi-yoy-2026-09" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

تُعاد الأعداد العشرية كسلاسل نصية. تستخدم الاحتمالات أربع منازل عشرية، مثل "0.8250". الأوقات بتوقيت UTC مع Z.

المواضيع والأحداث

اعرض قائمة المواضيع، ثم اطلب موضوعًا باستخدام topic_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"]. تكون قيمة resolution_kind هي release أو price_fix أو price_window أو occurrence. يحتوي calendar على country وfamily وvariant، أو تكون قيمته null.

حقول الحدث

تستخدم جميع أشكال الأحداث هذه الحقول. يعتمد body على الشكل.

الاحتمالات حسب شكل السوق

اطلب الحدث عبر المسار الخاص بشكله. تقبل طلبات القيم العددية والقيم القصوى والتوقيت والنتائج الثنائية الحقل الاختياري at لتحديد دقيقة سابقة سُجلت بتوقيت UTC.

المحتويات التالية أمثلة توضيحية. القيم افتراضية.

عددي

يأتي scale مع outcomes. يحتوي كل ناتج على key وlabel وlower وupper وprobability وquotes. يحتوي summary على median وp10 وp90 وmethod مضبوطًا على bucket_upper، و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. تظهر احتمالات الحد الأعلى والأدنى في صفوف up وdown التي تحتوي على key وlevel وprobability وquotes. تكون قيمة 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"
}

ثنائي

يحتوي المحتوى على labels التي تضم yes وno، و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 وunit مضبوطًا على bps و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 لقراءة بيانات أي دقيقة جرى التقاطها، مع مراعاة تأخير الخطة.

تعرض الخطة المجانية جميع البيانات بتأخير 15 دقيقة، بما في ذلك أحدث البيانات ونهايات السجل ومسارات السياسة النقدية. إذا كانت قيمة at أحدث من ذلك الحد، تُعاد 403 plan_upgrade_required. توفّر خطتا Basic وPro البيانات المباشرة.

يتوفر البث وwebhooks التوقعات في خطتي Basic وPro فقط. راجع مرجع واجهة API لـ Webhook لمعرفة تفاصيل webhooks التوقعات.

البث

أرسل 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. توضح التفاصيل المسار الصحيح.