نقاط النهاية المتاحة

عنوان URL الأساسي والمعاملات المشتركة

جميع نقاط النهاية طلبات GET تحت https://metalapi.com/api/v1 وتتطلب مفتاح API (راجع المصادقة). ويقبل معظمها المعاملات الاختيارية نفسها:

• base: العملة التي تُعرض بها الأسعار. القيمة الافتراضية USD، ويصلح أي رمز مدعوم.
• currencies، أو اسمه البديل symbols: قائمة بالرموز المطلوبة مفصولة بفواصل، مثل XAU,XAG,EUR. احذفه للحصول على جميع الرموز.
• unit: وحدة الكتلة لأسعار المعادن، وهي إحدى القيم troy_oz (الافتراضية) أو gram أو kilogram أو ounce أو pound أو metric_ton أو short_ton.

تُكتب التواريخ بالصيغة YYYY-MM-DD وتُفسَّر بتوقيت UTC.

أحدث الأسعار: /latest

الأسعار الحالية وفق فترة التحديث في خطتك، من التحديث اليومي في Free إلى كل 5 ثوانٍ في Enterprise. في خطة Standard وما فوقها، أضف رموزًا مثل XAU-BID وXAU-ASK إلى currencies لتلقي سعري الطلب والعرض (bid/ask).

GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,EUR

الأسعار التاريخية: /{date}

أسعار الإغلاق ليوم سابق. تُقبل ثلاث صيغ: التاريخ كمسار، أو /historical?date=، أو /yesterday.

GET /api/v1/2026-10-01?api_key=YOUR_API_KEY&currencies=XAU,XAG
GET /api/v1/historical?date=2026-10-01&api_key=YOUR_API_KEY&currencies=XAU,XAG
GET /api/v1/yesterday?api_key=YOUR_API_KEY&currencies=XAU,XAG

التحويل: /convert

يحوّل المبلغ amount من from إلى to، كتحويل الدولارات إلى أونصات من الذهب أو الفضة إلى اليورو. أضف date للتحويل بسعر إغلاق تاريخي، وunit لتحويل غرامات أو كيلوغرامات من معدن ما.

GET /api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000

# 500 grams of silver in euros at the close of 1 October 2026
GET /api/v1/convert?api_key=YOUR_API_KEY&from=XAG&to=EUR&amount=500&unit=gram&date=2026-10-01

النطاق الزمني: /timeframe

أسعار الإغلاق اليومية لكل يوم بين start_date وend_date. يمكن أن يغطي الطلب الواحد حتى 30 يومًا في خطة Free و365 يومًا في الخطط المدفوعة، وتُرجع النطاقات الأطول الخطأ 207. أما /timeseries فهو اسم بديل محفوظ لأغراض التوافق.

GET /api/v1/timeframe?api_key=YOUR_API_KEY&start_date=2026-09-01&end_date=2026-09-30&currencies=XAU

التغيّر: /change

سعر البداية وسعر النهاية والتغيّر المطلق والتغيّر بالنسبة المئوية بين تاريخين لكل رمز. مفيد لعرض عبارات مثل «ارتفع الذهب 3.6% هذا الشهر». وحدود النطاق هي نفسها في /timeframe.

GET /api/v1/change?api_key=YOUR_API_KEY&start_date=2026-09-30&end_date=2026-10-23&currencies=XAU,XAG

OHLC: /ohlc

سعر الافتتاح والأعلى والأدنى والإغلاق ليوم واحد. احذف date، أو مرّر latest، للحصول على شريط اليوم حتى اللحظة.

GET /api/v1/ohlc?api_key=YOUR_API_KEY&date=2026-10-22&currencies=XAU,XAG

الذهب حسب العيار: /carat

أسعار الذهب بعيارات المجوهرات من عيار 24 نزولًا إلى عيار 8، بأي عملة ووحدة. مرّر carat=24 (الافتراضي)، أو عيارًا واحدًا مثل 18، أو carat=all. العيارات المدعومة هي 24 و23 و22 و21 و20 و18 و16 و14 و12 و10 و9 و8. أضف date للحصول على أسعار العيارات التاريخية.

نقطة النهاية هذه متاحة في الخطط المدفوعة، وتتلقى مفاتيح خطة Free الخطأ 106.

GET /api/v1/carat?api_key=YOUR_API_KEY&carat=all&base=EUR&unit=gram

الرموز: /symbols

قائمة الرموز المدعومة وأسماؤها. أضف details=1 لتضمين فئة كل رمز ووحدته. لا تُحتسب نقطة النهاية هذه من حصتك الشهرية.

GET /api/v1/symbols?api_key=YOUR_API_KEY&details=1

الاستهلاك: /usage

الطلبات المستخدمة والمتبقية في شهر الفوترة الحالي. وهي مجانية أيضًا، لذا يمكنك استدعاؤها من أدوات المراقبة دون استهلاك الحصة.

GET /api/v1/usage?api_key=YOUR_API_KEY

البث اللحظي: /stream

بث Server-Sent Events يدفع تحديثات الأسعار فور حدوثها، فلا تحتاج إلى استطلاع /latest بشكل دوري. متاح في خطة Pro وما فوقها، ويصف توثيق البث صيغة الأحداث.

curl -N "https://metalapi.com/api/v1/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"