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

تقع جميع نقاط النهاية تحت https://api.cognivolabs.io/v1/api. نقاط نهاية الذكاء تستخدم POST مع جسم JSON (هذا يمنع معاينات الروابط والزواحف وأدوات الجلب المسبق من تشغيل أي تنفيذ على الإطلاق). توجد GET فقط لـ health وme وdiscover.

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

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

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

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

data - نتيجة الذكاء نفسها؛ يختلف شكلها بحسب نقطة النهاية
meta.request_id - معرّف فريد لهذا الاستدعاء؛ احتفظ به، إذ يمكن للدعم تتبّع الاستدعاء منه
meta.credits_charged - الأرصدة التي كلّفها هذا الاستدعاء: سعر نقطة النهاية بالأرصدة عند استدعاء مدفوع ناجح؛ و0 لنقاط النهاية المجانية واستدعاءات المخصص التجريبي (trial) وأي نتيجة فاشلة أو فارغة نزيهة
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 أو base أو bsc (غير حساسة لحالة الأحرف)
address / wallet / token - عنوان EVM بصيغة 0x… (40 حرفاً سداسي عشرياً)

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

التسعير

المفاتيح الحية خدمة ذاتية وبنظام الدفع حسب الاستخدام: المفتاح الحي الجديد يشغّل نقاط النهاية هذه فوراً، وكل استدعاء ناجح يُحصَّل بأرصدة Cognivo من رصيد حسابك؛ والاستدعاءات الفاشلة لا يُحصَّل عليها شيء أبداً، والاستدعاء الناجح يُحصَّل مرة واحدة بالضبط (الإرسالات المكررة لنفس العملية لا يمكن أن تُحصَّل مرتين). إذا لم يستطع رصيدك تغطية استدعاء، فستحصل على 402 payment_required (لا يُحصَّل شيء): اشحن رصيدك في صفحة الفوترة لحساب Cognivo الخاص بك وأعد المحاولة. مفاتيح 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
`GET health` و`GET me`	مجانية
`GET discover`	مجانية، مع حد معدل مشدود

الخدمة

GET /v1/api/health

فحص حيوية. لا يتطلب مفتاح 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" }

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

GET /v1/api/me

تستعرض المفتاح المُستدعي. النطاق: أي مفتاح صالح. مجانية. للمفاتيح الحية ذات الخدمة الذاتية تعرض أيضاً رصيد credits_balance الخاص بحساب المالك (يكون null إذا كان غير متاح مؤقتاً) وإرشادات 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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

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

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

POST /v1/api/intel/why-down - النطاق `intel:read`

لماذا ينخفض هذا التوكن: قراءة موثّقة للنشاط الأخير على السلسلة بحثاً عن المحرك المهيمن (عمليات بيع، سحب LP، تحركات المالك).

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

جسم الطلب:

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

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 - النطاق `intel:read`

فحص محافظ الفريق والتحكم لتوكن ما: محافظ الناشر والمالك والمتحكمين إضافة إلى سلوكها الأخير.

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

جسم الطلب:

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

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

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

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

القيود: تحدد المحافظ من العلاقات على السلسلة (النشر، الملكية، التحكم)؛ ولا يمكنها رؤية بنية الفريق خارج السلسلة.

POST /v1/api/intel/liquidity - النطاق `liquidity:read`

حالة المجمع/LP لتوكن ما: سياق المجمع، حيازة LP، وسياق القفل/الحرق.

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

جسم الطلب (القيم المنطقية الاختيارية metadata وlocks وfull تضيف بيانات وصفية موثّقة للمجمع، وإثبات القفل الزمني، وأشمل قراءة متاحة):

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

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

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

الاستجابة: الغلاف القياسي؛ تحمل data هوية التوكن ولقطة سوقية وحيازة LP إضافة إلى سياق القفل/الحرق.

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

POST /v1/api/intel/risk - النطاق `intel:read`

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

جسم الطلب:

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

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

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

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

القيود: النتيجة النظيفة لا تعني أبداً "آمن"؛ بل تعني أنه لم يُعثر على أعلام حمراء معروفة وقت القراءة.

ذكاء المحافظ

POST /v1/api/wallet/pnl - النطاق `intel:read`

الأرباح والخسائر المحققة (PnL) لمحفظة على توكن واحد، من نشاط محفظة موثّق. كل من wallet وtoken مطلوبان.

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

جسم الطلب:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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

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

الاستجابة: الغلاف القياسي؛ تحمل data حساب PnL المحقق لزوج المحفظة/التوكن ذاك.

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

POST /v1/api/wallet/approvals - النطاق `security:read`

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

جسم الطلب (تتيح limit وoffset اختيارياً التنقل عبر مجموعات موافقات كبيرة):

{ "chain": "eth", "address": "0xWALLET" }

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

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

الاستجابة: الغلاف القياسي؛ تحمل data قائمة الموافقات مع سياق الجهة المنفقة والتوكن والمخصص المسموح به.

القيود: النتيجة الفارغة (لم يُعثر على موافقات) إجابة صحيحة وناجحة ولا يُحصَّل عليها شيء.

POST /v1/api/wallet/exact-movements - النطاق `intel:read`

التحركات الأخيرة الدقيقة لمحفظة (قراءة بنمط المالك/الناشر). token اختياري ويحصر القراءة في توكن واحد.

جسم الطلب:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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

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

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

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

الاستكشاف

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'

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

الاستجابة:

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

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

مخطط له (غير متاح بعد)

هذه موثّقة من أجل شفافية خارطة الطريق ولا تعيد شيئاً اليوم:

تتبع المحفظة العميق عبر الـ API (wallet/trace) - تدفق المهام غير المتزامن يقتصر حالياً على الدردشة/dApp
جلب التقارير بالمعرّف (reports/:id)
Webhooks
نقاط نهاية Solana

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

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

التسعير​

الخدمة​

GET /v1/api/health​

GET /v1/api/me​

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

POST /v1/api/intel/why-down - النطاق intel:read​

POST /v1/api/intel/team-wallets - النطاق intel:read​

POST /v1/api/intel/liquidity - النطاق liquidity:read​

POST /v1/api/intel/risk - النطاق intel:read​

ذكاء المحافظ​

POST /v1/api/wallet/pnl - النطاق intel:read​

POST /v1/api/wallet/approvals - النطاق security:read​

POST /v1/api/wallet/exact-movements - النطاق intel:read​

الاستكشاف​

GET /v1/api/discover​

مخطط له (غير متاح بعد)​

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

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

التسعير

الخدمة

GET /v1/api/health

GET /v1/api/me

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

POST /v1/api/intel/why-down - النطاق `intel:read`

POST /v1/api/intel/team-wallets - النطاق `intel:read`

POST /v1/api/intel/liquidity - النطاق `liquidity:read`

POST /v1/api/intel/risk - النطاق `intel:read`

ذكاء المحافظ

POST /v1/api/wallet/pnl - النطاق `intel:read`

POST /v1/api/wallet/approvals - النطاق `security:read`

POST /v1/api/wallet/exact-movements - النطاق `intel:read`

الاستكشاف

GET /v1/api/discover

مخطط له (غير متاح بعد)