مرجع API العملات الرقمية

الأسعار والسجل التاريخي لأزواج العملات الرقمية

نظرة عامة

أسعار وسجل أسعار أزواج العملات الرقمية. يحتاج كل طلب إلى مفتاح Bearer، ويسحب REST وMCP من رصيد واحد.

معرّف الزوج هو العملة الرقمية ثم شرطة ثم عملة التسعير، مثل BTC-USD أو ETH-EUR. تصلح أي حالة أحرف، ويُقبل أيضًا الشرطة المائلة بدل الشرطة. تحمل كل إجابة الزوج القياسي. عملات التسعير هي USD وEUR وGBP. الأسعار سلاسل عشرية بحد أقصى 8 أرقام معنوية.

تُتداول العملات الرقمية طوال اليوم، فلا توجد جلسة سوق. ويكون السعر قديمًا (stale) إذا تجاوز عمره 5 دقائق.

عنوان URL الأساسي: https://api.narwhalapi.com. أداة MCP هي crypto, with one action لكل مسار أدناه.

ما يحصل عليه كل حساب

ما	كل حساب
أحدث سعر	مباشر
التغير خلال 24 ساعة	مشمول
أشرطة يومية	السجل التاريخي الكامل
شموع الدقيقة الواحدة	مشمول
قائمة الأزواج	مشمول

راجع التسعير لمعرفة تكلفة الاستدعاء. يُحاسَب الطلب بسعر واجهته ما لم يذكر المسار خلاف ذلك.

لا يوجد حجم تداول للعملات الرقمية. لا تحمل الأسعار ولا الشموع حقل حجم.
الشمعة اليومية تمثل يومًا واحدًا بتوقيت UTC وتظهر عند 00:00 UTC. ولا تظهر شمعة اليوم الجزئية أبدًا.
تضم قائمة الأزواج الأزواج التي نسعّرها. يبقى الزوج في القائمة ما دام يُتداول مرة واحدة على الأقل كل 30 ثانية، ويُحذف إذا انخفض عن مرة كل دقيقتين.

نقاط النهاية

كل مسار هو طلب GET ويحتاج إلى مفتاحك في: Authorization: Bearer الترويسة. تعرض الأمثلة شكل الاستجابة، وليست بيانات مباشرة.

أزواج العملات الرقمية التي نسعّرها

GET /v1/crypto/pairs

كل زوج نسعّره، مرتبًا حسب الزوج (بصيغة BTC-USD). المعامل quote اختياري (USD أو EUR أو GBP). يبقى الزوج في القائمة ما دام يُتداول مرة واحدة على الأقل كل 30 ثانية، ويُحذف إذا انخفض عن مرة كل دقيقتين. تُقرأ من قائمة الأزواج لدينا، فهي متاحة لكل حساب وتُحسب استدعاءً واحدًا.

MCP: الأداة crypto, action pairs.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`quote`	استعلام	لا	إحدى القيم: USD, EUR, GBP	الأزواج المسعّرة بهذه العملة فقط (USD أو EUR أو GBP).

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

حقل	النوع	يُرسل	المعنى
`pairs`	قائمة كائنات	دائمًا	كل زوج نسعّره، مرتبًا حسب الزوج. يبقى الزوج في القائمة ما دام يُتداول مرة واحدة على الأقل كل 30 ثانية، ويُحذف إذا انخفض عن مرة كل دقيقتين.
`pairs[].pair`	سلسلة نصية	دائمًا	الزوج القياسي، مثل BTC-USD.
`pairs[].base`	سلسلة نصية	دائمًا	رمز تداول العملة الرقمية.
`pairs[].quote`	سلسلة نصية	دائمًا	عملة التسعير.
`pairs[].name`	سلسلة نصية	دائمًا	اسم العملة الرقمية.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/crypto/pairs?quote=USD"

