exchangerate.devيمكن للمتصفح البدء بطلب مجهول. أما Node.js والخادم فيجب أن يضعا المفتاح في متغير بيئة ويحفظا مصدر السعر ووقت رصده.
- يدعم Node 18+ وDeno وBun والمتصفحات الحديثة fetch.
- لا تضع مفتاح الحساب في كود المتصفح.
- يحسب currency.js المبالغ وينسقها ولا يجلب الأسعار.
- تحقق من حالة HTTP واحترم Retry-After بعد 429.
- اعرض source وeffective_at عند الحاجة إلى شرح حداثة القيمة.
استدعاؤك الأول، دون مفتاح
في Node 18 أو أي متصفح حديث لديك fetch جاهزة. await واحدة تكفي لقراءة سعر اليورو:
الاستدعاءات المجهولة محدودة لكل عنوان IP، فانتقل إلى مفتاح مجاني قبل أن تتجاوز مرحلة التجربة السريعة.
أضف مفتاحًا ومعالجة للأخطاء
مرّر مفتاحك كرمز bearer في ترويسة Authorization. افحص res.ok وارمِ استثناء عند حالة سيئة كي تظهر الأخطاء مبكرًا:
ترويسة X-API-Key: exr_live_... مقبولة أيضًا، للمنصات التي لا تستطيع ضبط ترويسة Authorization (بعض بيئات serverless وZapier وأدوات no-code المماثلة).
حوّل مبلغًا
للتحويل المباشر استدعِ /v1/convert/{from}/{to}/{amount}. تعطيك الاستجابة السعر والمبلغ المحوّل في رحلة واحدة:
يعيد مسار التحويل حقلي source وmarket_session نفسيهما اللذين يعيدهما مسار latest، فتستطيع أن تعرض للمستخدمين فئة السعر وهل أسبوع التداول بين البنوك مفتوح.
افهم source وmarket_session
للعملة المعروضة، اقرأ sources[currency] لمعرفة نوع المصدر وeffective_at[currency] لمعرفة وقت الرصد. يلخص source البيانات الأقل حداثة في الاستجابة كلها. يصف market_session جلسة السوق، بينما يشير timestamp إلى وقت إنشاء الاستجابة لا إلى وقت رصد السعر.
| قيمة الحقل | ما معناها | متى تتحرك |
|---|---|---|
| source: live | سعر فوري إرشادي | خلال اليوم (~60 ث)، أسبوع التداول |
| source: ecb_daily | التثبيت المرجعي للبنك المركزي الأوروبي | مرة كل يوم عمل (~16:00 CET) |
| source: market_daily | إغلاق محفوظ دون تثبيت ECB | سوق يومي |
| market_session: weekend | سبت أو أحد (سوق ما بين البنوك مغلقة) | التثبيتات المرجعية تحمل قيمة الجمعة؛ التغذية الحية لا تتحدث |
يخبرك حقل data_updated_at بآخر مرة كُتب فيها السعر الأساسي. ويسجّل timestamp وقت بناء الاستجابة. معًا يتيحان لك تقرير كيفية التخزين المؤقت للقيمة وعرضها.
تُنشر هذه الأسعار للمرجعية والتحليل والعرض. ليست تسعيرة تداول ويجب ألا تُستخدم لتسوية صفقة أو تحويل. تصرّح كل استجابة بذلك في حقل notice الخاص بها.
حدود الخطة المجانية
تُعاد الحصة الشهرية عند الساعة 00:00 UTC في اليوم الأول من كل شهر. عند تلقي 429، انتظر المدة المحددة في Retry-After قبل إعادة المحاولة.
- 5,000 استدعاء شهريًا
- 10 طلبات في الدقيقة
- دون بطاقة ائتمان
- يغطي
/v1/latestو/v1/convertو/v1/rangeو/v1/{date}/{base}
احسب المبلغ ونسقه
يساعد currency.js في المبالغ والدقة والتنسيق. اجلب السعر أولاً من API ثم اضرب المبلغ.
const response = await fetch("https://api.exchangerate.dev/v1/latest/USD?symbols=EUR,GBP", { signal: AbortSignal.timeout(10_000),});if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);const data = await response.json();console.log(data.rates.EUR);console.log(data.sources.EUR, data.effective_at.EUR);console.log(data.market_session);// Node.js server only. Never put an account key in browser code.const KEY = process.env.EXCHANGERATE_API_KEY;if (!KEY) throw new Error("Set EXCHANGERATE_API_KEY on your server");async function getLatest(base = "USD") { const response = await fetch(`https://api.exchangerate.dev/v1/latest/${encodeURIComponent(base)}`, { headers: { Authorization: `Bearer ${KEY}` }, redirect: "error", signal: AbortSignal.timeout(10_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`); return response.json();}const data = await getLatest("USD");console.log(data.rates.GBP, data.effective_at.GBP);// Node.js server only.const KEY = process.env.EXCHANGERATE_API_KEY;if (!KEY) throw new Error("Set EXCHANGERATE_API_KEY on your server");const response = await fetch("https://api.exchangerate.dev/v1/convert/USD/EUR/100", { headers: { Authorization: `Bearer ${KEY}` }, redirect: "error", signal: AbortSignal.timeout(10_000),});if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);const data = await response.json();console.log(data.rate, data.converted);import currency from "currency.js";const response = await fetch("https://api.exchangerate.dev/v1/latest/USD?symbols=EUR", { signal: AbortSignal.timeout(10_000),});if (!response.ok) throw new Error(`HTTP ${response.status}`);const data = await response.json();const rate = data.rates.EUR;if (!Number.isFinite(rate) || rate <= 0) throw new Error("Invalid rate");const euros = currency("100.00", { precision: 2, symbol: "€" }).multiply(rate);console.log(euros.format());