مرجع indices API للمؤشرات

المستويات والسجل التاريخي لـ 18 مؤشرًا

نظرة عامة

مستويات وسجل مستويات 18 مؤشرًا للأسهم والتذبذب. يحتاج كل طلب إلى مفتاح Bearer، ويسحب REST وMCP من رصيد واحد.

المعرّف هو الرمز القياسي للمؤشر، مثل SPX لمؤشر S&P 500، وNDX لمؤشر Nasdaq-100، وDJI لمؤشر Dow Jones Industrial Average. تصلح أي حالة أحرف. يعيد مسار القائمة كل معرّف مع اسمه ومنطقته وعملته.

يحمل السعر الإغلاق السابق والتغير ونسبته المئوية متى توفر السجل اليومي للمؤشر.

عنوان URL الأساسي: https://api.narwhalapi.com. أداة MCP هي indices, with one action لكل مسار أدناه.

ما يحصل عليه كل حساب

ما	كل حساب
آخر مستوى	مباشر
أشرطة يومية	السجل التاريخي الكامل
شموع الدقيقة الواحدة	آخر 12 شهرًا
قائمة المؤشرات	مشمول

راجع التسعير لمعرفة تكلفة الاستدعاء. يُحاسَب الطلب بسعر واجهته ما لم يذكر المسار خلاف ذلك.

يبدأ السجل التاريخي من حيث نحتفظ به. ويبدأ سجل S&P 500 في فبراير 2023.
مؤشر التذبذب (VIX وOVX وGVZ) ليس مبلغًا نقديًا، لذا لا تحمل إجاباته عملة.
تكون market_session بالقيمة open أو closed بحسب ساعات المؤشر المنشورة. المؤشر المغلق يجيب بآخر مستوى له وليس قديمًا. والمؤشر المفتوح يكون قديمًا (stale) إذا تجاوز عمر مستواه 15 دقيقة.
الشمعة اليومية تمثل يوم تداول واحدًا وتظهر عند 00:00 UTC. ولا تظهر شمعة اليوم الجزئية أبدًا.
لا تحمل الشموع حجم تداول. تُحفظ شموع الدقيقة الواحدة 12 شهرًا، ويغطي الطلب الواحد 5 أيام كحد أقصى.
تحتوي الدفعة على 50 معرّفًا كحد أقصى وتُحتسب استدعاءً واحدًا لكل معرّف يعيد مستوى. المعرّف غير المعروف يُدرج في errors ولا يُحتسب.

نقاط النهاية

كل مسار هو طلب GET ويحتاج إلى مفتاحك في: Authorization: Bearer الترويسة. تعرض الأمثلة شكل الاستجابة، وليست بيانات مباشرة.

المؤشرات التي نسعّرها

GET /v1/indices

كل سلسلة مؤشرات نسعّرها، مرتبة حسب المعرّف، مع اسمها ووحدتها. تُقرأ من قائمتنا، فهي متاحة لكل حساب وتُحسب استدعاءً واحدًا.

MCP: الأداة indices, action list.

المعلمات

لا يأخذ هذا المسار أي معاملات.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`indices`	قائمة كائنات	دائمًا	كل مؤشر نسعّره، مرتبًا حسب المعرّف.
`indices[].id`	سلسلة نصية	دائمًا	رمز المؤشر، مثل SPX.
`indices[].name`	سلسلة نصية	دائمًا	اسم المؤشر.
`indices[].region`	إحدى القيم: us, uk, europe, global, asia	دائمًا	المكان الذي تُتداول فيه مكوّناته.
`indices[].currency`	سلسلة نصية	اختياري	العملة التي يُقاس بها المؤشر. تُحذف لمؤشر التذبذب لأنه ليس مبلغًا نقديًا.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/indices"

{
  "indices": [
    {
      "id": "SPX",
      "name": "S&P 500",
      "region": "us",
      "currency": "USD"
    },
    {
      "id": "VIX",
      "name": "Cboe Volatility Index",
      "region": "us"
    }
  ]
}