{
  "pairs": [
    {
      "pair": "BTC-USD",
      "base": "BTC",
      "quote": "USD",
      "name": "Bitcoin"
    },
    {
      "pair": "ETH-EUR",
      "base": "ETH",
      "quote": "EUR",
      "name": "Ethereum"
    }
  ]
}

آخر سعر لزوج عملات رقمية واحد

GET /v1/crypto/{pair}/price

آخر سعر مركّب لزوج، مع التغير خلال 24 ساعة (يُحذف إذا لم يكن معروفًا). تُتداول العملات الرقمية طوال اليوم، فلا توجد جلسة سوق؛ وقيمة stale تكون true إذا تجاوز عمر السعر 5 دقائق. change_24h_percent بالنسبة المئوية.

MCP: الأداة crypto, action price.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`pair`	مسار	نعم	سلسلة نصية	زوج عملات رقمية: العملة الرقمية ثم شرطة ثم عملة التسعير، مثل BTC-USD أو ETH-EUR. تصلح أي حالة أحرف، ويُقبل الشرطة المائلة بدل الشرطة. تحمل الإجابة الزوج القياسي.

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

حقل	النوع	يُرسل	المعنى
`pair`	سلسلة نصية	دائمًا	الزوج القياسي.
`base`	سلسلة نصية	دائمًا	رمز تداول العملة الرقمية.
`quote`	سلسلة نصية	دائمًا	عملة التسعير؛ كل سعر بها.
`price`	سلسلة نصية	دائمًا	آخر سعر، بحد أقصى 8 أرقام معنوية.
`change_24h`	سلسلة نصية	اختياري	`price` مطروحًا منه السعر قبل 24 ساعة، ويُحسب من نسبة التغير خلال 24 ساعة. يُحذف إذا لم يكن معروفًا.
`change_24h_percent`	سلسلة نصية	اختياري	التغير خلال 24 ساعة بالنسبة المئوية (1.5 تعني 1.5%). يُحذف مع `change_24h`.
`timestamp`	تاريخ ووقت	دائمًا	وقت صلاحية السعر (بالتوقيت العالمي UTC، بالثواني الكاملة).
`stale`	منطقي	دائمًا	تكون true إذا تجاوز عمر السعر 5 دقائق أو تعذّر تحديثه.
`delayed`	دائمًا true	اختياري	لا يُرسل: الأسعار فورية لكل حساب.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/crypto/BTC-USD/price"

{
  "pair": "BTC-USD",
  "base": "BTC",
  "quote": "USD",
  "price": "68250.5",
  "change_24h": "812.4",
  "change_24h_percent": "1.2",
  "timestamp": "2026-10-26T15:42:00Z",
  "stale": false
}

آخر أسعار حتى 50 زوج عملات رقمية

GET /v1/crypto/prices

آخر سعر لكل زوج مذكور. يُحتسب استدعاء واحد لكل زوج يعيد سعرًا، ويُخصم في خطوة واحدة: إذا لم يكفِ رصيدك لتغطية الأزواج التي تم حلّها، يُرفض الطلب كله مع 402 insufficient_credits. الأزواج التي لا تعيد سعرًا تُدرج في errors (باسم id) ولا تُكلّف شيئًا. change_24h_percent بالنسبة المئوية.

أرسل حتى 50 زوجًا. تُحاسَب الدفعة في خطوة واحدة: إذا لم يكفِ رصيدك لتغطية الأزواج التي يتم حلّها، يعيد الطلب كله 402 insufficient_credits.

MCP: الأداة crypto, action prices.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`pairs`	استعلام	نعم	سلسلة نصية	أزواج مفصولة بفواصل، بحد أقصى 50 بعد حذف المكرر. يخضع كل زوج لقواعد مسار السعر الواحد نفسها. يُحتسب استدعاء واحد لكل زوج يعيد سعرًا.

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

