مرجع نقاط النهاية

ما هذه الصفحة

تتيح واجهة Cognivo البرمجية للمطورين أن تطرح شيفرتك الخاصة على Cognivo الأسئلة نفسها التي يجيب عنها التطبيق. كل نقطة نهاية تقع تحت https://api.cognivolabs.io/v1/api.

استخدمها عندما تريد أن يعمل فحص Cognivo في مكان غير التطبيق: داخل بوت خاص بك، أو لوحة تحكم، أو مهمة جدول بيانات، أو سكربت ليلي يراقب قائمة توكنات.

نقاط نهاية الذكاء هي POST مع جسم JSON. وهذا مقصود: لا يمكن أبداً لمعاينة رابط أو زاحف أو جلب مسبق من المتصفح أن يشغّل تنفيذاً بمجرد تحميل عنوان URL. ولا توجد GET إلا لـ health وme وdiscover.

أين تجد هذا في التطبيق

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

علامة تبويب نقاط النهاية في صفحة المطورين، حيث تُدرَج كل نقطة نهاية في Cognivo مع الصلاحية التي تحتاجها وتكلفتها.تكبير الصورة

علامة التبويب مرجع لا مشغّل. تسرد كل نقطة نهاية حية مع مثال قابل للنسخ، والصلاحية التي يحتاجها المفتاح، والسعر بالأرصدة. وتجمّع بطاقة Permissions explained تلك الصلاحيات في ثلاث: Intelligence (لماذا هبط، ومحافظ الفريق، والمخاطر، وأرباح وخسائر المحفظة، والحركات الدقيقة)، وSecurity (موافقات التوكنات)، وLiquidity (السيولة والأقفال والحرق). امنح كل مفتاح الصلاحيات التي يحتاجها فقط.

تفضّل نسخة قابلة للقراءة آلياً؟ تغطي مواصفة OpenAPI الكاملة كل ما في هذه الصفحة.

غلاف الاستجابة

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

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

• data هو النتيجة نفسها. ويختلف شكله بحسب نقطة النهاية.
• meta.request_id معرّف فريد لهذا الاستدعاء. احتفظ به، فالدعم يستطيع تتبّع استدعاء منه.
• meta.credits_charged هو ما كلّفه الاستدعاء: سعر نقطة النهاية على استدعاء مدفوع ناجح، و0 لنقاط النهاية المجانية ولأي نتيجة فاشلة أو فارغة بصدق.
• meta.generated_at هو وقت إنتاج النتيجة.
• يظهر meta.chain في الاستدعاءات الخاصة بشبكة معينة، ويظهر meta.sources عندما تستشهد النتيجة بمصادر.

الفشل:

{ "ok": false, "error": "invalid_chain", "message": "chain must be one of: eth, base, bsc", "request_id": "capi_..." }

error كود ثابت قابل للقراءة آلياً. وmessage تلميح بشري اختياري. القائمة الكاملة في حدود المعدل والأخطاء.

حقول الجسم الشائعة

• chain هو واحد من eth (Ethereum) أو base (Base) أو bsc (BNB Chain)، ولا يميّز بين الأحرف الكبيرة والصغيرة.
• address وwallet وtoken هي عناوين EVM تبدأ بـ 0x وتتكون من 40 حرفاً ست عشرياً.

يستخدم كل مثال القيمة النائبة YOUR_API_KEY. في الشيفرة الحقيقية، حمّل المفتاح من متغيّر بيئة أو مدير أسرار. لا تضعه في الشيفرة أبداً.

ما تكلّفه كل نقطة نهاية

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

يحصل كل حساب على 5 أرصدة مجانية يومياً، وتُعاد ضبطها عند منتصف الليل بتوقيت UTC. إذا كان رصيدك لا يغطي استدعاءً فستحصل على 402 payment_required ولا تُحصَّل رسوم. اشحن رصيدك في صفحة فوترة حسابك وأعد المحاولة. لا تستطيع مفاتيح Sandbox (cogv_test_) تشغيل الذكاء الحي. راجع الفوترة والأرصدة.

