Referensi endpoint

Semua endpoint berada di bawah https://api.cognivolabs.io/v1/api. Endpoint intelijen menggunakan POST dengan body JSON (ini mencegah pratinjau tautan, crawler, dan prefetcher memicu eksekusi). GET hanya ada untuk health, me, dan discover.

Lebih suka versi yang dapat dibaca mesin? Spesifikasi OpenAPI lengkap mencakup semua yang ada di halaman ini.

Amplop respons

Setiap endpoint menjawab dengan amplop yang sama. Sukses:

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

data - hasil intelijen itu sendiri; bentuknya berbeda-beda per endpoint
meta.request_id - id unik untuk panggilan ini; simpan, tim dukungan bisa melacak panggilan darinya
meta.credits_charged - kredit yang menjadi biaya panggilan ini: 0 untuk endpoint gratis, jatah demo sandbox atau trial, dan hasil apa pun yang gagal atau kosong; harga kredit endpoint tersebut pada penggunaan berbayar
meta.generated_at - kapan hasil diproduksi
meta.chain muncul pada panggilan yang spesifik chain, dan meta.sources (array label sumber) muncul saat hasil mengutip sumber

Gagal:

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

error adalah kode stabil yang dapat dibaca mesin (lihat Batas laju dan error); message adalah petunjuk opsional untuk manusia.

Field body yang umum

chain - salah satu dari eth, base, bsc (tidak peka huruf besar/kecil)
address / wallet / token - alamat EVM 0x… (40 karakter heksadesimal)

Semua contoh di bawah memakai placeholder YOUR_API_KEY; dalam kode sungguhan, muat key dari environment variable atau secret manager, jangan pernah hardcode.

Akses dan biaya kredit

Endpoint intelijen yang dapat dieksekusi membutuhkan akses trial, partner, berbayar, atau enterprise. Tanpa akses, endpoint ini tidak berjalan gratis: Anda mendapat error 403 yang jelas seperti access_required (lihat Batas laju dan error). Penggunaan berbayar ditagih dalam kredit Cognivo per panggilan yang sukses; panggilan yang gagal tidak ditagih. Biaya per endpoint (berlaku untuk penggunaan berbayar; ditampilkan demi transparansi):

Endpoint	Kredit per panggilan sukses
`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`	gratis
`GET discover`	gratis, dengan batas laju yang ketat

Layanan

GET /v1/api/health

Probe keaktifan. Tidak butuh API key.

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

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

Respons (sengaja bukan amplop standar):

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

Keterbatasan: kalau API publik dimatikan, di sini pun Anda mendapat 404 public_api_disabled, jadi endpoint ini sekaligus berfungsi sebagai pemeriksaan ketersediaan.

GET /v1/api/me

Mengintrospeksi key yang memanggil. Scope: key valid mana pun. Gratis. Untuk key live swalayan, endpoint ini juga menampilkan credits_balance akun pemilik (null jika sementara tidak tersedia) dan panduan top_up, ditambah access_mode key tersebut.

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

Respons:

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

Keterbatasan: hanya menampilkan key tersamar, tidak pernah materi key lengkap. credits_balance adalah saldo kredit Cognivo akun pemilik dan bisa bernilai null jika sementara tidak tersedia.

Intelijen token

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

Kenapa token ini turun: pembacaan terverifikasi atas aktivitas on-chain terbaru untuk mencari pemicu dominan (penjualan, penarikan LP, pergerakan pemilik).

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 3 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan:

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

Respons: amplop standar; data memuat analisis penurunan (pemicu dominan, pengamatan on-chain pendukung) dengan meta.chain terisi.

Keterbatasan: butuh aktivitas terbaru agar bisa mengatakan sesuatu yang berguna; untuk token dengan riwayat perdagangan yang sangat sedikit, pembacaannya bisa tipis. Sinyal, bukan nasihat keuangan.

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

Pemindaian dompet tim dan pengendali untuk sebuah token: dompet deployer, pemilik, dan pengendali beserta perilaku terbaru mereka.

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 5 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan:

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

Respons: amplop standar; data mencantumkan dompet tim/pengendali yang teridentifikasi dan perilaku terbaru mereka, sering dengan meta.sources.

Keterbatasan: mengidentifikasi dompet dari relasi on-chain (deploy, kepemilikan, kendali); struktur tim off-chain tidak bisa dilihatnya.

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