حقل	النوع	يُرسل	المعنى
`prices`	قائمة كائنات	دائمًا	سعر واحد لكل زوج تم حلّه، مرتبًا حسب الزوج.
`prices[].pair`	سلسلة نصية	دائمًا	الزوج القياسي.
`prices[].base`	سلسلة نصية	دائمًا	رمز تداول العملة الرقمية.
`prices[].quote`	سلسلة نصية	دائمًا	عملة التسعير؛ كل سعر بها.
`prices[].price`	سلسلة نصية	دائمًا	آخر سعر، بحد أقصى 8 أرقام معنوية.
`prices[].change_24h`	سلسلة نصية	اختياري	`price` مطروحًا منه السعر قبل 24 ساعة، ويُحسب من نسبة التغير خلال 24 ساعة. يُحذف إذا لم يكن معروفًا.
`prices[].change_24h_percent`	سلسلة نصية	اختياري	التغير خلال 24 ساعة بالنسبة المئوية (1.5 تعني 1.5%). يُحذف مع `change_24h`.
`prices[].timestamp`	تاريخ ووقت	دائمًا	وقت صلاحية السعر (بالتوقيت العالمي UTC، بالثواني الكاملة).
`prices[].stale`	منطقي	دائمًا	تكون true إذا تجاوز عمر السعر 5 دقائق أو تعذّر تحديثه.
`prices[].delayed`	دائمًا true	اختياري	لا يُرسل: الأسعار فورية لكل حساب.
`errors`	قائمة كائنات	دائمًا	الأزواج التي لم تعد سعرًا. لا تُحاسَب.
`errors[].id`	سلسلة نصية	دائمًا	المعرّف كما طُلب.
`errors[].code`	إحدى القيم: not_found, not_covered, upstream_busy	دائمًا	not_found: لا يوجد رمز مُدرج بهذا المعرّف. not_covered: لا أسعار لهذه البورصة بعد. upstream_busy: تعذر جلب السعر الآن، فأعد المحاولة بعد قليل.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/crypto/prices?pairs=BTC-USD,ETH-USD"

{
  "prices": [
    {
      "pair": "BTC-USD",
      "base": "BTC",
      "quote": "USD",
      "price": "68250.5",
      "change_24h": "812.4",
      "change_24h_percent": "1.2",
      "timestamp": "2026-10-26T15:42:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XYZ-USD",
      "code": "not_found"
    }
  ]
}

شموع أسعار زوج عملات رقمية واحد

GET /v1/crypto/{pair}/bars

شموع يومية (1d، يوم UTC واحد، تُغلق عند 00:00 UTC) أو بدقيقة واحدة (1m)، الأقدم أولًا. تصدر شمعة اليوم عند 00:00 UTC؛ ولا تظهر شمعة اليوم الجزئية أبدًا. السجل التاريخي: كامله، لكل حساب. حتى 5,000 شمعة في الصفحة، مع next_cursor؛ والمؤشر الذي لم يعد يطابق الأسعار يعيد 409 cursor_expired. استدعاء واحد لكل صفحة.

إذا تغيرت الأسعار التي يقوم عليها مؤشر، يتوقف المؤشر عن العمل ويعيد 409 cursor_expired.

MCP: الأداة crypto, action bars.

المعلمات

معلمة	الموضع	مطلوب	النوع	المعنى
`pair`	مسار	نعم	سلسلة نصية	زوج عملات رقمية: العملة الرقمية ثم شرطة ثم عملة التسعير، مثل BTC-USD أو ETH-EUR. تصلح أي حالة أحرف، ويُقبل الشرطة المائلة بدل الشرطة. تحمل الإجابة الزوج القياسي.
`interval`	استعلام	لا	إحدى القيم: 1d, 1m	`1d` (شمعة واحدة لكل يوم UTC، تُغلق عند 00:00 UTC) أو `1m` (شموع الدقيقة الواحدة). أي قيمة أخرى تعيد 400 invalid_interval.
`start`	استعلام	لا	سلسلة نصية	أول شمعة. `1d`: تاريخ (YYYY-MM-DD)، شاملًا؛ وحذفه يعني أقدم شمعة متاحة. `1m`: وقت بتوقيت UTC (YYYY-MM-DDTHH:MM:SSZ، أو تاريخ للدلالة على 00:00 UTC)، شاملًا؛ وحذفه يعني يومًا واحدًا قبل `end`.
`end`	استعلام	لا	سلسلة نصية	آخر شمعة. `1d`: تاريخ شامل؛ وحذفه يعني آخر يوم مكتمل. `1m`: وقت UTC غير شامل؛ وحذفه يعني الآن، أو بعد خمسة أيام من `start`. بحد أقصى 5 أيام بين `start` و`end` للقيمة `1m` (400 range_too_large).
`cursor`	استعلام	لا	سلسلة نصية	`next_cursor` من الصفحة السابقة، مع المعاملات نفسها.

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

