واجهة 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",
  "start_date": "2026-08-20",
  "end_date": "2026-08-28",
  "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,
  "has_more": false
}

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

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

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

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

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

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

قد يحتوي التاريخ على مجموعة فرعية فقط من العملات المطلوبة. في المثال، لا يملك NZD سجلًا في 24 أغسطس بينما يملكه EUR. هذه ملاحظة متفرقة صادقة وليست خطأ استجابة جزئية.

الأخطاء

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

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

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

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

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