مرجع API الذهب: النقاط والأمثلة

تحتاج كل نقطة إلى مفتاح API: غياب المفتاح أو خطؤه يعيد 401، وتجاوز الحد يعيد 429. وتذكر كل نقطة أكوادها بالأسفل، وشرحها كلها في الأخطاء

GETFree /api/v1/price/{symbol}/{currency}/{karat} سعر المعدن بأي عملة، للوحدة وللجرام. GETFree /api/v1/karat سعر الجرام لكل عيارات الذهب في طلب واحد. GETFree /api/v1/convert بين المعادن والعملات ووحدات الوزن. GETFree /api/v1/symbols المعادن التي يمكنك طلبها. GETFree /api/v1/rates أسعار اليوم مقابل الدولار. GETBasic /api/v1/history/{symbol} إغلاقات المعدن اليومية خلال فترة. GETPro /api/v1/ohlc/{symbol} الفتح والأعلى والأدنى والإغلاق لكل يوم.

المصادقة

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

Header

X-API-Key: YOUR_API_KEY

عند الوصول إلى الحد

تشمل الباقة المجانية 100 طلب في الساعة، وBasic 2,000، وPro بلا حد. يشمل العد كل مفاتيح حسابك معًا، وكذلك الطلبات المرفوضة بسبب الباقة، ويبدأ من جديد مع كل ساعة. وتوضح الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (بتوقيت Unix) موقفك، بينما ترسل Pro فقط X-RateLimit-Limit: unlimited. وعند تجاوز الحد يعود 429 مع ترويسة Retry-After بالثواني. حدود الخطة المجانية

السعر المباشر

GET/api/v1/price/{symbol}/{currency}/{karat}مفتاح API · Free وما فوق

السعر المباشر للمعدن بأي عملة، لوحدته وللجرام. ويمكنك اختيار العيار للذهب.

معاملات المسار

symbolstringمطلوب: المعدن: XAU أو XAG أو XPT أو XPD أو HG.
currencystring: رمز العملة، والافتراضي USD. يقبل أي رمز في نقطة rates.
karatint: للذهب فقط: 24 أو 22 أو 21 أو 18 أو 14، و24 افتراضيًا. ويغيّر سعر الجرام.

معاملات الاستعلام

currencystring: القيمة نفسها كمعامل استعلام. وإذا أُرسلا معًا يُعتمد المسار.
karatint: القيمة نفسها كمعامل استعلام. وإذا أُرسلا معًا يُعتمد المسار.

حقول الرد

price: السعر لكل وحدة، ولا يتغير بالعيار. والذهب بالجنيه المصري يتبع السوق المحلية في مصر.
gram: سعر الجرام، وفي الذهب بالعيار المذكور في الرد. بالجنيه المصري يكون رقمًا صحيحًا ما لم يقل عن 10 جنيهات.
gramBuy, gramSell: للذهب بالجنيه المصري فقط: سعرا الشراء والبيع التقديريان للجرام.
karat: للذهب فقط: عيار سعر الجرام.
prevClose, chPercent: لباقة Pro فقط: آخر إغلاق بالعملة المطلوبة ونسبة التغير عنه %. وتكون null إذا لم يوجد إغلاق.
updatedAt: وقت هذا الرد.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable400 unknown_karat400 karat_only_for_gold404 unknown_symbol429 rate_limit_exceeded

شكل الرد

{
  "symbol": string,
  "name": string,
  "currency": string,
  "unit": string,        // "oz" | "lb"
  "price": number,
  "gram": number,
  "gramBuy"?: number,    // gold in EGP
  "gramSell"?: number,   // gold in EGP
  "karat"?: number,      // gold
  "prevClose"?: number | null,  // Pro
  "chPercent"?: number | null,  // Pro
  "updatedAt": string    // ISO-8601
}

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

{
    "symbol": "XAU",
    "name": "Gold",
    "currency": "USD",
    "unit": "oz",
    "price": 4072.1,
    "gram": 130.921,
    "karat": 24,
    "updatedAt": "2026-11-07T02:39:36+02:00"
}

