تصفّح التوثيق كاملًا

مرجع futures API للعقود الآجلة

الأسعار والسجل التاريخي لـ 29 عقدًا آجلًا

نظرة عامة

أسعار وسجل أسعار 29 عقدًا آجلًا: سلع ومؤشرات أسهم وسندات خزانة وعملات. يحتاج كل طلب إلى مفتاح Bearer، ويسحب REST وMCP من رصيد واحد.

المعرّف هو الرمز الجذري في البورصة، مثل CL لخام WTI، وGC للذهب، وES لعقد E-mini S&P 500، و6E لليورو. تصلح أي حالة أحرف. يعيد مسار القائمة كل معرّف مع اسمه وفئته وبورصته وعملته ووحدته.

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

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

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

ماكل حساب
أحدث سعرمباشر
أشرطة يوميةالسجل الكامل، منذ أبريل 2017
شموع الدقيقة الواحدةآخر 12 شهرًا
قائمة السلاسلمشمول

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

  • لا يحمل سعر العقد الآجل إغلاقًا سابقًا ولا تغيرًا ولا حجم تداول. وأي تغير عبر تدوير العقد سيكون غير صحيح، لذلك لا تحسبه الواجهة.
  • الأسعار والشموع هي الشهر الأقرب كما جرى تداوله. وتقفز في كل يوم تدوير: قفز CL بنحو 4 دولارات في 19 أكتوبر 2026. لا تقرأ هذه القفزة على أنها حركة يوم واحد.
  • تكون market_session بالقيمة open أو closed بحسب ساعات العقد المنشورة. السلسلة المغلقة تجيب بآخر سعر لها وليست قديمة. والسلسلة المفتوحة تكون قديمة (stale) إذا تجاوز عمر سعرها 15 دقيقة.
  • الشمعة اليومية تمثل يوم تداول واحدًا وتظهر عند 00:00 UTC. ولا تظهر شمعة اليوم الجزئية أبدًا.
  • تُحفظ شموع الدقيقة الواحدة 12 شهرًا، ويغطي الطلب الواحد 5 أيام كحد أقصى.
  • تحتوي الدفعة على 50 معرّفًا كحد أقصى وتُحتسب استدعاءً واحدًا لكل معرّف يعيد سعرًا. المعرّف غير المعروف يُدرج في errors ولا يُحتسب.

نقاط النهاية

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

العقود الآجلة التي نسعّرها

GET /v1/futures

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

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

المعلمات

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

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

حقلالنوعيُرسلالمعنى
futuresقائمة كائناتدائمًاكل سلسلة نسعّرها، مرتبة حسب المعرّف.
futures[].idسلسلة نصيةدائمًاالرمز الجذري، مثل CL.
futures[].nameسلسلة نصيةدائمًااسم السلسلة.
futures[].categoryإحدى القيم: energy, metals, grains, livestock, equity_index, interest_rate, currencyدائمًا
futures[].commodity_keyسلسلة نصيةاختياريمفتاح ثابت للسلعة، وهو نفسه في الأسعار الفورية والعقود الآجلة والتوقعات والأسعار الفعلية، مثل gold أو crude-oil. استخدمه لربطها معًا. يُحذف لعقود مؤشرات الأسهم وأسعار الفائدة والعملات الآجلة.
futures[].benchmarkإحدى القيم: wti, brent, urals, dubaiاختياريمرجع النفط الخام: wti أو brent أو urals أو dubai. يُرسل للنفط الخام فقط؛ وصف النفط الخام الذي لا يحمله يمثل النفط الخام ككل.
futures[].exchangeسلسلة نصيةدائمًاالبورصة التي تُدرجه.
futures[].exchange_micسلسلة نصيةاختياريرمز معرّف السوق للبورصة وفق ISO 10383، مثل XNYM.
futures[].currencyسلسلة نصيةدائمًاعملة السعر.
futures[].unitسلسلة نصيةدائمًاالوحدة التي يُقاس بها السعر، مثل usd_per_barrel أو index_point.
futures[].unit_keyسلسلة نصيةاختياريالاسم القياسي للوحدة بأحرف صغيرة، وهو نفسه في كل واجهة تستخدمه، مثل barrel أو troy_ounce أو mmbtu أو tonne. ويحتفظ unit بصياغة المصدر.
futures[].price_scaleسلسلة نصيةاختيارييُرسل فقط عندما يكون السعر مسعّرًا بوحدة صغرى. اضرب price فيه لتحصل على السعر بعملة currency: القيمة 0.01 تعني أن price بالسنتات، فسعر 450 بوحدة cent_per_bushel يساوي 4.50 USD للبوشل الواحد.
طلب
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures"
استجابة نموذجية
{
  "futures": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "category": "energy",
      "exchange": "NYMEX",
      "currency": "USD",
      "unit": "usd_per_barrel"
    },
    {
      "id": "GC",
      "name": "Gold",
      "category": "metals",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce"
    }
  ]
}

