واجهة API لأسعار الصرف التاريخية

طلب

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD/observations?currencies=EUR,NZD&start_date=2026-08-20&end_date=2026-08-28&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

أداة MCP هي fx_get_rate_historyإنها currencies يُقدَّم كمدخل على هيئة مصفوفة JSON؛ ولكل حقل آخر المعنى نفسه.

الاستجابة

{
  "base": "USD",
  "observations": [
    {
      "date": "2026-08-20",
      "rates": [
        { "currency": "EUR", "rate": "0.85609" },
        { "currency": "NZD", "rate": "1.681" }
      ]
    },
    {
      "date": "2026-08-21",
      "rates": [
        { "currency": "EUR", "rate": "0.85477" },
        { "currency": "NZD", "rate": "1.6714" }
      ]
    },
    {
      "date": "2026-08-24",
      "rates": [{ "currency": "EUR", "rate": "0.85734" }]
    }
  ],
  "next_cursor": null
}

كل سعر سلسلة نصية لعدد عشري. وحدة واحدة من base تساوي المبلغ المُعاد من currency في تاريخ الرصد هذا.

يُرجع start_date وend_date فقط عندما تغيّر خطتك التواريخ المطلوبة.

ترقيم الصفحات

limit يحسب عدد التواريخ، لذا لا تُقسَّم سجلات العملات الخاصة بتاريخ واحد بين الصفحات. عندما تكون قيمة next_cursor غير null، أعد إرساله مع قيم base وcurrencies وتاريخ البدء وتاريخ الانتهاء نفسها. يرتبط المؤشر بهذه المرشحات. ويؤدي تغييرها إلى إرجاع 400 invalid_cursor.

لا يوجد حد أقصى إجمالي للمدة الزمنية. لجلب السجل التاريخي الكامل، تُطلب الصفحات تباعًا بالحجم المحدود نفسه، حتى يكون next_cursor هو null.

لا تُختلق التواريخ والعملات المفقودة

تظهر تواريخ الرصد الفعلية المخزنة فقط. وتُحذف عطلات نهاية الأسبوع والعطلات وتواريخ النشر المفقودة الأخرى. ولا يملؤها Narwhal بقيم سابقة.

قد يتضمن تاريخ معين بعض العملات المطلوبة فقط. في المثال، لا يوجد سجل لـNZD في 24 أغسطس، بينما يوجد سجل لـEUR. يعكس ذلك قراءات متفرقة فعلية، وليس خطأ في اكتمال الاستجابة.

أعمدة الأسعار

يعيد GET /v1/fx/rates/{base}/bars أعمدة مكتملة تتضمن أسعار الافتتاح والأعلى والأدنى والإغلاق لعملة واحدة مقابل USD. أداة MCP: fx_get_rate_bars.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD/bars?currency=EUR&interval=1h&start=2026-10-08T00:00:00Z&end=2026-10-08T03:00:00Z" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

يحتوي كل عمود على timestamp (بداية العمود)، وopen وhigh وlow وclose بوحدات currency لكل وحدة واحدة من base. لا نملأ الفجوات أبدًا: تبقى الأعمدة المفقودة مفقودة. نحتفظ بأعمدة 1m و5m لمدة 30 يومًا، وبأعمدة 15m و1h و4h و1d دون حد زمني، ضمن نطاق السجل التاريخي في خطتك. يُرجع النطاق الواقع خارج فترة الاحتفاظ قائمة bars فارغة، وليس خطأً.

يُرجع start وend فقط عندما تغيّر خطتك النطاق المطلوب.

يمكن أن يغطي الطلب 3 أيام كحد أقصى لأعمدة 1m، و14 يومًا لأعمدة 5m، و60 يومًا لأعمدة 15m؛ ويعيد النطاق الأطول 400 invalid_query. لا حد لطول النطاق للفواصل الأكبر.

الأخطاء

• 400 invalid_query للعملات أو التواريخ أو حجم الصفحة غير الصالحة.
• 400 invalid_cursor عندما تكون حالة ترقيم الصفحات غير سليمة الصيغة أو لا تطابق المرشحات.
• 401 invalid_api_key لمفتاح Bearer مفقود أو غير صالح.
• 403 plan_upgrade_required عندما ينتهي النطاق المطلوب قبل نافذة السجل في خطتك (Free لمدة 12 شهرًا، وBasic لمدة 5 سنوات).
• 404 currency_not_supported عندما تكون العملة المحددة غير متاحة.
• 429 rate_limit_exceeded عند بلوغ الحد خلال الفترة الزمنية القصيرة؛ انتظر المدة المحددة في Retry-After قبل إعادة المحاولة.
• 429 quota_exhausted عند استنفاد الحصة الشهرية المشتركة.
• 503 upstream_unavailable عندما يتعذر قراءة البيانات التاريخية المقبولة بأمان.

راجع الـ دليل الأخطاء والحدود للاطلاع على مجموعتَي ترويسات تحديد معدل الطلبات وسلوك إعادة المحاولة.

التغطية والحدود

تبدأ التغطية في تواريخ مختلفة حسب العملة. تبدأ أقدم سلسلة مخزنة مدعومة في 1971؛ وتبدأ معظم التغطية اليومية في 1999 أو 2000. ويمكن توسيع التغطية دون تغيير مواصفات الواجهة هذه.

تعيد هذه الواجهة السلسلة التاريخية المقبولة الحالية، لا كل نسخة نُشرت سابقًا. ولا تتضمن حقول المصدر والمزوّد والترخيص والاشتقاق والتقادم وجلسة السوق. اقرأ منهجية أسعار الصرف للاطلاع على سياسة البيانات العامة، و صفحة منتج FX للاطلاع على جميع العمليات المتاحة حاليًا.