Endpoint referansı

Tüm endpoint'ler https://api.cognivolabs.io/v1/api altında yaşar. İstihbarat endpoint'leri JSON gövdeli POST kullanır (bu, bağlantı önizlemelerinin, tarayıcı botlarının ve önden getiricilerin bir yürütmeyi tetiklemesini engeller). GET yalnızca health, me ve discover için vardır.

Makine tarafından okunabilir bir sürüm mü tercih edersiniz? Tam OpenAPI spesifikasyonu bu sayfadaki her şeyi kapsar.

Yanıt zarfı

Her endpoint aynı zarfla yanıt verir. Başarı:

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

data - istihbarat sonucunun kendisi; yapısı endpoint'e göre değişir
meta.request_id - bu çağrının benzersiz kimliği; saklayın, destek ekibi bir çağrıyı bununla izleyebilir
meta.credits_charged - bu çağrının maliyeti olan krediler: ücretsiz endpoint'ler, sandbox demo veya deneme hakları ile herhangi bir başarısız veya boş sonuç için 0; ücretli kullanımda endpoint'in kredi fiyatı
meta.generated_at - sonucun üretildiği zaman
meta.chain zincire özgü çağrılarda görünür; sonuç kaynaklara atıf yaptığında meta.sources (kaynak etiketleri dizisi) görünür

Hata:

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

error kararlı, makine tarafından okunabilir bir koddur (bkz. Hız limitleri ve hatalar); message isteğe bağlı, insanlara yönelik bir ipucudur.

Ortak gövde alanları

chain - eth, base, bsc değerlerinden biri (büyük/küçük harfe duyarsız)
address / wallet / token - 0x… biçiminde bir EVM adresi (40 hex karakter)

Aşağıdaki tüm örneklerde YOUR_API_KEY yer tutucusu kullanılır; gerçek kodda anahtarı bir ortam değişkeninden veya secret yöneticisinden yükleyin, asla koda gömmeyin.

Erişim ve kredi maliyetleri

Yürütülebilir istihbarat endpoint'leri deneme (trial), iş ortağı, ücretli veya kurumsal erişim gerektirir. Erişim olmadan ücretsiz çalışmazlar: access_required gibi net bir 403 hatası alırsınız (bkz. Hız limitleri ve hatalar). Ücretli kullanım, başarılı çağrı başına Cognivo kredisiyle ücretlendirilir; başarısız çağrılar ücretlendirilmez. Endpoint başına maliyetler (ücretli kullanım için geçerlidir; şeffaflık için gösterilmiştir):

Endpoint	Başarılı çağrı başına kredi
`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`	ücretsiz
`GET discover`	ücretsiz, sıkı bir hız sınırıyla

Servis

GET /v1/api/health

Canlılık kontrolü. API anahtarı gerekmez.

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

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

Yanıt (bilinçli olarak standart zarf değil):

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

Sınırlamalar: herkese açık API kapatılırsa burada da 404 public_api_disabled alırsınız; bu yüzden bu endpoint aynı zamanda bir erişilebilirlik kontrolü olarak da işe yarar.

GET /v1/api/me

Çağıran anahtarı inceler. Kapsam: herhangi bir geçerli anahtar. Ücretsiz. Self-servis live anahtarlar için, sahip hesabın credits_balance değerini (geçici olarak kullanılamıyorsa null) ve top_up rehberini, ayrıca anahtarın access_mode değerini de gösterir.

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();

Yanıt:

{
  "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": "…" }
}

Sınırlamalar: yalnızca maskelenmiş anahtarı gösterir, tam anahtar içeriğini asla göstermez. credits_balance, sahip hesabın Cognivo kredi bakiyesidir ve geçici olarak kullanılamıyorsa null olabilir.

Token istihbaratı

POST /v1/api/intel/why-down - kapsam `intel:read`

Bu token neden düşüyor: baskın etkeni (satışlar, LP çekilmeleri, sahip hareketleri) arayan, yakın zamanlı zincir üstü aktivitenin doğrulanmış bir okuması.

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 3 kredi.

İstek gövdesi:

