للمطوّرين

ابدأ في ثلاث خطوات

01

احصل على رمز وصول

تُصدَر الرموز بعد محادثةٍ تفهم حاجتك، لا بتسجيلٍ ذاتيّ، محكومةً بنطاقاتٍ وحدودِ استخدام. تحصل على رمزٍ بالصلاحيات التي تحتاجها فقط.

02

اطلب السعر

نداءٌ واحد إلى API يعيد آخر سعرٍ للمعادن بالعملة التي تختارها ضمن عقدٍ ثابت، مع عيارات الذهب وحالةِ كلّ سعر.

03

اقرأ حالته أوّلاً

قبل أن تبني قراراً على السعر، تحقّق من حالته المرفقة، حيّ، أو السوق مغلق، أو بائت. هكذا لا تعتمد سعراً ميّتاً.

المصادقة والحدود

كلُّ طلبٍ يحمل رمز وصولٍ في ترويسة Authorization. بعض النقاط تتطلّب نطاق صلاحيةٍ إضافيّاً.

رمز وصول

يُرسَل مع كلّ طلبٍ في ترويسة Authorization بصيغة Bearer TOKEN. تُصدَر الرموز يدويّاً بعد محادثة.

نطاقات صلاحية

لكلّ رمزٍ صلاحياتُه، فالأسعار الأساسيّة متاحةٌ دائماً، والإحصائيات اليوميّة والبثّ الحيّ يحتاجان نطاقاً مخصّصاً.

حدُّ معدّل

يُسمح لرمزك بأكثر من طلبٍ في الثانية، وكلُّ استجابةٍ ناجحة تحمل ترويسات تُخبرك بحدّك وبما تبقّى منه في النافذة الحاليّة.

النطاقات

default الأسعار الحيّة مع حالتها وعياراتها، والمعادن والعملات والحالة وتفاصيل رمزك. متاحٌ لكلّ رمز.

daily_stats إحصائيات اليوم، الافتتاح والأعلى والأدنى والإغلاق والتغيّر، ونقطة ‏/daily-stats.

instant_change معدّل التغيّر اللحظيّ لكلّ معدنٍ مرفقاً بسعره داخل ‏/prices.

live_stream المصادقة على قناة البثّ اللحظيّ عبر WebSocket.

الترويسات وحدّ المعدّل

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

X-RateLimit-Limit أقصى عددٍ من الطلبات المسموح لرمزك في النافذة.

X-RateLimit-Remaining ما تبقّى لك في النافذة الحاليّة.

X-RateLimit-Window طول النافذة الزمنيّة، وقيمتها ثانيةٌ واحدة.

Retry-After يظهر مع رمز 429 عند تجاوز الوتيرة، وهو عددُ الثواني قبل إعادة المحاولة.

وضع التجربة

جرّب بنية الاستجابة قبل أن تُصدَر رموزك. أرسل الرمز الحرفيّ test فتصلك الاستجابة بشكلها الكامل وقيمها العدديّة مصفّرةً إلى صفر، فتبني تكاملك على البنية الحقيقيّة دون بياناتٍ حيّة.

نقاط الوصول

العنوان الأساسيّ

https://barqmetal.com/api/v1

كلُّ الطلبات تحتاج رمز وصول. النقاط الموسومة بنطاقٍ تتطلّب صلاحيةً إضافيّة.

GET /prices الأسعار الحيّة للمعادن، بالعملة المطلوبة، مع الحالة والعيارات. default

GET /daily-stats إحصائيات اليوم لكلّ معدن. daily_stats

GET /metals قائمة المعادن المتاحة ورموزها. default

GET /currencies العملات المدعومة ومعدّلات صرفها. default

GET /status حالة الخدمة الحاليّة وآخر تحديث. default

GET /token تفاصيل رمزك، صلاحياته وحدوده واستخدامه. default

POST /websocket/auth مصادقة قناة البثّ اللحظيّ. live_stream

GET /websocket/info بيانات الاتّصال بالبثّ اللحظيّ وشكل حدثه. default

مثال الاستجابة

شكلٌ ثابتٌ لكلّ استجابة. أيُّ تطويرٍ يُنسَّق مسبقاً مع الأنظمة المستهلِكة، فلا ينكسر تكاملُك فجأة.

هذا مثال استجابةٍ أساسيّة. بنطاق instant_change يُضاف لكلّ معدنٍ حقلُ التغيّر اللحظيّ، وبنطاق daily_stats يُضاف حقلُ إحصائيات اليوم. راجع مرجع النقاط أدناه لكلّ حقلٍ بنوعه.

أسعار الغرام تصلك بأربع خاناتٍ عشريّة، وأسعار الأونصة والعيارات بخانتَين. القيم في المثال توضيحيّة، فاقرأ الدقّة من مرجع الحقول لا من المثال.