Status pool/LP untuk sebuah token: konteks pool, kustodi LP, dan konteks lock/burn.

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 2 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan (boolean opsional metadata, locks, dan full menambahkan metadata pool terverifikasi, bukti lock berjangka waktu, dan pembacaan terlengkap yang tersedia):

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

Respons: amplop standar; data memuat identitas token, snapshot pasar, dan kustodi LP plus konteks lock/burn.

Keterbatasan: asal-usul burn historis yang dalam tidak diekspos di v1; konteks lock mencakup pola locker yang dikenali, dan locker kustom yang tidak dikenali bisa terbaca sebagai kustodi tanpa lock.

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

Sinyal risiko Cognivo yang sadar chain untuk sebuah token (pembacaan red-flag sebagai cadangan).

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 2 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan:

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

Respons: amplop standar; data memuat sinyal risiko dan flag yang ditemukan untuk token itu.

Keterbatasan: hasil yang bersih tidak pernah berarti "aman"; artinya tidak ada red flag yang diketahui ditemukan pada saat pembacaan.

Intelijen dompet

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

PnL terealisasi sebuah dompet pada satu token, dari aktivitas dompet yang terverifikasi. wallet dan token keduanya wajib.

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 10 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan:

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

Respons: amplop standar; data memuat perhitungan PnL terealisasi untuk pasangan dompet/token itu.

Keterbatasan: mengembalikan 422 (misalnya insufficient_data) saat dompet tidak punya transaksi berharga pada token itu, sehingga angka yang adil tidak bisa dihitung. Cognivo tidak pernah mengarang angka, dan 422 tidak pernah ditagih. Hanya PnL terealisasi; posisi yang belum terealisasi (masih dipegang) tidak dinilai di sini.

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

Approval token yang melekat pada sebuah dompet, dengan penandaan allowance tak terbatas. Hanya-baca: Cognivo tidak pernah memindahkan dana dan tidak bisa mencabut untuk Anda.

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 2 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan (limit dan offset opsional untuk memfilter halaman pada set approval yang besar):

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

Respons: amplop standar; data memuat daftar approval dengan konteks spender, token, dan allowance.

Keterbatasan: hasil kosong (tidak ada approval ditemukan) adalah jawaban valid dan sukses, dan tidak ditagih.

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

Pergerakan terbaru secara persis untuk sebuah dompet (pembacaan gaya pemilik/deployer). token opsional dan mempersempit pembacaan ke satu token.

Akses dan biaya: membutuhkan akses live (trial, partner, berbayar, atau enterprise); 5 kredit per panggilan sukses pada penggunaan berbayar.

Body permintaan:

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

Respons: amplop standar; data memuat daftar pergerakan beserta hitungannya.

Keterbatasan: mengembalikan pergerakan paling baru (hingga 25 per panggilan); dompet tanpa pergerakan yang cocok mengembalikan 422, bukan riwayat yang dikarang.

Discover

GET /v1/api/discover

Feed Discover publik: kartu intelijen publik berkualitas tinggi terbaru (identitas token, hook, poin-poin). Scope: key valid mana pun. Gratis, dengan batas laju yang ketat.

Parameter query: limit (1-50, default 20) dan chain opsional (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();

Respons:

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

Keterbatasan: nilai limit di luar 1-50 dipangkas ke dalam rentang; feed hanya berisi intelijen yang dipilih pengguna untuk dipublikasikan, jadi ini sampel, bukan cakupan penuh.

Direncanakan (belum live)

Berikut ini didokumentasikan demi transparansi roadmap dan hari ini tidak mengembalikan apa pun:

Penelusuran dompet mendalam lewat API (wallet/trace) - alur job asinkron untuk saat ini hanya ada di chat/dApp
Pengambilan laporan berdasarkan id (reports/:id)
Webhook
Endpoint Solana

Amplop respons​

Field body yang umum​

Akses dan biaya kredit​

Layanan​

GET /v1/api/health​

GET /v1/api/me​

Intelijen token​

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

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

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

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

Intelijen dompet​

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

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

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

Discover​

GET /v1/api/discover​

Direncanakan (belum live)​

Amplop respons

Field body yang umum

Akses dan biaya kredit

Layanan

GET /v1/api/health

GET /v1/api/me

Intelijen token

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

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

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

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

Intelijen dompet

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

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

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

Discover

GET /v1/api/discover

Direncanakan (belum live)