التوثيق
مرجع واجهة API لأسعار المعادن الفورية
الأسعار الفورية للذهب والفضة والبلاتين والبلاديوم، إضافةً إلى الأسعار المرجعية لخام WTI وخام برنت والنحاس، مع الوحدات والطوابع الزمنية بتوقيت UTC.
المصادقة والطلب
أرسل مفتاح API في ترويسة Authorization باستخدام Bearer. نظرة عامة على المنتج ←
curl "https://api.narwhalapi.com/v1/commodities/spot/XAU/USD" \
--header "Authorization: Bearer $NARWHAL_API_KEY"العمليات
| نقطة النهاية | عملية |
|---|---|
GET /v1/commodities/spot/{commodity}/{currency} | احصل على سعر فوري أو سعر مرجعي مشتق من العقود الآجلة. |
GET /v1/commodities/spot/{commodity}/{currency}/bars | احصل على أعمدة أسعار الافتتاح والأعلى والأدنى والإغلاق للذهب والفضة والبلاتين والبلاديوم وWTI وBRENT. سجل أسعار النحاس غير متاح بعد. |
المعلمات
| حقل | المعنى |
|---|---|
commodity | معلمة مسار. XAU أو XAG أو XPT أو XPD أو WTI (خام غرب تكساس الوسيط) أو BRENT (خام برنت) أو XCU (النحاس). |
currency | معلمة مسار بأحرف كبيرة. الذهب: USD, AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY أو ZAR. الفضة والبلاتين والبلاديوم وWTI وBRENT وXCU: بعملة USD فقط. |
interval | للأعمدة فقط. 1m أو 5m أو 15m أو 1h أو 4h أو 1d (الافتراضي). |
start / end | للأعمدة فقط. لحظات بتوقيت UTC عند حدود الفواصل الكاملة (4h عند 00 و04 و08 وهكذا؛ و1d عند منتصف الليل). تشمل البداية ولا تشمل النهاية. |
limit / cursor | للأعمدة فقط. الافتراضي 100، والحد الأقصى 500. أعد استخدام next_cursor مع الاستعلام نفسه. |
حقول السعر
| حقل | المعنى |
|---|---|
symbol, currency, unit | الرمز وعملة التسعير. قيمة unit هي troy_ounce للمعادن الثمينة، وbarrel لخامَي WTI وBRENT، وpound للنحاس XCU. |
price | سعر إرشادي واحد موجب بصيغة سلسلة نصية لعدد عشري. |
timestamp, stale | الطابع الزمني للسعر بتوقيت UTC ومؤشر صريح لحداثة البيانات. |
bars | للأعمدة فقط. أعمدة مكتملة، الأقدم أولًا، يتضمن كل منها timestamp (بداية العمود) وopen وhigh وlow وclose كسلاسل نصية بأربع منازل عشرية. للذهب بعملات غير USD، يتوفر close فقط. |
next_cursor | للأعمدة فقط. مؤشر متابعة؛ قيمته null عندما لا تتبقى أعمدة. |
استجابة توضيحية لـ GET /v1/commodities/spot/{commodity}/{currency}.
{
"symbol": "XAU-USD",
"price": "2500.00",
"currency": "USD",
"unit": "troy_ounce",
"timestamp": "2026-08-21T12:00:00Z",
"stale": true
}تفسير البيانات
أسعار WTI وBRENT وXCU هي أسعار مرجعية مشتقة من أسواق العقود الآجلة، وليست أسعارًا فورية لشحنات فعلية. اعرض الوحدة والطابع الزمني مع السعر. يمثل الطابع الزمني بداية الدقيقة التي يعود إليها السعر؛ وتُرجع الاستجابة stale: true خلال فترة التوقف اليومية 21:00-22:00 UTC. قد يكون السعر متقادمًا أثناء إغلاق الأسواق؛ فلا تعرضه على أنه سعر سوق حديث. تُرجع تركيبات السلع أو العملات الأخرى 404. يتوفر سجل الأسعار للذهب والفضة والبلاتين والبلاديوم وWTI وBRENT، لكنه غير متاح لـXCU. لا نملأ الفجوات أبدًا: تبقى الأعمدة المفقودة مفقودة. نحتفظ بأعمدة الدقائق لمدة 30 يومًا وبأعمدة الساعات والأيام دون حد زمني، ضمن نطاق السجل التاريخي في خطتك. يتوفر سجل WTI وBRENT بفاصل 15 دقيقة وفاصل ساعة منذ عام 2020.
أدوات MCP
commodities_get_spot_pricecommodities_get_price_history