المصادقة ومفاتيح API

ما هو مفتاح API

مفتاح API هو السر الذي ترسله شيفرتك إلى Cognivo كي نعرف أن الطلب طلبك. كل استدعاء لواجهة المطورين البرمجية يحمل مفتاحاً. توجد المفاتيح داخل مشروع، والمشروع يجمع مفاتيحك واستخدامها معاً.

اقرأ هذه الصفحة قبل أول استدعاء لك، أو عندما تحتاج إلى معرفة ما يُسمح للمفتاح بفعله، أو عندما يكون مفتاح قد تسرّب وتحتاج إلى إيقافه.

أين تجدها

سجّل الدخول إلى تطبيق Cognivo اللامركزي، وافتح Account في الشريط الجانبي الأيسر، ثم Developers. عند تسجيل الخروج، تعرض الصفحة شاشة تعريفية فقط.

تحتوي صفحة Developers على أربع علامات تبويب: Keys وUsage وEndpoints وQuickstart. كل ما في هذه الصفحة يحدث في علامة التبويب Keys.

الوصول الحي ورصيد أرصدتك

يوضّح شريط في أعلى الصفحة نموذج الوصول بصراحة: بعض نقاط النهاية مجانية مع أي مفتاح نشط، وأخرى تُحصَّل لكل استدعاء ناجح من رصيد أرصدة Cognivo لديك. وفي الأسفل، تؤكد بطاقة Live API access أن المفتاح الحي يعمل لحظة إنشائه. لا توجد خطوة موافقة ولا قائمة انتظار.

وإلى جانبها تعرض الصفحة رصيد أرصدتك الحالي، وزر Top up credits، وزر Enterprise access. Enterprise هو مسار الوصول الوحيد الذي يمر عبر طلب، من أجل تسعير مخصص أو حدود أعلى. وكل ما عداه خدمة ذاتية.

لوحة الوصول الحي إلى API، أسفل صفحة Developers.تكبير الصورة

يحصل كل حساب Cognivo أيضاً على 5 أرصدة مجانية كل يوم، تُعاد ضبطها عند منتصف الليل بتوقيت UTC. راجع الفوترة والأرصدة لمعرفة كيف يعمل الرصيد، وحدود المعدل والأخطاء والفوترة لأسعار كل نقطة نهاية.

علامة التبويب Keys

اختر مشروعاً من القائمة المنسدلة Project، أو أنشئ واحداً بـ New project. عندها تسرد علامة التبويب Keys كل مفتاح ينتمي إليه.

علامة تبويب المفاتيح في صفحة Developers، تسرد كل مفتاح ينتمي إلى المشروع المحدد.تكبير الصورة

يعرض كل صف مفتاح الاسم الذي أعطيته له، وما إذا كان مفتاحاً تجريبياً أو حياً، والحد الساعي المطبَّق، والصلاحيات التي يحملها، ووقت إنشائه وآخر استخدام له. Last used: Never تعني أنه لم يُنفَّذ أي استدعاء بذلك المفتاح قط.

تُعرض البادئة وآخر أربعة أحرف من المفتاح فقط. لا يخزّن Cognivo أي شيء آخر يمكن قراءته مرة أخرى، ولهذا يظهر المفتاح الكامل مرة واحدة بالضبط.

إنشاء مفتاح

اختر + New key. يطلب النموذج ثلاثة أشياء: اسماً اختيارياً يساعدك على التمييز بين مفاتيحك، ووضعاً Test أو Live، وصلاحية واحدة على الأقل.

نموذج المفتاح الجديد في صفحة Developers، ويُفتح بزر مفتاح جديد.تكبير الصورة

اختيار Live يعرض رصيد أرصدتك أسفل قائمة الوضع، كتذكير بأن الاستدعاءات الحية استدعاءات حقيقية وتُحصَّل من ذلك الرصيد. واختيار Test ينشئ مفتاح بيئة اختبار لا تُحصَّل عليه رسوم أبداً وله حدود ضيقة.

اختر Create key فيظهر المفتاح الكامل مرة واحدة، في نافذة.

