واجهة سعر الذهب البرمجية على Reddit: أسئلة المطورين، مُجابة

ابحث في Reddit عن واجهة برمجية لسعر الذهب، وستجد أن الموضوع يتكرر بالشكل نفسه دائماً تقريباً. شخص ما يبني لوحة تحكم، أو تنبيه سعر، أو بوت تداول، أو متجراً يعرض أسعار السبائك، ويريد سعر ذهب حياً يستطيع سحبه من الكود مباشرة. قبل ربط أي شيء، يطرحون الأسئلة نفسها في r/algotrading وr/webdev وr/golang: هل يوجد مستوى مجاني، ما مدى حداثة الرقم، ما هي الحدود، هل يمكنني استخدامه تجارياً، وهل يمكنني الوثوق بالبيانات.

تجيب هذه المقالة عن تلك الأسئلة مباشرة، مستخدمة goldprice.dev كمثال عملي. لا حاجة للتسجيل لقراءتها، وأول استدعاء للواجهة البرمجية أدناه يعمل بلا مفتاح.

ما هو goldprice.dev، وما لا يكون

هو واجهة برمجية لأسعار السلع موجهة للمطورين: الذهب والفضة والنحاس، عبر نقطة نهاية REST واحدة موثّقة على https://api.goldprice.dev. تحمل كل استجابة علامة تحقّق متقاطعة لحداثة البيانات (staleness)، ويمكنك طلب أسعار وطوابع زمنية لكل مصدر على حدة، أو رقم تباعد (divergence) عبر ?include=، كي يعرف الكود متى يتأخر أحد المصادر بدلاً من أن يفشل بصمت. يشحن خادم MCP على كل خطة، بما فيها المجانية.

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

هل يوجد مستوى مجاني؟

نعم، ولا يحتاج بطاقة. تمنحك الخطة المجانية 1,000 استدعاء شهرياً بمعدل 30 طلباً في الدقيقة، تغطي سعر الذهب (XAU) الفوري الحي. تضيف الخطط المدفوعة الفضة والنحاس، وبيانات تسوية العقود الآجلة، وحدوداً أعلى، وحقوقاً تجارية:

كم مرة يتحدث السعر؟

السعر الفوري الحي عبارة عن أوراكل (oracle) يتحدث باستمرار، لا لقطة يومية واحدة. تتحدث قيم تسوية العقود الآجلة وفق جدول تسوية البورصة. الفكرة من الواجهة البرمجية هي أنك لست مضطراً أبداً لتخمين أيهما تنظر إليه: تحمل كل استجابة computed_at وتضبط is_stale عندما تكون القيمة أقدم من نافذة تحديثها المتوقعة، ويفصّل ?include=sources ذلك إلى طابع زمني لكل مصدر عند الحاجة. تقرأ حداثة البيانات من الحمولة نفسها بدلاً من الثقة بتصنيف عام مثل "لحظي".

ما هي حدود المعدل؟

الخطة المجانية 30 طلباً في الدقيقة؛ تصل الخطط المدفوعة إلى 120 و500. تعيد كل استجابة الترويسة القياسية X-RateLimit-Remaining، فالنمط الصحيح هو قراءة تلك الترويسة والتباطؤ عندما تقترب من الصفر، بدلاً من الاستطلاع الأعمى وتلقي أخطاء 429. لمعظم التطبيقات، تكفي ذاكرة تخزين مؤقتة قصيرة من جهة العميل، مضبوطة على وتيرة تغيّر القيمة الفعلية، لتبقى ضمن حدود الخطة المجانية بأمان.

كيف أُصادِق؟

عبر رمز حامل (bearer token). المفاتيح تبدأ بـ ga_live_ وتوضع في ترويسة Authorization. توجد أيضاً واجهة مجهولة، محدودة بـ 100 طلب في الساعة لكل عنوان IP، تعيد الشكل الافتراضي المختصر نفسه الذي تعيده استجابة موثّقة (السعر، والعرض، والطلب، وحقول الحداثة) كي تختبر قبل التسجيل. المصادقة لا تغيّر الشكل الافتراضي، لكنها تفتح ?include=stats للافتتاح والأعلى والأدنى وإغلاق الجلسة السابقة وحقول التغيّر وحقول التباعد بين المصادر — أما ?include=sources و?include=karat فمتاحان في الحالتين.

هل يمكنني رؤية مصدر الرقم؟

نعم، وهذا الجزء الذي تخفيه معظم الواجهات البرمجية. أضف ?include=sources وستتضمن الاستجابة مصفوفة sources[]، صفاً واحداً لكل مصدر أساسي (upstream)، لكل منها سعره وطابعه الزمني الخاص. عندما تختلف المصادر، يحمل ?include=stats (موثّق فقط) الحقلين divergence_bps وdivergence_flag، كي تحدد تفاوتك الخاص بدلاً من الثقة برقم واحد مدمج بلا مصدر واضح. إذا كنت تبني شيئاً يترتب على سعر خاطئ فيه تكلفة، فتلك الشفافية هي سبب استخدام واجهة برمجية منظّمة بدلاً من كشط صفحة ويب.

هل يمكنني استخدامه تجارياً؟

المستويان Free وPhysical للاستخدام الشخصي والتقييم. الاستخدام التجاري، أي عرض السعر مجدداً داخل منتج تشحنه، يبدأ من خطة Pro ويتطلب إسناداً (attribution). إذا كنت تضع سعر ذهب أمام مستخدميك الخاصين، فـ Pro هو الحد الأدنى.

هل يمكن لوكيل LLM الخاص بي استخدامه؟

نعم. خادم MCP مشمول في كل خطة، بما فيها المجانية. تضيف كتلة إعداد واحدة إلى Claude أو Cursor أو أي بيئة تشغيل تدعم MCP، ويجلب الوكيل السعر الحي مباشرة، دون كتابة كود أدوات يدوياً. البيانات هي نفسها التي تخدمها واجهة REST. يوجد شرح كامل لـ MCP إذا أردت تفاصيل الإعداد.

أقصر استدعاء

بلا مفتاح، بلا اعتماديات:

curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT

تحصل على JSON يحتوي السعر والعرض والطلب وعلامة حداثة. هذا الاستدعاء الواحد كافٍ لوضع سعر ذهب حي وصادق فيما تبنيه. أضف ?include=karat لتفصيل لكل غرام حسب القيراط، أو ?include=sources للمصادر المساهمة. عندما تريد الشكل الكامل وحدوداً أعلى، يستغرق مفتاح مجاني دقيقة واحدة.

للنسخة الخاصة بلغة برمجة معينة، تغطي جلب أسعار الذهب الحية بلغة JavaScript مسار REST من البداية إلى النهاية، وتغطي تخزين أسعار الذهب مؤقتاً والبقاء ضمن حدود المعدل فعل ذلك عند الحجم الكبير.