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

أول استدعاء لك خلال 30 ثانية: أنشئ مشروعاً، وأنشئ مفتاحاً حياً، وتحقق من رصيدك، والصق أمراً واحداً. المفاتيح الحية خدمة ذاتية وتعمل فوراً؛ يُحصَّل عليك 2 من الأرصدة عندما ينجح الاستدعاء في المثال، ولا يُحصَّل عليك شيء أبداً مقابل استدعاء فاشل.

1. أنشئ مشروعاً ومفتاحاً حياً

1. افتح بوابة المطورين وسجّل الدخول بحساب Cognivo الخاص بك.
2. أنشئ مشروعاً (مثلاً "بوت التداول الخاص بي").
3. أنشئ مفتاح API حياً. اختر الصلاحيات (النطاقات) التي يحتاجها - لهذه البداية السريعة، امنح ذكاء التوكنات والمحافظ (intel:read) وقراءات السيولة (liquidity:read).
4. انسخ المفتاح الآن. يُعرض مرة واحدة بالضبط؛ وبعد ذلك تظهر فقط نسخة مقنّعة (cogv_live_****abcd). إذا فقدته، فقم بتدوير (rotate) المفتاح.

تأتي المفاتيح في بيئتين:

• cogv_live_... - المفتاح القياسي. خدمة ذاتية: يعمل فوراً، ويُفوتر بالدفع حسب الاستخدام بأرصدة Cognivo لكل استدعاء ناجح من رصيد أرصدة حسابك. لا حاجة إلى وصول تجريبي (trial) ولا موافقة.
• cogv_test_... - مفاتيح Sandbox، موسومة بوضوح بأنها Sandbox، للعروض التوضيحية المحدودة واختبار التكامل فقط. لا يمكنها تشغيل الذكاء الحي وهي محدودة بصرامة (25 طلباً/ساعة و100/يوم و1/ثانية).

2. تحقق من مفتاحك ورصيدك

curl 'https://api.cognivolabs.io/v1/api/me' \
  -H 'X-API-Key: YOUR_API_KEY'

ستحصل على مفتاحك المقنّع ومشروعك وبيئتك ونطاقاتك وحد المعدل بالساعة، إضافة إلى access_mode ورصيد credits_balance الخاص بحسابك (حتى ترى ما إذا كنت تستطيع تحمّل تكلفة الاستدعاء التالي) وإرشادات top_up. هذا الاستدعاء مجاني دائماً.

3. نفّذ أول استدعاء حي (curl)

تستخدم نقاط نهاية الذكاء POST مع جسم JSON. هذا الأمر بالضبط يشغّل فحص سيولة حقيقياً على توكن Base حقيقي (RWA Inc، وهو عقد عام نستخدمه في العروض التوضيحية). ويُنفَّذ فوراً على مفتاحك الحي الجديد:

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"}'

يُفترض أن ترى "ok": true مع هوية التوكن (الاسم/الرمز) ولقطة سوقية وسياق LP/الأقفال في data. عند النجاح يُحصَّل عليك سعر نقطة النهاية - 2 من الأرصدة لفحص السيولة - وتؤكد ذلك meta.credits_charged. أما إذا حصلت بدلاً من ذلك على خطأ 402 بالكود payment_required، فهذا يعني أن رصيد أرصدة Cognivo لديك لا يغطي الاستدعاء: لم يُحصَّل شيء، فاشحن رصيدك في صفحة الفوترة لحساب Cognivo الخاص بك ونفّذ الأمر نفسه مجدداً. الاستدعاءات الفاشلة لا يُحصَّل عليها شيء أبداً. استبدل address بأي عقد توكن على eth أو base أو bsc عندما تكون جاهزاً.

حافظ على سرية مفتاحك

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

4. نفس الاستدعاء بلغة 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, // never hardcode keys
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);        // the intelligence result
  console.log(json.meta.request_id); // keep for support/debugging
} else {
  console.error(json.error);     // e.g. "payment_required": top up, then retry
}

5. شكل الاستجابة

تجيب كل نقطة نهاية بنفس الغلاف (المعرّفات والطوابع الزمنية أدناه قيم توضيحية):

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 2,
    "generated_at": "2026-07-08T00:00:00.000Z"
  }
}

عند الفشل (لا يُحصَّل شيء أبداً):

{ "ok": false, "error": "payment_required", "request_id": "capi_..." }

الفوترة وشحن الرصيد

• الدفع حسب الاستخدام، لكل استدعاء ناجح. كل استدعاء ناجح يخصم سعر نقطة النهاية المنشور بالأرصدة من رصيد أرصدة Cognivo الخاص بمالك المشروع (نفس الأرصدة التي تستخدمها في Chat والـ dApp). لا اشتراك ولا حد أدنى.
• أين تشحن الرصيد. في صفحة الفوترة لحساب Cognivo الخاص بك في الـ dApp. تعرض GET /v1/api/me رصيد credits_balance الحالي وإرشادات top_up.
• الاستدعاءات الفاشلة لا يُحصَّل عليها شيء أبداً. الأخطاء والمهلات والاستدعاءات المرفوضة لا تكلّف شيئاً. وخطأ 402 payment_required نفسه مجاني: اشحن رصيدك وأعد المحاولة.
• النتائج الفارغة النزيهة مجانية. تعيد wallet/pnl الخطأ 422 عندما لا تملك المحفظة صفقات مسعّرة في ذلك التوكن، والقائمة الفارغة من wallet/approvals إجابة صحيحة؛ ولا يُحصَّل على أي منهما شيء.
• إعادة المحاولة آمنة. الاستدعاء الناجح يُحصَّل مرة واحدة بالضبط؛ والإرسالات المكررة لنفس العملية لا يمكن أن تُحصَّل عليك مرتين. عند 5xx أو 429، أعد المحاولة مع تراجع (backoff)؛ وعند 402، اشحن الرصيد أولاً.
• التعليق. المفتاح المعلّق (أو المشروع المعطّل) لا يمكنه تنفيذ أي شيء ولا يُحصَّل عليه شيء أبداً؛ وتعرض البوابة السبب.

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

• استدعِ الـ API من خادم، وليس أبداً من كود متصفح أو عميل جوال.
• خزّن المفتاح في متغير بيئة أو مدير أسرار.
• إذا كان من المحتمل أن مفتاحاً قد تسرّب، فقم بإبطاله أو تدويره في البوابة - يتوقف المفتاح القديم عن العمل خلال دقيقة.