آخر سعر لسلسلة عقود آجلة واحدة

GET /v1/futures/{id}/price

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

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

المعلمات

معلمةالموضعمطلوبالنوعالمعنى
idمسارنعمسلسلة نصيةمعرّف العقد الآجل: الرمز الجذري في البورصة، مثل CL أو GC أو ES أو 6E. تصلح أي حالة أحرف. السلسلة هي الشهر الأقرب المتصل دون تعديل: وفيها فجوة في كل يوم تدوير.

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

حقلالنوعيُرسلالمعنى
idسلسلة نصيةدائمًاالرمز الجذري.
nameسلسلة نصيةدائمًاالاسم كما تحتفظ به قائمة الرموز لدينا.
commodity_keyسلسلة نصيةاختياريمفتاح ثابت للسلعة، وهو نفسه في الأسعار الفورية والعقود الآجلة والتوقعات والأسعار الفعلية، مثل gold أو crude-oil. استخدمه لربطها معًا. يُحذف لعقود مؤشرات الأسهم وأسعار الفائدة والعملات الآجلة.
benchmarkإحدى القيم: wti, brent, urals, dubaiاختياريمرجع النفط الخام: wti أو brent أو urals أو dubai. يُرسل للنفط الخام فقط؛ وصف النفط الخام الذي لا يحمله يمثل النفط الخام ككل.
exchangeسلسلة نصيةدائمًا
exchange_micسلسلة نصيةاختياريرمز معرّف السوق للبورصة وفق ISO 10383، مثل XNYM.
currencyسلسلة نصيةدائمًاعملة الأسعار.
unitسلسلة نصيةدائمًا
unit_keyسلسلة نصيةاختياريالاسم القياسي للوحدة بأحرف صغيرة، وهو نفسه في كل واجهة تستخدمه، مثل barrel أو troy_ounce أو mmbtu أو tonne. ويحتفظ unit بصياغة المصدر.
price_scaleسلسلة نصيةاختيارييُرسل فقط عندما يكون السعر مسعّرًا بوحدة صغرى. اضرب price فيه لتحصل على السعر بعملة currency: القيمة 0.01 تعني أن price بالسنتات، فسعر 450 بوحدة cent_per_bushel يساوي 4.50 USD للبوشل الواحد.
priceسلسلة نصيةدائمًاآخر سعر للشهر الأقرب المتصل.
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/futures/CL/price"
استجابة نموذجية
{
  "id": "CL",
  "name": "WTI Crude Oil",
  "commodity_key": "crude-oil",
  "benchmark": "wti",
  "exchange": "NYMEX",
  "exchange_mic": "XNYM",
  "currency": "USD",
  "unit": "usd_per_barrel",
  "unit_key": "barrel",
  "price": "102.11",
  "market_session": "open",
  "timestamp": "2026-10-29T18:38:00Z",
  "stale": false
}

آخر أسعار حتى 50 سلسلة عقود آجلة

GET /v1/futures/prices

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

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

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

المعلمات

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

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