أسعار العيارات

GET/api/v1/karatمفتاح API · Free وما فوق

سعر جرام الذهب المباشر لكل العيارات (24 و22 و21 و18 و14) في طلب واحد. ولعيار واحد فقط استخدم /price.

معاملات الاستعلام

currencystring: رمز العملة، والافتراضي USD. يقبل أي رمز في نقطة rates.

حقول الرد

karats[].karat: العيار ونسبة نقائه: 24 = 100%, 22 = 91.66%, 21 = 87.5%, 18 = 75%, 14 = 58.33%.
karats[].gram: سعر الجرام، وفي الذهب بالعيار المذكور في الرد. بالجنيه المصري يكون رقمًا صحيحًا ما لم يقل عن 10 جنيهات.
karats[].gramBuy, gramSell: للذهب بالجنيه المصري فقط: سعرا الشراء والبيع التقديريان للجرام.
updatedAt: وقت هذا الرد.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

شكل الرد

{
  "currency": string,
  "karats": [
    {
      "karat": number,
      "gram": number,
      "gramBuy"?: number,   // EGP
      "gramSell"?: number   // EGP
    }
  ],
  "updatedAt": string    // ISO-8601
}

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

{
    "currency": "USD",
    "karats": [
        {
            "karat": 24,
            "gram": 130.921
        },
        {
            "karat": 22,
            "gram": 120.0022
        },
        {
            "karat": 21,
            "gram": 114.5558
        },
        {
            "karat": 18,
            "gram": 98.1907
        },
        {
            "karat": 14,
            "gram": 76.3662
        }
    ],
    "updatedAt": "2026-11-07T02:39:36+02:00"
}

التحويل

GET/api/v1/convertمفتاح API · Free وما فوق

يحوّل بين معدن وعملة، أو معدنين، أو عملتين، بالسعر المباشر. وللذهب يمكنك اختيار العيار.

معاملات الاستعلام

fromstringمطلوب: ما تحوّل منه: معدن (XAU وXAG وXPT وXPD وHG) أو رمز عملة موجود في /rates.
tostringمطلوب: ما تحوّل إليه، بنفس اختيارات from.
amountnumber: الكمية، و1 افتراضيًا. ويجب أن تكون أكبر من 0.
unitstring: وحدة المعدن: gram, tola, oz, tael, kilo, lb. وافتراضيًا وحدة المعدن نفسه (oz، أو lb للنحاس).
karatint: عندما يكون أحد الطرفين ذهبًا: 24, 22, 21, 18, 14. و24 افتراضيًا.

حقول الرد

unit: وحدة المعدن. لا تظهر إذا كان الطرفان عملتين.
karat: العيار المستخدم. يظهر فقط إذا كان أحد الطرفين ذهبًا.
rate: قيمة الوحدة الواحدة من from بعملة أو معدن to.
result: الكمية مضروبة في rate.
updatedAt: وقت هذا الرد.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 from_and_to_required400 invalid_amount400 unknown_unit400 unknown_karat400 karat_only_for_gold400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

شكل الرد

{
  "from": string,
  "to": string,
  "amount": number,
  "unit"?: string,     // metal side
  "karat"?: number,    // gold side
  "rate": number,
  "result": number,
  "updatedAt": string  // ISO-8601
}

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

{
    "from": "XAU",
    "to": "USD",
    "amount": 1,
    "unit": "gram",
    "karat": 24,
    "rate": 130.921,
    "result": 130.92,
    "updatedAt": "2026-11-07T02:39:36+02:00"
}

الرموز

GET/api/v1/symbolsمفتاح API · Free وما فوق

المعادن التي يعرفها الـAPI، بأسمائها ووحداتها.

حقول الرد

symbol: رمز المعدن.
name: اسم المعدن.
unit: وحدة السعر: oz أو lb.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

شكل الرد

{
  "symbols": [
    { "symbol": string, "name": string, "unit": string }
  ],
  "_server_time": string  // ISO-8601
}

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