آخر سعر لسلسلة مؤشرات واحدة

GET /v1/indices/{id}/price

آخر سعر. تكون market_session بالقيمة open أو closed بحسب ساعات السلسلة؛ والسلسلة المغلقة تجيب بآخر سعر لها، وتكون stale بالقيمة true فقط عندما لا يكون للسلسلة المفتوحة سعر خلال آخر 15 دقيقة. previous_close هو إغلاق يوم التداول السابق، وchange_percent بالنسبة المئوية.

MCP: الأداة indices, action price.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`id`	مسار	نعم	سلسلة نصية	معرّف المؤشر، مثل SPX أو NDX أو DJI. تصلح أي حالة أحرف.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`id`	سلسلة نصية	دائمًا	رمز المؤشر.
`name`	سلسلة نصية	دائمًا	الاسم كما تحتفظ به قائمة الرموز لدينا.
`currency`	سلسلة نصية	اختياري	العملة التي يُقاس بها المؤشر. تُحذف لمؤشر التذبذب لأنه ليس مبلغًا نقديًا.
`price`	سلسلة نصية	دائمًا	آخر مستوى للمؤشر.
`previous_close`	سلسلة نصية	اختياري	إغلاق يوم التداول السابق. يُحذف إذا لم يكن معروفًا.
`change`	سلسلة نصية	اختياري	`price` مطروحًا منه `previous_close`.
`change_percent`	سلسلة نصية	اختياري	التغير بالنسبة المئوية (1.5 تعني 1.5%). يُحذف مع `change`.
`market_session`	إحدى القيم: open, closed	دائمًا	`open` ما دامت السلسلة تُتداول وفق ساعاتها المنشورة، وإلا `closed`. وتظل السلسلة المغلقة تجيب بآخر سعر لها؛ أما العطلة الواقعة ضمن الساعات فتظهر `open` وتُعرض `stale`.
`timestamp`	تاريخ ووقت	دائمًا	وقت صلاحية السعر (بالتوقيت العالمي UTC، بالثواني الكاملة).
`stale`	منطقي	دائمًا	تكون true إذا كانت السلسلة مفتوحة وتجاوز عمر سعرها 15 دقيقة، أو تعذّر تحديثه. والسلسلة المغلقة ليست قديمة.
`delayed`	دائمًا true	اختياري	لا يُرسل: الأسعار فورية لكل حساب.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/indices/SPX/price"

{
  "id": "SPX",
  "name": "S&P 500",
  "currency": "USD",
  "price": "7696.46",
  "previous_close": "7681.2",
  "change": "15.26",
  "change_percent": "0.2",
  "market_session": "open",
  "timestamp": "2026-10-29T18:38:00Z",
  "stale": false
}

آخر أسعار حتى 50 سلسلة مؤشرات

GET /v1/indices/prices

آخر سعر لكل معرّف مذكور. يُحتسب استدعاء واحد لكل معرّف يعيد سعرًا، ويُخصم في خطوة واحدة: إذا لم يكفِ رصيدك لتغطية المعرّفات التي تم حلّها، يُرفض الطلب كله مع 402 insufficient_credits. المعرّفات التي لا تعيد سعرًا تُدرج في errors (باسم id) ولا تُكلّف شيئًا؛ وإذا لم يُحلّ أي معرّف تبقى الإجابة 200 مع prices فارغة. previous_close هو إغلاق يوم التداول السابق، وchange_percent بالنسبة المئوية.

أرسل حتى 50 معرّفًا. تُحاسَب الدفعة في خطوة واحدة: إذا لم يكفِ رصيدك لتغطية المعرّفات التي تُحل، يعيد الطلب كله 402 insufficient_credits.