حقلالنوعيُرسلالمعنى
pricesقائمة كائناتدائمًاسعر واحد لكل معرّف تم حله، مفهرسًا بالمعرّف.
prices[].idسلسلة نصيةدائمًاالرمز الجذري.
prices[].nameسلسلة نصيةدائمًاالاسم كما تحتفظ به قائمة الرموز لدينا.
prices[].commodity_keyسلسلة نصيةاختياريمفتاح ثابت للسلعة، وهو نفسه في الأسعار الفورية والعقود الآجلة والتوقعات والأسعار الفعلية، مثل gold أو crude-oil. استخدمه لربطها معًا. يُحذف لعقود مؤشرات الأسهم وأسعار الفائدة والعملات الآجلة.
prices[].benchmarkإحدى القيم: wti, brent, urals, dubaiاختياريمرجع النفط الخام: wti أو brent أو urals أو dubai. يُرسل للنفط الخام فقط؛ وصف النفط الخام الذي لا يحمله يمثل النفط الخام ككل.
prices[].exchangeسلسلة نصيةدائمًا
prices[].exchange_micسلسلة نصيةاختياريرمز معرّف السوق للبورصة وفق ISO 10383، مثل XNYM.
prices[].currencyسلسلة نصيةدائمًاعملة الأسعار.
prices[].unitسلسلة نصيةدائمًا
prices[].unit_keyسلسلة نصيةاختياريالاسم القياسي للوحدة بأحرف صغيرة، وهو نفسه في كل واجهة تستخدمه، مثل barrel أو troy_ounce أو mmbtu أو tonne. ويحتفظ unit بصياغة المصدر.
prices[].price_scaleسلسلة نصيةاختيارييُرسل فقط عندما يكون السعر مسعّرًا بوحدة صغرى. اضرب price فيه لتحصل على السعر بعملة currency: القيمة 0.01 تعني أن price بالسنتات، فسعر 450 بوحدة cent_per_bushel يساوي 4.50 USD للبوشل الواحد.
prices[].priceسلسلة نصيةدائمًاآخر سعر للشهر الأقرب المتصل.
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/futures/prices?ids=CL,GC,ES"
استجابة نموذجية
{
  "prices": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "commodity_key": "crude-oil",
      "benchmark": "wti",
      "exchange": "NYMEX",
      "exchange_mic": "XNYM",
      "currency": "USD",
      "unit": "usd_per_barrel",
      "unit_key": "barrel",
      "price": "102.11",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    },
    {
      "id": "GC",
      "name": "Gold",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce",
      "price": "4021.3",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XX",
      "code": "not_found"
    }
  ]
}

شموع أسعار سلسلة عقود آجلة واحدة

GET /v1/futures/{id}/bars

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

الشموع هي أسعار الشهر الأقرب الخام، لذا قد تفتتح الشمعة بعيدًا عن إغلاق الشمعة التي قبلها في يوم التدوير.

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

المعلمات

معلمةالموضعمطلوبالنوعالمعنى
idمسارنعمسلسلة نصيةمعرّف العقد الآجل: الرمز الجذري في البورصة، مثل CL أو GC أو ES أو 6E. تصلح أي حالة أحرف. السلسلة هي الشهر الأقرب المتصل دون تعديل: وفيها فجوة في كل يوم تدوير.
intervalاستعلاملاإحدى القيم: 1d, 1m1d (شمعة لكل يوم تداول، تحمل تاريخ اليوم الذي تخصه) أو 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سلسلة نصيةدائمًا
commodity_keyسلسلة نصيةاختياريمفتاح ثابت للسلعة، وهو نفسه في الأسعار الفورية والعقود الآجلة والتوقعات والأسعار الفعلية، مثل gold أو crude-oil. استخدمه لربطها معًا. يُحذف لعقود مؤشرات الأسهم وأسعار الفائدة والعملات الآجلة.
benchmarkإحدى القيم: wti, brent, urals, dubaiاختياريمرجع النفط الخام: wti أو brent أو urals أو dubai. يُرسل للنفط الخام فقط؛ وصف النفط الخام الذي لا يحمله يمثل النفط الخام ككل.
currencyسلسلة نصيةدائمًاعملة الأسعار.
price_scaleسلسلة نصيةاختيارييُرسل فقط عندما يكون السعر مسعّرًا بوحدة صغرى. اضرب price فيه لتحصل على السعر بعملة currency: القيمة 0.01 تعني أن price بالسنتات، فسعر 450 بوحدة cent_per_bushel يساوي 4.50 USD للبوشل الواحد.
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/futures/ES/bars?interval=1d&start=2017-04-03&end=2017-04-05"
استجابة نموذجية
{
  "id": "ES",
  "currency": "USD",
  "bars": [
    {
      "timestamp": "2017-04-03T00:00:00Z",
      "open": "2357.5",
      "high": "2363.25",
      "low": "2340",
      "close": "2354.5"
    }
  ],
  "next_cursor": null
}

الأخطاء

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

الرمزالحالةالمعنى
invalid_query400معامل مفقود أو غير معروف أو مكرر أو خارج نطاقه.
invalid_id400معرّف أو زوج غير مكتوب بالصيغة التي تتوقعها هذه الواجهة.
too_many_ids400تحتوي الدفعة على أكثر من 50 معرّفًا.
invalid_interval400الفاصل الزمني ليس 1d ولا 1m، أو غير متاح لهذه الأداة.
range_too_large400النافذة أطول مما يسمح به المسار.
not_found404لا يوجد رمز مُدرج أو صندوق أو زوج بهذا المعرّف.
invalid_cursor400مؤشر الصفحة هذا لم يُعده هذا الطلب، أو أنه من طلب مختلف.
insufficient_credits402رصيدك أقل من تكلفة الطلب.
area_unavailable503هذا القسم لا يستطيع الإجابة الآن.

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