البدء مع MetalAPI

مقدمة

MetalAPI واجهة JSON REST API لأسعار المعادن الثمينة الفورية والمعادن الصناعية والطاقة ونحو 55 عملة و13 عملة مشفرة. تقدّم الأسعار اللحظية، والسجل اليومي حتى عام 1999، وتحويل المبالغ، وأشرطة OHLC، وأسعار الذهب حسب العيار.

كل نقطة نهاية هي طلب HTTPS GET بسيط تحت https://metalapi.com/api/v1، لذا تعمل مع أي لغة برمجة أو عميل HTTP. يأخذك هذا الدليل من التسجيل إلى أول استجابة في بضع دقائق.

احصل على مفتاح API

أنشئ حسابًا مجانيًا باستخدام بريدك الإلكتروني، دون الحاجة إلى بطاقة ائتمان. تتيح خطة Free إرسال 100 طلب شهريًا مع تحديث يومي للأسعار، وهذا يكفي لتجربة الواجهة.

افتح API keys في لوحة التحكم وأنشئ مفتاحًا. تبدأ المفاتيح بـ mk_live_ يليها 32 حرفًا. لا نخزّن إلا قيمة تجزئة لكل مفتاح، لذا يُعرض المفتاح كاملًا مرة واحدة فقط. انسخه فورًا إلى مدير كلمات المرور أو إلى متغيرات البيئة.

أرسل طلبك الأول

اطلب أحدث أسعار المعادن الثمينة الأربعة بالدولار الأمريكي. استبدل YOUR_API_KEY بمفتاحك:

curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,XPT,XPD"

فهم الاستجابة

يحدد base العملة التي تُعرض بها الأسعار (افتراضيًا USD). ويقصر currencies الاستجابة على الرموز التي تحتاجها؛ احذفه لتتلقى جميع الرموز في استجابة واحدة. يُرجع الطلب الناجح JSON على النحو التالي:

{
  "success": true,
  "timestamp": 1792713600,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "XAG": 0.01853911754,
    "USDXAG": 53.94,
    "XPT": 0.000620212733,
    "USDXPT": 1612.35,
    "XPD": 0.0006775985906,
    "USDXPD": 1475.8
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 99,
    "reset": 1793491200,
    "used": 1,
    "plan": "Free",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

يظهر كل رمز مرتين. USDXAU هو سعر أونصة تروي واحدة من الذهب بعملة الأساس، وهو عادةً الرقم الذي تريد عرضه. أما XAU فهو المقلوب: عدد أونصات التروي التي يشتريها دولار أمريكي واحد. ويشرح دليل صيغ البيانات الاتجاهين بالتفصيل.

تُظهر كتلة rate_limit، التي تُرسل أيضًا في ترويسات X-RateLimit-*، المتبقي من حصتك الشهرية وموعد إعادة تعيينها.

الاستدعاء من الشيفرة البرمجية

إليك الطلب نفسه من JavaScript (Node.js 18+ أو Deno أو Bun). هذه المرة يُرسل المفتاح في ترويسة بدلًا من عنوان URL:

const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
});
const data = await res.json();

if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
console.log("Gold, USD per troy ounce:", data.rates.USDXAU);

الخطوات التالية

• المصادقة: إرسال المفاتيح في الترويسات، والمفاتيح المقيّدة بالنطاق للاستخدام في المتصفح.
• نقاط النهاية المتاحة: الأسعار التاريخية والتحويل والسلاسل الزمنية وOHLC وأسعار الذهب حسب العيار.
• حدود المعدل والخطط: الحصص وحدود الطلبات في الدقيقة وفترات التحديث.
• معالجة الأخطاء: رموز الأخطاء واستراتيجية مدروسة لإعادة المحاولة.