واجهة API لأسعار الفضة: أسعار XAG اللحظية والتاريخية بصيغة JSON

ما الذي تقدّمه لك واجهة API لأسعار الفضة

تُرجع واجهة API لأسعار الفضة سعر الفضة الحالي والتاريخي كبيانات منظَّمة، بصيغة JSON عبر HTTPS عادةً، حتى يستخدمها متجر أو تطبيق أو تقرير دون نسخ الأرقام من موقع ويب. في MetalAPI، رمز الفضة هو XAG، وهو رمز ISO 4217 لأونصة تروي واحدة من الفضة. وسعره اللحظي هو السعر الفوري: النقطة الوسطى بين سعري الطلب والعرض في سوق الجملة.

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

• سعر الفضة اللحظي في طلب واحد، وكيف تقرؤه.
• أسعار الفضة لكل أونصة وغرام وكيلوغرام.
• الفضة بعملات أخرى، من طلب واحد أيضًا.
• أسعار الفضة التاريخية منذ عام 2000.
• حالات الاستخدام: متاجر السبائك، ومشترو الأواني الفضية والفضة الكسر، وتطبيقات الاستثمار.

كيف تحصل على سعر الفضة اللحظي عبر API

أنشئ حسابًا مجانيًا وأضف مفتاح API من لوحة التحكم. تبدأ المفاتيح بـmk_live_. احفظ مفتاحك في متغير بيئة وأرسله في ترويسة، ثم اطلب /latest مع XAG:

export METALAPI_KEY="mk_live_your_key_here"

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAG" \
  -H "X-API-Key: $METALAPI_KEY"

تبدو الاستجابة على النحو التالي. والأرقام هي القيم النموذجية المستخدمة في توثيق MetalAPI كله، وليست أسعارًا لحظية:

{
  "success": true,
  "timestamp": 1792713600,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAG": 0.01853911754,
    "USDXAG": 53.94
  }
}

USDXAG هو سعر أونصة تروي واحدة من الفضة بعملة الأساس، أي 53.94 دولارًا أمريكيًا في هذا المثال. وXAG هو المعكوس، أي أونصات التروي من الفضة لكل دولار، ويُحتفظ به للتوافق مع واجهات API على نمط سوق العملات. اقرأ دائمًا المفتاح المسبوق بعملة الأساس: فاعتبار rates.XAG هو السعر سيعرض 0.0185 بدلًا من 53.94.

timestamp هو وقت البيانات، لا وقت طلبك. وتُتداول الفضة الفورية على مدار الساعة في أيام العمل، وتتوقف من الجمعة الساعة 17:00 حتى الأحد الساعة 17:00 بتوقيت نيويورك، لذا تواصل الواجهة خلال عطلة نهاية الأسبوع إرجاع سعر إغلاق الجمعة. اعرض الطابع الزمني بجوار السعر، خاصةً يومَي السبت والأحد.

وإذا احتجت أيضًا إلى الذهب أو البلاتين أو البلاديوم، فأضفها إلى الطلب نفسه: currencies=XAU,XAG,XPT,XPD. فالطلب يُحتسب مرة واحدة، مهما كان عدد الرموز التي يُرجعها.

سعر الفضة لكل أونصة وغرام وكيلوغرام

أسعار الفضة لكل أونصة تروي، أي 31.1034768 غرامًا، ما لم تمرّر unit. والقيم المدعومة هي troy_oz (الافتراضية) وgram وkilogram وounce وpound وmetric_ton وshort_ton، وتضيف الاستجابة حقل unit على المستوى الأعلى كلما كانت الوحدة غير الافتراضية:

curl "https://metalapi.com/api/v1/latest?currencies=XAG&unit=kilogram" \
  -H "X-API-Key: $METALAPI_KEY"

بالسعر النموذجي البالغ 53.94 دولارًا لكل أونصة تروي، تكلّف الفضة:

ثمة عادتان تستحقان التبني مع الفضة. أولًا، اعرض منازل عشرية أكثر لسعر الغرام: فعند 1.7342 دولار، تخفي منزلتان عشريتان معظم التحرك اليومي، لذا يشيع استخدام أربع منازل. ثانيًا، إذا كنت تعرض عدة وحدات، فاطلب السعر بأونصة التروي مرة واحدة وحوّل محليًا بدلًا من إرسال طلب لكل وحدة. والمعاملات دقيقة:

const GRAMS_PER_TROY_OZ = 31.1034768;

const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();
if (!data.success) throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);

const perOz = data.rates[`${data.base}XAG`]; // 53.94 in the docs' example
const perGram = perOz / GRAMS_PER_TROY_OZ; // 1.7342...
const perKg = perGram * 1000; // 1734.21...

console.log({ perOz, perGram: perGram.toFixed(4), perKg: perKg.toFixed(2) });

ويسرد مقال أونصة التروي والغرام والكيلوغرام كل المعاملات، بما فيها البنيويت، وقواعد التقريب في الفواتير.

أسعار الفضة بعملات أخرى

اضبط base لتسعير الفضة بعملة أخرى: يُرجع base=EUR المفتاح EURXAG، ويُرجع base=INR المفتاح INRXAG. وبالجمع مع unit، يُرجع هذا الطلب سعر الغرام باليورو:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

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

ولعرض الفضة بعدة عملات، يكفي طلب واحد أيضًا. اطلب الفضة والعملات مع الأساس USD، ثم اقسم: سعر الفضة باليورو هو USDXAG ÷ USDEUR، لأن USDEUR هو سعر اليورو الواحد بالدولار. وجميع القيم تأتي من اللقطة نفسها، لذا تطابق النتيجة ما يُرجعه base=EUR. وبسعر التوثيق النموذجي البالغ 1.1642 دولار لكل يورو، تعطي القسمة 53.94 ÷ 1.1642 مبلغ 46.33 يورو لكل أونصة تروي، أي 1.4896 يورو لكل غرام، وهو الرقم نفسه أعلاه:

import os

import requests

GRAMS_PER_TROY_OZ = 31.1034768
CURRENCIES = ["EUR", "GBP", "INR", "TRY"]

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": ",".join(["XAG", *CURRENCIES])},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

rates = data["rates"]
silver_usd = rates["USDXAG"]
for cur in ["USD", *CURRENCIES]:
    per_oz = silver_usd if cur == "USD" else silver_usd / rates["USD" + cur]
    print(f"{cur}: {per_oz:,.2f} per troy oz, {per_oz / GRAMS_PER_TROY_OZ:,.4f} per gram")

تعمل أي عملة من العملات الـ57 المدعومة بهذه الطريقة، وكذلك الذهب والبلاتين والبلاديوم، لذا يمكن لاستدعاء واحد تغذية لوحة أسعار كاملة. وفي الهند، حيث تُسعَّر الفضة عادةً لكل كيلوغرام، يعطي base=INR&unit=kilogram الرقم المألوف مباشرةً.

أسعار الفضة التاريخية عبر API

يبدأ سجل الفضة في عام 2000 ويستخدم المعاملات وصيغة الاستجابة نفسها التي يستخدمها السعر اللحظي. وقيم كل يوم هي أسعار إغلاقه، مع تواريخ بتوقيت UTC. وتغطي أربع نقاط نهاية معظم الاحتياجات:

• /YYYY-MM-DD أو /historical?date= أو /yesterday: إغلاق يوم واحد. وفي عطلة نهاية الأسبوع أو العطلات الرسمية، يُرجَع إغلاق آخر يوم تداول.
• /timeframe: أسعار الإغلاق اليومية بين start_date وend_date، حتى 30 يومًا لكل طلب في خطة Free و365 يومًا في الخطط المدفوعة.
• /change: سعر البداية وسعر النهاية والتغير المطلق والتغير بالنسبة المئوية بين تاريخين.
• /ohlc: سعر الافتتاح والأعلى والأدنى والإغلاق ليوم واحد.