حين تطلب معدناً واحداً عبر symbol، يعود حقل data كائناً مفرداً لا مصفوفة. بلا symbol يعود مصفوفةً بكلّ المعادن.

استجابة ‏GET /prices (قيمٌ توضيحيّة)

{
  "success": true,
  "currency": "SAR",
  "request_time": "2026-08-14T11:42:05.417+03:00",
  "system": { "is_running": true, "last_update": "2026-08-14T11:42:05.417+03:00", "server_time": "2026-08-14T11:42:05.417+03:00" },
  "data": [
    {
      "metal": { "id": 1, "symbol": "XAU", "name_ar": "الذهب", "name_en": "Gold" },
      "state": "live",
      "prices": {
        "buy_per_ounce": 12545.60,
        "sell_per_ounce": 12551.20,
        "buy_per_gram": 403.20,
        "sell_per_gram": 403.50,
        "fetched_at": "2026-08-14T11:42:05.417+03:00",
        "last_success_at": "2026-08-14T11:42:07.912+03:00",
        "price_changed_at": "2026-08-14T11:40:11.005+03:00"
      },
      "karats": {
        "24": { "sell_per_gram": 403.50 },
        "22": { "sell_per_gram": 369.88 },
        "21": { "sell_per_gram": 353.06 },
        "18": { "sell_per_gram": 302.63 }
      }
    }
  ]
}

مرجع النقاط

لكلّ نقطةٍ معاملاتُها وحقولُ استجابتها بنوعها ومعناها، فتكامل مقابل هذه الصفحة وحدها دون محادثة.

GET /prices الأسعار الحيّة للمعادن مع الحالة والعيارات.

المعاملات

المعاملالنوعالمعنى

symbol string رمز معدنٍ واحد لترشيح النتيجة، مثل XAU. حروفٌ وأرقامٌ حتّى عشرة. بلا قيمةٍ تعود كلُّ المعادن.

currency string رمز العملة، حروفٌ حتّى عشرة. الافتراضيّ USD، وعملةٌ غير مدعومةٍ تعود بالدولار.

include_daily_stats 0 أو 1 ضمّ إحصائيات اليوم لكلّ معدن. مفعّلٌ ما لم تُرسِل 0.

حقول الاستجابة

الحقلالنوعالمعنى

currency string العملة المحلولة لهذه الاستجابة.

request_time string لحظة معالجة الطلب بصيغة ISO8601.

system.is_running bool هل التغذية حيّةٌ الآن.

system.last_update string لحظة آخر تحديثٍ للتغذية، ISO8601 بدقّة ميلي-ثانية.

system.server_time string ساعة النظام الحيّة، تتقدّم كلَّ ثانيةٍ حتى حين يجفّ المصدر، ISO8601 بدقّة ميلي-ثانية.

data[].metal object المعدن، المعرّف والرمز والاسم عربيّاً وإنكليزيّاً.

data[].state string حالة السعر، إحدى live أو market_closed أو stale.

data[].prices.buy_per_ounce number سعر شراء الأونصة، خانتان عشريّتان.

data[].prices.sell_per_ounce number سعر بيع الأونصة، خانتان عشريّتان.

data[].prices.buy_per_gram number سعر شراء الغرام، أربع خانات.

data[].prices.sell_per_gram number سعر بيع الغرام، أربع خانات.

data[].prices.fetched_at string لحظة آخر جلبٍ مقبولٍ لهذا السعر (بوّابة الطزاجة)، ISO8601 بدقّة ميلي-ثانية.

data[].prices.last_success_at string لحظة آخر جلبٍ ناجحٍ ولو رُفضت القيمة، ISO8601 بدقّة ميلي-ثانية.

data[].prices.price_changed_at string لحظة آخر تغيّرٍ فعليٍّ للسعر، ISO8601 بدقّة ميلي-ثانية، وقيمتها null قبل أوّل تغيّر.

data[].karats object أسعار العيارات 24 و22 و21 و18 لبيع الغرام بخانتَين، للذهب فقط.

data[].instant_change object التغيّر اللحظيّ، مقدارُ ونسبةُ الشراء والبيع مع اتّجاهٍ up أو down أو stable.instant_change

data[].daily_stats object إحصائيات اليوم لهذا المعدن، الافتتاح والأعلى والأدنى والإغلاق والتغيّر والمدى وعدد التحديثات.daily_stats

GET /daily-stats إحصائيات اليوم لكلّ معدن.

المعاملات

المعاملالنوعالمعنى

symbol string ترشيح بمعدنٍ واحد، مثل XAU.

currency string رمز العملة، الافتراضيّ USD.

حقول الاستجابة

