Référence des endpoints

Tous les endpoints se trouvent sous https://api.cognivolabs.io/v1/api. Les endpoints d'intelligence sont en POST avec un corps JSON (cela empêche les aperçus de liens, les robots d'indexation et les préchargeurs de déclencher une exécution). GET n'existe que pour health, me et discover.

Vous préférez une version lisible par machine ? La spécification OpenAPI complète couvre tout le contenu de cette page.

L'enveloppe de réponse

Chaque endpoint répond avec la même enveloppe. Succès :

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

data - le résultat d'intelligence lui-même ; sa forme varie selon l'endpoint
meta.request_id - identifiant unique de cet appel ; conservez-le, le support peut retracer un appel à partir de lui
meta.credits_charged - les crédits que cet appel a coûté : 0 pour les endpoints gratuits, les allocations de démo sandbox ou de trial, et tout résultat échoué ou vide ; le prix en crédits de l'endpoint en usage payant
meta.generated_at - moment où le résultat a été produit
meta.chain apparaît sur les appels spécifiques à une chaîne, et meta.sources (un tableau d'étiquettes de sources) apparaît quand le résultat cite des sources

Échec :

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

error est un code stable lisible par machine (voir Limites de débit et erreurs) ; message est une indication facultative pour les humains.

Champs de corps communs

chain - l'un de eth, base, bsc (insensible à la casse)
address / wallet / token - une adresse EVM 0x… (40 caractères hexadécimaux)

Tous les exemples ci-dessous utilisent l'espace réservé YOUR_API_KEY ; dans du vrai code, chargez la clé depuis une variable d'environnement ou un gestionnaire de secrets, ne la codez jamais en dur.

Accès et coûts en crédits

Les endpoints d'intelligence exécutables nécessitent un accès trial, partenaire, payant ou enterprise. Sans accès, ils ne s'exécutent pas gratuitement : vous obtenez une erreur 403 claire comme access_required (voir Limites de débit et erreurs). L'usage payant est facturé en crédits Cognivo par appel réussi ; les appels échoués ne sont pas facturés. Coûts par endpoint (ils s'appliquent à l'usage payant ; affichés par souci de transparence) :

Endpoint	Crédits par appel réussi
`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`	gratuit
`GET discover`	gratuit, avec un plafond de débit strict

Service

GET /v1/api/health

Sonde de disponibilité. Aucune clé d'API requise.

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

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

Réponse (pas l'enveloppe standard, volontairement) :

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

Limites : si l'API publique est désactivée, vous obtenez 404 public_api_disabled ici aussi, donc cet endpoint sert également de vérification de disponibilité.

GET /v1/api/me

Introspection de la clé appelante. Scope : n'importe quelle clé valide. Gratuit. Pour les clés live en libre-service, il affiche aussi le credits_balance du compte propriétaire (null si temporairement indisponible) et le guide top_up, ainsi que l'access_mode de la clé.

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

Réponse :

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

Limites : n'affiche que la clé masquée, jamais le matériel complet de la clé. credits_balance est le solde de crédits Cognivo du compte propriétaire et peut être null s'il est temporairement indisponible.

Intelligence de tokens

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

Pourquoi ce token baisse : une lecture vérifiée de l'activité on-chain récente à la recherche du facteur dominant (ventes, retraits de LP, mouvements du propriétaire).

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 3 crédits par appel réussi en usage payant.

Corps de la requête :

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

Réponse : l'enveloppe standard ; data contient l'analyse de la baisse (facteur dominant, observations on-chain à l'appui) avec meta.chain renseigné.

Limites : a besoin d'activité récente pour dire quelque chose d'utile ; pour un token avec très peu d'historique de trading, la lecture peut être maigre. Des signaux, pas des conseils financiers.

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

Analyse des wallets d'équipe et de contrôle pour un token : wallets du déployeur, du propriétaire et des contrôleurs, plus leur comportement récent.

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 5 crédits par appel réussi en usage payant.

Corps de la requête :

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

Réponse : l'enveloppe standard ; data liste les wallets d'équipe/de contrôle identifiés et leur comportement récent, souvent avec meta.sources.

Limites : identifie les wallets à partir de relations on-chain (déploiement, propriété, contrôle) ; elle ne peut pas voir la structure d'équipe hors chaîne.

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

Statut du pool/LP d'un token : contexte du pool, garde des LP et contexte de verrouillage/burn.

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 2 crédits par appel réussi en usage payant.

Corps de la requête (les booléens facultatifs metadata, locks et full ajoutent des métadonnées de pool vérifiées, une preuve de verrouillage temporisé et la lecture la plus complète disponible) :

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

Réponse : l'enveloppe standard ; data contient l'identité du token, un instantané de marché, et la garde des LP plus le contexte de verrouillage/burn.

Limites : la provenance historique profonde des burns n'est pas exposée en v1 ; le contexte de verrouillage couvre les schémas de lockers reconnus, et un locker personnalisé non reconnu peut apparaître comme une garde non verrouillée.

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

Signaux de risque Cognivo adaptés à la chaîne pour un token (lecture des drapeaux rouges en solution de repli).

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 2 crédits par appel réussi en usage payant.

Corps de la requête :

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

Réponse : l'enveloppe standard ; data contient les signaux de risque et les drapeaux trouvés pour le token.

Limites : un résultat propre ne signifie jamais "sûr" ; il signifie qu'aucun drapeau rouge connu n'a été trouvé au moment de la lecture.

Intelligence de wallets

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

PnL réalisé d'un wallet sur un token, à partir d'une activité de wallet vérifiée. wallet et token sont tous deux obligatoires.

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 10 crédits par appel réussi en usage payant.

Corps de la requête :

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

Réponse : l'enveloppe standard ; data contient le calcul du PnL réalisé pour cette paire wallet/token.

Limites : renvoie 422 (par exemple insufficient_data) quand le wallet n'a aucune transaction valorisée sur ce token, de sorte qu'un chiffre honnête ne peut pas être calculé. Cognivo n'invente jamais de chiffre, et un 422 n'est jamais facturé. PnL réalisé uniquement ; les positions non réalisées (encore détenues) ne sont pas valorisées ici.

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

Approbations de tokens en vigueur sur un wallet, en signalant les autorisations illimitées. Lecture seule : Cognivo ne déplace jamais de fonds et ne peut pas révoquer à votre place.

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 2 crédits par appel réussi en usage payant.

Corps de la requête (limit et offset permettent facultativement de paginer les grands ensembles d'approbations) :

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

Réponse : l'enveloppe standard ; data contient la liste des approbations avec le contexte du spender, du token et de l'autorisation.

Limites : un résultat vide (aucune approbation trouvée) est une réponse valide et réussie, et n'est pas facturé.

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

Mouvements récents exacts d'un wallet (lecture de type propriétaire/déployeur). token est facultatif et restreint la lecture à un seul token.

Accès et coût : nécessite un accès en direct (trial, partenaire, payant ou enterprise) ; 5 crédits par appel réussi en usage payant.

Corps de la requête :

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

Réponse : l'enveloppe standard ; data contient la liste des mouvements avec des décomptes.

Limites : renvoie les mouvements les plus récents (jusqu'à 25 par appel) ; un wallet sans mouvement correspondant renvoie 422 plutôt qu'un historique inventé.

Discover

GET /v1/api/discover

Le flux public Discover : des cartes d'intelligence publiques récentes et de haute qualité (identité du token, accroche, points clés). Scope : n'importe quelle clé valide. Gratuit, avec un plafond de débit strict.

Paramètres de requête : limit (1-50, 20 par défaut) et facultativement 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();

Réponse :

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

Limites : les valeurs de limit hors de 1-50 sont ramenées dans la plage ; le flux ne contient que l'intelligence que les utilisateurs ont choisi de publier, c'est donc un échantillon, pas une couverture complète.

Prévu (pas encore en ligne)

Ces éléments sont documentés par souci de transparence sur la feuille de route et ne renvoient rien aujourd'hui :

Traçage profond de wallet via l'API (wallet/trace) - le flux de tâches asynchrones est pour l'instant réservé au chat/à la dApp
Récupération de rapports par id (reports/:id)
Webhooks
Endpoints Solana

L'enveloppe de réponse​

Champs de corps communs​

Accès et coûts en crédits​

Service​

GET /v1/api/health​

GET /v1/api/me​

Intelligence de tokens​

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​

Intelligence de wallets​

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​

Prévu (pas encore en ligne)​

L'enveloppe de réponse

Champs de corps communs

Accès et coûts en crédits

Service

GET /v1/api/health

GET /v1/api/me

Intelligence de tokens

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`

Intelligence de wallets

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

Prévu (pas encore en ligne)