{ "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();

Yanıt: standart zarf; data düşüş analizini (baskın etken, destekleyici zincir üstü gözlemler) içerir ve meta.chain doludur.

Sınırlamalar: faydalı bir şey söyleyebilmek için yakın zamanlı aktivite gerekir; çok az işlem geçmişi olan bir token için okuma zayıf kalabilir. Bunlar sinyaldir, finansal tavsiye değildir.

POST /v1/api/intel/team-wallets - kapsam `intel:read`

Bir token için ekip ve kontrol cüzdanı taraması: dağıtıcı (deployer), sahip ve kontrol cüzdanları ile yakın zamandaki davranışları.

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 5 kredi.

İstek gövdesi:

{ "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();

Yanıt: standart zarf; data tespit edilen ekip/kontrol cüzdanlarını ve yakın zamandaki davranışlarını listeler, çoğunlukla meta.sources ile birlikte.

Sınırlamalar: cüzdanları zincir üstü ilişkilerden (dağıtım, sahiplik, kontrol) tespit eder; zincir dışı ekip yapısını göremez.

POST /v1/api/intel/liquidity - kapsam `liquidity:read`

Bir token için havuz/LP durumu: havuz bağlamı, LP saklama durumu ve kilit/yakma bağlamı.

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 2 kredi.

İstek gövdesi (isteğe bağlı boolean'lar metadata, locks ve full sırasıyla doğrulanmış havuz üst verilerini, süreli kilit kanıtını ve mevcut en kapsamlı okumayı ekler):

{ "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();

Yanıt: standart zarf; data token kimliğini, bir piyasa anlık görüntüsünü ve LP saklama durumu ile kilit/yakma bağlamını içerir.

Sınırlamalar: derin tarihsel yakma kaynağı v1'de sunulmaz; kilit bağlamı tanınan kilitleyici desenlerini kapsar ve tanınmayan özel bir kilitleyici, kilitsiz saklama gibi görünebilir.

POST /v1/api/intel/risk - kapsam `intel:read`

Bir token için zincire duyarlı Cognivo risk sinyalleri (yedek olarak kırmızı bayrak okuması).

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 2 kredi.

İstek gövdesi:

{ "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();

Yanıt: standart zarf; data token için bulunan risk sinyallerini ve bayrakları içerir.

Sınırlamalar: temiz bir sonuç asla "güvenli" anlamına gelmez; okuma anında bilinen kırmızı bayrak bulunmadığı anlamına gelir.

Cüzdan istihbaratı

POST /v1/api/wallet/pnl - kapsam `intel:read`

Bir cüzdanın tek bir token'daki gerçekleşmiş PnL'i, doğrulanmış cüzdan aktivitesinden. Hem wallet hem token zorunludur.

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 10 kredi.

İstek gövdesi:

{ "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();

Yanıt: standart zarf; data o cüzdan/token çifti için gerçekleşmiş PnL hesaplamasını içerir.

Sınırlamalar: cüzdanın o token'da fiyatlandırılmış işlemi yoksa ve dolayısıyla adil bir sayı hesaplanamıyorsa 422 döndürür (örneğin insufficient_data). Cognivo asla bir rakam uydurmaz ve 422 asla ücretlendirilmez. Yalnızca gerçekleşmiş PnL; gerçekleşmemiş (hâlâ tutulan) pozisyonlar burada değerlenmez.

POST /v1/api/wallet/approvals - kapsam `security:read`

Bir cüzdan üzerinde tutulan token onayları; sınırsız izinler (allowance) işaretlenir. Salt okunur: Cognivo asla fon taşımaz ve sizin adınıza iptal edemez.

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 2 kredi.

İstek gövdesi (limit ve offset isteğe bağlı olarak büyük onay kümelerinde sayfalama yapar):

{ "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();

Yanıt: standart zarf; data harcayıcı, token ve izin bağlamıyla birlikte onay listesini içerir.

Sınırlamalar: boş bir sonuç (onay bulunamadı) geçerli ve başarılı bir cevaptır ve ücretlendirilmez.

POST /v1/api/wallet/exact-movements - kapsam `intel:read`

Bir cüzdanın tam ve yakın zamanlı hareketleri (sahip/dağıtıcı tarzı okuma). token isteğe bağlıdır ve okumayı tek bir token'a daraltır.

Erişim ve maliyet: canlı erişim gerektirir (deneme, iş ortağı, ücretli veya kurumsal); ücretli kullanımda başarılı çağrı başına 5 kredi.

İstek gövdesi:

{ "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();

Yanıt: standart zarf; data sayaçlarla birlikte hareket listesini içerir.

Sınırlamalar: en yakın zamanlı hareketleri döndürür (çağrı başına en fazla 25); eşleşen hareketi olmayan bir cüzdan, uydurulmuş bir geçmiş yerine 422 döndürür.

Discover

GET /v1/api/discover

Herkese açık Discover akışı: yakın zamanlı, yüksek kaliteli herkese açık istihbarat kartları (token kimliği, kanca, maddeler). Kapsam: herhangi bir geçerli anahtar. Ücretsiz, sıkı bir hız sınırıyla.

Sorgu parametreleri: limit (1-50, varsayılan 20) ve isteğe bağlı 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();

Yanıt:

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

Sınırlamalar: 1-50 aralığı dışındaki limit değerleri aralığa sıkıştırılır; akış yalnızca kullanıcıların yayımlamayı seçtiği istihbaratı içerir, dolayısıyla bir örneklemdir, tam kapsam değildir.

Planlandı (henüz canlı değil)

Bunlar yol haritası şeffaflığı için belgelenmiştir ve bugün hiçbir şey döndürmez:

API üzerinden derin cüzdan izleme (wallet/trace) - eşzamansız iş akışı şimdilik yalnızca sohbet/dApp tarafındadır
Kimlikle rapor getirme (reports/:id)
Webhook'lar
Solana endpoint'leri

Yanıt zarfı​

Ortak gövde alanları​

Erişim ve kredi maliyetleri​

Servis​

GET /v1/api/health​

GET /v1/api/me​

Token istihbaratı​

POST /v1/api/intel/why-down - kapsam intel:read​

POST /v1/api/intel/team-wallets - kapsam intel:read​

POST /v1/api/intel/liquidity - kapsam liquidity:read​

POST /v1/api/intel/risk - kapsam intel:read​

Cüzdan istihbaratı​

POST /v1/api/wallet/pnl - kapsam intel:read​

POST /v1/api/wallet/approvals - kapsam security:read​

POST /v1/api/wallet/exact-movements - kapsam intel:read​

Discover​

GET /v1/api/discover​

Planlandı (henüz canlı değil)​

Yanıt zarfı

Ortak gövde alanları

Erişim ve kredi maliyetleri

Servis

GET /v1/api/health

GET /v1/api/me

Token istihbaratı

POST /v1/api/intel/why-down - kapsam `intel:read`

POST /v1/api/intel/team-wallets - kapsam `intel:read`

POST /v1/api/intel/liquidity - kapsam `liquidity:read`

POST /v1/api/intel/risk - kapsam `intel:read`

Cüzdan istihbaratı

POST /v1/api/wallet/pnl - kapsam `intel:read`

POST /v1/api/wallet/approvals - kapsam `security:read`

POST /v1/api/wallet/exact-movements - kapsam `intel:read`

Discover

GET /v1/api/discover

Planlandı (henüz canlı değil)