صيغ البيانات والوحدات

اتجاهان لكل سعر

لكل رمز تطلبه، يحتوي rates على رقمين. بالنسبة إلى الذهب (XAU) مع عملة الأساس USD:

• USDXAU: سعر أونصة تروي واحدة من الذهب بالدولار الأمريكي، مثل 3997.89. هذا هو الرقم الذي يُعرض للمستخدمين.
• XAU: المقلوب، أي عدد أونصات التروي من الذهب مقابل دولار أمريكي واحد، مثل 0.0002501319446. وتُحفظ هذه الصيغة للتوافق مع واجهات API على نمط أسواق العملات (الفوركس).

وتتبع العملات القاعدة نفسها: مع عملة الأساس USD، يكون USDEUR سعر يورو واحد بالدولار، وEUR عدد اليوروهات مقابل دولار واحد.

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "EUR": 0.8589589418,
    "USDEUR": 1.1642
  }
}

اختيار عملة الأساس

يحدد base عملة كل سعر في الاستجابة. قيمته الافتراضية USD، ويقبل أي رمز مدعوم: EUR أو GBP أو JPY، بل حتى BTC أو XAU إذا أردت تقييم الأشياء بالبيتكوين أو بالذهب. تُحسب الأسعار المتقاطعة من اللقطة نفسها، لذا تبقى دائمًا متسقة فيما بينها.

يُرجع هذا الطلب EURXAU، أي سعر أونصة تروي من الذهب باليورو:

GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR&currencies=XAU,XAG

وحدات الكتلة

أسعار المعادن لكل أونصة تروي (31.1035 غرامًا) ما لم تمرّر unit. القيم المدعومة:

• troy_oz (الافتراضية)، وgram، وkilogram، وounce (أونصة أفواردوبوا، 28.35 غرامًا)، وpound، وmetric_ton، وshort_ton

تُقبل أيضًا الصيغ المختصرة مثل g وkg وlb وtonne. لاحظ أن oz تعني أونصة الأفواردوبوا؛ استخدم troy_oz، أو احذف unit، للحصول على أونصة التروي التي تُسعَّر بها السبائك.

تنطبق unit على المعادن الثمينة والصناعية فقط. تبقى أسعار الطاقة لكل برميل أو MMBtu أو غالون، ولا تتأثر العملات والعملات المشفرة. وعند استخدام وحدة غير الافتراضية، تتضمن الاستجابة الحقل unit. للطلب GET /api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram:

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAU": 0.009057444725,
    "EURXAU": 110.4064149,
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

المعادن الصناعية والطاقة

تُسعَّر المعادن الصناعية (XCU النحاس، وALU الألومنيوم، وZNC الزنك، وHRC لفائف الصلب المدرفلة على الساخن) افتراضيًا لكل أونصة تروي مثل أي معدن آخر، بحيث يمكن مقارنة جميع المعادن مباشرةً. وللحصول على الوحدة التي يُتداول بها كل سوق، مرّر unit=pound للنحاس، وunit=metric_ton للألومنيوم والزنك، وunit=short_ton للصلب.

أسعار الطاقة لكل وحدة عقد: WTI وBRENT لكل برميل، وNATURALGAS لكل MMBtu، وGASOLINE وHEATINGOIL لكل غالون.

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XCU&unit=pound

الرموز المدعومة

• المعادن الثمينة: XAU الذهب، XAG الفضة، XPT البلاتين، XPD البلاديوم
• المعادن الصناعية: XCU النحاس، ALU الألومنيوم، ZNC الزنك، HRC الصلب
• الطاقة: WTI، BRENT، NATURALGAS، GASOLINE، HEATINGOIL
• العملات: نحو 55 عملة وفق معيار ISO 4217، منها USD وEUR وGBP وJPY وCHF وCAD وAUD وCNY وINR
• العملات المشفرة: BTC، ETH، SOL، XRP، BNB، ADA، DOGE، DOT، LINK، LTC، TRX، USDT، USDC

القائمة الكاملة المحدّثة موجودة في صفحة الرموز ومتاحة أيضًا عبر /api/v1/symbols.

أسعار الطلب والعرض

في خطة Standard وما فوقها، أضف -BID أو -ASK إلى رمز في currencies لتلقي سعري الطلب والعرض إلى جانب السعر الوسطي. وهي متاحة للرموز المسعّرة من مصادر ما بين البنوك، أي المعادن الثمينة والعملات الرئيسية. للطلب currencies=XAU,XAU-BID,XAU-ASK:

"rates": {
  "XAU": 0.0002501319446,
  "USDXAU": 3997.89,
  "XAU-BID": 0.0002501488386,
  "USDXAU-BID": 3997.62,
  "XAU-ASK": 0.0002501150529,
  "USDXAU-ASK": 3998.16
}

أسعار الذهب حسب العيار

تُرجع /carat أسعار الذهب بعيارات المجوهرات، حيث النقاوة = العيار ÷ 24، بأي عملة ووحدة. وهي متاحة في الخطط المدفوعة. للطلب GET /api/v1/carat?carat=all&unit=gram (مختصرًا):

{
  "success": true,
  "carat": "all",
  "date": "2026-10-23",
  "base": "USD",
  "timestamp": 1792765800,
  "rates": {
    "XAU24K": { "price": 128.53515, "unit": "gram", "carat": "24", "purity": 1 },
    "XAU22K": { "price": 117.82389, "unit": "gram", "carat": "22", "purity": 0.916667 },
    "XAU18K": { "price": 96.401361, "unit": "gram", "carat": "18", "purity": 0.75 },
    "XAU14K": { "price": 74.978836, "unit": "gram", "carat": "14", "purity": 0.583333 }
  }
}

الطوابع الزمنية والتواريخ

timestamp هو وقت Unix بالثواني (UTC) للأسعار المُرجعة، وdate هو اليوم نفسه بصيغة YYYY-MM-DD بتوقيت UTC. تحمل الاستجابات التاريخية الطابع الزمني 00:00 UTC لليوم المطلوب، وتحتوي على أسعار إغلاق ذلك اليوم.

const date = new Date(data.timestamp * 1000);
console.log(date.toISOString()); // 2026-10-23T14:30:00.000Z

الدقة

الأسعار أرقام JSON تصل إلى 10 أرقام معنوية، وهذا يكفي للأسعار المقلوبة مثل 0.0002501319446. لا تقرّب القيمة إلا عند عرضها، وليس قبل إجراء الحسابات بها.

ساعات التداول وعطلات نهاية الأسبوع

تُتداول المعادن الفورية والعملات على مدار الساعة في أيام العمل. تُغلق الأسواق يوم الجمعة الساعة 17:00 بتوقيت نيويورك وتُعاد فتحها يوم الأحد الساعة 17:00. وخلال عطلة نهاية الأسبوع تتجمد الأسعار عند آخر تسعير، وتستمر الواجهة في إرجاع سعر إغلاق يوم الجمعة (وتعرض صفحات الرموز عبارة «السوق مغلق»).

تُتداول العملات المشفرة على مدار الساعة طوال أيام الأسبوع، وتستمر في التحديث خلال عطلات نهاية الأسبوع. أما المعادن الصناعية والطاقة فتتبع ساعات التداول في بورصات العقود الآجلة الخاصة بها.