MCP: الأداة indices, action prices.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`ids`	استعلام	نعم	سلسلة نصية	معرّفات مفصولة بفواصل، بحد أقصى 50 بعد حذف المكرر. يخضع كل معرّف لقواعد مسار السعر الواحد نفسها. يُحتسب استدعاء واحد لكل معرّف يعيد سعرًا.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`prices`	قائمة كائنات	دائمًا	سعر واحد لكل معرّف تم حله، مفهرسًا بالمعرّف.
`prices[].id`	سلسلة نصية	دائمًا	رمز المؤشر.
`prices[].name`	سلسلة نصية	دائمًا	الاسم كما تحتفظ به قائمة الرموز لدينا.
`prices[].currency`	سلسلة نصية	اختياري	العملة التي يُقاس بها المؤشر. تُحذف لمؤشر التذبذب لأنه ليس مبلغًا نقديًا.
`prices[].price`	سلسلة نصية	دائمًا	آخر مستوى للمؤشر.
`prices[].previous_close`	سلسلة نصية	اختياري	إغلاق يوم التداول السابق. يُحذف إذا لم يكن معروفًا.
`prices[].change`	سلسلة نصية	اختياري	`price` مطروحًا منه `previous_close`.
`prices[].change_percent`	سلسلة نصية	اختياري	التغير بالنسبة المئوية (1.5 تعني 1.5%). يُحذف مع `change`.
`prices[].market_session`	إحدى القيم: open, closed	دائمًا	`open` ما دامت السلسلة تُتداول وفق ساعاتها المنشورة، وإلا `closed`. وتظل السلسلة المغلقة تجيب بآخر سعر لها؛ أما العطلة الواقعة ضمن الساعات فتظهر `open` وتُعرض `stale`.
`prices[].timestamp`	تاريخ ووقت	دائمًا	وقت صلاحية السعر (بالتوقيت العالمي UTC، بالثواني الكاملة).
`prices[].stale`	منطقي	دائمًا	تكون true إذا كانت السلسلة مفتوحة وتجاوز عمر سعرها 15 دقيقة، أو تعذّر تحديثه. والسلسلة المغلقة ليست قديمة.
`prices[].delayed`	دائمًا true	اختياري	لا يُرسل: الأسعار فورية لكل حساب.
`errors`	قائمة كائنات	دائمًا	المعرّفات التي لم تعد سعرًا. لا تُحتسب عليها رسوم.
`errors[].id`	سلسلة نصية	دائمًا	المعرّف كما طُلب.
`errors[].code`	دائمًا "not_found"	دائمًا	not_found: لا توجد سلسلة بهذا المعرّف.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/indices/prices?ids=SPX,NDX,DJI"

{
  "prices": [
    {
      "id": "SPX",
      "name": "S&P 500",
      "currency": "USD",
      "price": "7696.46",
      "previous_close": "7681.2",
      "change": "15.26",
      "change_percent": "0.2",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    },
    {
      "id": "NDX",
      "name": "Nasdaq-100",
      "currency": "USD",
      "price": "27310.5",
      "previous_close": "27264.9",
      "change": "45.6",
      "change_percent": "0.17",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XX",
      "code": "not_found"
    }
  ]
}

شموع أسعار سلسلة مؤشرات واحدة

GET /v1/indices/{id}/bars

شموع يومية (1d، شمعة لكل يوم تداول) أو بدقيقة واحدة (1m)، الأقدم أولًا. تصدر شمعة اليوم عند 00:00 UTC بعد انتهاء اليوم؛ ولا تظهر شمعة اليوم الجزئية أبدًا. تُحفظ شموع الدقيقة الواحدة 12 شهرًا. السجل التاريخي: كامله، لكل حساب. حتى 5,000 شمعة في الصفحة، مع next_cursor. استدعاء واحد لكل صفحة.