نقطة النهاية	الأرصدة لكل استدعاء ناجح
POST intel/liquidity	2
POST intel/risk	2
POST wallet/approvals	2
POST intel/why-down	3
POST intel/team-wallets	5
POST wallet/exact-movements	5
POST wallet/pnl	10
POST contract/analysis	مجانية
GET health، GET me	مجانية
GET discover	مجانية، مع حد معدل ضيق

الخدمة

GET /v1/api/health

يتحقق من أن واجهة Cognivo البرمجية تعمل. لا يحتاج إلى مفتاح API.

curl 'https://api.cognivolabs.io/v1/api/health'

const res = await fetch("https://api.cognivolabs.io/v1/api/health");
const json = await res.json();

الاستجابة، وهي ليست الغلاف القياسي، بحكم التصميم:

{ "ok": true, "service": "cognivo-public-api", "version": "v1", "generated_at": "2026-07-09T00:00:00.000Z" }

إذا كانت الواجهة البرمجية العامة مطفأة فستحصل على 404 public_api_disabled هنا أيضاً، فتصلح نقطة النهاية هذه كذلك للتحقق من التوافر.

GET /v1/api/me

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

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

const res = await fetch("https://api.cognivolabs.io/v1/api/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

{
  "ok": true,
  "data": {
    "key": "cogv_live_****abcd",
    "project_id": "…",
    "environment": "live",
    "tier": "basic",
    "access_mode": "live",
    "scopes": ["intel:read", "liquidity:read"],
    "rate_limit_per_hour": 1000,
    "credits_balance": 1250,
    "top_up": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

القيود: تعرض المفتاح المقنّع فقط، ولا تعرض أبداً مادة المفتاح الكاملة. وقد يعود credits_balance بقيمة null، ما يعني أن Cognivo لم يستطع قراءة الرصيد في تلك اللحظة، لا أن الرصيد صفر.

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

ذكاء التوكنات

POST /v1/api/intel/why-down، الصلاحية Intelligence (intel:read)

قراءة بلغة بسيطة لسبب هبوط سعر توكن، مبنية على النشاط الحديث على السلسلة: بيع كثيف، أو سحب سيولة، أو تحرّك محافظ المالك أو الفريق.

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

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

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/why-down", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

الاستجابة: الغلاف القياسي. يحمل data المسبّب المهيمن والملاحظات على السلسلة التي تقف خلفه، مع ضبط meta.chain.

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

POST /v1/api/intel/team-wallets، الصلاحية Intelligence (intel:read)

تُظهر المحافظ المرتبطة بفريق توكن أو خزينته: محافظ الناشر والمالك والمتحكم، إضافة إلى ما كانت تفعله مؤخراً.

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

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

الاستجابة: الغلاف القياسي. يسرد data المحافظ المحددة وسلوكها الأخير، وغالباً مع meta.sources.

القيود: تُحدَّد المحافظ من العلاقات على السلسلة مثل النشر والملكية والتحكم. لا يستطيع Cognivo رؤية بنية الفريق خارج السلسلة، لذا فالقائمة الفارغة تعني أنه لم يكن هناك ما يمكن ربطه على السلسلة، لا أن التوكن بلا فريق.

POST /v1/api/intel/liquidity، الصلاحية Liquidity (liquidity:read)

تفحص سيولة توكن وأقفاله وعمليات الحرق بأدلة على السلسلة: سياق المجمّع، ومن يحوز توكنات LP، وسياق القفل أو الحرق.

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

القيم المنطقية الاختيارية metadata وlocks وfull تضيف بيانات وصفية للمجمّع، ودليل قفل موقوت، وأشمل قراءة متاحة.

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":"0xTOKEN_CONTRACT","locks":true}'

الاستجابة: الغلاف القياسي. يحمل data هوية التوكن، ولقطة سوقية، وحيازة LP مع سياق القفل أو الحرق.

القيود: أصل الحرق التاريخي العميق غير مكشوف في v1. يغطي سياق القفل أنماط أدوات القفل المعروفة، لذا قد تُقرأ أداة قفل مخصصة غير معتادة على أنها حيازة عادية لا قفل. اقرأ ذلك على أنه "غير مُتحقَّق منه"، لا على أنه "غير مقفل".

POST /v1/api/intel/risk، الصلاحية Intelligence (intel:read)

إشارات مخاطر Cognivo لعقد توكن، واعية بالشبكة، مع قراءة للأعلام الحمراء كاحتياط.

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

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":"bsc","address":"0xTOKEN_CONTRACT"}'

الاستجابة: الغلاف القياسي. يحمل data الإشارات والأعلام التي وُجدت للتوكن.

القيود: النتيجة النظيفة لا تعني أن التوكن آمن. تعني أنه لم تُوجد أعلام حمراء معروفة وقت القراءة.

POST /v1/api/contract/analysis، الصلاحية Contract (contract:read)

أدلة العقد والتحكم لعنوان عقد: هل هو موجود، ومن يملكه، وهل تُنُوزل عن الملكية، وهل هو وكيل ومن يديره، ومن نشره، وأي المحافظ يمكن نسبتها كمتحكمين أو فريق، وهل المصدر موثّق.

التكلفة: 0 من الأرصدة. هذه نقطة النهاية مجانية بقرار، على كل خطة. لا يُخصم شيء.

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

الاستجابة: الغلاف القياسي. يحمل data الحقول contract وownership وproxy وdeployer وcontrollers وsource_verification وlimitations وunavailable.

كل حقل يخبرك من أين جاء. ويربط meta.provenance كل حقل بواحد بالضبط مما يلي:

التسمية	ماذا تعني
verified_onchain	قُرئ من عقدة لتلك الشبكة وقت طلبك. حقيقة.
augmented	ذكاء Cognivo المعزَّز: مزوَّد من مصدر خارجي، مُدقَّق تقاطعياً لكن غير مُثبَت من Cognivo.
interpretation	قراءة Cognivo للحقائق. حكم لا حقيقة.
unavailable	لم يستطع Cognivo الحصول على هذا. السبب في data.unavailable.

لا شيء يُخمَّن، أو يُعطى قيمة افتراضية، أو يُعاد كصفر لملء فجوة.

يخبرك meta.chain_data_source.cognivo_grounded بما إذا كان Cognivo يشغّل البنية التحتية التي جاءت منها القراءة. يشغّل Cognivo عقدة Ethereum خاصة به، لذا فقراءات Ethereum هي true. أما قراءات Base وBNB Chain فتأتي من بنية RPC خارجية، لذا فهي false. تلك القراءات دقيقة، لكنها لا تُقدَّم من عتاد يتحكم به Cognivo، ويقول Cognivo ذلك بدلاً من أن يدعك تفترض غير ذلك.

القيود على Base، وتُعاد أيضاً في data.limitations:

• رسم المتحكمين العميق خاص بـ Ethereum فقط. على Base، تأتي نسبة المتحكمين والفريق من قراءة أضيق لدور المحفظة.
• دليل الناشر على Base يأتي من مصدر خارجي، لا من قراءة أرشيف لدى Cognivo. عامله كمؤشر قوي، لا كحقيقة مُثبَتة.
• جداول قفل السيولة غير مفكوكة الترميز على Base. استخدم POST /v1/api/intel/liquidity لحيازة LP وأدلة الحرق، ولا تقرأ قفلاً مفقوداً على أنه قفل غائب.

تبلّغ نقطة النهاية هذه عن أدلة التحكم بالعقد فقط. ولا تقول شيئاً عن السيولة، والنتيجة النظيفة لا تعني أبداً أن العقد آمن.

للقراءة فقط: لا شيء يُوقَّع، ولا تُبنى معاملة، ولا يُبَث شيء، ولا تُفوَّض أي محفظة.

ذكاء المحافظ

POST /v1/api/wallet/pnl، الصلاحية Intelligence (intel:read)

الأرباح والخسائر لمحفظة واحدة على توكن واحد، محسوبة من مبادلات مؤصَّلة على السلسلة. كل من wallet وtoken مطلوب.

السعر المعلن: 10 أرصدة لكل استدعاء ناجح. الاستدعاءات الفاشلة، ونتائج 422 التي لا بيانات لها، لا تُحصَّل عليها رسوم أبداً. تحصيل الرسوم على استدعاءات Developer API متوقف اليوم، لذا لا يخصم الاستدعاء الناجح أي رصيد ولا يتغير رصيدك.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/pnl' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET","token":"0xTOKEN_CONTRACT"}'

الاستجابة: الغلاف القياسي. يحمل data الرقم المحقق، ورقماً غير محقق للمركز الذي لا يزال محتفظاً به عندما يوجد أساس تكلفة يمكن الدفاع عنه.

القيود: عندما لا يمكن تأسيس أساس تكلفة يمكن الدفاع عنه، يعود الرقم غير المحقق بقيمة null بدلاً من رقم مختلَق. وعندما لا تكون للمحفظة صفقات مسعّرة في ذلك التوكن إطلاقاً، يعيد الاستدعاء 422 (مثلاً insufficient_data)، ما يعني أن Cognivo لم يستطع حساب رقم عادل، لا أن الربح كان صفراً. ولا تُحصَّل رسوم على 422 أبداً. وتُعرض المبادلات التي لم يستطع Cognivo تسعيرها على أنها غير مسعّرة بدلاً من إسقاطها.

POST /v1/api/wallet/approvals، الصلاحية Security (security:read)

تسرد موافقات إنفاق التوكنات التي منحتها محفظة، وتضع علامة على التفويضات غير المحدودة.

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

الحقلان الاختياريان limit وoffset يتصفحان مجموعات الموافقات الكبيرة.

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

الاستجابة: الغلاف القياسي. يحمل data قائمة الموافقات مع سياق المنفِق والتوكن والتفويض.

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

POST /v1/api/wallet/exact-movements، الصلاحية Intelligence (intel:read)

تسرد الحركات الدقيقة لتوكنات محفظة: عمليات الشراء والبيع والتحويلات. الحقل token اختياري ويحصر القراءة بتوكن واحد.

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

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/exact-movements' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET"}'

الاستجابة: الغلاف القياسي. يحمل data قائمة الحركات مع الأعداد.

القيود: يعيد الاستدعاء أحدث الحركات، حتى 25 لكل استدعاء. والمحفظة التي لا حركات مطابقة لها تعيد 422 بدلاً من تاريخ مختلَق.

Discover

GET /v1/api/discover

تدفق Discover العام: بطاقات ذكاء حديثة على السلسلة ومجهولة الهوية، كل واحدة بهوية توكن وخطّاف ونقاط. تعمل مع أي مفتاح نشط. مجانية، ضمن حد يومي ضيق.

معاملات الاستعلام: limit (من 1 إلى 50، الافتراضي 20) وchain اختياري (eth أو base أو bsc).

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

القيود: قيم limit خارج النطاق من 1 إلى 50 تُقصَر داخل النطاق. ولا يحتوي التدفق إلا على الذكاء الذي اختار المستخدمون نشره، فهو عيّنة لا تغطية كاملة.

غير متاح بعد

هذه مدرجة من باب الشفافية ولا تعيد شيئاً اليوم:

• التتبع العميق للمحافظ عبر الواجهة البرمجية (wallet/trace). تدفق المهام غير المتزامن متاح في المحادثة والتطبيق فقط في الوقت الحالي.
• جلب التقرير بالمعرّف (reports/:id).
• Webhooks.
• نقاط نهاية Solana.

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

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