# Silver at the close of 15 January 2024 (USDXAG 23.162 in the docs' example)
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Daily silver closes in euros per gram for September 2026
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

# What 500 grams of silver were worth in euros at the close of 1 October 2026
curl "https://metalapi.com/api/v1/convert?from=XAG&to=EUR&amount=500&unit=gram&date=2026-10-01" \
  -H "X-API-Key: $METALAPI_KEY"

أسعار إغلاق الأيام الماضية لا تتغير أبدًا، لذا خزّنها بدلًا من طلبها مجددًا. ومع حد الـ365 يومًا في الخطط المدفوعة، يتطلب ملء البيانات الكامل منذ عام 2000 طلب /timeframe واحدًا لكل سنة. وتذكّر أن أسعار المعادن قبل أكتوبر 2026 مشتقة من العقود الآجلة للشهر الأقرب، لذا قد تختلف قليلًا عن السعر الفوري في اليوم نفسه.

ويتضمن مقال أسعار الذهب والفضة التاريخية عبر API سكربتًا كاملًا لملء البيانات السابقة، ونصائح للتخزين والتحقق، ورسمًا بيانيًا للذهب مع نسبة الذهب إلى الفضة.

حالات استخدام واجهة API لأسعار الفضة

متاجر السبائك وتجار العملات المعدنية. يبيع التجار بأعلى من السعر الفوري ويعيدون الشراء بأقل منه. وسعر البيع المعتاد هو السعر الفوري لكل أونصة تروي مضروبًا في محتوى الفضة الخالصة، مضافًا إليه علاوة المنتج ورسم ثابت لكل قطعة. خزّن العلاوة لكل منتج، وحدّث السعر الفوري وفق فترة التحديث في خطتك، وأظهر للعملاء وقت آخر تحديث للسعر. ومن خطة Standard فما فوق، أضف XAG-BID وXAG-ASK إلى currencies لتسعير الجانبين انطلاقًا من فارق السوق نفسه. ويبيّن مقال السعر الفوري والطلب والعرض كيف يحوّل التجار هذه الأرقام إلى أسعار بيع وشراء.

مشترو الأواني الفضية والمجوهرات والفضة الكسر. تُسعَّر القطع الفضية بالوزن ودرجة النقاوة، أي نسبة الفضة الخالصة بالأجزاء من الألف. والدرجات الشائعة هي 999 (الفضة الخالصة) و958 (بريتانيا) و925 (الفضة الإسترلينية) و800، الموجودة في الأواني الفضية الأوروبية القارية القديمة. وقيمة الصهر هي الوزن بالغرام × درجة النقاوة × سعر الغرام. وبالسعر النموذجي البالغ 1.7342 دولار للغرام، تحتوي صينية إسترلينية وزنها 500 غرام على 462.5 غرامًا من الفضة قيمتها نحو 802.07 دولار. ويدفع مشترو الفضة الكسر نسبة مئوية من قيمة الصهر، لذا اجعل هذه النسبة إعدادًا قابلًا للتغيير لا قيمة ثابتة في الشيفرة.

نقطة نهاية العيارات في MetalAPI، /carat، تغطي الذهب فقط، لذا فإن حساب نقاوة الفضة يجري من جهتك:

const GRAMS_PER_TROY_OZ = 31.1034768;

/** Melt value of a silver item: weight in grams × fineness (e.g. 0.925) × price per gram. */
export function meltValue(grams, fineness, pricePerTroyOz) {
  return grams * fineness * (pricePerTroyOz / GRAMS_PER_TROY_OZ);
}

meltValue(500, 0.925, 53.94); // 802.07…  sterling tray at the example price
meltValue(1000, 0.999, 53.94); // 1732.48… one-kilogram bar of 999 silver