الحقلالنوعالمعنى

currency string العملة المحلولة.

date string يوم الإحصاء بصيغة سنة-شهر-يوم.

data[].metal object المعدن، المعرّف والرمز والاسم العربيّ.

data[].sell object إحصاء البيع، الافتتاح والأعلى والأدنى والإغلاق والتغيّر ونسبته.

data[].buy object إحصاء الشراء، بالحقول نفسها.

data[].direction string اتّجاه اليوم، up أو down أو stable.

data[].range number مدى اليوم، الفرق بين الأعلى والأدنى.

data[].update_count int عدد التحديثات المسجّلة اليوم.

GET /metals المعادن المتاحة ورموزها.

المعاملات

لا معاملات، رمز وصولك يكفي.

حقول الاستجابة

الحقلالنوعالمعنى

count int عدد المعادن.

data[].symbol string رمز المعدن، مثل XAU.

data[].name_ar string الاسم العربيّ.

data[].name_en string الاسم الإنكليزيّ.

data[].gram_per_base_unit number عدد الغرامات في وحدة القياس الأساس.

GET /currencies العملات المدعومة ومعدّلات صرفها.

المعاملات

لا معاملات، رمز وصولك يكفي.

حقول الاستجابة

الحقلالنوعالمعنى

base_currency string عملة الأساس، وهي الدولار دائماً.

data[].code string رمز العملة، مثل SAR.

data[].symbol string رمز العرض.

data[].exchange_rate number كم وحدةً من هذه العملة يساوي دولاراً واحداً.

data[].is_default bool هل هي العملة الافتراضيّة.

GET /status حالة الخدمة الحاليّة وآخر تحديث.

المعاملات

لا معاملات، رمز وصولك يكفي.

حقول الاستجابة

الحقلالنوعالمعنى

data.is_running bool هل التغذية حيّةٌ الآن.

data.last_update string لحظة آخر تحديث.

GET /token تفاصيل رمزك، صلاحياته وحدوده واستخدامه.

المعاملات

لا معاملات، رمز وصولك يكفي.

حقول الاستجابة

الحقلالنوعالمعنى

data.abilities array النطاقات، كلٌّ باسمه وهل هو ممنوحٌ لرمزك.

data.rate_limit object حدُّ رمزك، الطلبات في الثانية ووصفُه.

data.usage object استخدامك، مجموع الطلبات وآخر استعمال.

data.expires_at string انتهاء صلاحية الرمز إن وُجد.

GET /websocket/info بيانات الاتّصال بالبثّ الحيّ وشكل حدثه.

المعاملات

لا معاملات، رمز وصولك يكفي.

حقول الاستجابة

الحقلالنوعالمعنى

data.connection object بيانات الخادم، المضيف والمنفذ والمفتاح والمخطّط.

data.auth object رابط المصادقة وطريقته وترويساته ومعاملاته.

data.channels array القنوات وأحداثها وشكل بيانات الحدث.

POST /websocket/auth مصادقة قناة البثّ الحيّ الخاصّة.

المعاملات

المعاملالنوعالمعنى

socket_id string معرّف الاتّصال، يعطيه لك عميل البثّ تلقائيّاً. مطلوب.

channel_name string اسم القناة الخاصّة المطلوب الاشتراك بها. مطلوب.

حقول الاستجابة

الحقلالنوعالمعنى

auth string توقيع المصادقة الذي يمرّره عميل البثّ للقناة.

الأخطاء والرموز

كلُّ خطأٍ يعود بشكلٍ واحدٍ ثابت، رمزُ حالةٍ وكائنٌ يشرح السبب، فيبني نظامُك منطق إعادة المحاولة بثقة.

شكل كائن الخطأ

{
  "success": false,
  "error": "...",
  "status": 404,
  "request_time": "2026-08-14T11:42:05+03:00"
}

401 رمز الوصول مفقودٌ أو غير صالح.

403 الرمز موقوفٌ أو منتهٍ، أو ينقصه النطاق المطلوب، أو الـ IP غير مسموح.

404 المعدن المطلوب غير معروف، أو لا معادن مفعّلة.

422 معاملات الطلب غير صالحة، والتفاصيل في حقل errors.

429 تجاوزت وتيرة الطلب المسموحة، انتظر ثمّ أعد المحاولة.

500 خطأٌ داخليّ عارض، أعد المحاولة بعد قليل.

حقل errors يُرفَق مع رمز 422 وحده، فيحمل تفاصيل المعامل الخاطئ. ومع رمز 429 قد تصلك ترويسة Retry-After تخبرك متى تعيد المحاولة.

البثّ الحيّ

بدل الاستعلام المتكرّر، اشترك مرّةً فيصلك كلُّ تحديثٍ في اللحظة نفسها. خطوتان، صادِق القناة، ثمّ اتّصل.

