استرجع تاريخاً كاملاً
اقرأ كل السجل صفحة بصفحة واحفظه في ملف واستأنف إذا توقف.
اقرأ الدليل ←جميع واجهات API
API العقود الآجلة للسلع: النفط والمعادن والحبوب والماشية
احصل على آخر سعر وتاريخ يومي أو بدقيقة واحدة لـ 13 عقدًا آجلًا للسلع عبر REST أو MCP. كل سلسلة هي عقد الشهر الأقرب، لذا تقفز الأسعار في أيام التدوير.
الطلب الأول
الحصول على آخر سعر لخام WTI
curl --request GET \
--url "https://api.narwhalapi.com/v1/futures/CL/price" \
--header "Authorization: Bearer $NARWHAL_API_KEY"استجابة نموذجية
{
"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
}نقاط النهاية
GETعرض العقود الآجلة/v1/futures
اعرض كل عقد آجل نسعّره، مع اسمه وفئته وبورصته وعملته ووحدته.
حقول الاستجابة
futuresقائمة كائناتكل عقد نسعّره، مع معرّفه واسمه وفئته وبورصته وعملته ووحدته.
المرجع الكامل ←
GETالحصول على سعر عقد آجل/v1/futures/{id}/price
احصل على آخر سعر لعقد واحد.
المعلمات
idمطلوبمعرّف العقد الآجل: الرمز الجذري في البورصة، مثل CL أو GC أو ES أو 6E. تصلح أي حالة أحرف. السلسلة هي الشهر الأقرب المتصل دون تعديل: وفيها فجوة في كل يوم تدوير.
حقول الاستجابة الرئيسية
idسلسلة نصيةالرمز الجذري، مثل CL.
nameسلسلة نصيةالاسم الرسمي للعقد.
commodity_keyسلسلة نصيةمفتاح ثابت للسلعة، وهو نفسه في الأسعار الفورية والعقود الآجلة والتوقعات والأسعار الفعلية، مثل gold أو crude-oil. استخدمه لربطها معًا. يُحذف لعقود مؤشرات الأسهم وأسعار الفائدة والعملات الآجلة.
benchmarkإحدى القيم: wti, brent, urals, dubaiمرجع النفط الخام: wti أو brent أو urals أو dubai. يُرسل للنفط الخام فقط؛ وصف النفط الخام الذي لا يحمله يمثل النفط الخام ككل.
exchangeسلسلة نصيةالبورصة التي يُتداول فيها العقد.
exchange_micسلسلة نصيةرمز معرّف السوق للبورصة وفق ISO 10383، مثل XNYM.
currencyسلسلة نصيةعملة السعر.
unitسلسلة نصيةالوحدة التي يُقاس بها السعر، مثل usd_per_barrel أو index_point.
unit_keyسلسلة نصيةالاسم القياسي للوحدة بأحرف صغيرة، وهو نفسه في كل واجهة تستخدمها، مثل barrel أو troy_ounce أو mmbtu أو tonne. ويحافظ unit على صياغة المصدر.
price_scaleسلسلة نصيةيُرسل فقط عندما يكون السعر مقوّماً بوحدة فرعية. اضرب price فيه لتحصل على السعر بوحدة currency: القيمة 0.01 تعني أن price بالسنتات، فالسعر 450 مع unit بالقيمة cent_per_bushel يساوي 4.50 دولار أمريكي للبوشل.
المرجع الكامل ←
GETالحصول على عدة أسعار للعقود الآجلة/v1/futures/prices
احصل على آخر أسعار ما يصل إلى 50 عقدًا في استدعاء واحد.
المعلمات
idsمطلوبمعرّفات مفصولة بفواصل، بحد أقصى 50 بعد حذف المكرر. يخضع كل معرّف لقواعد مسار السعر الواحد نفسها. يُحتسب استدعاء واحد لكل معرّف يعيد سعرًا.
حقول الاستجابة
pricesقائمة كائناتعنصر واحد لكل معرّف أعاد سعرًا، بحقول السعر الفردي نفسها.
errorsقائمة كائناتالمعرّفات التي لم تُرجع سعرًا، لكل منها الرمز not_found. وهي مجانية.
المرجع الكامل ←
GETالحصول على أشرطة العقود الآجلة/v1/futures/{id}/bars
احصل على أشرطة يومية أو بدقيقة واحدة لعقد واحد، من الأقدم إلى الأحدث. الأسعار هي أسعار الشهر الأقرب الخام، لذا تقفز في أيام التدوير.
المعلمات
idمطلوبمعرّف العقد الآجل: الرمز الجذري في البورصة، مثل CL أو GC أو ES أو 6E. تصلح أي حالة أحرف. السلسلة هي الشهر الأقرب المتصل دون تعديل: وفيها فجوة في كل يوم تدوير.
intervalاختياري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سلسلة نصيةالرمز الجذري، مثل CL.
commodity_keyسلسلة نصيةمفتاح ثابت للسلعة، وهو نفسه في الأسعار الفورية والعقود الآجلة والتوقعات والأسعار الفعلية، مثل gold أو crude-oil. استخدمه لربطها معًا. يُحذف لعقود مؤشرات الأسهم وأسعار الفائدة والعملات الآجلة.
benchmarkإحدى القيم: wti, brent, urals, dubaiمرجع النفط الخام: wti أو brent أو urals أو dubai. يُرسل للنفط الخام فقط؛ وصف النفط الخام الذي لا يحمله يمثل النفط الخام ككل.
currencyسلسلة نصيةعملة السعر.
price_scaleسلسلة نصيةيُرسل فقط عندما يكون السعر مقوّماً بوحدة فرعية. اضرب price فيه لتحصل على السعر بوحدة currency: القيمة 0.01 تعني أن price بالسنتات، فالسعر 450 مع unit بالقيمة cent_per_bushel يساوي 4.50 دولار أمريكي للبوشل.
startسلسلة نصيةيُرسل فقط عندما يُنقل بدء النطاق إلى الأمام.
endسلسلة نصيةلا يُرسل، لأن الأسعار مباشرة لكل حساب.
barsقائمة كائناتالأشرطة من الأقدم إلى الأحدث. يحتوي كل منها على timestamp وopen وhigh وlow وclose، ولا يحتوي على حجم تداول.
next_cursorسلسلة نصيةأعد إرساله لقراءة الصفحة التالية. تكون قيمته null في الصفحة الأخيرة.
المرجع الكامل ←
حالات الاستخدام
سحب يومي للبيانات
شغّل سكربتًا صغيرًا مرة في اليوم وأضف النتيجة إلى ملف CSV.
اقرأ الدليل ←التخزين المؤقت وأخطاء 429
Cache responses by data type and tell a rate limit (429) from an empty credit balance (402).
اقرأ الدليل ←التغطية
الطاقة
- خام WTICL · NYMEX · دولار أمريكي لكل برميل
- الغاز الطبيعي Henry HubNG · NYMEX · دولار أمريكي لكل MMBtu
- بنزين RBOBRB · NYMEX · دولار أمريكي لكل غالون
- وقود الديزل منخفض الكبريت في ميناء نيويورك (NY Harbor ULSD)HO · NYMEX · دولار أمريكي لكل غالون
المعادن
- الذهبGC · COMEX · دولار أمريكي لكل أونصة تروي
- الفضةSI · COMEX · دولار أمريكي لكل أونصة تروي
- البلاتينPL · NYMEX · دولار أمريكي لكل أونصة تروي
- النحاسHG · COMEX · دولار أمريكي لكل رطل
الحبوب
- الذرةZC · CBOT · سنتات لكل بوشل
- قمح شيكاغو SRWZW · CBOT · سنتات لكل بوشل
- فول الصوياZS · CBOT · سنتات لكل بوشل
Livestock
- الماشية الحيةLE · CME · سنتات لكل رطل
- الخنازير الحية (Lean Hog)HE · CME · سنتات لكل رطل
واجهات API ذات صلة
futures API لبيانات العقود الآجلة
الأسعار والتاريخ لـ 29 عقدًا آجلًا عبر REST وMCP
استكشف API ←واجهة API لأسعار المعادن الفورية
أسعار الذهب والفضة والبلاتين والبلاديوم الفورية، إضافة إلى أسعار WTI وبرنت والنحاس المرجعية.
استكشف API ←API المؤشرات
المستويات والتاريخ لـ 18 مؤشرًا عبر REST وMCP
استكشف API ←الأسعار
رصيد مجاني بقيمة 10 دولارات شهريًا، ثم ابتداءً من 2 دولار لكل 1,000 استدعاء.
عرض الأسعار ←الأسئلة الشائعة
ما العقود الآجلة للسلع التي يمكنني الحصول عليها؟
13 عقدًا. الطاقة: خام WTI والغاز الطبيعي Henry Hub وبنزين RBOB ووقود الديزل منخفض الكبريت في ميناء نيويورك. المعادن: الذهب والفضة والبلاتين والنحاس. الحبوب: الذرة والقمح وفول الصويا. الماشية: الماشية الحية والخنازير الحية.
ما الفرق بينها وبين API السعر الفوري؟
يسعّر API الفوري الذهب بعملات كثيرة، والفضة والبلاتين والبلاديوم بالدولار الأمريكي. أما العقود الآجلة للسلع فهي عقد الشهر الأقرب بالدولار الأمريكي وبوحدة العقد نفسه. العقود الآجلة للذهب (GC) والذهب الفوري (XAU) سعران مختلفان.
لماذا يقفز السعر في بعض الأيام؟
كل سلسلة هي عقد الشهر الأقرب، موصولة طرفًا بطرف دون تعديل. عندما يتغير الشهر الأقرب تنتقل السلسلة إلى العقد التالي ويقفز السعر إلى سعر ذلك العقد. وقد قفز CL بنحو 4 دولارات في 19 أكتوبر 2026. تعرض الأسعار والأشرطة هذه القفزة كما جرى تداولها، فلا تقرأها على أنها حركة يوم واحد. ولهذا أيضًا لا يحتوي سعر العقد الآجل على إغلاق سابق أو تغير: فعبر التدوير سيكون أي تغير خاطئًا.
ما وحدة السعر؟
تحمل كل إجابة وحدة. الوحدة لـ CL هي usd_per_barrel، ولـ NG هي usd_per_mmbtu، ولـ RB وHO هي usd_per_gallon، ولـ GC وSI وPL هي usd_per_troy_ounce، ولـ HG هي usd_per_pound. الحبوب بوحدة cent_per_bushel والماشية بوحدة cent_per_pound، فهذه الأسعار بالسنتات لا بالدولارات.
هل الأسعار مباشرة أم متأخرة؟
الأسعار مباشرة لكل حساب. تعود الشموع اليومية إلى أبريل 2017، ويحصل كل حساب على التاريخ الكامل.
كم التكلفة؟
تكلفة الاستدعاءات 2 دولار لكل 1,000 استدعاء من رصيد الائتمان المدفوع مسبقًا. يحصل كل حساب على 10 دولارات من الرصيد المجاني كل شهر خلال أول 12 شهرًا.
ابدأ بمفتاح مجاني
رصيد مجاني بقيمة 10 دولارات كل شهر لمدة 12 شهرًا. لا حاجة إلى بطاقة.رصيد مجاني بقيمة 10 دولارات كل شهر. لا حاجة إلى بطاقة.