1. استخدم أيقونة النسخ لنسخ المفتاح كاملاً ما دام معروضاً على الشاشة، فهو لا يُعرض مرة أخرى.
2. اختر تم بعد أن تخزّن المفتاح في مكان يمكنك العثور عليه لاحقاً.

حوار المفتاح لمرة واحدة في علامة تبويب المفاتيح، ويظهر لحظة إنشاء مفتاح جديد.تكبير الصورة

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

إرسال مفتاحك

الترويسة المعتمدة هي X-API-Key:

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

ويُقبل Authorization: Bearer YOUR_API_KEY كاسم بديل لمكتبات العملاء التي تفضّله. احتفظ بالمفتاح على خادمك. لا تضعه أبداً في شيفرة المتصفح.

تغطي الواجهة البرمجية Ethereum وBase وBNB Chain اليوم في معامل chain المشترك. وRobinhood Chain حيّة في Cognivo ولها نقطة نهاية خاصة بها في الواجهة البرمجية بدلاً من أن تكون قيمة chain في نقاط النهاية المشتركة.

الصلاحيات

المفاتيح ترفض افتراضياً. لا يستطيع المفتاح استدعاء إلا مجموعات نقاط النهاية التي منحتها عند إنشائه. هناك ثلاث صلاحيات، وكل واحدة تفتح مجموعة من نقاط النهاية.

Intelligence (intel:read) هي الصلاحية اليومية. تجيب عن سؤال "ما الذي يجري مع هذا التوكن أو هذه المحفظة؟": مسبّبات هبوط السعر، وإشارات المخاطر، وسلوك محافظ الفريق، والأرباح والخسائر المحققة، والحركات الدقيقة. تفتح POST /v1/api/intel/why-down وPOST /v1/api/intel/team-wallets وPOST /v1/api/intel/risk وPOST /v1/api/wallet/pnl وPOST /v1/api/wallet/exact-movements.

Security (security:read) تتيح للمفتاح فحص ما وافقت عليه محفظة، بما في ذلك أي العقود يمكنها إنفاق توكناتها وأي التفويضات غير محدودة. وهي للقراءة فقط. لا يستطيع مفتاح يحمل هذه الصلاحية أبداً تحريك أموال أو إلغاء موافقة. تفتح POST /v1/api/wallet/approvals.

Liquidity (liquidity:read) تتيح للمفتاح قراءة سياق المجمّعات، وحيازة LP، وسياق الأقفال والحرق. تفتح POST /v1/api/intel/liquidity.

لا تحتاج GET /v1/api/health إلى مفتاح إطلاقاً. وتعمل GET /v1/api/me وGET /v1/api/discover مع أي مفتاح صالح، مهما كانت صلاحياته.

تُثبَّت الصلاحيات عند إنشاء المفتاح. لتغييرها، أنشئ مفتاحاً جديداً بالصلاحيات التي تحتاجها وألغِ القديم. الاستدعاء الذي يفشل بـ 403 scope_denied يعني أن المفتاح لا يحمل الصلاحية التي تحتاجها تلك نقطة النهاية.

المفاتيح التجريبية والمفاتيح الحية

البادئة	لماذا تُستخدم	الفوترة	حد المعدل
cogv_test_	تجربة الواجهة البرمجية. موسومة بـ Test وSandbox في البوابة. لا تستطيع تشغيل الذكاء الحي.	لا تُحصَّل عليها رسوم أبداً	25 طلباً في الساعة، و100 في اليوم، و1 في الثانية
cogv_live_	حركة حقيقية. خدمة ذاتية، تعمل فوراً.	أرصدة Cognivo لكل استدعاء ناجح. الاستدعاءات الفاشلة لا تُحصَّل عليها رسوم أبداً.	1,000 طلب في الساعة للبداية، راجع حدود المعدل

المفتاح التجريبي ليس مفتاح إنتاج مجانياً. الاستدعاءات الحية المنفَّذة بواحد منها تجيب بـ 403 sandbox_limited. تحصيل الرسوم على استدعاءات Developer API متوقف اليوم، لذا لا يخصم الاستدعاء الناجح أي رصيد ولا يتغير رصيدك.