01 صادِق القناةأرسل POST إلى ‏/websocket/auth برمزٍ يحمل نطاق live_stream، فتحصل على بيانات الاتّصال المؤقّتة.
02 اتّصل واستقبلافتح الاتّصال باستخدام تلك البيانات، فيصلك كلُّ تحديثِ سعرٍ فور حدوثه بالشكل نفسه المرفق حالتُه.

أمثلة الكود

انسخ وابدأ. استبدل TOKEN برمز وصولك.

cURL

curl -H "Authorization: Bearer TOKEN" \
  "https://barqmetal.com/api/v1/prices?currency=SAR"

JavaScript

const res = await fetch(
  "https://barqmetal.com/api/v1/prices?currency=SAR",
  { headers: { Authorization: "Bearer TOKEN" } }
);
const { data } = await res.json();
console.log(data[0].state, data[0].prices.sell_per_gram);

WebSocket

// npm install pusher-js
// GET /websocket/info returns host, port, key, scheme and the channel name
import Pusher from "pusher-js";

const pusher = new Pusher("YOUR_APP_KEY", {
  wsHost: "YOUR_HOST",
  wsPort: YOUR_PORT,
  forceTLS: false,
  enabledTransports: ["ws", "wss"],
  authEndpoint: "https://barqmetal.com/api/v1/websocket/auth",
  auth: { headers: { Authorization: "Bearer TOKEN" } }
});

// the client POSTs socket_id + channel_name to the auth endpoint for you
const channel = pusher.subscribe("private-prices");
channel.bind("price.updated", (p) => {
  console.log(p.metal.symbol, p.prices.sell_per_gram, p.state);
});

جرّبها

اختر نقطةً واضغط «نفّذ»، فيصلك ردٌّ حيٌّ من الواجهة فوراً، مع أمر cURL وكود JavaScript جاهزَين للنسخ.

النقطة العملة رمز الوصول

أمر cURL

JavaScript (fetch)

الاستجابة الحيّة

نداءٌ حيٌّ حقيقيّ. بلا رمز يُستخدم الوضع التجريبيّ، بنية الاستجابة نفسها بقيمٍ مصفّرة. برمزك تصلك القيم الحقيقيّة.

أسئلة المطوّرين

كيف أربط سعر ذهبٍ حيٍّ بتطبيقي أو موقعي؟

اطلب رمز وصول، ثم نادِ API أسعار بَرق لتحصل على آخر سعرٍ للذهب والفضّة بالعملة التي تختارها، أو اشترك في البثّ الحيّ لتصلك التحديثات لحظةَ حدوثها. كل سعرٍ يصلك بحالته الصريحة فيعرف نظامُك متى يثق به.

ما هي API أسعار الذهب التي يقدّمها بَرق؟

واجهةٌ برمجيّة موثّقة تعيد سعر الذهب والفضّة الحيّ بعقدِ بياناتٍ ثابت، مع أسعار العيارات (24 و22 و21 و18) بالريال السعوديّ والدولار، وبثٌّ لحظيّ عبر WebSocket لمن يريد التحديث الفوريّ.

بأيّ عملةٍ يعيد بَرق سعر الذهب؟

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

كم يتأخّر السعر، وهل هو لحظيّ فعلاً؟

يتجدّد السعر أكثر من مرّةٍ في الثانية على البثّ الحيّ، ويصل نظامَك فور حدوثه بلا استعلامٍ متكرّر. وقراءة API تعيد آخر سعرٍ معتمَدٍ عند الطلب، مرفقاً بلحظة تحديثه وحالته.

ماذا يحدث لسعري إن تعطّل مصدرٌ عند بَرق؟

لا يتوقّف السعر الذي يصل واجهتك، ينتقل بَرق تلقائياً إلى المصدر الأفضل التالي. وإن انقطعت المصادر أثناء التداول وصلك السعر موسوماً «بائتاً» بدل رقمٍ مضلّل، فلا تبني قراراً على سعرٍ ميّت.

ادمج طبقةَ سعرٍ حيٍّ موثوقٍ في نظامك عبر واجهةٍ واحدة.

ابدأ في ثلاث خطوات

احصل على رمز وصول

اطلب السعر

اقرأ حالته أوّلاً

المصادقة والحدود

رمز وصول

نطاقات صلاحية

حدُّ معدّل

النطاقات

الترويسات وحدّ المعدّل

وضع التجربة

نقاط الوصول

مثال الاستجابة

مرجع النقاط

الأخطاء والرموز

البثّ الحيّ

أمثلة الكود

جرّبها

أسئلة المطوّرين

رمزُ الوصول يبدأ بمحادثة.