Endpoint Referansı

Bu sayfa nedir

Cognivo Developer API, kendi kodunuzun Cognivo'ya uygulamanın yanıtladığı soruların aynısını sormasını sağlar. Her endpoint https://api.cognivolabs.io/v1/api altında yer alır.

Bir Cognivo kontrolünün uygulama dışında bir yerde çalışmasını istediğinizde kullanın: kendi botunuzun içinde, bir panoda, bir hesap tablosu görevinde ya da bir token listesini izleyen gecelik bir betikte.

Intelligence endpoint'leri JSON gövdeli POST isteğidir. Bu bilinçli bir tercihtir: bir bağlantı önizlemesi, bir tarayıcı botu ya da bir tarayıcı ön yüklemesi bir URL'yi açarak asla bir yürütmeyi tetikleyemez. GET yalnızca health, me ve discover için vardır.

Bunu uygulamada nerede bulursunuz

Cognivo uygulamasında oturum açın, sol kenar çubuğunda Account altındaki Developers sayfasını açın, ardından Endpoints sekmesini seçin.

Developers sayfasındaki Endpoint'ler sekmesi; burada her Cognivo endpoint'i, ihtiyaç duyduğu izin ve maliyetiyle birlikte listelenir.Görseli büyüt

Bu sekme bir referanstır, bir çalıştırıcı değil. Canlı olan her endpoint'i kopyalanabilir bir örnekle, anahtarın ihtiyaç duyduğu izinle ve kredi cinsinden fiyatıyla listeler. Permissions explained kartı bu izinleri üçe ayırır: Intelligence (neden düşüyor, ekip cüzdanları, risk, cüzdan PnL'i, tam hareketler), Security (token onayları) ve Liquidity (likidite, kilitler ve yakmalar). Her anahtara yalnızca ihtiyaç duyduğu izinleri verin.

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 cevap verir. Aşağıdaki örneklerdeki kimlikler ve zaman damgaları yer tutucu değerlerdir. Başarı:

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

• data sonucun kendisidir. Şekli endpoint'e göre değişir.
• meta.request_id bu çağrıya özgü benzersiz bir kimliktir. Saklayın; destek ekibi bir çağrıyı bu değerden izleyebilir.
• meta.credits_charged çağrının maliyetidir: başarılı ve ücretli bir çağrıda endpoint'in fiyatı, ücretsiz endpoint'lerde ve başarısız ya da dürüstçe boş dönen her sonuçta 0.
• meta.generated_at sonucun ne zaman üretildiğidir.
• meta.chain zincire özgü çağrılarda görünür ve meta.sources sonuç kaynak gösterdiğinde görünür.

Başarısızlık:

{ "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. message isteğe bağlı, insana yönelik bir ipucudur. Tam liste Hız limitleri ve hatalar sayfasındadır.

Ortak gövde alanları

• chain değeri eth (Ethereum), base (Base) ya da bsc (BNB Chain) olabilir ve büyük küçük harfe duyarlı değildir.
• address, wallet ve token alanları, 40 onaltılık karakterden oluşan 0x EVM adresleridir.

Her örnek YOUR_API_KEY yer tutucusunu kullanır. Gerçek kodda anahtarı bir ortam değişkeninden ya da bir gizli bilgi yöneticisinden yükleyin. Asla koda sabitlemeyin.

Her endpoint'in maliyeti

Canlı anahtarlar self servistir ve kullandıkça ödeme esasına dayanır. Yeni bir canlı anahtar bu endpoint'leri hemen çalıştırır ve her başarılı çağrı hesap bakiyenizden Cognivo kredisi olarak ücretlendirilir. Başarısız çağrılar asla ücretlendirilmez ve başarılı bir çağrı tam olarak bir kez ücretlendirilir; bu yüzden aynı işlemin yeniden gönderilmesi sizden iki kez ücret alamaz.

Her hesap günde 5 ücretsiz kredi alır ve bunlar UTC gece yarısında sıfırlanır. Bakiyeniz bir çağrıyı karşılayamıyorsa 402 payment_required alırsınız ve hiçbir ücret kesilmez. Hesabınızın faturalandırma sayfasından kredi yükleyip yeniden deneyin. Sandbox (cogv_test_) anahtarları canlı istihbarat çalıştıramaz. Bkz. Billing ve Krediler.

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
POST contract/analysis	ücretsiz
GET health, GET me	ücretsiz
GET discover	ücretsiz, dar bir hız üst sınırıyla

Servis

GET /v1/api/health

Cognivo API'sinin çalışır durumda olup olmadığını kontrol eder. 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, tasarım gereği standart zarf değildir:

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

Herkese açık API kapatılmışsa burada da 404 public_api_disabled alırsınız; böylece bu endpoint aynı zamanda bir erişilebilirlik kontrolü işlevi görür.

GET /v1/api/me

Çağrıyı yapan anahtara dair ayrıntıları gösterir: katmanı, izinleri ve hız limiti. Etkin herhangi bir anahtarla çalışır ve ücretsizdir. Canlı self servis anahtarlar için ayrıca sahip hesabın credits_balance değerini ve top_up yönergelerini, bunun yanında anahtarın access_mode bilgisini 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();

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

Sınırlamalar: yalnızca maskelenmiş anahtarı gösterir, asla tam anahtar materyalini göstermez. credits_balance değeri null dönebilir; bu, bakiyenin sıfır olduğu anlamına gelmez, Cognivo'nun o anda bakiyeyi okuyamadığı anlamına gelir.

Kalan endpoint'lerin hepsi aşağıdaki örneklerle aynı çağrı biçimini izler. Yolu ve gövde alanlarını değiştirin.

Token istihbaratı

POST /v1/api/intel/why-down, izin Intelligence (intel:read)

Bir token'ın fiyatının neden düştüğüne dair sade dilde bir okuma; yakın zamanlı zincir üstü etkinlikten oluşturulur: yoğun satış, likiditenin çekilmesi, sahip ya da ekip cüzdanlarının hareket etmesi.

Liste fiyatı: başarılı çağrı başına 3 kredi. Başarısız çağrılar asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

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, baskın etkeni ve bunun arkasındaki zincir üstü gözlemleri tutar, meta.chain ayarlanmış olarak.

Sınırlamalar: bu okumanın anlamlı bir şey söyleyebilmesi için yakın zamanlı etkinliğe ihtiyacı vardır; bu yüzden çok az işlem geçmişi olan bir token zayıf bir yanıt verir. Bunlar sinyaldir, finansal tavsiye değildir.

POST /v1/api/intel/team-wallets, izin Intelligence (intel:read)

Bir token'ın ekibine ya da hazinesine bağlı cüzdanları ortaya çıkarır: dağıtıcı (deployer), sahip ve denetleyici cüzdanlar ile bunların son zamanlarda neler yaptığı.

Liste fiyatı: başarılı çağrı başına 5 kredi. Başarısız çağrılar asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

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

Yanıt: standart zarf. data, tespit edilen cüzdanları ve son davranışlarını listeler, çoğu zaman meta.sources ile birlikte.

Sınırlamalar: cüzdanlar; dağıtım, sahiplik ve denetim gibi zincir üstü ilişkilerden tespit edilir. Cognivo zincir dışı ekip yapısını göremez; bu yüzden boş bir liste, token'ın ekibi olmadığı anlamına gelmez, zincir üzerinde bağlanabilecek bir şey bulunmadığı anlamına gelir.

POST /v1/api/intel/liquidity, izin Liquidity (liquidity:read)

Bir token'ın likiditesini, kilitlerini ve yakmalarını zincir üstü kanıtla kontrol eder: havuz bağlamı, LP token'larını kimin tuttuğu ve kilit ya da yakma bağlamı.

Liste fiyatı: başarılı çağrı başına 2 kredi. Başarısız çağrılar asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

İsteğe bağlı metadata, locks ve full boolean değerleri sırasıyla havuz metadata'sını, zamanlanmış kilit kanıtını ve mevcut en kapsamlı okumayı ekler.

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

Yanıt: standart zarf. data, token kimliğini, bir piyasa anlık görüntüsünü ve kilit ya da yakma bağlamıyla birlikte LP saklama durumunu tutar.

Sınırlamalar: derin geçmişe dayalı yakma kökeni v1'de sunulmaz. Kilit bağlamı, tanınan kilitleyici (locker) kalıplarını kapsar; bu yüzden alışılmadık, özel bir kilitleyici bir kilit yerine düz saklama olarak okunabilir. Bunu "kilitli değil" değil, "doğrulanmadı" olarak okuyun.

POST /v1/api/intel/risk, izin Intelligence (intel:read)

Bir token kontratı için zincir farkındalıklı Cognivo Risk Sinyalleri; geri dönüş olarak kırmızı bayrak okumasıyla birlikte.

Liste fiyatı: başarılı çağrı başına 2 kredi. Başarısız çağrılar asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

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

Yanıt: standart zarf. data, token için bulunan sinyalleri ve bayrakları tutar.

Sınırlamalar: temiz bir sonuç, token'ın güvenli olduğu anlamına gelmez. Okuma anında bilinen hiçbir kırmızı bayrağın bulunmadığı anlamına gelir.

POST /v1/api/contract/analysis, izin Contract (contract:read)

Bir kontrat adresi için kontrat ve denetim kanıtı: var mı, sahibi kim, sahiplik devredildi mi, bir proxy mi ve yöneticisi kim, onu kim dağıttı, hangi cüzdanlar denetleyici ya da ekip olarak ilişkilendirilebilir ve kaynak kodu doğrulanmış mı.

Maliyet: 0 kredi. Bu endpoint karar gereği tüm planlarda ücretsizdir. Hiçbir şey düşülmez.

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

Yanıt: standart zarf. data şunları tutar: contract, ownership, proxy, deployer, controllers, source_verification, limitations ve unavailable.

Her alan nereden geldiğini size söyler. meta.provenance, her alanı aşağıdakilerden tam olarak birine eşler:

Etiket	Ne anlama gelir
verified_onchain	İsteğiniz sırasında o ağa ait bir node'dan okundu. Bir olgu.
augmented	Cognivo Augmented Intelligence: dış bir kaynak tarafından sağlandı, çapraz kontrol edildi ama Cognivo tarafından kanıtlanmadı.
interpretation	Cognivo'nun olgulara dair okuması. Bir olgu değil, bir değerlendirme.
unavailable	Cognivo bunu elde edemedi. Nedeni data.unavailable içindedir.

Bir boşluğu doldurmak için hiçbir şey tahmin edilmez, varsayılana çekilmez ya da sıfır olarak döndürülmez.

meta.chain_data_source.cognivo_grounded, okumanın geldiği altyapıyı Cognivo'nun işletip işletmediğini söyler. Cognivo kendi Ethereum node'unu çalıştırır, bu yüzden Ethereum okumaları true olur. Base ve BNB Chain okumaları dış RPC altyapısından gelir, bu yüzden false olur. Bu okumalar doğrudur ama Cognivo'nun kontrol ettiği donanımdan sunulmaz ve Cognivo, aksini varsaymanıza izin vermek yerine bunu açıkça belirtir.

Base üzerindeki sınırlamalar, aynı zamanda data.limitations içinde de döner:

• Derin denetleyici grafiği yalnızca Ethereum içindir. Base üzerinde denetleyici ve ekip ilişkilendirmesi daha dar bir cüzdan rolü okumasından gelir.
• Base üzerindeki dağıtıcı kanıtı bir Cognivo arşiv okumasından değil, dış bir kaynaktan gelir. Bunu kanıtlanmış bir olgu değil, güçlü bir ipucu olarak değerlendirin.
• Likidite kilit takvimleri Base üzerinde çözümlenmez. LP saklama ve yakma kanıtı için POST /v1/api/intel/liquidity kullanın ve eksik bir kilidi kilit yokluğu olarak okumayın.

Bu endpoint yalnızca kontrat denetim kanıtını bildirir. Likidite hakkında hiçbir şey söylemez ve temiz bir sonuç asla kontratın güvenli olduğu anlamına gelmez.

Yalnızca okuma: hiçbir şey imzalanmaz, hiçbir işlem oluşturulmaz, hiçbir şey yayına verilmez ve hiçbir cüzdana yetki devredilmez.

Cüzdan istihbaratı

POST /v1/api/wallet/pnl, izin Intelligence (intel:read)

Bir cüzdanın tek bir token üzerindeki kar ve zararı; temellendirilmiş zincir üstü takaslardan hesaplanır. Hem wallet hem token zorunludur.

Liste fiyatı: başarılı çağrı başına 10 kredi. Başarısız çağrılar ve 422 veri yok sonuçları asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

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

Yanıt: standart zarf. data, gerçekleşmiş rakamı ve savunulabilir bir maliyet esası bulunduğunda hala tutulan pozisyon için gerçekleşmemiş bir rakamı tutar.

Sınırlamalar: savunulabilir bir maliyet esası oluşturulamadığında gerçekleşmemiş rakam, uydurma bir sayı yerine null olarak döner. Cüzdanın o token'da hiç fiyatlanmış işlemi yoksa çağrı 422 döndürür (örneğin insufficient_data); bu, karın sıfır olduğu anlamına gelmez, Cognivo'nun adil bir sayı hesaplayamadığı anlamına gelir. Bir 422 asla ücretlendirilmez. Cognivo'nun fiyatlandıramadığı takaslar atılmak yerine fiyatlanmamış olarak gösterilir.

POST /v1/api/wallet/approvals, izin Security (security:read)

Bir cüzdanın verdiği token harcama onaylarını listeler ve sınırsız izinleri işaretler.

Liste fiyatı: başarılı çağrı başına 2 kredi. Başarısız çağrılar asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

İsteğe bağlı limit ve offset, büyük onay kümelerinde sayfalama yapar.

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

Yanıt: standart zarf. data, harcayan, token ve izin bağlamıyla birlikte onay listesini tutar.

Sınırlamalar: bu yalnızca okumadır. Cognivo asla fon hareket ettirmez ve sizin adınıza bir onayı iptal edemez. İptal işlemi her zaman kendi cüzdanınızdan yapılır. Boş bir liste geçerli ve başarılı bir yanıttır ve ücretlendirilmez.

POST /v1/api/wallet/exact-movements, izin Intelligence (intel:read)

Bir cüzdanın tam token hareketlerini listeler: alımlar, satışlar ve transferler. token isteğe bağlıdır ve okumayı tek bir token'a daraltır.

Liste fiyatı: başarılı çağrı başına 5 kredi. Başarısız çağrılar asla ücretlendirilmez. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

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

Yanıt: standart zarf. data, sayılarla birlikte hareket listesini tutar.

Sınırlamalar: çağrı, çağrı başına en fazla 25 olmak üzere en son hareketleri döndürür. Eşleşen hareketi olmayan bir cüzdan, uydurma bir geçmiş yerine 422 döndürür.

Discover

GET /v1/api/discover

Herkese açık Discover akışı: her biri token kimliği, bir kanca ve maddelerden oluşan, yakın zamanlı ve anonimleştirilmiş zincir üstü istihbarat kartları. Etkin herhangi bir anahtarla çalışır. Ücretsizdir, dar bir günlük limit altında.

Sorgu parametreleri: limit (1 ile 50 arası, 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'

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

Sınırlamalar: 1 ile 50 aralığının 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, bu yüzden tam kapsam değil bir örneklemdir.

Henüz kullanılamayanlar

Bunlar şeffaflık için listelenmiştir ve bugün hiçbir şey döndürmez:

• API üzerinden derin cüzdan izleme (wallet/trace). Asenkron iş akışı şimdilik yalnızca sohbet ve uygulamada mevcuttur.
• Kimliğe göre rapor getirme (reports/:id).
• Webhook'lar.
• Solana endpoint'leri.

Sonraki adımlar

İlk çağrınızı Hızlı Başlangıç ile yapın, Kimlik doğrulama ve anahtarlar sayfasında bir anahtar oluşturup kapsamlandırın ve bir şeyi zamanlanmış olarak çalıştırmadan önce Hız limitleri ve hatalar sayfasını okuyun.