تعرض البوابة أيضاً وضع وصول على كل مفتاح. Paid هو الدفع حسب الاستخدام العادي. Trial هو مخصّص تقييم مؤقت له تاريخ انتهاء. Partner وEnterprise ترتيبات تُعدّ مع Cognivo. Suspended تعني أن المفتاح لا يستطيع تنفيذ أي شيء، وتعرض البوابة السبب. عدد قليل من المفاتيح الأقدم يسبق الفوترة الذاتية ولا يستطيع سوى استدعاء نقاط نهاية البيانات الوصفية، فتجيب الاستدعاءات الحية بـ 403 access_required. أنشئ مفتاحاً حياً جديداً لنقل تلك إلى الدفع حسب الاستخدام.

تبلّغ GET /v1/api/me عن وضع وصول مفتاحك، وصلاحياته، وcredits_balance الخاص بك، وإرشادات الشحن. إذا كان رصيدك لا يغطي استدعاءً فستحصل على 402 payment_required ولا تُحصَّل رسوم. اشحن رصيدك وأعد المحاولة.

التدوير والإلغاء

يوجد كلا العنصرين على يمين كل صف مفتاح.

1. اقرأ شارتَي Test و Sandbox بجانب الاسم لتعرف نوع هذا المفتاح، إضافةً إلى الحد بالساعة المعروض بجانبهما.
2. اختر التدوير لاستبدال هذا المفتاح بمفتاح جديد، يُعرض مرة واحدة ويوقف عمل المفتاح القديم فوراً.
3. اختر الإبطال لإيقاف مفتاح نهائياً، مثلاً إذا لم تعد بحاجة إليه أو كنت تظن أن شخصاً آخر قد اطّلع عليه.

صفوف المفاتيح في علامة تبويب المفاتيح بصفحة Developers.تكبير الصورة

يطلب التدوير منك التأكيد أولاً، وتوضّح النافذة بالضبط ما الذي سيحدث.

تأكيد التدوير في علامة تبويب المفاتيح، ويظهر بعد اختيارك التدوير على مفتاح.تكبير الصورة

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

دوّر المفتاح عند أي تسرّب مشتبه به، وعلى جدول منتظم.

القيود التي يمكن لـ Cognivo تطبيقها على مفتاح

تُضبط هذه على سجل المفتاح لا في نموذج البوابة، وتُطبَّق على كل طلب. يمكنك تأكيد ما ينطبق على مفتاحك بـ GET /v1/api/me.

• تقييد الشبكة. يمكن حصر مفتاح بشبكات محددة. الطلب الذي يسمّي شبكة مختلفة يُرفض بـ 403 chain_denied. يقع الرفض قبل أن يستدعي Cognivo أي شيء أعلى السلسلة وقبل استخدام أي مخصّص، فالاستدعاء الذي لا يُسمح لمفتاحك بتنفيذه لا يكلّفك شيئاً أبداً. يُبلَّغ عنه كـ allowed_chains، حيث تعني null عدم وجود تقييد.
• الانتهاء. يمكن إعطاء مفتاح تاريخ انتهاء. بعد مروره، يتوقف المفتاح عن العمل في كل مكان، بما في ذلك GET /v1/api/me، ويعيد 403 key_expired. يُبلَّغ عنه كـ expires_at، حيث تعني null أنه لا ينتهي. وإذا كان لمخصّص تجريبي تاريخ انتهاء أيضاً، فالأسبق منهما هو ما ينطبق.
• قوائم السماح للأصول وعناوين IP. يمكن حصر مفتاح بأصول محددة، بما في ذلك النطاقات الفرعية بأحرف البدل مثل https://*.yourapp.com، أو بعناوين IP ونطاقات CIDR محددة. الطلبات من أي مكان آخر تُرفض بـ 403 origin_denied. القوائم الفارغة تعني عدم وجود تقييد.

الخطوات التالية

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