مرجع تدفق الأسعار

الوصول والحدود

يتوفر تدفق الأسعار في خطتي Basic وPro. يتلقى مفتاح خطة Free الرمز plan_upgrade_required، ثم يُغلق الاتصال.

تشترك تدفقات الأسعار والأحداث والتوقعات في حد للاتصالات المتزامنة: اتصال واحد في Free، واتصالان في Basic، و10 اتصالات في Pro. يستهلك كل اتصال استدعاءً واحدًا من الحصة الشهرية.

اتصال

اتصل بـwss://api.narwhalapi.com/v1/prices/stream مع وضع مفتاح API في الترويسة Authorization: Bearer.

لا تستطيع المتصفحات تعيين تلك الترويسة في اتصال WebSocket. أرسل POST /v1/prices/stream-ticket من خادمك، ثم اتصل باستخدام ?ticket= والتذكرة المُعادة. تُستخدم التذكرة مرة واحدة، وتنتهي صلاحيتها بعد 30 ثانية، وتتطلب أصلًا مسموحًا به. يخضع تدفق التوقعات لقواعد التذاكر نفسها.

الاشتراك

يرسل الخادم {"type":"ready"}. أرسل رسالة اشتراك واحدة خلال 5 ثوانٍ:

{
  "action": "subscribe",
  "commodities": [
    {
      "commodity": "XAU",
      "currency": "USD"
    }
  ],
  "fx": [
    {
      "base": "USD",
      "currencies": [
        "EUR",
        "JPY"
      ]
    }
  ]
}

• commodities: ما يصل إلى 20 زوجًا من السلع والعملات يدعمها GET /v1/commodities/spot/{commodity}/{currency}.
• fx: ما يصل إلى 5 عملات أساس. الحقل currencies اختياري: احذفه لتلقي كل عملة متاحة لعملة الأساس، أو أدرج ما يصل إلى 64 عملة.

يرد الخادم بـ{"type":"subscribed"} ويرسل كل سعر مشترك فيه مرة واحدة. بعد ذلك، لا يرسل السعر إلا عندما يتغير. تُفحص الأسعار مرة كل ثانية تقريبًا.

لتغيير الاشتراك، أعد الاتصال. تؤدي رسالة اشتراك ثانية إلى إغلاق الاتصال بالرمز resubscribe_required.

الرسائل

تحتوي رسائل الأسعار على محتوى الاستجابة نفسه الذي تعيده نقاط نهاية REST، بما في ذلك المنازل العشرية والقيم البديلة وعلامات البيانات القديمة.

{
  "type": "commodity",
  "spot": {
    "symbol": "XAU-USD",
    "price": "4195.86",
    "currency": "USD",
    "unit": "troy_ounce",
    "timestamp": "2026-10-11T06:25:00Z",
    "stale": false
  }
}

{
  "type": "fx",
  "base": "USD",
  "market_session": "open",
  "rate": {
    "currency": "EUR",
    "rate": "0.8924",
    "timestamp": "2026-10-09T00:00:00Z",
    "stale": false
  }
}

مرجع الأسعار الفورية · مرجع أسعار صرف العملات

الحفاظ على الاتصال نشطًا

أرسل {"action":"ping"} للحصول على {"type":"pong"}. يرسل الخادم أيضًا heartbeat كل 30 ثانية. اقرأ الرسائل فور وصولها: يُغلق اتصال العميل الذي يتوقف عن القراءة لمدة 5 ثوانٍ بالرمز slow_consumer.

يمكنك إرسال ما يصل إلى 30 إطارًا لكل اتصال. عند إعادة الاتصال، تُرسل جميع الأسعار المشترك فيها مجددًا؛ ولا تُعاد التغييرات التي فاتتك.

الأخطاء

تصل الأخطاء بصيغة {"type":"error","code":"..."}، ثم يُغلق الاتصال.