حقل	النوع	يُرسل	المعنى
`pair`	سلسلة نصية	دائمًا	الزوج القياسي.
`start`	سلسلة نصية	اختياري	لا يُرسل أبدًا: لا يُنقل `start`.
`end`	سلسلة نصية	اختياري	لا يُرسل أبدًا: لا تُقتطع الشموع اليومية.
`bars`	قائمة كائنات	دائمًا	5,000 شمعة في الصفحة كحد أقصى.
`bars[].timestamp`	تاريخ ووقت	دائمًا	بداية فترة الشمعة (UTC): 00:00 للشمعة اليومية، والدقيقة نفسها لشمعة الدقيقة الواحدة.
`bars[].open`	سلسلة نصية	دائمًا	أول سعر في الفترة.
`bars[].high`	سلسلة نصية	دائمًا	أعلى سعر في الفترة.
`bars[].low`	سلسلة نصية	دائمًا	أدنى سعر في الفترة.
`bars[].close`	سلسلة نصية	دائمًا	آخر سعر في الفترة.
`next_cursor`	سلسلة نصية	دائمًا	أعد إرساله لقراءة الصفحة التالية. تكون قيمته null في الصفحة الأخيرة.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/crypto/BTC-USD/bars?interval=1d&start=2026-10-01"

{
  "pair": "BTC-USD",
  "bars": [
    {
      "timestamp": "2026-10-25T00:00:00Z",
      "open": "67210.3",
      "high": "68540.9",
      "low": "66980.1",
      "close": "68100.2"
    }
  ],
  "next_cursor": null
}

الأخطاء

تستخدم الأخطاء بنية المشكلة المشتركة مع: request_id. راجع أخطاء API والرصيد لمعرفة الشكل وترويسات الرصيد. لا تُحاسَب الطلبات الفاشلة.

الرمز	الحالة	المعنى
`invalid_query`	400	معامل مفقود أو غير معروف أو مكرر أو خارج نطاقه.
`invalid_id`	400	معرّف أو زوج غير مكتوب بالصيغة التي تتوقعها هذه الواجهة.
`too_many_ids`	400	تحتوي الدفعة على أكثر من 50 معرّفًا.
`invalid_interval`	400	الفاصل الزمني ليس 1d ولا 1m، أو غير متاح لهذه الأداة.
`range_too_large`	400	النافذة أطول مما يسمح به المسار.
`not_found`	404	لا يوجد رمز مُدرج أو صندوق أو زوج بهذا المعرّف.
`invalid_cursor`	400	مؤشر الصفحة هذا لم يُعده هذا الطلب، أو أنه من طلب مختلف.
`cursor_expired`	409	تغيرت الأسعار التي يقوم عليها المؤشر. ابدأ من جديد دون المؤشر.
`insufficient_credits`	402	رصيدك أقل من تكلفة الطلب.
`upstream_busy`	503	تعذّر جلب السعر الآن. وفي الدفعة يُدرج في errors. حاول مجددًا بعد قليل.
`area_unavailable`	503	هذا القسم لا يستطيع الإجابة الآن.

هل كانت هذه الصفحة مفيدة؟