{
    "symbols": [
        {
            "symbol": "XAU",
            "name": "Gold",
            "unit": "oz"
        },
        {
            "symbol": "XAG",
            "name": "Silver",
            "unit": "oz"
        },
        {
            "symbol": "XPT",
            "name": "Platinum",
            "unit": "oz"
        },
        {
            "symbol": "XPD",
            "name": "Palladium",
            "unit": "oz"
        },
        {
            "symbol": "HG",
            "name": "Copper",
            "unit": "lb"
        }
    ],
    "_server_time": "2026-11-07T02:39:36+02:00"
}

أسعار الصرف

GET/api/v1/ratesمفتاح API · Free وما فوق

أسعار صرف اليوم مقابل الدولار الأمريكي، والعملات الأكثر استخدامًا أولًا.

حقول الرد

base: العملة الأساسية: USD.
rates: سعر كل عملة مقابل دولار واحد.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

شكل الرد

{
  "base": "USD",
  "rates": { [currency: string]: number },
  "_server_time": string  // ISO-8601
}

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

{
    "base": "USD",
    "rates": {
        "USD": 1,
        "EUR": 0.89048,
        "GBP": 0.742915,
        "INR": 94.537031,
        "CNY": 6.682525,
        "JPY": 157.835475
    },
    "_server_time": "2026-11-07T02:39:36+02:00"
}

السجل اليومي

GET/api/v1/history/{symbol}مفتاح API · Basic وما فوق

أسعار إغلاق المعدن اليومية، من الأقدم إلى الأحدث، بقدر ما يتوفر في الأرشيف، وآخرها اليوم الجاري، لذا قد يزيد الرد صفًا واحدًا على days. يستخدم كل يوم سعر صرفه، والذهب بالجنيه المصري يستخدم أيضًا علاوة السوق المحلية لذلك اليوم. ويُستبعد اليوم الذي ليس له سعر صرف محفوظ.

معاملات المسار

symbolstringمطلوب: المعدن: XAU أو XAG أو XPT أو XPD أو HG.

معاملات الاستعلام

currencystring: رمز العملة، والافتراضي USD. العملات التي لها بيانات يومية فقط، وتجدها في قسم العملات.
rangestring: 1W أو 1M أو 3M أو 6M أو 1Y أو ALL (10 سنوات). يتقدم على days، وأي قيمة أخرى تُتجاهل.
daysint: عدد الأيام، والافتراضي 365. يبقى بين 1 و3650.

حقول الرد

days: الأيام المستخدمة بعد تطبيق range وحد 1 إلى 3650.
count: عدد الصفوف في الرد.
history[].date, close: اليوم وسعر إغلاقه لكل وحدة. وإغلاق اليوم الحالي يظل يتغير حتى ينتهي اليوم.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_basic404 unknown_symbol429 rate_limit_exceeded

شكل الرد

{
  "symbol": string,
  "currency": string,
  "days": number,
  "count": number,
  "history": [
    { "date": string, "close": number }  // YYYY-MM-DD, oldest first
  ],
  "_server_time": string  // ISO-8601
}

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

{
    "symbol": "XAU",
    "currency": "USD",
    "days": 1,
    "count": 2,
    "history": [
        {
            "date": "2026-11-06",
            "close": 4072
        },
        {
            "date": "2026-11-07",
            "close": 4072.1001
        }
    ],
    "_server_time": "2026-11-07T02:39:36+02:00"
}

الشموع اليومية

GET/api/v1/ohlc/{symbol}مفتاح API · Pro وما فوق

شمعة لكل يوم، من الأقدم إلى الأحدث، وآخرها اليوم الجاري. يستخدم كل يوم سعر صرفه، والذهب بالجنيه المصري يستخدم أيضًا علاوة السوق المحلية لذلك اليوم. ويُستبعد اليوم الذي ليس له سعر صرف محفوظ.

معاملات المسار

symbolstringمطلوب: المعدن: XAU أو XAG أو XPT أو XPD أو HG.

معاملات الاستعلام