تطبيقات الاستثمار والمحافظ. يحتفظ المستخدمون بعملات وأقراص وسبائك كيلوغرام ويريدون معرفة قيمتها بعملتهم. خزّن الحيازات داخليًا بأونصات التروي، وحوّل وحدة الإدخال مرة واحدة، وقيّم المحفظة بعملة المستخدم قيمةً لـbase. وتُرجع /change نسبة التغير بين تاريخين لأسطر مثل «الفضة هذا الشهر»، وتغذّي أسعار الإغلاق اليومية المخزنة من /timeframe الرسوم البيانية.

تنبيهات الأسعار. إذا كنت تحتاج فقط إلى التصرف عندما تتجاوز الفضة مستوى معيّنًا، فإن تنبيهات الأسعار تستطيع مراقبة XAG بأي عملة وإبلاغك بالبريد الإلكتروني من خطة Lite، أو عبر خطاف ويب موقَّع من خطة Advanced، دون أي استطلاع من جهتك.

حداثة البيانات والحصص والخطط

تعتمد حداثة سعر الفضة على الخطة. والاستطلاع بوتيرة أسرع من فترة التحديث في خطتك لا يُرجع إلا الأرقام نفسها مجددًا:

• خزّن مؤقتًا لمدة لا تقل عن فترة التحديث. في خطة Free، يكفي طلب واحد يوميًا للأسعار الحالية.
• اطلب كل المعادن في استدعاء واحد. يكلّف currencies=XAU,XAG,XPT,XPD طلبًا واحدًا، بينما تكلّف أربعة استدعاءات منفصلة أربعة طلبات.
• أبقِ المفتاح على الخادم. قدّم الأسعار المخزنة مؤقتًا لصفحاتك بدلًا من استدعاء الواجهة من متصفح كل زائر.
• راقب الاستخدام مجانًا. لا تُحتسب /usage و/symbols من الحصة أبدًا، وتحمل كل استجابة الجزء rate_limit.

هل أنت جاهز للبناء؟ أنشئ حسابًا مجانيًا لتحصل على مفتاح API خلال دقيقة، دون الحاجة إلى بطاقة ائتمان. وقارن فترات التحديث والحصص في صفحة الأسعار، واعتمد على توثيق API مرجعًا لكل نقطة نهاية ومعامل.

الأسئلة الشائعة

ما رمز الفضة في واجهة API للأسعار؟

XAG، وهو رمز ISO 4217 لأونصة تروي واحدة من الفضة. وفي MetalAPI، سعر الفضة بعملة الأساس لديك هو المفتاح الذي يجمع الرمزين، مثل USDXAG للدولارات لكل أونصة أو EURXAG لليورو لكل أونصة.

هل توجد واجهة API مجانية لأسعار الفضة؟

نعم. تتضمن خطة Free في MetalAPI الفضة وكل الرموز الأخرى والسجل الكامل، مع 100 طلب شهريًا وتحديثات يومية للأسعار، ولا تتطلب بطاقة ائتمان. وتبدأ الخطط المدفوعة من $4.99 شهريًا لتحديثات كل 30 دقيقة و1,000 طلب.

كيف أحصل على سعر الفضة لكل غرام؟

مرّر unit=gram، أو اقسم السعر لكل أونصة تروي على 31.1034768. ولا تقسم على 28.35: فتلك أونصة الأفوارديبوا، وهي تضخّم سعر الغرام بنحو 9.7%.

إلى أي مدى تعود أسعار الفضة التاريخية؟

تتوفر أسعار الفضة اليومية من عام 2000 فصاعدًا في كل الخطط. ويغطي طلب النطاق الواحد حتى 30 يومًا في خطة Free وحتى 365 يومًا في الخطط المدفوعة.

لماذا يختلف سعر الفضة لدى التاجر عن سعر الواجهة؟

تُرجع الواجهة السعر الفوري الوسطي في سوق الجملة. ويضيف التجار عند البيع علاوات للسك والتوزيع وهامش ربحهم، ويدفعون أقل من السعر الفوري عند إعادة الشراء، لذا تقع أسعار التجزئة للعملات والسبائك فوق السعر الفوري وأسعار إعادة الشراء دونه.