MCP: الأداة indices, action bars.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`id`	مسار	نعم	سلسلة نصية	معرّف المؤشر، مثل SPX أو NDX أو DJI. تصلح أي حالة أحرف.
`interval`	استعلام	لا	إحدى القيم: 1d, 1m	`1d` (شمعة لكل يوم تداول، تحمل تاريخ اليوم الذي تخصه) أو `1m` (شموع الدقيقة الواحدة؛ تُحفظ 12 شهرًا). أي قيمة أخرى تعيد 400 invalid_interval.
`start`	استعلام	لا	سلسلة نصية	أول شمعة. `1d`: تاريخ (YYYY-MM-DD)، شاملًا؛ وحذفه يعني أقدم شمعة متاحة. `1m`: وقت بتوقيت UTC (YYYY-MM-DDTHH:MM:SSZ، أو تاريخ للدلالة على 00:00 UTC)، شاملًا؛ وحذفه يعني يومًا واحدًا قبل `end`.
`end`	استعلام	لا	سلسلة نصية	آخر شمعة. `1d`: تاريخ شامل؛ وحذفه يعني آخر يوم مكتمل. `1m`: وقت UTC غير شامل؛ وحذفه يعني الآن، أو بعد خمسة أيام من `start`. بحد أقصى 5 أيام بين `start` و`end` للقيمة `1m` (400 range_too_large).
`cursor`	استعلام	لا	سلسلة نصية	`next_cursor` من الصفحة السابقة، مع المعاملات نفسها.

حقول الاستجابة

حقل	النوع	يُرسل	المعنى
`id`	سلسلة نصية	دائمًا
`currency`	سلسلة نصية	اختياري	العملة التي يُقاس بها المؤشر. تُحذف لمؤشر التذبذب لأنه ليس مبلغًا نقديًا.
`start`	سلسلة نصية	اختياري	لا يُرسل أبدًا: لا يُنقل `start`.
`end`	سلسلة نصية	اختياري	لا يُرسل أبدًا: لا تُقتطع الشموع اليومية.
`bars`	قائمة كائنات	دائمًا	5,000 شمعة في الصفحة كحد أقصى.
`bars[].timestamp`	تاريخ ووقت	دائمًا	بداية فترة الشمعة (UTC): 00:00 من يوم التداول للشمعة اليومية، والدقيقة نفسها لشمعة الدقيقة الواحدة.
`bars[].open`	سلسلة نصية	دائمًا	أول سعر في الفترة.
`bars[].high`	سلسلة نصية	دائمًا	أعلى سعر في الفترة.
`bars[].low`	سلسلة نصية	دائمًا	أدنى سعر في الفترة.
`bars[].close`	سلسلة نصية	دائمًا	آخر سعر في الفترة.
`next_cursor`	سلسلة نصية	دائمًا	أعد إرساله لقراءة الصفحة التالية. تكون قيمته null في الصفحة الأخيرة.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/indices/SPX/bars?interval=1d&start=2026-10-01"

{
  "id": "SPX",
  "currency": "USD",
  "bars": [
    {
      "timestamp": "2026-10-28T00:00:00Z",
      "open": "7655.1",
      "high": "7702.4",
      "low": "7640.8",
      "close": "7681.2"
    }
  ],
  "next_cursor": null
}

الأخطاء

تستخدم الأخطاء بنية المشكلة المشتركة مع: request_id. راجع أخطاء API والرصيد لمعرفة الشكل وترويسات الرصيد. لا تُحاسَب الطلبات الفاشلة.

الرمز	الحالة	المعنى
`invalid_query`	400	معامل مفقود أو غير معروف أو مكرر أو خارج نطاقه.
`invalid_id`	400	معرّف أو زوج غير مكتوب بالصيغة التي تتوقعها هذه الواجهة.
`too_many_ids`	400	تحتوي الدفعة على أكثر من 50 معرّفًا.
`invalid_interval`	400	الفاصل الزمني ليس 1d ولا 1m، أو غير متاح لهذه الأداة.
`range_too_large`	400	النافذة أطول مما يسمح به المسار.
`not_found`	404	لا يوجد رمز مُدرج أو صندوق أو زوج بهذا المعرّف.
`invalid_cursor`	400	مؤشر الصفحة هذا لم يُعده هذا الطلب، أو أنه من طلب مختلف.
`insufficient_credits`	402	رصيدك أقل من تكلفة الطلب.
`area_unavailable`	503	هذا القسم لا يستطيع الإجابة الآن.

هل كانت هذه الصفحة مفيدة؟