goldprice.dev
ابحث في Reddit عن واجهة برمجية لسعر الذهب، وستجد أن الموضوع يتكرر بالشكل نفسه دائماً تقريباً. شخص ما يبني لوحة تحكم، أو تنبيه سعر، أو بوت تداول، أو متجراً يعرض أسعار السبائك، ويريد سعر ذهب حياً يستطيع سحبه من الكود مباشرة. قبل ربط أي شيء، يطرحون الأسئلة نفسها في r/algotrading وr/webdev وr/golang: هل يوجد مستوى مجاني، ما مدى حداثة الرقم، ما هي الحدود، هل يمكنني استخدامه تجارياً، وهل يمكنني الوثوق بالبيانات.
تجيب هذه المقالة عن تلك الأسئلة مباشرة، مستخدمة goldprice.dev كمثال عملي. لا حاجة للتسجيل لقراءتها، وأول استدعاء للواجهة البرمجية أدناه يعمل بلا مفتاح.
ما هو goldprice.dev، وما لا يكون
هو واجهة برمجية لأسعار السلع موجهة للمطورين: الذهب والفضة والنحاس، عبر نقطة نهاية REST واحدة موثّقة على https://api.goldprice.dev. تحمل كل استجابة علامة تحقّق متقاطعة لحداثة البيانات (staleness)، ويمكنك طلب أسعار وطوابع زمنية لكل مصدر على حدة، أو رقم تباعد (divergence) عبر ?include=، كي يعرف الكود متى يتأخر أحد المصادر بدلاً من أن يفشل بصمت. يشحن خادم MCP على كل خطة، بما فيها المجانية.
هو ليس وسيط تداول ولا تغذية تسوية. الأسعار بيانات مرجعية إرشادية، منشورة للعرض والتحليل والتنبيهات. إذا احتجت عرض تنفيذ قابل للتنفيذ لتسوية صفقة، فلا توجد واجهة برمجية عامة لسعر الذهب مناسبة لذلك، بما فيها هذه.
هل يوجد مستوى مجاني؟
نعم، بلا بطاقة. توفر Free عدد 5,000 استدعاء شهرياً بمعدل 10 طلبات في الدقيقة، وأسعار الذهب والفضة والنحاس الفورية بتأخير 15 دقيقة. تضيف الخطط المدفوعة أسعاراً حية وأسعار التجار وحدوداً أعلى:
| الخطة | السعر | الاستدعاءات / شهرياً | ما تضيفه |
|---|---|---|---|
| Free | $0 | 5,000 | أسعار XAU/XAG/HG الفورية، MCP، سجل يومي لـ30 يوماً |
| Basic | $19/شهرياً | 100,000 | أسعار حية وأسعار التجار، سجل يومي لسنة |
| Plus | $39/شهرياً | 300,000 | سجل يومي كامل (الذهب من 1996)؛ شموع 1h/4h لـ30 يوماً؛ اتصال بث واحد |
| Pro | $89/شهرياً | 1,000,000 | سجل لحظي كامل؛ 5 SSE + 5 WebSocket؛ بث أسعار التجار |
كم مرة يتحدث السعر؟
تأتي الأسعار الفورية من بيانات سوق أولية مرخّصة. تحصل الخطط المدفوعة على أسعار حية؛ وتصل إلى Free والطلبات المجهولة وهذا الموقع متأخرة 15 دقيقة. تحمل كل استجابة computed_at وتضبط is_stale عندما تتجاوز القيمة نافذة تحديثها. يوفر ?include=sources الطوابع الزمنية لكل مصدر للتحقق من حداثة البيانات.
ما هي حدود المعدل؟
تتيح Free عشرة طلبات في الدقيقة، وBasic عدد 60، وPlus عدد 120، وPro عدد 300. تعيد كل استجابة الترويسة القياسية X-RateLimit-Remaining، فالنمط الصحيح هو قراءة تلك الترويسة والتباطؤ عندما تقترب من الصفر، بدلاً من الاستطلاع الأعمى وتلقي أخطاء 429. لمعظم التطبيقات، تكفي ذاكرة تخزين مؤقتة قصيرة من جهة العميل، مضبوطة على وتيرة تغيّر القيمة الفعلية، لتبقى ضمن حدود الخطة المجانية بأمان.
كيف أُصادِق؟
عبر رمز حامل (bearer token). المفاتيح تبدأ بـ ga_live_ وتوضع في ترويسة Authorization. توجد أيضاً واجهة مجهولة، محدودة لكل عنوان IP بـ30 طلباً في الدقيقة و100 في الساعة و1,000 في الشهر، تعيد السعر والطوابع الزمنية وحقول الحداثة. bid وask اختياريان للخطط المدفوعة فقط عند توفر عرض متسق للجانبين. المصادقة تفتح ?include=stats للافتتاح والأعلى والأدنى وإغلاق الجلسة السابقة وحقول التغيّر وحقول التباعد بين المصادر, أما ?include=sources و?include=karat فمتاحان في الحالتين.
هل يمكنني رؤية مصدر الرقم؟
نعم، وهذا الجزء الذي تخفيه معظم الواجهات البرمجية. أضف ?include=sources وستتضمن الاستجابة مصفوفة sources[]، صفاً واحداً لكل مصدر أساسي (upstream)، لكل منها سعره وطابعه الزمني الخاص. عندما تختلف المصادر، يحمل ?include=stats (موثّق فقط) الحقلين divergence_bps وdivergence_flag، كي تحدد تفاوتك الخاص بدلاً من الثقة برقم واحد مدمج بلا مصدر واضح. إذا كنت تبني شيئاً يترتب على سعر خاطئ فيه تكلفة، فتلك الشفافية هي سبب استخدام واجهة برمجية منظّمة بدلاً من كشط صفحة ويب.
هل يمكنني استخدامه تجارياً؟
تسمح كل الخطط بالاستخدام التجاري. لا تتطلب أي خطة رابط إسناد. إعادة توزيع البيانات نفسها أو بيعها تحتاج اتفاقاً منفصلاً عبر hello@goldprice.dev.
هل يمكن لوكيل LLM الخاص بي استخدامه؟
نعم. خادم MCP مشمول في كل خطة، بما فيها المجانية. تضيف كتلة إعداد واحدة إلى Claude أو Cursor أو أي بيئة تشغيل تدعم MCP، ويجلب الوكيل السعر الحي مباشرة، دون كتابة كود أدوات يدوياً. البيانات هي نفسها التي تخدمها واجهة REST. يوجد شرح كامل لـ MCP إذا أردت تفاصيل الإعداد.
أقصر استدعاء
بلا مفتاح، بلا اعتماديات:
curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOTتحصل على JSON يحتوي السعر وعلامة حداثة بتأخير 15 دقيقة. bid وask اختياريان للخطط المدفوعة فقط عند توفر عرض متسق للجانبين. أضف ?include=karat لتفصيل لكل غرام حسب القيراط، أو ?include=sources للمصادر المساهمة. عندما تريد الشكل الكامل وحدوداً أعلى، يستغرق مفتاح مجاني دقيقة واحدة.
للنسخة الخاصة بلغة برمجة معينة، تغطي جلب أسعار الذهب الحية بلغة JavaScript مسار REST من البداية إلى النهاية، وتغطي تخزين أسعار الذهب مؤقتاً والبقاء ضمن حدود المعدل فعل ذلك عند الحجم الكبير.
أسعار الذهب اللحظية، بيانات OHLC التاريخية، وتجميع متعدد المصادر, متاحة عبر REST و SSE.