currencystring: رمز العملة، والافتراضي USD. العملات التي لها بيانات يومية فقط، وتجدها في قسم العملات.
startunix: أول يوم بتوقيت Unix بالثواني. الافتراضي أول يوم محفوظ.
endunix: آخر يوم بتوقيت Unix بالثواني. الافتراضي حتى اليوم.

حقول الرد

count: عدد الصفوف في الرد.
candles[].date, open, high, low, close: اليوم وأسعاره لكل وحدة.
candles[].sealed: true عندما يصبح اليوم نهائيًا، وfalse ما دام قد يتغير.

رموز الرد

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_pro404 unknown_symbol429 rate_limit_exceeded

شكل الرد

{
  "symbol": string,
  "currency": string,
  "count": number,
  "candles": [
    {
      "date": string,  // YYYY-MM-DD
      "open": number,
      "high": number,
      "low": number,
      "close": number,
      "sealed": boolean
    }
  ],
  "_server_time": string  // ISO-8601
}

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

{
    "symbol": "XAU",
    "currency": "USD",
    "count": 2,
    "candles": [
        {
            "date": "2026-11-06",
            "open": 4090.3,
            "high": 4106.7998,
            "low": 4032.5,
            "close": 4072,
            "sealed": true
        },
        {
            "date": "2026-11-07",
            "open": 4072.3999,
            "high": 4072.3999,
            "low": 4072.1001,
            "close": 4072.1001,
            "sealed": false
        }
    ],
    "_server_time": "2026-11-07T02:39:36+02:00"
}

العملات

تعمل نقاط price وkarat وconvert وrates مع 166 عملة، وتعرضها rates. وتعمل نقطتا history وohlc مع 47 عملة بالأسفل، لأن كل يوم يحفظ أسعاره. وأي رمز آخر في هاتين النقطتين يعيد 400 unknown_currency.

USDEGPSARAEDKWDQARBHDOMRJODIQDLBPSDGYERLYDTNDDZDMADEURGBPTRYINRIDRCNYVNDPKRJPYCADAUDSGDHKDKRWTHBPHPMXNBRLZARCHFNZDILSMYRPLNCZKSEKNOKDKKHUFRON

الأخطاء

الأخطاء بصيغة JSON فيها الحقل error، وبعضها يضيف الحقول المذكورة في الجدول. ويُفحص الطلب بهذا الترتيب: المفتاح، ثم حد الساعة، ثم الباقة، ثم المعاملات.

الحالة	الخطأ	متى	يعيد أيضًا
400	`unknown_currency_or_unavailable`	عملة غير معروفة، أو السعر غير متاح الآن	`symbol, currency`
400	`unknown_currency`	في history وohlc: عملة ليس لها بيانات يومية	`currency, allowed`
400	`unknown_karat`	عيار غير 24 أو 22 أو 21 أو 18 أو 14	`karat, allowed`
400	`karat_only_for_gold`	عيار مع معدن غير الذهب	`symbol`
400	`from_and_to_required`	from أو to غير موجود
400	`invalid_amount`	amount ليس رقمًا أكبر من 0	`amount`
400	`unknown_unit`	وحدة غير gram, tola, oz, tael, kilo, lb	`unit, allowed`
401	`api_key_required`	الطلب بلا مفتاح
401	`invalid_api_key`	المفتاح غير صالح
403	`feature_requires_basic`	الخطة لا تشمل هذه النقطة
403	`feature_requires_pro`	الخطة لا تشمل هذه النقطة
403	`key_disabled`	المفتاح معطّل
403	`account_suspended`	الحساب موقوف
403	`email_not_verified`	بريد الحساب لم يتأكد بعد
403	`Forbidden`	العنوان api أو api/v1 وحده. ورده فيه الحقلان status وmessage بدل error.
404	`unknown_symbol`	معدن غير معروف	`symbol`
404	`not_found`	لا توجد نقطة بهذا العنوان، أو توجد أجزاء زائدة في المسار. ويقبل السجل والشموع العملة كمعامل استعلام فقط.
429	`rate_limit_exceeded`	تجاوز عدد الطلبات في الساعة
503	`prices_unavailable`	سعر المعدن غير متاح الآن