البداية السريعة

أول استدعاء لك لواجهة Cognivo البرمجية

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

متى تستخدمها

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

أين تجدها

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

أنشئ مشروعاً، ثم مفتاحاً

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

1. اختر مشروع جديد لفتح النموذج القصير أسفل محدّد المشروع.
2. اكتب اسماً في حقل اسم المشروع حتى تتمكن من التمييز بين مشاريعك لاحقاً.
3. اختر إنشاء لإضافة المشروع، أو إلغاء لإغلاق النموذج دون حفظ.
4. اختر إنشاء مفتاح مباشر لإنشاء مفتاح للمشروع، ثم أرسله مع طلباتك من داخل شيفرتك الخاصة.

عناصر التحكم بالمشاريع في صفحة Developers، حيث تُعِدّ مشروعاً قبل إنشاء مفتاح.تكبير الصورة

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

عندما تختار Create live key، يعرض Cognivo المفتاح الكامل مرة واحدة بالضبط، في نافذة فيها زر نسخ. انسخه حينها واحفظه في مكان آمن. بعد ذلك تعرض الصفحة نسخة مقنّعة فقط، البادئة وآخر أربعة أحرف، لأن Cognivo يخزّن المفتاح بصيغة لا يستطيع قراءتها مرة أخرى. إذا فقدت مفتاحاً، أو ظننت أنه تسرّب، فاستخدم Rotate أو Revoke على صف المفتاح. يتوقف المفتاح القديم عن العمل فوراً.

يحمل كل مفتاح أيضاً Permissions تتحكم بما يمكنه استدعاؤه: Intelligence وSecurity وLiquidity. امنح كل مفتاح الصلاحيات التي يحتاجها فقط. المثال أدناه يحتاج Liquidity.

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

نفّذ استدعاء المثال

افتح علامة التبويب Quickstart. تحمل مثالاً عاملاً يمكنك نسخه وتشغيله دون كتابة أي شيء بنفسك.

علامة تبويب البداية السريعة في صفحة Developers، حيث تنسخ مثال استدعاء جاهزاً للعمل.تكبير الصورة

توضّح بطاقة Test keys vs live keys الفرق. المفتاح التجريبي ينفّذ استدعاءات آمنة بحدود ضيقة، وهو مناسب لتوصيل الأمور معاً. المفتاح الحي ينفّذ استدعاءات حقيقية تُحصَّل من رصيد أرصدة Cognivo لديك. ثم تعطيك بطاقة Test a live endpoint خمس خطوات مرقّمة والأمر نفسه، مع أيقونة نسخ.

الأمر هو فحص سيولة حقيقي على عقد Base حقيقي:

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

الاستدعاء نفسه من JavaScript أو TypeScript:

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);
  console.log(json.meta.request_id);
} else {
  console.error(json.error);
}

ما الذي يعود إليك

تجيب كل نقطة نهاية بالغلاف نفسه، وهو ما تعرضه كتلة Expected response في علامة تبويب Quickstart:

{
  "ok": true,
  "data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 0,
    "generated_at": "..."
  }
}

يحمل data النتيجة. ويستحق meta.request_id أن تسجّله، لأن الدعم يستطيع تتبّع استدعاء واحد به. ويخبرك meta.credits_charged بالضبط بما كلّفه ذلك الاستدعاء.

قد يعود حقل فارغاً أو مجهولاً أو غير متاح. يعني ذلك أن Cognivo لم يستطع التحقق منه من البيانات التي يصل إليها، لا أنه لا يوجد شيء هناك. اقرأه على أنه "غير مؤكَّد"، ولا تعامل النتيجة الصامتة على أنها براءة تامة. يبلّغ Cognivo بما فحصه وبما وجده، ولا شيء في أي استجابة يثبت أن توكناً احتيالي أو يثبت أنه آمن.

يجيب الاستدعاء الفاشل بقيمة ok مضبوطة على false، مع كود error ومعرّف request_id. لا تُحصَّل رسوم على الاستدعاءات الفاشلة.

التكلفة والشبكات والحدود

• بعض نقاط النهاية مجانية مع أي مفتاح نشط. وأخرى تُحصَّل لكل استدعاء ناجح من رصيد أرصدة Cognivo لديك. تسرد علامة التبويب Endpoints كل نقطة نهاية مع سعرها بأرصدة Cognivo، أو Free حيث تكون مجانية، فتحقق منها هناك قبل أن تبني اعتماداً على نقطة نهاية.
• تُحصَّل عليك رسوم الاستدعاء الناجح فقط، ويؤكد meta.credits_charged المبلغ. الأخطاء والمهل المنتهية والاستدعاءات المحجوبة لا تكلّف شيئاً.
• يحصل كل حساب على 5 أرصدة مجانية يومياً. تُعاد ضبطها عند منتصف الليل بتوقيت UTC وتُستخدم قبل أي أرصدة مدفوعة.
• تغطي الواجهة البرمجية Ethereum وBase وBNB Chain اليوم. بعض نقاط النهاية تدعم شبكات أقل من غيرها.
• المفاتيح التجريبية محدودة بصرامة وليست طبقة إنتاج مجانية. يعرض كل صف مفتاح في علامة التبويب Keys الحدود التي يطبّقها Cognivo على ذلك المفتاح الآن، وقد تكون أدنى من الحد الافتراضي للطبقة.
• المفتاح المعلَّق، أو المفتاح داخل مشروع معلَّق، لا يستطيع تشغيل أي شيء، وتعرض البوابة السبب.

حافظ على أمان مفتاحك

استدعِ الواجهة البرمجية من خادم، لا من شيفرة متصفح أو تطبيق جوال أبداً. احتفظ بالمفتاح في متغيّر بيئة أو مدير أسرار، ولا تضعه أبداً في مستودع عام أو رسالة محادثة أو لقطة شاشة. إذا احتُمل تسرّب مفتاح، فقم بتدويره أو إلغائه في علامة التبويب Keys.

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

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